# 技术方案评审规范 > 适用范围：新功能、复杂业务改造、跨模块变更、基础设施建设和需要多人评审的技术方案。 > 核心目标：让评审人能够判断“为什么这样做、是否能落地、失败后怎么办”，而不是仅看到表结构和代码清单。 --- ## 一、方案分级 技术方案不要求统一篇幅，也不要求每个需求都强行画图。 | 等级 | 典型场景 | 最低要求 | |------|----------|----------| | 简化方案 | 单字段、单表 CRUD、局部筛选、纯展示修复 | 背景、改动范围、接口/字段、前端影响、兼容性、人工验收点 | | 标准方案 | 新接口、异步任务、跨表写入、配置化、第三方调用 | 简化方案全部内容 + 关键流程图 + 数据与异常处理 + 发布回滚 | | 完整方案 | 金额、审批、状态机、并发、跨模块事务、可靠事件、公共基础设施 | 标准方案全部内容 + 系统上下文图 + 状态图/时序图 + 前后端方案 + 风险与待决策项 | 以下场景即使代码量不大，也必须使用完整方案： - 涉及资金、余额、信用额度、退款或充值。 - 涉及审批、权限、审计或敏感数据导出。 - 涉及异步任务、消息投递、最终一致性或第三方回调。 - 修改公共基础设施或多个业务模块共同依赖的契约。 --- ## 二、文档状态 需要进入评审的文档，开头必须标明状态： ```text 状态：草稿 | 待评审 | 评审通过 | 已废弃 负责人：姓名或角色 评审人：后端、前端、产品、验收负责人、运维（按实际参与方） 最后更新：YYYY-MM-DD 关联需求：需求编号或 OpenSpec change ``` 状态含义： - `草稿`：允许存在未收敛内容，不可直接进入开发。 - `待评审`：方案作者认为信息已经完整，待评审人确认。 - `评审通过`：关键决策和待办已有结论，可以进入实施。 - `已废弃`：保留历史原因，并链接替代方案。 存在评审阻塞项时，禁止标记为“评审通过”。 --- ## 三、必备内容 ### 3.1 背景、目标与非目标 必须回答： - 当前问题是什么，谁受到影响。 - 本次要达成的业务结果和可观察结果是什么。 - 本次明确不做什么，为什么不做。 - 当前系统有哪些不能忽略的约束。 ### 3.2 现状与改造范围 - 标出当前入口、主要调用链、现有表和已有接口。 - 列出新增、修改、废弃的模块和接口。 - 说明是否触发 DDD 迁移，以及选择复杂写、简单写或 Query 通道的依据。 - 禁止只写理想结构而不说明与旧代码如何共存。 ### 3.3 架构与关键流程 按问题选择图，不为凑数量画图： | 图 | 适用问题 | |----|----------| | 系统上下文图 | 谁调用谁、系统边界和外部依赖是什么 | | 组件图 | Handler、Application、Domain、Repository、队列等如何协作 | | 流程图 | 条件分支、人工操作和业务步骤如何推进 | | 状态图 | 哪些状态允许转换，哪些是终态 | | 时序图 | 事务边界、异步事件、回调和失败重试的先后顺序 | | 数据关系图 | 新增多张表且关系仅靠文字难以理解 | 图使用 Mermaid，图下必须补充关键约束。图不能替代状态枚举、接口字段和异常规则。 ### 3.4 后端技术方案 至少包含： - 领域或模块边界，以及核心不变量归属。 - 数据模型、索引、唯一约束、迁移和历史数据处理。 - API 请求、响应、错误码、权限、分页和兼容策略。 - 事务边界、并发控制、幂等策略和失败重试。 - 异步任务的载荷、状态、重试、死信或人工补偿入口。 - 查询性能、N+1 风险和必要的批量查询方案。 - 审批类方案必须明确审批意见、附件、必填规则、不可修改审计和下载权限，不能只设计状态字段。 ### 3.5 前端技术方案 不能只写“前端新增按钮”或“前端展示字段”。至少说明： - 涉及哪些端：后台管理、代理端、企业端、C 端 H5/公众号。 - 页面入口、建议路由、页面间跳转和权限控制。 - API 模块、请求参数、响应状态和刷新策略。 - 表单、列表、详情、弹框、上传和异步任务的交互状态。 - 加载、空数据、重复提交、部分成功、失败、重试和过期状态。 - 金额单位、时间格式、枚举显示和后端字段的唯一口径。 - 滚动发布时说明新旧前后端兼容方式；停机发布时说明维护页、版本一致性和开放访问前检查。 当前仓库不包含前端源码时，方案可以保持框架无关，但必须标明需要前端仓库确认的实现映射，不能凭空指定状态库或组件库。 ### 3.6 非功能设计 按实际风险覆盖： - 权限和数据范围。 - 敏感字段与导出控制。 - 审计日志。 - 性能目标和容量假设。 - 日志、指标、告警和人工排查入口。 - 外部依赖不可用时的降级策略。 ### 3.7 发布、回滚与兼容 至少回答： - 数据库、后端、Worker、前端和配置按什么顺序发布。 - 是否需要先加字段、双写、回填、迁移存量进行中业务或兼容旧接口。 - 如何关闭新入口或停用新流程。 - 回滚时哪些数据不能删除，哪些状态需要人工处理。 - 滚动发布时说明新旧版本并存风险；停机发布时说明如何阻止新写入、迁移存量任务并确认整套版本一致。 ### 3.8 风险、待决策与验收 - 风险必须写触发条件、影响和应对方式。 - 待决策项必须给出推荐方案、备选方案和最晚确认时间。 - 验收使用本项目允许的人工方式：接口调用、PostgreSQL 数据核对、日志检查和页面操作。 - 不得用“后续再看”掩盖会影响数据模型、接口契约或安全边界的问题。 --- ## 四、评审检查清单 ### 业务与范围 - [ ] 目标、非目标和验收结果明确。 - [ ] 原始需求中的歧义已经决策或明确列为阻塞项。 - [ ] Phase 1 与后续阶段边界清晰。 ### 架构与数据 - [ ] 现状调用链和目标调用链都能解释。 - [ ] DDD 使用有业务理由，没有为简单 CRUD 强行建模。 - [ ] 状态、事务、并发、幂等和最终一致性闭环。 - [ ] 审批意见、附件和业务凭证边界明确，历史操作不可被覆盖。 - [ ] PostgreSQL DDL、索引和历史数据策略可执行。 - [ ] 存量进行中业务有明确的回填、结束或人工处理方案，不会因旧入口下线而悬空。 ### 前端与接口 - [ ] 前端页面、状态和异常分支完整。 - [ ] API 路径使用项目真实前缀，字段和枚举一致。 - [ ] 权限不依赖前端隐藏按钮。 - [ ] 异步任务和审批完成后有明确刷新或轮询策略。 ### 上线与运维 - [ ] 发布顺序、功能开关或停用方式明确。 - [ ] 回滚不会删除历史审批、资金流水或审计记录。 - [ ] 关键失败能够通过日志、任务状态或管理页面定位。 --- ## 五、合格标准 “业内合格”不等于文档很长，而是评审人能基于文档回答以下问题： 1. 方案是否解决了正确的问题。 2. 前后端和外部系统的边界是否一致。 3. 正常路径、异常路径和并发路径是否闭环。 4. 数据是否可追溯，资金和权限是否安全。 5. 能否分阶段发布，失败后能否止损和恢复。 6. 实施人员是否还需要自行猜测关键业务规则。 任一关键问题仍需实施人员自行猜测时，方案只能保持“待评审”，不能视为评审通过。