7.5 KiB
7.5 KiB
技术方案评审规范
适用范围：新功能、复杂业务改造、跨模块变更、基础设施建设和需要多人评审的技术方案。 核心目标：让评审人能够判断“为什么这样做、是否能落地、失败后怎么办”，而不是仅看到表结构和代码清单。
一、方案分级
技术方案不要求统一篇幅，也不要求每个需求都强行画图。
| 等级 | 典型场景 | 最低要求 |
|---|---|---|
| 简化方案 | 单字段、单表 CRUD、局部筛选、纯展示修复 | 背景、改动范围、接口/字段、前端影响、兼容性、人工验收点 |
| 标准方案 | 新接口、异步任务、跨表写入、配置化、第三方调用 | 简化方案全部内容 + 关键流程图 + 数据与异常处理 + 发布回滚 |
| 完整方案 | 金额、审批、状态机、并发、跨模块事务、可靠事件、公共基础设施 | 标准方案全部内容 + 系统上下文图 + 状态图/时序图 + 前后端方案 + 风险与待决策项 |
以下场景即使代码量不大，也必须使用完整方案：
- 涉及资金、余额、信用额度、退款或充值。
- 涉及审批、权限、审计或敏感数据导出。
- 涉及异步任务、消息投递、最终一致性或第三方回调。
- 修改公共基础设施或多个业务模块共同依赖的契约。
二、文档状态
需要进入评审的文档，开头必须标明状态：
状态：草稿 | 待评审 | 评审通过 | 已废弃
负责人：姓名或角色
评审人：后端、前端、产品、验收负责人、运维（按实际参与方）
最后更新：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 路径使用项目真实前缀，字段和枚举一致。
- 权限不依赖前端隐藏按钮。
- 异步任务和审批完成后有明确刷新或轮询策略。
上线与运维
- 发布顺序、功能开关或停用方式明确。
- 回滚不会删除历史审批、资金流水或审计记录。
- 关键失败能够通过日志、任务状态或管理页面定位。
五、合格标准
“业内合格”不等于文档很长，而是评审人能基于文档回答以下问题：
- 方案是否解决了正确的问题。
- 前后端和外部系统的边界是否一致。
- 正常路径、异常路径和并发路径是否闭环。
- 数据是否可追溯，资金和权限是否安全。
- 能否分阶段发布，失败后能否止损和恢复。
- 实施人员是否还需要自行猜测关键业务规则。
任一关键问题仍需实施人员自行猜测时，方案只能保持“待评审”，不能视为评审通过。