# L2 技术方案设计

## 每个子任务一份文档

每个子任务只创建一份：

```text
02.技术实现方案.md
```

该子任务的全部功能、接口、CRUD、消息、回调、定时任务、批处理和数据模型设计都写在同一文档内。除非用户明确要求，不得拆成多个功能方案文件。使用目录、编号标题、功能编号和接口总览表管理长文档。

## 设计流程

```text
读取已确认的 01
→ 确认需求版本和代码基线
→ 调查现有实现和测试
→ 识别复用和约束
→ 设计总体流程
→ 设计每个功能和接口
→ 设计数据模型和一致性
→ 分析影响与回归
→ 设计实施顺序和验证
→ 更新 STATUS
```

设计中发现业务规则缺失或矛盾时，将受影响内容退回需求分析。

## 文档结构

```markdown
# 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

建立：

```text
需求 → F-XXX → 方案章节 → 涉及工程 → AC-XXX → TC-XXX 验证用例
```

`02.技术实现方案.md` 和 `03.冒烟与逻辑验证.md` 的验证计划部分完成后，一起提交 G2；确认前不得开始实现。