契约先行与并行解耦联调手册（contract-first-development）
蒸馏来源：docs/superpowers/specs/mvp-execution-spec-design.md（§3 契约先行 / §6 并行解耦与 Mock / §8.3 联调规则）、docs/architecture/系统概要设计-开发团队版.md（§6 联调协议）、docs/architecture/系统概要设计-技术决策版.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 开始。把"等对方接口"的串行依赖，换成"对着契约并行"。
前置
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） |
