Genarrative/docs/technical/MATCH3D_SPACETIME_CLIENT_AND_API_FACADE_2026-04-30.md

抓大鹅 Match3D B4+B5 spacetime-client 与 api-server facade 落地记录

日期：2026-04-30

1. 本阶段目标

本文件记录 B4+B5 的技术落地范围：把 B3 已生成的 Match3D SpacetimeDB procedure 接到 spacetime-client，再通过 api-server 暴露给前端使用的 HTTP facade。

本阶段不改 SpacetimeDB 表结构，不新增 migration，不接入真实题材素材生成，也不改前端即时反馈实现。

2. 已落地范围

2.1 SpacetimeDB bindings

使用仓库封装脚本重新生成 bindings：

npm run spacetime:generate

Windows 下 SpacetimeDB CLI 可能在 Rust bindings 已生成后输出 Could not format generated files: 文件名或扩展名太长。 (os error 206)。脚本已调整为：当 CLI 退出码为 0 且只是格式化警告时继续同步生成文件。

生成文件仍视为机器产物，禁止手写修改。

2.2 spacetime-client facade

新增：

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

并在 spacetime-client/src/lib.rs 导出 match3d 模块与 Match3D Record 类型。

已覆盖：

1. 创作会话：create / get / submit message / finalize / compile draft。
2. 作品：list / get detail / update / publish / delete / public gallery list。
3. 运行态：start / get / click / stop / restart / time-up。

mapper.rs 负责把 procedure 返回的 JSON 字符串解析为稳定 Record，不把 generated bindings 泄露到 api-server。

2.3 api-server HTTP facade

新增：

server-rs/crates/api-server/src/match3d.rs

并在 main.rs 注册模块，在 app.rs 挂载路由。

已挂载路由：

POST /api/creation/match3d/sessions
GET  /api/creation/match3d/sessions/{session_id}
POST /api/creation/match3d/sessions/{session_id}/messages
POST /api/creation/match3d/sessions/{session_id}/messages/stream
POST /api/creation/match3d/sessions/{session_id}/actions
POST /api/creation/match3d/sessions/{session_id}/compile

GET    /api/creation/match3d/works
GET    /api/creation/match3d/works/{profile_id}
PATCH  /api/creation/match3d/works/{profile_id}
PUT    /api/creation/match3d/works/{profile_id}
DELETE /api/creation/match3d/works/{profile_id}
POST   /api/creation/match3d/works/{profile_id}/publish

GET  /api/runtime/match3d/gallery
POST /api/runtime/match3d/works/{profile_id}/runs
GET  /api/runtime/match3d/runs/{run_id}
POST /api/runtime/match3d/runs/{run_id}/click
POST /api/runtime/match3d/runs/{run_id}/stop
POST /api/runtime/match3d/runs/{run_id}/restart
POST /api/runtime/match3d/runs/{run_id}/time-up

api-server 返回 shared-contracts 中的 Match3D DTO，前端不需要感知 SpacetimeDB 内部 JSON 快照结构。

3. 创作 Agent 当前口径

B5 首版先采用确定性配置抽取，不在本阶段新增真实 LLM prompt。

2026-05-01 起，抓大鹅创作入口必须按三轮 Agent 问答收集配置，不能在用户未回答前用默认值生成“已确认”回复：

1. POST /api/creation/match3d/sessions 创建会话后，首条 assistant 消息固定为“你想创作什么题材”。
2. 用户第一轮回复只写入题材，assistant 继续问“需要消除多少次才能通关”。
3. 用户第二轮回复只写入需要消除次数，assistant 继续问“如果难度是从1-10，你要创作的关卡是难度几”。
4. 用户第三轮回复写入难度后，assistant 才返回“已确认：...”，并把进度推进到 100、stage 推进到 ReadyToCompile。
5. SpacetimeDB 当前配置快照仍要求合法数值，因此 api-server facade 可以在 config_json 内保留兜底合法值，但回复、进度和是否允许生成结果页必须以三轮问答进度为准。
6. match3d_compile_draft 动作只能在三项收集完成后调用 SpacetimeDB compile_match3d_draft，生成 draft work profile。

后续若要接真实 LLM turn，应复用现有创作 Agent 公共编排，并保持 submit/finalize 两阶段职责不变。

4. 运行态确认协议

B5 保持 PRD 调整后的边界：

1. 前端负责点击、飞入、入槽、三消、腾格、胜负等即时表现。
2. 后端通过 click_match3d_item、finish_match3d_time_up 等 procedure 做权威确认。
3. HTTP response 会把 SpacetimeDB Accepted / VersionConflict / RunFinished 等状态归一到前端 shared contract 可消费的 accepted / rejectReason / run 结构。
4. snapshotVersion 继续作为前端即时反馈和后端确认之间的版本校验字段。

5. shared contract 对齐

本阶段补齐 Rust shared contract 与 TypeScript contract 的已知差异：

1. Match3DAgentSessionSnapshotResponse 增加 anchorPack。
2. Match3DResultDraftResponse 增加 profileId / summaryText / totalItemCount，同时保留 summary 兼容结果页读取。
3. PutMatch3DWorkRequest 增加可选 themeText，结果页可编辑题材；旧请求缺省时 API 会沿用已有作品题材。

6. 验收命令

本阶段至少执行：

cargo check -p spacetime-client --manifest-path server-rs\Cargo.toml
cargo check -p api-server --manifest-path server-rs\Cargo.toml
cargo test -p shared-contracts match3d --manifest-path server-rs\Cargo.toml
npm run check:encoding
npm run api-server

api-server 是修改后端后的必跑项；如果本地 SpacetimeDB 发布态不一致，需要在最终结果里明确说明。

7. 后续接入点

1. F1/F2/F3 可把 mock client 替换到上述 HTTP facade。
2. F4 平台分发可先读取 /api/runtime/match3d/gallery 的已发布作品列表。
3. 若后续要记录排行榜或作品播放统计，需要补 Match3D 成绩表或 play record procedure，并同步更新 migration。