183 lines
7.5 KiB
Markdown
183 lines
7.5 KiB
Markdown
# 技术方案评审规范
|
||
|
||
> 适用范围：新功能、复杂业务改造、跨模块变更、基础设施建设和需要多人评审的技术方案。
|
||
> 核心目标：让评审人能够判断“为什么这样做、是否能落地、失败后怎么办”，而不是仅看到表结构和代码清单。
|
||
|
||
---
|
||
|
||
## 一、方案分级
|
||
|
||
技术方案不要求统一篇幅，也不要求每个需求都强行画图。
|
||
|
||
| 等级 | 典型场景 | 最低要求 |
|
||
|------|----------|----------|
|
||
| 简化方案 | 单字段、单表 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. 实施人员是否还需要自行猜测关键业务规则。
|
||
|
||
任一关键问题仍需实施人员自行猜测时，方案只能保持“待评审”，不能视为评审通过。
|