技术方案设计规范

技术方案编写模板、方案选型、非功能需求

方案文档模板

规则：技术方案是开发前的设计共识，必须使用统一模板编写，确保信息完整、可评审、可追溯。

[Requirement] 所有涉及新模块、新接口、数据结构变更、外部依赖引入的工作，必须先产出技术方案文档。

[Requirement] 方案文档须在开发启动前完成评审，评审通过后方可编码。

[Standard] 方案文档使用 Markdown 格式，存放于 docs/design/ 目录，命名格式 YYYYMMDD-<需求简称>-design.md。

[Default] 模板章节固定为以下 8 节，不允许省略关键章节。

方案文档模板：

# <需求名称> 技术方案
 
## 1. 背景与目标
- 业务背景：
- 技术目标：
- 非目标（明确不做什么）：
 
## 2. 需求概述
- 关联需求：REQ-XXX
- 核心功能点：
- 验收标准链接：
 
## 3. 现状分析
- 当前架构/实现：
- 存在的问题：
 
## 4. 方案设计
### 4.1 整体架构
（架构图）
 
### 4.2 模块划分
| 模块 | 职责 | 负责人 |
|------|------|--------|
 
### 4.3 接口设计
（接口列表、请求/响应结构）
 
### 4.4 数据模型
（表结构、字段说明、索引）
 
### 4.5 关键流程
（时序图/流程图）
 
## 5. 方案选型
（见"选型比较方法"章节）
 
## 6. 非功能需求
（见"非功能需求"章节）
 
## 7. 风险评估
（见"风险评估"章节）
 
## 8. 排期与任务拆分
| 任务 | 负责人 | 估算 | 依赖 |
|------|--------|------|------|

[Suggestion] 方案文档控制在 5-15 页内，过长说明需求粒度过大或文档冗余。

反模式：

❌ 不写方案直接编码，边写边想，返工率高。
❌ 方案只有架构图没有接口和数据设计，开发时全靠猜。
❌ 方案文档写完就归档，开发中变更不更新文档。

选型比较方法

规则：技术选型必须有比较过程，至少列出 2 个候选方案并基于统一维度打分，禁止”我觉得 X 好”式选型。

[Requirement] 选型必须列出至少 2 个候选方案，逐一分析优缺点，禁止只写一个方案直接通过。

[Standard] 使用决策矩阵打分，维度包括：功能匹配度、性能、可维护性、学习成本、社区活跃度、团队熟悉度。

[Standard] 每个维度权重由团队共识确定，打分采用 1-5 分制，加权总分最高者为推荐方案。

[Caution] 选型须考虑团队技术栈与运维能力，避免引入”技术先进但无人能维护”的方案。

决策矩阵示例（消息队列选型）：

维度	权重	Kafka	RabbitMQ	Redis Stream
功能匹配度	30%	5	4	3
性能	20%	5	3	4
可维护性	15%	3	4	5
学习成本	15%	2	4	5
团队熟悉度	20%	3	4	5
加权总分	100%	3.85	3.85	4.4

结论：Redis Stream 加权总分最高，推荐使用。但需补充说明：当消息量超过 10w/s 或需要持久化回溯时，应重新评估 Kafka。

[Suggestion] 选型结论须注明”适用边界”，说明在什么条件下该选型成立、什么条件下需重新评估。

反模式：

❌ “Kafka 性能好，就用 Kafka”——没有比较，没有考虑团队能力。
❌ 选了最火的技术，但团队没人会，上线后无人维护。
❌ 选型只看性能，忽略了运维成本和学习曲线。

非功能需求

规则：技术方案除功能外，必须明确非功能需求（NFR），并给出可量化的指标与验证方法。

[Requirement] 方案文档必须包含性能、可用性、安全性、可观测性四类非功能需求，缺一不可。

[Requirement] 每条非功能需求必须有量化指标和验证方法，禁止”高性能""高可用”等无指标描述。

[Standard] 非功能需求须与业务场景匹配，不盲目追求超出业务需要的指标（如内部管理系统要求 99.99% 可用性）。

非功能需求模板：

类别	指标	目标值	验证方法
性能	接口响应时间 P95	≤ 500ms	压测报告
性能	并发能力	≥ 100 QPS	压测报告
可用性	服务可用性	≥ 99.9%	监控月报
可用性	故障恢复时间 (RTO)	≤ 5 分钟	故障演练
安全性	敏感数据传输	HTTPS 加密	安全扫描
安全性	SQL 注入防护	0 高危漏洞	安全扫描
可观测性	关键链路覆盖率	≥ 90%	链路追踪检查
可观测性	告警响应时间	≤ 10 分钟	告警记录

各业务场景的非功能需求参考：

业务场景	可用性	响应时间 P95	数据一致性
对外 C 端交易	99.95%	≤ 300ms	强一致
内部管理后台	99.5%	≤ 1s	最终一致
数据报表	99%	≤ 5s	T+1 可接受
实时消息	99.9%	≤ 200ms	最终一致

[Caution] 非功能需求不是越高越好，超出业务需要的指标会带来不必要的成本与复杂度。

反模式：

❌ “系统要高性能、高可用、高安全”——没有量化指标。
❌ 内部工具要求 99.99% 可用性，成本远超业务价值。
❌ 方案写了非功能需求，但排期里没有对应的验证任务。

风险评估

规则：技术方案必须识别风险并给出应对措施，禁止”没有风险”的乐观评估。

[Requirement] 方案文档必须包含风险评估章节，至少识别 3 项风险并给出应对措施。

[Standard] 风险评估采用”概率 × 影响”矩阵，划分为高/中/低三个等级。

[Standard] 高风险项必须有明确的缓解措施和负责人，中风险项须有监控或预案。

[Caution] 风险评估须在开发中持续更新，新发现的风险及时补充到文档。

风险评估矩阵：

概率\影响	低	中	高
高	中	高	极高
中	低	中	高
低	低	低	中

风险评估表示例：

风险项	概率	影响	等级	缓解措施	负责人
微信支付接口联调不顺利	中	高	高	提前申请沙箱环境，预留 2 天联调缓冲	张三
数据库性能瓶颈	低	高	中	提前压测，准备分表预案	李四
第三方 SDK 版本不兼容	中	中	中	先做技术验证（POC），确认后再大规模使用	王五
关键人员请假	低	高	中	关键模块双人备份，文档齐全	全员

风险等级处理策略：

等级	处理策略
极高	必须有缓解措施，否则不允许开发
高	有缓解措施 + 负责人，每日跟踪
中	有监控或预案，每周跟踪
低	记录在案，按需关注

反模式：

❌ 风险评估写”暂无风险”——这是最大的风险。
❌ 识别了风险但没有应对措施，等于没识别。
❌ 高风险项没有负责人，出问题后无人负责。

评审要点

规则：技术方案评审须聚焦设计合理性与可落地性，评审通过后方可开发。

[Requirement] 评审须至少包含：方案作者、模块负责人、架构师（或资深研发）、测试代表。

[Requirement] 评审结论必须为：通过 / 有条件通过 / 打回，不允许”原则通过”这种模糊结论。

[Standard] 评审前须提前 1 个工作日发出方案文档，评审会聚焦讨论而非宣读。

[Standard] 评审记录须包含：结论、修改项、负责人、截止时间，归档至方案文档末尾。

评审检查清单：

检查项	通过标准
完整性	模板 8 节齐全，无空章节
正确性	接口、数据模型、流程与需求一致
可行性	技术方案可实现，无不可控外部依赖
非功能需求	性能、可用性、安全、可观测性有量化指标
风险	高风险项有缓解措施与负责人
排期	任务拆分合理，估算可信，依赖清晰
可测试性	验收标准可转化为测试用例

评审结论模板：

## 评审记录

评审时间：2024-10-14
评审人：张三、李四、王五、赵六
结论：有条件通过

修改项：
1. [中] 补充支付失败的重试机制设计 — 张三 — 10-15 前
2. [低] 数据库索引设计需补充覆盖查询场景 — 李四 — 10-15 前

验证：以上修改项完成后，由李四确认即视为通过。

反模式：

❌ 评审会变成方案宣讲会，评审人现场才看文档。
❌ 评审结论”原则通过，但有些地方需要改”——哪些地方？谁改？什么时候改完？都不清楚。
❌ 评审只看架构图，不看接口和数据设计，开发时才发现问题。