lili 7bd9cd05e6 docs(governance): Phase7 收口——治理门反转 + 源档归档 + 入口对账 + 死链门

设计文档域化重构总收口:
- §10 治理门反转(engineering-conventions §10.5/10.6/10.7):canonical 根从 agent-specs 改为 docs/architecture 6 域树;品牌门白名单加 architecture/_archive。
- 归档 11 settled 源档(7 根 architecture + 4 非生成 agent-specs canonical)→ 各自 _archive(git mv 保 history + tombstone redirect)。生成域设计链过渡期保留(架构演进中)。
- rewire 17 个活层文件(.agents/knowledge|rules|skills + docs/mvp + AGENTS.md + 新树)指向新树路径;活层零残留旧 canonical 路径。
- AGENTS.md §4 必读表/§3.2 目录树/§3.3-3.4 指针 → 新树;_index.md 瘦身为 trace/spike + 生成域演进链 + 修 line22↔40 自相矛盾。
- 新增死链门 .agents/tools/check-deadlinks.sh(§10.7 死链项的可执行脚本)。
- 全门齐跑:死链 0 / 新树无旧品牌 / 无超 2000 行 / 活层无残留。

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2026-06-20 20:48:38 -07:00

6.0 KiB

Raw Blame History

契约先行与并行解耦联调手册（contract-first-development）

蒸馏来源：docs/superpowers/specs/mvp-execution-spec-design.md（§3 契约先行 / §6 并行解耦与 Mock / §8.3 联调规则）、docs/architecture/架构/README.md（§6 联调协议）、docs/architecture/架构/README.md（§7.7 API 契约与版本）。适用：多工位（前端/后端/SDK/AI/数据）并行开发同一交付时，先锁契约、再各自 mock 解耦、最后集中联调。配套：工程规范（错误码/API 路径/-api 包）见 ../rules/engineering-conventions.md；新模块契约落地见 ./add-business-module.md；生成链路契约见 ./ai-generation-pipeline.md；SDK 契约见 ./runtime-and-multichannel.md；任务协议见 ../workflows/ai-development-protocol.md。

目标

Day0（开发首日）半天全员锁定契约，写入 contracts/ 并提交 git；之后各工位基于契约 mock 对方接口独立开发，集中联调在 Day11 开始。把"等对方接口"的串行依赖，换成"对着契约并行"。

前置

已读 ../knowledge/product-and-architecture.md，对齐 13 模块边界与端（/app vs /admin）。
工位划分明确（MVP spec：WS1 基座 / WS2 AI / WS3 运行时+SDK / WS4 前端 / WS5 数据变现）。

1. 理念

Day0 上午（半天）：全员对齐 → 锁定 7 个 Day-0 契约文件 → 提交 git（里程碑 M0）
       ↓
Day1~Day10：各工位基于契约 mock 对方接口，独立并行开发
       ↓
Day11~Day12：集中联调（只联调、不加功能）

契约体系共 8 类契约：下列 7 个 Day-0 contracts/ 文件 + Prompt Registry（contracts/prompts/ 目录）为第 8 类（见 ./prompt-governance.md）。本手册聚焦 Day-0 锁定的 7 个文件。

契约一旦锁定即为各工位的"对接面"。变更契约必须同步 contracts/ 并通知相关方（见第 4 节）。

2. 7 个 Day-0 契约文件清单（第 8 类 Prompt Registry 见 prompt-governance.md）

契约文件	内容	负责人
`contracts/api-schemas/*.yaml`	所有模块 API 的 OpenAPI 3.0 定义（Request/Response）	WS1 lead 主笔，全员 review
`contracts/db-schemas/V1__*.sql`	核心表结构（Flyway 迁移脚本）	WS1
`contracts/sdk-interface.d.ts`	WanxiangGameSDK 全部 public API 类型 + postMessage 协议	WS3 SDK 负责人
`contracts/game-package.schema.json`	GamePackage manifest 格式 + 目录结构	WS3 + WS2
`contracts/events.schema.json`	telemetry 事件名 + 字段（v1）	WS5
`contracts/dify-workflow-io.json`（⚠️ 降级远期未部署，见 `contracts/DEPRECATED-dify-workflow-io.md`；现行生成主线=new-api 网关）	Dify workflow 的输入/输出契约	WS2
`contracts/ad-slot.schema.json`	广告位配置格式	WS5

3. Mock 策略表

工位	依赖谁	Mock 方式	真实对接时间
WS4 前端	WS1/WS2/WS3/WS5 的 API	`vite-plugin-mock` 基于契约 yaml 自动生成	Day6 起逐步替换
WS3 SDK	WS4（宿主）	独立测试页模拟 postMessage	Day6 集成
WS2 aigc	WS1（project）	内存态写入 + MQ mock	Day5 真实对接
WS5 telemetry	WS3（SDK 上报）	curl 模拟 `/events/batch`	Day6 真实对接

4. 真实对接切换

场景	做法
前端 mock → 真实 API	改 `.env` 中 `VITE_API_BASE_URL` 即可（开发团队版 §6.1，MVP spec §8.3）
后端新增/变更 API	必须同步 `contracts/api-schemas/` 并通知前端（MVP spec §8.3）
契约定义顺序	后端先写 `-api` 包的 VO/DTO，前端据此定义 TS 类型（开发团队版 §6.1）

API 演进规则：新增字段不算 breaking；删除/重命名字段 = 升版本（技术决策版 §7.7）。

5. 联调规则

规则	说明	出处
时间窗	Day11~Day12 预留 2 天，只联调不加新功能	MVP spec §6.3
主导与响应	前端主导提 bug，后端 30 分钟内响应	MVP spec §6.3
Bug 优先级	P0 当天必修；P1 联调期内修复	MVP spec §6.3
阻塞升级	阻塞 > 30 分钟立即升级到每日站会	MVP spec §6.2 / §8.3
每日站会	每天 10:00，每人 2 分钟（昨天/今天/阻塞点）	MVP spec §6.2
问题跟踪	联调 bug 提 Issue，打标签 `联调` + 模块名	开发团队版 §6.1

6. 联调速查

观察点	地址 / 工具
后端 API 文档	Swagger / Knife4j `http://localhost:48080/doc.html`
生成链路日志	~~Dify UI `http://localhost:3001`~~（已降级远期未部署）→ 现行=编排器批跑日志 `docs/agent-specs/2026-06-09-agent-loop-v1/orchestrator/` + new-api 网关 `http://100.64.0.8:3000`
SDK 事件流	game-studio 开发模式 DebugPanel（实时 postMessage 事件流，开发团队版 §6.3）

7. 常见坑

坑	后果	应对
契约偏差到联调才暴露	Day11 集中爆雷、返工	WS1 在 Day10 预留时间专门修对接时发现的契约偏差（MVP spec §4 Week1 Day10）；前端 Day6 起提前对接早暴露
契约变更未同步	前后端字段不一致、联调失败	任何 API 增改先改 `contracts/` 再写代码，并通知相关方（MVP spec §8.3）
前端先于 `-api` 定 TS 类型	与后端 VO/DTO 错位	顺序固定：后端 `-api` VO/DTO 先行 → 前端据此定 TS（开发团队版 §6.1）
mock 与真实响应结构不一致	切真实 API 后页面崩	mock 严格依据契约 yaml 生成，不手捏假数据
阻塞硬扛不升级	拖垮整条链路进度	阻塞 > 30 分钟必升级站会，会后 10 分钟两人对齐（MVP spec §6.2）

6.0 KiB Raw Blame History Unescape Escape