games-development-ai/contracts/README.md

contracts/ —— 绘境AI 八类契约单一事实源（Day-0 / M0）

定位：本目录是跨三仓（game-cloud 后端 / game-admin 管理端 / game-studio 产品端）与五工位（WS1-WS5）共享的契约单一事实源。 纪律：任何接口 / 数据结构 / 事件 / SDK 签名变更，先改本目录、再写代码，并通知相关方（见 .agents/skills/contract-first-development.md）。 里程碑：Day-0（6/9 上午）全员锁定下列契约并 git 提交 = M0。锁定后各工位 mock 对方接口并行开发，集中联调 Day11 起。

---

一、八类契约清单与 owner

#	契约	路径	owner（主笔）	消费方
1	API OpenAPI	api-schemas/*.yaml	WS1 lead（全员 review）	前端 mock / 各模块互调
2	DB 迁移	db-schemas/V*.sql	WS1	后端各模块
3	SDK 接口 + postMessage 协议	sdk-interface.d.ts	WS3 SDK 负责人	game-studio 宿主 / 游戏侧
4	GamePackage 清单	game-package.schema.json	WS3 + WS2	生成→编译→预览→发布→运行全链路
5	telemetry 事件	events.schema.json	WS5	前端埋点 / SDK 上报 / 看板
6	Dify workflow I/O	dify-workflow-io.json	WS2	aigc Java 壳 ↔ Dify
7	广告位配置	ad-slot.schema.json	WS5	ad 模块 / SDK Plugin.Ad
8	Prompt Registry	prompts/（独立目录）	各 prompt owner 工位	aigc / 生成链路（见 prompt-governance）

M0 八类契约已锁（JSON/YAML/Schema 语法校验通过）：#1 project.yaml · #2 V1.0.0__…sql · #3 sdk-interface.d.ts · #4 game-package · #5 events · #6 dify-workflow-io · #7 ad-slot · #8 prompts/。 Wave1 脊柱 4 模块契约已补并锁（aigc/runtime/feed/telemetry，2026-06-08）：经契约先行起草 + 一致性评审 + 收口（§2.1）+ 主 agent 校验（YAML 语法/裸 select* 0/错误码段 101-104 独占/Flyway V2-5 唯一）。其余 8 模块（pay/trade/community/ip/compliance/biz/ad）待后续波次补。

contracts/
├── README.md                       # 本文件
├── api-schemas/                    # #1 OpenAPI 3.0（每模块一个 yaml）
│   ├── project.yaml                #   黄金模块 project（已落地）
│   ├── aigc.yaml                   #   Wave1 生成（已锁）
│   ├── runtime.yaml                #   Wave1 预览/试玩/包服务（已锁）
│   ├── feed.yaml                   #   Wave1 游戏流/双轨专区（已锁）
│   └── telemetry.yaml              #   Wave1 遥测/聚合回灌（已锁）
├── db-schemas/                     # #2 Flyway 迁移（本目录=授权源；执行副本在 game-cloud/yudao-server/src/main/resources/db/migration/，Flyway 校验和敏感须保持 diff 一致）
│   ├── V1.0.0__create_game_project.sql
│   ├── V2.0.0__create_game_aigc.sql       # aigc（每模块独占主版本号）
│   ├── V3.0.0__create_game_runtime.sql
│   ├── V4.0.0__create_game_feed.sql
│   └── V5.0.0__create_game_telemetry.sql
├── game-package.schema.json        # #4 GamePackage 清单（已落地）
├── events.schema.json              # #5 telemetry 事件 v1（已落地）
├── sdk-interface.d.ts              # #3 已锁（SDK API + postMessage 协议）
├── dify-workflow-io.json           # #6 已锁（Dify workflow I/O）
├── ad-slot.schema.json             # #7 已锁（广告位配置）
└── prompts/                        # #8 已锁（README + registry.yaml + 01-safety 示例 + 8 阶段）

二、版本与兼容规则（硬约束，来自工程规范 §5）

• API：URL Path 版本，新增字段不算 breaking；删除/重命名字段 = 升版本；旧版本保留 ≥ 3 个月，废弃用 Deprecation: true + Sunset: <date>。
• 事件：每事件带 schema_version（如 game_play_start.v2）；新增字段给默认值、老消费者忽略未知字段；不兼容变更用新事件名并行消费。
• DB：V{版本号}__{描述}.sql；已合入的迁移禁止修改，回滚写新补偿迁移；CI 跑 flyway validate 阻断不合规。
• 契约对齐顺序：后端先写 -api 包的 VO/DTO，前端据此定义 TS 类型。

2.1 跨模块对齐约定（Phase A 评审收口，HJ-BUILD-FIX）

• 两个 qualityScore 不同量纲、不可互相回灌：aigc=生成质量分（0-1，对齐 Dify #6）；telemetry/feed=运营质量分（0-100）。两者来源与计算口径不同，禁止跨模块直接赋值或换算回填。
• game_version.package_url/checksum/bundle_size 权威写者=runtime（编译成功后回写）；aigc 只回填 version_id 与生成元数据，不得写入编译产物字段。
• play_count 权威源=telemetry game_play_start 事件聚合；runtime session 仅作时长/质量观测，不作为播放计数源；sessionId 透传至 telemetry session_id 用于对账。

三、端与鉴权（API 契约共同前提，来自工程规范 §4）

/app-api/**    → 产品端（game-studio），用户 Token + DataPermission（创作者只见自己数据）
/admin-api/**  → 管理后台（game-admin），管理员 RBAC

URL 格式：/{端前缀}/{模块}/{资源}/{动作}。端前缀 /app-api·/admin-api 沿用 yudao 默认，由框架按 controller.app·controller.admin 包名自动添加（Controller 内 @RequestMapping 只写 /{模块}，不含端前缀）。权限在网关 + 注解双重校验，前端不可作为唯一边界。

四、错误码段（每模块独占，来自工程规范 §1.3）

1-{模块段}-{业务}-{细分}：project=100 / aigc=101 / runtime=102 / feed=103 / telemetry=104 / pay=105 / trade=106 / community=107 / ip=108 / compliance=109 / biz=110 / ad=111。新增模块在 -api 错误码常量类登记，禁止重叠。