① 困境锚定
产品经理甩过来一个需求："做一个文档上传功能。"
当时我想，这还不简单？一个上传按钮、一个文件列表、一个删除操作，半小时搞定。
结果做了两周。
因为"文档上传"只是冰山一角。水面底下是：文件类型校验、大小限制、上传进度反馈、上传失败重试。上传完了要存云存储、建数据库记录。然后还有审核——谁有资格审核、审核通过/驳回后状态怎么变、审核意见存哪。审核完了要通知用户——通知列表怎么管理、未读已读怎么标记。
最后还有统计：待审核多少、已通过多少、管理员的视角要不要看到全单位的数据？
一个"上传功能"背后，是一整套业务闭环。
② 误区打脸
很多开发者接到这类需求时，第一反应是：先做页面，后补逻辑。
打开微信开发者工具，先把上传页面画好——选择文件按钮、进度条、文件列表。看起来很能出活。
但问题来了：你上传到哪？云存储还是服务器？云存储的路径怎么规划？文件ID怎么和数据库记录关联？用户还没登录呢，上传接口的openid从哪来？
页面做得再漂亮，后端没想清楚就是空中楼阁。
更深的误区是：把状态管理当成简单的CRUD。
文档的状态不是"待审核、已通过、已驳回"三个字段切换那么简单。状态之间有流转规则——待审核才能变成已通过，已通过不能再变回待审核。谁有权限改状态？状态变更时触发什么副作用（比如发通知）？
这不是CRUD，这是状态机。用CRUD的思路去做状态机，代码会变成一堆if-else的屎山。
③ 思维框架
后来我养成了一个习惯：拿到一个功能需求，先不碰代码，先画数据流。
数据从哪来、到哪去、中间经过哪些处理节点、每个节点谁有权限操作、操作完成后状态怎么变。
拿文档管理来举例，完整的数据流是：
用户选择文件 → 前端校验（类型、大小）→ 上传到云存储 → 创建数据库记录（状态：待审核）→ 管理员查看待审核列表 → 审核操作 → 状态更新 → 触发通知 → 用户收到通知
这条链路上的每一个节点都是独立的决策点：
- 文件存云存储还是数据库？文件大的必须走云存储，云数据库有文档大小限制。
- 数据库记录存哪些字段？不是越多越好，每个查询都会消耗读操作次数。
- 审核是同步还是异步？大文件的处理可能很慢，同步等的话用户体验很差。
- 通知怎么发？微信订阅消息有模板限制，不是想发什么就发什么。
每个决策点都有2-3种实现路径，选择哪条取决于你的业务场景和性能要求。
④ 实战一瞥
分享一个我在项目中做的设计决策：审核为什么必须是异步的。
在最初的设计中，管理员点"通过"按钮，前端直接调用云函数更新数据库状态，然后给用户发一条通知。看起来很直接。
但实际用起来有两个问题：
第一，管理员审核一个文档时，可能要打开文档看内容。如果文档是PDF，要从云存储下载再预览，这个加载过程本身就需要时间。如果审核操作是同步的，管理员在等文档加载的时候接口可能就超时了。
第二，审核操作应该有记录。谁在什么时间审核的、审核意见是什么——这些信息不只需要告诉用户，还需要留痕。如果同步处理，这些额外操作都会拖慢响应。
所以最终我把它设计成：审核操作只负责更新状态和写入审核意见，通知通过云函数的异步逻辑发送。即使通知发送失败，也不会影响审核结果。
这种"核心操作和副作用分离"的思路，在后续的功能扩展中帮了大忙。后来加了审核提醒定时任务、批量审核功能，核心审核逻辑完全不需要改。
⑤ 留白引导
业务闭环的设计没有标准答案，但有一个通用的思考框架：数据流 → 状态机 → 权限边界 → 通知触发点。
沿着这条线捋一遍，大多数功能的设计决策就自然浮出水面了。
具体到这个项目的审核状态机设计、通知触发的实现方案、分页查询的性能优化——每个都是独立的专题，有机会可以展开聊聊。
如果你的项目也在做类似的功能，或者被"简单需求"的复杂度困扰过，欢迎交流。
