抓大鹅B3实现

docs/technical/MATCH3D_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-30.md

@@ -190,8 +190,8 @@ Rust DTO 只承载 HTTP contract 和跨 crate 稳定模型，不直接暴露 `mo
 8. `draft_json: String`，序列化草稿结果。
 9. `last_assistant_reply: String`。
 10. `published_profile_id: String`，未发布为空字符串。
-11. `created_at: i64`。
-12. `updated_at: i64`。
+11. `created_at: Timestamp`。
+12. `updated_at: Timestamp`。
 
 ## 5.2 `match3d_agent_message`
 
@@ -204,7 +204,7 @@ Rust DTO 只承载 HTTP contract 和跨 crate 稳定模型，不直接暴露 `mo
 3. `role: String`，建议值：`user`、`assistant`、`system`。
 4. `kind: String`，建议值：`text`、`action`、`error`。
 5. `text: String`。
-6. `created_at: i64`。
+6. `created_at: Timestamp`。
 
 ## 5.3 `match3d_work_profile`
 
@@ -227,8 +227,8 @@ Rust DTO 只承载 HTTP contract 和跨 crate 稳定模型，不直接暴露 `mo
 13. `config_json: String`。
 14. `publication_status: String`，建议值：`Draft`、`Published`。
 15. `play_count: u32`。
-16. `updated_at: i64`。
-17. `published_at: i64`，未发布为 `0`。
+16. `updated_at: Timestamp`。
+17. `published_at: Option<Timestamp>`，未发布为 `None`。
 
 ## 5.4 `match3d_runtime_run`
 
@@ -250,8 +250,8 @@ Rust DTO 只承载 HTTP contract 和跨 crate 稳定模型，不直接暴露 `mo
 12. `cleared_item_count: u32`。
 13. `failure_reason: String`，建议值为空、`TimeUp`、`TrayFull`。
 14. `snapshot_json: String`，序列化 `Match3DRunSnapshot`。
-15. `created_at: i64`。
-16. `updated_at: i64`。
+15. `created_at: Timestamp`。
+16. `updated_at: Timestamp`。
 
 ## 5.5 `match3d_play_record`
 
@@ -687,6 +687,14 @@ F3 运行态即时反馈分支可以先用本地 mock snapshot 开发，但必
 2. 与 `module-match3d` 规则接线。
 3. `spacetime build` 或仓库现有等价脚本通过。
 
+B3 当前落地状态：
+
+1. `server-rs/crates/spacetime-module/src/match3d/` 已承载 Match3D 的表、procedure 输入输出类型和 procedure 实现，并由 `server-rs/crates/spacetime-module/src/lib.rs` 挂载导出。
+2. `migration.rs` 已纳入 `match3d_agent_session`、`match3d_agent_message`、`match3d_work_profile`、`match3d_runtime_run` 四张表，后续字段变更继续按 `SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md` 追加兼容字段。
+3. 运行态 `start_match3d_run`、`click_match3d_item`、`stop_match3d_run`、`finish_match3d_time_up` 通过适配层调用 `module-match3d` 的领域规则，SpacetimeDB 层只负责归属校验、事务写入、权威快照持久化和 procedure JSON 返回。
+4. B3 对外仍返回当前首版快照字段 `snapshotVersion / clientSnapshotVersion` 对应语义；`module-match3d` 内部的 `board_version` 只在适配层中转换，避免影响并行中的 B4/F3 接入。
+5. SpacetimeDB module 的有效验收命令是 `spacetime build --module-path crates/spacetime-module`；不要用普通 native `cargo test -p spacetime-module` 作为验收口径，因为该 crate 会链接 SpacetimeDB 宿主符号。
+
 ### F1：创作入口与 Agent UI
 
 写入范围：

docs/technical/MATCH3D_DOMAIN_AND_CONTRACTS_STAGE1_2026-04-30.md

@@ -51,6 +51,8 @@ server-rs/crates/module-match3d
 
 该 crate 是纯领域层，不读写数据库，不访问网络，不依赖浏览器或文件系统。
 
+本阶段虽然不落 SpacetimeDB 表和 procedure，但领域模型已经为后续 SpacetimeDB 接入预留 `spacetime-types` feature。后续在 `spacetime-module` 内使用这些类型时，仍必须遵守 reducer 确定性、`ctx.sender()` 鉴权和表结构迁移约束。
+
 核心类型：
 
 1. `Match3DCreatorConfig`
@@ -89,6 +91,8 @@ server-rs/crates/module-match3d
 
 `Flying` 只作为前端表现态，不要求后端逐帧落库。后端只确认物品是否已从 `InBoard` 进入 `InTray` 或 `Cleared`。
 
+运行态领域内部使用 `board_version` 表示权威快照版本；HTTP 与 TypeScript shared contracts 对外使用 `snapshotVersion` / `clientSnapshotVersion`，由后续 `api-server` facade 做字段映射。
+
 ## 5. 生成规则 Stage1 口径
 
 1. `clearCount` 必须是正整数。

docs/technical/MATCH3D_F1_CREATION_ENTRY_AND_AGENT_UI_2026-04-30.md

@@ -0,0 +1,91 @@
+# 抓大鹅 Match3D F1 创作入口与 Agent UI 落地记录 2026-04-30
+
+## 1. 阶段边界
+
+本文件承接《MATCH3D_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-30.md》的 F1 包。
+
+F1 只处理前端创作入口、Agent 工作区和等待后端 B5 facade 前的 mock client。它不实现运行态规则，不修改 SpacetimeDB 表，不接 `api-server` 路由。
+
+## 2. 本阶段写入范围
+
+1. `src/components/platform-entry/`
+2. `src/components/match3d-creation/`
+3. `src/services/match3d-creation/`
+4. `packages/shared/src/contracts/match3dAgent.ts`
+
+其中 `packages/shared/src/contracts/match3dAgent.ts` 作为 F1 与后续 B5 的 DTO 对齐点，F1 mock client 不自建脱离共享契约的临时类型。
+
+## 3. 入口接入
+
+平台入口新增可见创作类型：
+
+```text
+id: match3d
+title: 抓大鹅
+subtitle: 经典消除玩法
+badge: 可创建
+```
+
+入口来源统一走 `getVisiblePlatformCreationTypes()`，因此创作首页首屏卡带与“选择创作类型”弹层会同时出现抓大鹅。
+
+## 4. Agent 工作区
+
+新增 `Match3DAgentWorkspace`，复用通用 `CreationAgentWorkspace`。
+
+Agent 只收集三类锚点：
+
+1. 题材主题。
+2. 需要消除次数。
+3. 难度。
+
+工作区支持参考图片上传入口。图片在 F1 中先以 Data URL 形式随消息 payload 带给 mock client；B5 接入后由后端 facade 替换为正式资产上传与引用。
+
+UI 中不默认展示玩法规则长文，只展示进度、锚点、聊天内容和必要按钮。
+
+## 5. mock client
+
+新增 `src/services/match3d-creation/match3dCreationClient.ts`。
+
+mock client 提供：
+
+1. `createMatch3DCreationSession`
+2. `getMatch3DCreationSession`
+3. `streamMatch3DCreationMessage`
+4. `executeMatch3DCreationAction`
+
+mock 行为：
+
+1. 创建本地会话。
+2. 从中文输入中提取题材、消除次数和难度。
+3. 支持“自动配置”。
+4. 当三项配置完整时允许执行 `match3d_compile_draft`。
+5. 编译后返回 `draft_ready` 会话和草稿。
+
+## 6. 结果承接
+
+F1 新增 `Match3DDraftReadyView` 作为草稿生成后的临时承接页，只展示草稿基础信息并允许返回 Agent 修改。
+
+正式结果页的基础信息编辑、封面图、试玩、发布由 F2 接入，F1 不在这里模拟发布。
+
+## 7. 后续替换点
+
+B5 完成后，只需要把 `match3dCreationClient` 的本地 Map mock 替换为 HTTP/SSE facade：
+
+```text
+POST /api/creation/match3d/sessions
+GET  /api/creation/match3d/sessions/:sessionId
+POST /api/creation/match3d/sessions/:sessionId/messages/stream
+POST /api/creation/match3d/sessions/:sessionId/compile
+```
+
+`PlatformEntryFlowShellImpl` 与 `Match3DAgentWorkspace` 不应再改一轮业务字段。
+
+## 8. 验收口径
+
+1. 创作首页能看到“抓大鹅 / 经典消除玩法”。
+2. 弹层选择“抓大鹅”能进入 Agent 工作区。
+3. 输入题材、消除次数、难度后进度到 `100%`。
+4. 点击“生成结果页”进入草稿承接页。
+5. 可从草稿承接页返回 Agent 修改。
+6. `npm run check:encoding` 通过。
+7. `npm run typecheck` 通过。

docs/technical/README.md

@@ -7,6 +7,7 @@
 - [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)：冻结 SpacetimeDB 表结构变更约束、自动迁移可接受范围、冲突后的系统行为，以及保留旧数据的增量迁移流程；凡涉及 `spacetime publish`、表字段调整或 `migration.rs` 对齐时优先参考。
 - [MATCH3D_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-30.md](./MATCH3D_CREATION_AND_RUNTIME_MINIMAL_IMPLEMENTATION_2026-04-30.md)：冻结抓大鹅 Match3D 首版 demo 的独立玩法域、表与 procedure、HTTP facade、前端即时反馈/后端权威确认协议，以及可并行开发包。
 - [MATCH3D_DOMAIN_AND_CONTRACTS_STAGE1_2026-04-30.md](./MATCH3D_DOMAIN_AND_CONTRACTS_STAGE1_2026-04-30.md)：冻结抓大鹅 Match3D B1+B2 的纯领域规则 crate、Rust/TypeScript shared contracts，以及 Stage1 不触碰 SpacetimeDB 表和 api-server 的边界。
+- [MATCH3D_F1_CREATION_ENTRY_AND_AGENT_UI_2026-04-30.md](./MATCH3D_F1_CREATION_ENTRY_AND_AGENT_UI_2026-04-30.md)：记录抓大鹅 F1 创作入口、Agent 工作区、参考图入口、本地 mock client 与后续 B5 HTTP facade 替换点。
 - [PLATFORM_MOBILE_BOTTOM_DOCK_VIEWPORT_FIX_2026-04-30.md](./PLATFORM_MOBILE_BOTTOM_DOCK_VIEWPORT_FIX_2026-04-30.md)：记录平台首页底部 dock 在手机浏览器地址栏展开时脱离可见区域的根因，以及 `100dvh`、固定底部锚点和安全区占位的修复口径。
 - [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md)：记录 SpacetimeDB private 表迁移 JSON 导出/导入 procedure、迁移操作员授权、HTTP 413 分片导入、Jenkins 自动迁移回灌和导入脚本参数。
 - [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)：记录 `Genarrative-Database-Export` / `Genarrative-Database-Import` 两条 SCM-backed 数据库迁移流水线参数、默认 dry-run、token 边界和 `CHUNK_SIZE` 413 规避参数。