Genarrative/docs/technical/MATCH3D_Q1_INTEGRATION_ACCEPTANCE_2026-05-01.md

抓大鹅 Match3D Q1 集成验收与收口记录 2026-05-01

1. 本轮目标

Q1 不新增玩法规则，只把第一至第三波已经形成的 Match3D 独立玩法域接成可跑主链：

1. 创作 Agent 前端从本地 mock 切到 api-server HTTP/SSE facade。
2. 结果页从临时草稿承接页升级为可编辑、可保存、可试玩、可发布的作品工作台。
3. 试玩运行态从结果页启动真实 /api/runtime/match3d/* run，并继续保持“前端即时反馈 + 后端权威确认”。
4. 创作中心至少能读取当前用户 Match3D 作品列表，并支持打开草稿继续编辑。

本轮结论：已按合并顺序完成 Q1 主链集成。第一至第三波的主体能力均已落到工程，Q1 已把它们串成“创作 Agent -> 结果页保存/发布/试玩 -> 公开详情/作品号搜索 -> 运行态”的最小可跑链路。

2. 第一至第三波验收口径

第一波 A0

文档已存在：

docs/technical/MATCH3D_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-30.md

结论：已完成。该文档冻结了独立玩法域、表与 procedure、HTTP facade、前端即时反馈协议和合并顺序。

第二波 B1 + B2

已落点：

server-rs/crates/module-match3d/
server-rs/crates/shared-contracts/src/match3d_*.rs
packages/shared/src/contracts/match3d*.ts

结论：已完成。领域 crate、Rust DTO、TypeScript DTO 已存在，并已通过 Q1 定向复跑。

第二波 B3

已落点：

server-rs/crates/spacetime-module/src/match3d/
server-rs/crates/spacetime-module/src/migration.rs

结论：已完成。四张 Match3D 表已纳入 migration，procedure 已接 module-match3d 领域规则。本轮不改表结构，不需要新增 migration。

第二波 F1

已落点：

src/components/match3d-creation/
src/services/match3d-creation/
src/components/platform-entry/

结论：已完成并已接入 Q1。入口与 Agent UI 已存在，match3dCreationClient 已从本地 mock 切到 api-server HTTP/SSE facade；本地 mock 只保留在测试夹具和 /match3d playground 运行调试链路中。

第二波 F3

已落点：

src/components/match3d-runtime/
src/services/match3d-runtime/match3dLocalRuntime.ts
src/Match3DPlaygroundApp.tsx

结论：已完成并已接入 Q1。圆形空间、7 格备选栏、乐观点击、三消反馈、结算面板和回滚校正语义已存在；Q1 已补真实 runtime client 与平台入口接线。

第三波 B4 + B5

已落点：

server-rs/crates/spacetime-client/src/match3d.rs
server-rs/crates/api-server/src/match3d.rs
server-rs/crates/api-server/src/app.rs

结论：已完成。HTTP facade 路由已注册，Q1 前端已按这些稳定路由接入。

第三波 F2

目标落点：

src/components/match3d-result/
src/services/match3d-works/

结论：已完成并已接入 Q1。新增 Match3DResultView 和 match3d-works service，支持基础信息编辑、保存、发布、试玩入口；发布仍要求封面和标签门槛，试玩只要求基础配置可保存。

第三波 F4

结论：已完成 Q1 最小平台分发。创作中心作品货架、公开卡片映射、统一作品详情、M3-xxxxxxxx 作品号搜索和详情页启动运行态已接入；排行榜、点赞、改造统计和更复杂推荐策略仍留到后续优化。

3. Q1 本轮代码落点

本轮实际落点：

1. src/services/match3d-creation/：替换本地 mock 为 HTTP/SSE facade。
2. src/services/match3d-works/：新增作品读取、保存、发布 service。
3. src/services/match3d-runtime/：新增真实运行态 service，保留本地 playground mock。
4. src/components/match3d-result/：新增结果页组件。
5. src/components/platform-entry/：串起结果页、试玩 run、作品列表刷新。
6. src/components/custom-world-home/ 与展示映射：扩展 Match3D 作品货架、公开卡片、统一详情页。
7. src/services/publicWorkCode.ts 与 src/routing/appPageRoutes.ts：新增 M3-xxxxxxxx 作品号与公开详情路由识别。
8. src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx：补齐 Match3D 作品号搜索启动运行态回归，并同步统一详情页后的 RPG/Big Fish 旧测试语义。

4. 验收命令

本轮已通过：

npm test -- src/components/match3d-result/Match3DResultView.test.tsx src/components/match3d-runtime/Match3DRuntimeShell.test.tsx src/routing/appPageRoutes.test.ts src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/custom-world-home/CustomWorldCreationHub.interaction.test.tsx src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx --reporter=verbose --silent

结果：6 passed，65 passed。

cargo test -p module-match3d
cargo test -p shared-contracts
cargo check -p api-server
cargo check -p spacetime-client
npm run check:encoding

结果：

1. module-match3d：7 passed。
2. shared-contracts：47 passed。
3. api-server：cargo check 通过。
4. spacetime-client：cargo check 通过。
5. 编码检查：2804 file(s) 通过。

5. 本轮不做与遗留风险

1. 不改 Match3D 表结构。
2. 不扩展排行榜、点赞、二次创作统计。
3. 不把 Match3D 公开广场并入更复杂的推荐、排行和运营榜单策略。
4. 不删除 /match3d 本地 playground；它作为开发调试入口继续保留。
5. 全量 npm run typecheck 曾存在非 Match3D 既有阻塞，本轮以 Q1 定向测试和后端定向检查作为集成验收口径。
6. 运行态仍依赖当前 SpacetimeDB 环境稳定性；如 npm run api-server 现场遇到订阅 HTTP 500，应按本地 SpacetimeDB 联调链路单独排查。