4.3 KiB
L2 技术方案设计
每个子任务一份文档
每个子任务只创建一份：
02.技术实现方案.md
该子任务的全部功能、接口、CRUD、消息、回调、定时任务、批处理和数据模型设计都写在同一文档内。除非用户明确要求，不得拆成多个功能方案文件。使用目录、编号标题、功能编号和接口总览表管理长文档。
设计流程
读取已确认的 01
→ 确认需求版本和代码基线
→ 调查现有实现和测试
→ 识别复用和约束
→ 设计总体流程
→ 设计每个功能和接口
→ 设计数据模型和一致性
→ 分析影响与回归
→ 设计实施顺序和验证
→ 更新 STATUS
设计中发现业务规则缺失或矛盾时，将受影响内容退回需求分析。
文档结构
# ST-XXX 技术实现方案
## 目录
## 1. 文档信息、依据和版本
## 2. 目标、范围和验收依据
## 3. 现有实现与复用分析
## 4. 总体实现方案
## 5. 功能点和接口总览
## 6. 各功能点实现方案
## 7. 数据模型设计
## 8. 跨工程改造与依赖顺序
## 9. 变更影响与回归范围
## 10. 权限、安全、事务、并发和幂等
## 11. 非功能、日志、监控和审计
## 12. 兼容、迁移、发布和回滚
## 13. 测试与验证设计
## 14. 实施步骤
## 15. 方案取舍、风险和待确认项
## 16. 需求追溯
确实不适用的章节写明原因，不得机械填充。
每个功能必须有方案
每个 F-XXX 都要说明：
- 目标及需求/验收依据；
- 涉及工程和模块；
- 现有实现、可复用符号及 Commit 证据；
- 新增、修改、复用和非范围；
- 正常、异常和适用的边界流程；
- 接口、请求、响应、错误码和权限；
- 业务校验；
- 数据读写；
- 事务、一致性、并发和幂等；
- 缓存、搜索和消息行为；
- 兼容性；
- 测试和验证；
- 风险与待确认项。
简单 CRUD 也必须提供精简方案，至少覆盖校验、唯一性、分页/筛选、删除语义、权限、数据影响、适用的幂等和冒烟验证。
数据模型设计
发生任何数据模型变化时，在同一文档第 7 节设计。
数据库
说明实体含义、表、字段类型/可空/默认值、主键、约束、索引及查询依据、关系、枚举、审计/逻辑删除、容量、DDL、历史迁移、兼容、发布和回滚。
Redis
说明 Key 规则、数据类型和值结构、事实数据源、TTL、读写时机、更新/失效、未命中/空值、原子性、并发、热 Key/大 Key 风险和旧 Key 清理。
Elasticsearch
说明索引/Alias、文档 ID 和示例、Mapping/分词、适用的分片/副本/Routing、查询场景、数据库到 ES 的同步、延迟目标、重试修复、Reindex、历史初始化、Alias 切换和回滚。
跨存储一致性
明确事实数据源、写入顺序、事件或 CDC 链路、缓存失效、ES 同步、幂等、重试/补偿、对账和失败行为。
没有数据模型变化时，也要写明并指出复用依据。
影响与回归
每个被修改的接口或功能都要调查：
- 上游调用方和下游依赖；
- 复用同一核心方法的其他接口；
- 共享数据库表、Redis Key 和 ES 文档；
- 消息、消费者、任务、报表、导入导出；
- 前端、客户端和外部集成；
- 权限、状态流转、监控和发布顺序。
影响分类：直接、间接、兼容、数据、行为、性能、发布、潜在或已验证无影响。
维护：
| 影响编号 | 变更项 | 受影响接口/功能 | 工程 | 类型 | 说明 | 是否改造 | 回归级别 |
|---|
以及：
| 回归编号 | 工程 | 接口/功能 | 回归场景 | 原因 | 优先级 |
|---|
禁止写“回归相关功能”等模糊描述。必须列出具体场景。“无影响”也要写明检查过的调用链和数据链证据。
影响超出已确认范围时，记录后果和选项并请用户确认，不得静默扩大范围。
追溯与 G2
建立：
需求 → F-XXX → 方案章节 → 涉及工程 → AC-XXX → TC-XXX 验证用例
02.技术实现方案.md 和 03.冒烟与逻辑验证.md 的验证计划部分完成后，一起提交 G2；确认前不得开始实现。