# 第 2 轮工作计划（轻量合并版）：契约漂移门禁补全

更新日期：2026-08-01

## 1. 本轮目标

把三个公共排产契约（`scheduling_problem.schema.json` / `scheduling_solution.schema.json` / `plan_node.schema.json`）纳入 `tests/golden/test_contract_sync.py` 的跨层契约校验链（schema ↔ Python DTO ↔ 消费方），并增加不兼容消费者测试与文档清单门禁；矩阵 M0「跨层契约和文档同轮同步」由 Partial 升为 Done。

## 2. 背景和当前状态

- 当前已完成：`test_contract_sync.py` 已覆盖 `intent`/`ui_block`/`viewport_command`/`schedule_result` 四个契约的三方一致性（schema 枚举/必填 ↔ pydantic ↔ TS literal union），并有 InterfaceGate 启动握手测试；`scheduling_problem`/`scheduling_solution` 的 Python 模型在 `server/aps_domain/scheduling_dto.py`，`plan_node` 的模型在 `server/agent_core/plan_runtime.py`（PlanLayer/PlanStatus/PlanCreator 枚举与 schema 一致，字段集合一致）。
- 当前缺口：三个公共排产契约未进入校验链；无"不兼容消费者"回归测试；无文档清单门禁（docs/README.md 目录与契约文件的对应关系无自动化检查）。
- 本轮为什么现在做：矩阵 P0 批次点名「三层契约漂移门禁已有可运行首切片」，剩余验收标准为"增加契约生成/差异检查和文档清单门禁，漂移直接阻断合并"。
- Workspace preflight：第 1 轮（证据链 v1）已收口（425 passed / 审计 PASS）；共享脏工作区、无提交。
- 方向分析：Q1 推荐选项 C（契约漂移门禁），目标续跑轮授权执行。

## 3. 本轮工作方向

```text
test_contract_sync.py（4 契约覆盖）
-> 扩展校验链：scheduling_problem / scheduling_solution / plan_node（schema ↔ Python DTO ↔ 消费方）
-> 不兼容消费者测试：Schema 漂移（删字段/改枚举）→ 校验失败
-> 文档清单门禁：docs/README.md 契约目录 ↔ shared/schemas/*.json 一一对应
-> 全量黄金测试 + 矩阵 M0 行 → Done
```

## 4. 已确认决策

任务重量：
- 档位：轻型（单测试域：test_contract_sync.py + docs/README.md；集成点唯一：黄金测试）。
- 规模依据：核心改动集中在 `tests/golden/test_contract_sync.py` 与 `docs/README.md`；无生产代码行为变化，风险 LOW。
- 选择原因：纯门禁/测试工程，直接服务 P0 批次验收出口「契约三方一致」。

P0/P1 决策（按 Q1 推荐采纳）：
- 决策 1（P0）：本轮切片 = 契约漂移门禁补全（选项 C）。
- 决策 2（P1）：不新建分支、不提交、不推送（沿用共享脏工作区约束）。
- 决策 3（P1）：验证深度 = 聚焦 test_contract_sync + 全量黄金回归。

默认假设：
- 假设 1：`scheduling_problem`/`scheduling_solution` 的 TS 消费方 = `apps/web/src/skills/SkillConsole.tsx` 只读展示（不做强类型消费），因此校验重点为 schema ↔ Python DTO 一致 + 网关契约端点返回可用。
- 假设 2：`plan_node` 消费方 = `server/agent_core/plan_runtime.py`（模型）与 `server/gateway/plan_api.py`（API），TS 无独立类型，校验 schema ↔ Python 模型一致。
- 假设 3：不兼容消费者测试用「schema 漂移注入」模拟：删除/改名 schema 字段或枚举 → 断言校验函数检测到漂移。

未决但不阻塞：契约生成自动化（从 schema 生成 pydantic/TS）留待后续轮次，本轮先做差异检查门禁。

## 5. 范围

In scope:
- `tests/golden/test_contract_sync.py`：新增三个契约的 schema↔Python 校验（字段集合、必填、枚举）、网关契约端点冒烟、不兼容消费者（漂移注入）测试。
- `docs/README.md`：文档清单门禁（列出全部 shared/schemas 契约与对应消费方文档）；必要时补一个 `docs/product/contracts.md` 或复用现有文档。
- `docs/product/plan-completion-matrix.md`：M0 契约行 Partial → Done。
- `docs/CHANGELOG.md`：追加本轮条目。

Out of scope:
- 契约生成器（schema → pydantic/TS 自动生成）；前端强类型化三个契约；任何生产代码行为变化。
- 提交/推送/合并/清理用户改动。

## 6. 成功标准

- `python -m pytest -q tests/golden/test_contract_sync.py -p no:cacheprovider` 全部通过（原 6 项 + 新增）。
- 全量 `python -m pytest tests/golden -q -p no:cacheprovider`（固定 .venv 运行时）通过，≥ 425。
- `python -m ruff check` 改动文件干净。
- `git diff --check` 无空白错误；`git status` 仅本轮文件。

## 7. 验证方式

- 聚焦：`python -m pytest -q tests/golden/test_contract_sync.py -p no:cacheprovider`
- 回归：全量黄金套件。
- 静态：ruff + git diff --check。

## 8. 关键风险

| 风险 | 影响 | 控制方式 |
|---|---|---|
| 三个契约存在真实漂移导致新测试失败 | 需要修复模型/schema | 先核对再断言；漂移修复限定契约文件 |
| SkillConsole 只读展示被误判为消费方 | 校验范围偏差 | 明确 TS 侧为展示型消费，校验 schema↔Python 为主 |
| 文档清单门禁误伤 | 无关文档改动触发失败 | 门禁只检查契约目录 ↔ docs 映射，不做全量文档校验 |

## 9. 停止条件

- 全量黄金测试出现非本轮相关回归且无法快速定位时暂停。
- 任何需要提交/推送/合并/清理用户改动的操作一律停下等待授权。

## 10. 本轮完成定义

- 实现、测试、审计、文档全部完成；聚焦与全量验证通过；矩阵与 CHANGELOG 回写；不提交。
- 收口：向用户报告主要结论、关键洞察、需要特别留意的地方。

## 11. 下一步

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