# 编码方案范本

创建人员：Codex  
文件职责：提供一份重型开发编码方案的参考范本，帮助 AI 理解方案应如何写；本文件不是必须复制的模板。  
管理规范/模板：编码规范.md；开发审计规范.md。  
引用文件：开发事项总纲.md；开发事项计划.md；开发执行日志.md；对应审计报告入口；开发问题记录.md。  
记录方式：参考范本；编码方案写法出现重大调整时更新。

## 1. 使用口径

默认开发体系不创建空的 `编码方案.md`。重型开发发生时，才在对应开发文档目录下按事项创建具体编码方案文件，例如 `开发方案/<CODE-DESIGN-ID>.md`。

本文件只提供参考写法。真正必须遵守的编码方案要求，以 `编码规范.md` 中“代码编写方案必须包含的内容”为准。

轻量开发可以不写完整编码方案。重型开发必须先写方案，并经过审核员审核通过后才能进入编码。

## 2. 范本：某模块链路编码方案

### 2.1 方案目标

本方案用于某个 P0~P3 多模块链路进入代码实现前的编码收口。

目标：

1. 以正式需求文档为唯一合同来源。
2. 先实现可闭环、可测试、可复算的最小链路。
3. 把跨模块公共合同下沉为薄 helper，避免多个模块重复实现 manifest、compare、JSON 校验、稳定 ID 等逻辑。
4. 每个阶段实现后都能用 targeted test 或最小 smoke 验证，不靠最终大流程一次性发现问题。

### 2.2 正式依据

正式实现依据：

1. 需求文档 A。
2. 需求文档 B。
3. 接口合同文档。
4. 数据格式或公共字段文档。

编码时以正式需求文档为主源；历史文档、镜像文档、聊天讨论只能作为背景，不作为第二套合同。

### 2.3 当前需求状态判断

当前需求是否具备编码基础：

1. 输入、输出、主键、枚举、状态已冻结。
2. 模块职责和接口边界已清楚。
3. 必过验收项和只读诊断项已分清。
4. 未决问题已记录，不影响最小链路编码。

如果上述条件不满足，应先回到需求修订，不要靠代码猜。

### 2.4 不做事项

本轮不做：

1. 不引入需求文档之外的正式输出字段。
2. 不提前接入未启用的下游主链。
3. 不设计新的大而全 validator。
4. 不做无证据的性能专项优化。
5. 不把只读诊断 helper 变成主流程阻断 gate。

不做事项要明确写出来，避免编码阶段范围膨胀。

### 2.5 建议代码文件

新增实现文件：

1. `dev/<target>-dev/common_v1.py`
2. `dev/<target>-dev/module_p0_v1.py`
3. `dev/<target>-dev/module_p1_v1.py`
4. `dev/<target>-dev/module_p2_v1.py`

新增测试文件：

1. `dev/<target>-dev/test/test_common_v1.py`
2. `dev/<target>-dev/test/test_module_p0_v1.py`
3. `dev/<target>-dev/test/test_minimal_chain_v1.py`

### 2.6 公共 helper 范围

公共 helper 只做 normalize / validate / bind，不持有具体业务语义。

第一批公共 helper：

1. `parse_json_object(value, field_name)`：解析 JSON object，非法输入 fail-fast。
2. `parse_json_array(value, field_name)`：解析 JSON array，统一输出格式。
3. `write_compare_report(path, rows)`：固定 compare report 字段。
4. `write_output_manifest(path, artifacts)`：统一输出文件、主键、row_count、hash、ready_flag。
5. `stable_object_id(kind, parts)`：封装稳定 ID 生成。

公共 helper 只在至少两个模块共用时保留；若只服务单模块，先放在对应模块私有函数里。

### 2.7 分阶段实现顺序

阶段 A：公共合同层

1. JSON 读写。
2. manifest 写出。
3. compare report 写出。
4. 稳定 ID 生成。
5. 公共负例测试。

阶段 B：P0 基础模块

1. 输入校验。
2. 特征或基础表输出。
3. summary、manifest、compare 输出。
4. 最小正例和缺字段反例测试。

阶段 C：P1 业务候选模块

1. 读取 P0 输出。
2. 执行候选扫描或路由。
3. 输出候选表和候选簇。
4. 验证不读取禁止字段、不删除应保留候选。

阶段 D：P2 合成或确认模块

1. 读取 P1 输出。
2. 生成确认结果、周期结果或最终中间表。
3. 保证主键、边界、状态和 row_count 可审计。

阶段 E：最小链路 smoke

1. P0 -> P1 -> P2 串联。
2. 校验所有关键输出存在且 schema 合法。
3. 校验失败输入会 fail-fast。

### 2.8 fail-fast / fail-closed 口径

以下情况必须失败，不得静默跳过：

1. 必需输入文件不存在。
2. 必需字段缺失。
3. 主键重复。
4. JSON 字段无法解析。
5. 枚举值非法。
6. 必需输出缺失。
7. summary 写 PASS 但必过 compare 未通过。

失败时应输出可定位的问题说明；已生成的中间产物必须如实标记，不得伪装成完成文件。

### 2.9 编码注意点

1. 不在业务模块里重复实现 manifest、compare、JSON 校验。
2. 不新增需求未定义的 formal 输出字段。
3. 不为了测试方便绕过 ID 合同。
4. 不把背景讨论当成正式业务规则。
5. 不把诊断项升级成主流程阻断项。
6. 不让半成品文件被后续流程误用。

### 2.10 验收命令建议

先跑公共测试：

```powershell
python -m unittest dev.<target>-dev.test.test_common_v1
```

再跑模块测试：

```powershell
python -m unittest dev.<target>-dev.test.test_module_p0_v1
python -m unittest dev.<target>-dev.test.test_module_p1_v1
```

最后跑最小链路：

```powershell
python -m unittest dev.<target>-dev.test.test_minimal_chain_v1
```

若任何模块测试失败，不进入下一阶段扩展。

### 2.11 关闭标准

开发完成必须满足：

1. 每个模块有可调用入口。
2. 每个模块合法最小样本 PASS。
3. 每个模块至少覆盖一个 fail-fast 负例。
4. 最小链路 smoke 通过。
5. 输出字段、枚举、主键、ID、manifest、compare 与需求文档一致。
6. 开发执行日志和对应审计报告入口已记录结论。