aps-agent/docs/round-9-contract-gen-plan.md

第 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. 本轮工作方向

手写 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 实现 + 验证 + 收口报告。