# 第 9 轮工作计划（轻量合并版）：契约生成自动化与差异检查门禁

更新日期：2026-08-01

## 1. 本轮目标

新增契约生成器：从 `shared/schemas/*.json` 自动生成 TypeScript 类型声明（interface + literal union），并新增黄金门禁测试锁定「生成结果 ↔ schema ↔ 手写 `apps/web/src/api/types.ts`」三方一致；矩阵 117 行剩余「契约生成自动化（schema → pydantic/TS）」落地，漂移直接失败。

## 2. 背景和当前状态

- 当前已完成：`test_contract_sync.py` 已校验全部 7 个 schema 的字段/必填/枚举与 Python 模型/TS literal union 一致；schema 清单门禁与不兼容消费者测试（第 2 轮）；文档漂移门禁（第 7 轮）。
- 当前缺口：无「从 schema 生成 TS 类型」的自动化脚本；手写 types.ts 与 schema 的一致性靠测试校验，但没有可复用的生成器。
- 本轮为什么现在做：矩阵 117 行剩余验收「契约生成自动化（schema → pydantic/TS）」；纯本地、低风险。
- Workspace preflight：第 8 轮收口（457 passed）；服务 8003/5173 正常；共享脏工作区、无提交。
- 方向分析：Q1 推荐选项 C（契约生成自动化），目标续跑轮授权执行。

## 3. 本轮工作方向

```text
手写 types.ts + schema（7 个契约）
-> scripts/generate_contract_types.py：schema → TS interface/literal union 生成器
-> 黄金门禁：生成结果 ↔ schema 必填/枚举/字段 ↔ 手写 types.ts 一致，漂移失败
-> 矩阵 117 行剩余项收口；CHANGELOG
```

## 4. 已确认决策

任务重量：
- 档位：轻型（生成器脚本 + 黄金测试 + 文档）。
- 规模依据：新增独立脚本与测试，不改生产代码路径；风险 LOW。
- 选择原因：矩阵明确剩余项；生成器是契约一致性的可复用工具。

P0/P1 决策（按 Q1 推荐采纳）：
- 决策 1（P0）：本轮切片 = 契约生成自动化与差异检查门禁（选项 C）。
- 决策 2（P1）：不新建分支、不提交、不推送。
- 决策 3（P1）：验证深度 = 聚焦生成门禁测试 + 全量黄金回归。

默认假设：
- 假设 1：生成器以 schema 为权威源，输出 TS 声明文本（interface + 简单 literal union），覆盖 7 个 schema 的字段/必填/枚举。
- 假设 2：手写 types.ts 是「经人工打磨的规范类型」，门禁要求生成结果的关键面（字段集合/必填集合/枚举集合）与手写一致；字段可选性以手写为准（schema 缺省可选的接口版本字段等兼容处理）。
- 假设 3：生成器不覆盖手写 types.ts（不自动改写），只提供可执行生成 + 差异报告，供人工采用。

未决但不阻塞：pydantic 端自动生成、JSON Schema → 复杂嵌套类型（objects/arrays）完整支持（后续轮）。

## 5. 范围

In scope:
- `scripts/generate_contract_types.py`（新）：读 `shared/schemas/*.json`，生成 `interface <Title>` 与 `type <Title>Xxx` 声明文本（字段、必填标记、枚举、基础类型映射）。
- `tests/golden/test_contract_generation.py`（新）：对每个 schema 调用生成器，断言生成文本含 schema 字段/必填/枚举；与手写 types.ts 的关键面 diff（生成的关键枚举/字段集合 ⊆ 手写，且手写关键面 ⊆ schema）。
- 文档：`docs/product/plan-completion-matrix.md`（117 行注记）、`docs/CHANGELOG.md`。

Out of scope:
- 自动改写 types.ts、pydantic 生成、复杂嵌套类型完整生成。
- 提交/推送/合并/清理用户改动。

## 6. 成功标准

- 聚焦：`python -m pytest -q tests/golden/test_contract_generation.py -p no:cacheprovider` 通过（≥4 项）。
- 全量：`python -m pytest tests/golden -q -p no:cacheprovider`（固定 .venv）≥ 457。
- ruff 干净；脚本可执行（`python scripts/generate_contract_types.py` 无异常）。

## 7. 验证方式

- 生成器单测（确定性、schema 驱动、字段/枚举覆盖）；门禁 diff 测试；全量回归。

## 8. 关键风险

| 风险 | 影响 | 控制方式 |
|---|---|---|
| 生成器对复杂 schema 支持不足 | 断言脆弱 | 只断言字段/必填/枚举关键面，类型映射宽松 |
| 手写 types.ts 与 schema 存在合法差异 | 误报漂移 | 兼容字段（interfaceVersion 可选等）显式豁免 |
| 生成文本格式漂移 | 测试不稳 | 断言用集合比较而非全文匹配 |

## 9. 停止条件

- 全量黄金测试非本轮相关回归无法快速定位时暂停。
- 任何提交/推送/合并/清理操作停下等待授权。

## 10. 本轮完成定义

- 生成器、门禁测试、矩阵/CHANGELOG 回写完成；聚焦与全量通过；不提交。
- 收口：报告主要结论、关键洞察、需要特别留意的地方。

## 11. 下一步

轻量合并版：主 agent 实现 + 验证 + 收口报告。