Enforce Genarrative play-type SOP and update docs

Rewrite Genarrative play-type integration guidance across .codex and .hermes to define a platform-level SOP: default to form/image workbench, unify single-image asset slots (CreativeImageInputPanel), standardize series-material sheet->cut->transparent->OSS pipeline, and forbid copying legacy chat/agent workflows as the default. Add decision-log entry freezing the SOP and a pitfalls note warning against direct reuse of old play tools. Update CONTEXT.md and docs/README.md, add a new PRD file, and apply related small server-side changes (module-auth, spacetime-client mappers and runtime) to align back-end code with the new contracts and flows.
2026-05-20 12:12:00 +08:00
parent f370539a6f
commit 3931442249
123 changed files with 15514 additions and 3419 deletions
--- a/docs/README.md
+++ b/docs/README.md
@@ -13,7 +13,7 @@
  重点补充：RPG 创作与运行时脚本职责地图见 [RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md](./reference/RPG_CREATION_AND_RUNTIME_SCRIPT_RESPONSIBILITY_MAP_2026-04-28.md)。
 - [埋点查询](./tracking/README.md)：埋点原始事件与聚合投影的本地 SQL 查询。
 - [运营查询](./operations/README.md)：任务、领奖、钱包对账等后台核查查询。
- [PRD](./prd/README.md)：产品需求与阶段计划；参考 MOKU / 幕间类 AI 文游的陶泥儿 `text-game` 模板口径见 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md](./prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md)，视觉小说模板 TXT 玩法平台化接入口径见 [AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md](./prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)，创意互动内容 Agent Phase 1 的 LangChain-Rust PoC、拼图闭环和并行任务拆分见 [CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md](./prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md)，幸存者类模板闭环见 [AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md](./prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md)，后台管理独立前端工程见 [ADMIN_WEB_CONSOLE_PRD_2026-04-30.md](./prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)，新增 RPG 开场动画方案见 [AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md](./prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md)，新增抓大鹅 Match3D 玩法方案见 [AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md](./prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md)，方洞挑战创作、发布与试玩闭环见 [AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md](./prd/AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)。
+- [PRD](./prd/README.md)：产品需求与阶段计划；参考 MOKU / 幕间类 AI 文游的陶泥儿 `text-game` 模板口径见 [AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md](./prd/AI_NATIVE_TEXT_GAME_TEMPLATE_MOKU_REFERENCE_PRD_2026-05-05.md)，视觉小说模板 TXT 玩法平台化接入口径见 [AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md](./prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md)，创意互动内容 Agent Phase 1 的 LangChain-Rust PoC、拼图闭环和并行任务拆分见 [CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md](./prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md)，幸存者类模板闭环见 [AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md](./prd/AI_NATIVE_SURVIVOR_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-05.md)，后台管理独立前端工程见 [ADMIN_WEB_CONSOLE_PRD_2026-04-30.md](./prd/ADMIN_WEB_CONSOLE_PRD_2026-04-30.md)，新增 RPG 开场动画方案见 [AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md](./prd/AI_NATIVE_RPG_OPENING_ANIMATION_PRD_2026-04-25.md)，新增抓大鹅 Match3D 玩法方案见 [AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md](./prd/AI_NATIVE_MATCH3D_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-04-30.md)，方洞挑战创作、发布与试玩闭环见 [AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md](./prd/AI_NATIVE_SQUARE_HOLE_CREATOR_AND_GAMEPLAY_SYSTEM_PRD_2026-05-04.md)，跳一跳俯视角玩法模板 PRD 见 [【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md](./prd/%E3%80%90%E7%8E%A9%E6%B3%95%E5%88%9B%E4%BD%9C%E3%80%91%E8%B7%B3%E4%B8%80%E8%B7%B3%E4%BF%AF%E8%A7%86%E8%A7%92%E7%8E%A9%E6%B3%95%E6%A8%A1%E6%9D%BFPRD-2026-05-19.md)。

 生产部署切换到 systemd + Nginx + SpacetimeDB 自托管的总方案见 [PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md](./technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md)，该文档也是当前生产 Jenkinsfile 的唯一入口。SpacetimeDB 表结构变更、自动迁移边界和保留旧数据的分阶段迁移流程见 [SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md](./technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md)；private 表迁移 JSON 导入导出、HTTP 413 分片导入和旧数据库迁移流水线经验见 [SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md](./technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md) 与 [JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md](./technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md)；后台管理独立前端工程技术方案见 [ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md](./technical/ADMIN_WEB_CONSOLE_TECHNICAL_SOLUTION_2026-04-30.md)。

--- a/docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md
+++ b/docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md
@@ -0,0 +1,485 @@
+# 跳一跳俯视角玩法模板 PRD 2026-05-19
+
+## 1. 目标
+
+新增一个可创作、可试玩、可发布的玩法模板：
+
+```text
+跳一跳
+```
+
+本模板参考拼图模板的创作闭环，沿用“创作入口 -> 生成过程页 -> 结果页 -> 试玩 -> 发布”的平台链路，但玩法本体改为俯视角 / 等距视角的跳跃闯关。
+
+首版要求：
+
+1. 初始草稿生成时，角色形象单独调用一次生图；
+2. 初始草稿生成时，地块只调用一次生图，输出 3D 视图的 2D 图片图集；
+3. 运行态不接真实 3D 网格，不生成 GLB / glTF；
+4. 作品可以直接进入试玩和发布。
+
+## 2. 模板定位
+
+模板 ID：
+
+```text
+jump-hop
+```
+
+用户展示名：
+
+```text
+跳一跳
+```
+
+体验关键词：
+
+1. 俯视角；
+2. 等距感地块；
+3. 单局闯关；
+4. 长按蓄力，松手起跳；
+5. 轻量休闲。
+
+首版采用竖屏优先的移动端体验，桌面端保持居中展示，画面比例以 `9:16` 为主。参考图的核心视觉要点是：
+
+1. 大面积留白或浅色渐变背景；
+2. 角色站在单个地块上；
+3. 地块有明显顶面、侧面和投影；
+4. 整体是俯视角 / 等距视角，而不是横版平台跳跃；
+5. UI 克制，只保留必要控制，不堆说明文案。
+
+## 3. 与拼图模板的复用边界
+
+可以复用：
+
+1. 创作入口和模板分流；
+2. 生成过程页；
+3. 结果页的草稿保存、返回编辑、试玩、发布、分享链路；
+4. 作品架展示和草稿恢复口径；
+5. 平台统一的发布与公开展示流程。
+
+不复用：
+
+1. 拼图关卡切片逻辑；
+2. 拼图拖拽拼块逻辑；
+3. 拼图 UI 背景和多关卡编辑结构；
+4. 任何方格拼合语义。
+
+## 4. 工程接入范围
+
+首版需要做到完整玩法闭环，不只做入口占位。
+
+新增前端阶段：
+
+```text
+jump-hop-workspace
+jump-hop-generating
+jump-hop-result
+jump-hop-runtime
+jump-hop-gallery-detail
+```
+
+新增前端组件建议：
+
+1. `src/components/jump-hop-creation/JumpHopWorkspace.tsx`；
+2. `src/components/jump-hop-result/JumpHopResultView.tsx`；
+3. `src/components/jump-hop-runtime/JumpHopRuntimeShell.tsx`；
+4. `src/services/jump-hop/jumpHopClient.ts`。
+
+新增共享契约建议：
+
+1. `packages/shared/src/contracts/jumpHop.ts`；
+2. `server-rs/crates/shared-contracts/src/jump_hop.rs`。
+
+新增后端模块建议：
+
+1. `server-rs/crates/module-jump-hop`：纯领域规则，包含路径生成、蓄力换算、落点判定、通关 / 失败状态机；
+2. `server-rs/crates/api-server/src/jump_hop.rs` 和 `src/jump_hop/` 子模块：HTTP handler、生成编排、资产保存和 DTO 映射；
+3. `server-rs/crates/spacetime-module/src/jump_hop.rs`：session、work profile、runtime run、公开 view 和 reducer / procedure；
+4. `server-rs/crates/spacetime-client/src/jump_hop.rs`：api-server 访问 SpacetimeDB 的 facade；
+5. `server-rs/crates/api-server/src/modules/jump_hop.rs`：路由挂载。
+
+入口配置事实源必须走 SpacetimeDB `creation_entry_type_config` 默认种子和后台配置接口，不新增前端硬编码入口配置。
+
+## 5. 创作输入
+
+创作者需要填写以下内容：
+
+1. 作品主题描述，必填；
+2. 角色形象描述，必填；
+3. 地块风格卡，必选；
+4. 难度，必选；
+5. 可选的终点氛围或节奏偏好。
+
+推荐的最小输入形态是：
+
+1. 一句话主题；
+2. 角色一句话描述；
+3. 风格卡；
+4. 难度卡。
+
+不在首版开放手工拖拽平台编辑器。平台路径、地块间距和终点位置由系统自动生成，创作者只负责风格与难度选择。
+
+### 5.1 地块风格卡
+
+建议提供以下风格：
+
+1. 极简积木；
+2. 纸模玩具；
+3. 霓虹玻璃；
+4. 森林石块；
+5. 未来金属；
+6. 自定义。
+
+### 5.2 难度
+
+建议提供以下离散档位：
+
+1. 轻松；
+2. 标准；
+3. 进阶；
+4. 挑战。
+
+难度主要影响：
+
+1. 平台路径长度；
+2. 平台间距；
+3. 可落点容差；
+4. 完美落点窗口；
+5. 终点前的节奏变化。
+
+## 6. 生成规则
+
+本模板必须把生图责任拆成两条独立链路：
+
+### 6.1 角色形象只生一次
+
+角色形象必须只调用一次生图，输出一张可直接进入运行态的主角色图。
+
+角色图要求：
+
+1. 单人主角；
+2. 全身可见；
+3. 透明背景；
+4. 角色站姿或轻微前倾姿态；
+5. 镜头和透视必须匹配俯视角场景；
+6. 不要求多视角，不要求多帧动画图集。
+
+角色图生成后作为作品级锚点资产使用，结果页、封面合成、试玩和发布都复用同一张图。后续如果只修改标题、标签、难度或路径，不应默认重新生角色。只有用户在结果页明确点击“重生成角色”时，才允许再调用一次角色生图。
+
+### 6.2 地块只生一次图集
+
+地块必须只调用一次生图，输出一张 3D 视图的 2D 图片图集，再由后端切成运行态可用的地块资产。
+
+地块图集要求：
+
+1. 统一使用等距 / 俯视角；
+2. 必须表现出顶面、侧面和投影；
+3. 必须与角色图保持同一光向；
+4. 必须有清晰的立体层次，但仍然是 2D 图片；
+5. 必须包含至少以下地块类型：
+   - 起点地块；
+   - 普通地块；
+   - 目标地块；
+   - 终点地块。
+
+建议额外包含：
+
+1. 奖励地块；
+2. 视觉强调地块；
+3. 风格化变体地块。
+
+图集生成后按地块类型切分并去掉背景，运行态直接消费切好的 PNG，不在前端做复杂拼接。只有用户在结果页明确点击“重生成地块”时，才允许再调用一次地块图集生图。
+
+### 6.3 不新增第三次生成
+
+首版不把封面、分享海报、路径预览再拆成第三次图像生成。封面和分享图必须由角色图 + 地块图集在本地或后端轻量合成，不额外增加新的角色生图次数。
+
+### 6.4 路径元数据
+
+除图片资产外，系统还必须生成跳跃路径元数据：
+
+1. 平台序列；
+2. 平台中心点；
+3. 平台宽度；
+4. 平台间距；
+5. 终点索引；
+6. 评分和容差参数。
+
+路径由领域规则自动生成，创作者不直接编辑坐标。路径元数据不依赖 LLM 或图片生成。
+
+### 6.5 推荐的难度区间
+
+| 难度 | 平台数量 | 平台间距 | 节奏 |
+| --- | ---: | --- | --- |
+| 轻松 | 12 - 14 | 短 | 宽容 |
+| 标准 | 16 - 18 | 中 | 稳定 |
+| 进阶 | 20 - 24 | 中长 | 紧凑 |
+| 挑战 | 26 - 32 | 长 | 高压 |
+
+平台宽度和容差由系统按难度自动缩放，不要求创作者手工填写。
+
+## 7. 契约草案
+
+### 7.1 草稿结构
+
+`JumpHopDraft` 至少包含：
+
+1. `templateId = "jump-hop"`；
+2. `templateName = "跳一跳"`；
+3. `profileId`；
+4. `workTitle`；
+5. `workDescription`；
+6. `themeTags`；
+7. `difficulty`；
+8. `stylePreset`；
+9. `characterPrompt`；
+10. `tilePrompt`；
+11. `characterAsset`；
+12. `tileAtlasAsset`；
+13. `tileAssets[]`；
+14. `path`；
+15. `coverComposite`；
+16. `generationStatus`。
+
+### 7.2 资产结构
+
+`JumpHopCharacterAsset` 至少包含：
+
+1. `assetId`；
+2. `imageSrc`；
+3. `imageObjectKey`；
+4. `assetObjectId`；
+5. `generationProvider`；
+6. `prompt`；
+7. `width`；
+8. `height`。
+
+`JumpHopTileAsset` 至少包含：
+
+1. `tileType`；
+2. `imageSrc`；
+3. `imageObjectKey`；
+4. `assetObjectId`；
+5. `sourceAtlasCell`；
+6. `visualWidth`；
+7. `visualHeight`；
+8. `topSurfaceRadius`；
+9. `landingRadius`。
+
+`tileType` 首版限定：
+
+```text
+start | normal | target | finish | bonus | accent
+```
+
+### 7.3 路径结构
+
+`JumpHopPath` 至少包含：
+
+1. `seed`；
+2. `difficulty`；
+3. `platforms[]`；
+4. `finishIndex`；
+5. `cameraPreset`；
+6. `scoring`。
+
+`JumpHopPlatform` 至少包含：
+
+1. `platformId`；
+2. `tileType`；
+3. `x`；
+4. `y`；
+5. `width`；
+6. `height`；
+7. `landingRadius`；
+8. `perfectRadius`；
+9. `scoreValue`。
+
+### 7.4 运行态快照
+
+`JumpHopRunSnapshot` 至少包含：
+
+1. `runId`；
+2. `profileId`；
+3. `status = playing | failed | cleared`；
+4. `currentPlatformIndex`；
+5. `score`；
+6. `combo`；
+7. `lastJump`；
+8. `startedAtMs`；
+9. `finishedAtMs`。
+
+`lastJump` 至少包含：
+
+1. `chargeMs`；
+2. `jumpDistance`；
+3. `targetPlatformIndex`；
+4. `landedX`；
+5. `landedY`；
+6. `result = miss | hit | perfect | finish`。
+
+## 8. API 草案
+
+HTTP 路由建议：
+
+```text
+POST /api/creation/jump-hop/sessions
+GET  /api/creation/jump-hop/sessions/{sessionId}
+POST /api/creation/jump-hop/sessions/{sessionId}/actions
+POST /api/creation/jump-hop/works/{profileId}/publish
+GET  /api/runtime/jump-hop/works/{profileId}
+POST /api/runtime/jump-hop/runs
+POST /api/runtime/jump-hop/runs/{runId}/jump
+POST /api/runtime/jump-hop/runs/{runId}/restart
+GET  /api/runtime/jump-hop/gallery
+GET  /api/runtime/jump-hop/gallery/{publicWorkCode}
+```
+
+动作类型建议：
+
+```text
+compile-draft
+regenerate-character
+regenerate-tiles
+update-work-meta
+update-difficulty
+```
+
+`compile-draft` 是长耗时动作。前端进入生成页后必须持久化 `generationStatus=generating`，刷新后能从作品架恢复生成页。失败前需要复读 session；如果后端已经完成草稿并写回资产，前端按成功收尾。
+
+## 9. SpacetimeDB 表和 view
+
+建议新增表：
+
+1. `jump_hop_agent_session`；
+2. `jump_hop_work_profile`；
+3. `jump_hop_runtime_run`；
+4. `jump_hop_event`；
+5. `jump_hop_leaderboard_entry`，首版可暂不对外展示；
+6. `jump_hop_gallery_view`；
+7. `jump_hop_gallery_card_view`。
+
+表结构新增字段必须按 SpacetimeDB 迁移规则放在结构体末尾并设置明确默认值。新增或调整表、reducer、procedure、view 后必须同步 `migration.rs`、表目录、生成 bindings，并执行 `npm run check:spacetime-schema`。
+
+公开列表主路径应优先订阅 `jump_hop_gallery_card_view` 后在 `api-server` 本地 cache 构造列表响应，不要让每个 HTTP 请求都调用 SpacetimeDB procedure 组装全量列表。
+
+## 10. 结果页能力
+
+结果页必须展示：
+
+1. 作品标题；
+2. 作品简介；
+3. 角色形象；
+4. 地块图集；
+5. 路径预览；
+6. 标签；
+7. 试玩；
+8. 发布；
+9. 返回编辑。
+
+结果页还必须支持：
+
+1. 单独重生成角色；
+2. 单独重生成地块图集；
+3. 单独修改标题和简介；
+4. 单独调整标签和难度。
+
+结果页不应强制再走一次封面生图。封面只做合成，不新增图像生成调用。
+
+## 11. 运行态规则
+
+运行态采用 2D 表现，但画面视觉上必须保留参考图那种俯视角 / 等距感。
+
+### 11.1 核心玩法
+
+1. 玩家长按蓄力；
+2. 松手后角色按蓄力长度起跳；
+3. 跳跃距离决定是否落到下一个地块；
+4. 落在目标区域内判定成功；
+5. 落在地块外或越界判定失败；
+6. 到达终点地块判定通关。
+
+### 11.2 判定规则
+
+1. 只做一个当前局面的起跳判定；
+2. 不做复杂连招动作树；
+3. 不新增生命数、体力、回合数；
+4. 不新增计时赛作为首版核心规则；
+5. 不把前端动画结果当成最终真相，通关与失败必须能回写运行态状态。
+
+### 11.3 角色动画
+
+角色不需要多帧生图，运行态只通过位移、缩放、轻微旋转和投影变化表达：
+
+1. 蓄力时轻微压缩；
+2. 起跳时向上抬升；
+3. 空中保持可读轮廓；
+4. 落地时轻微弹性回弹；
+5. 失败时从地块边缘跌落。
+
+### 11.4 摄像机与构图
+
+1. 相机以当前角色和下一地块为中心；
+2. 至少保证下一个落点一直可见；
+3. 画面要留出顶部和底部的 UI 安全区；
+4. 不要把地块做得太满，保留参考图那种疏朗感。
+
+### 11.5 UI
+
+运行态 UI 只保留必要元素：
+
+1. 分数；
+2. 暂停；
+3. 重新开始；
+4. 分享；
+5. 结算按钮。
+
+不默认展示大段规则说明。首进如果需要引导，只能用一次轻量提示，不允许常驻一屏的说明文案。
+
+## 12. 视觉规范
+
+本模板的视觉目标是“像 3D，但仍是 2D 图片”。
+
+必须遵守：
+
+1. 平台有明确厚度；
+2. 侧面可见分层或材质变化；
+3. 投影统一且方向一致；
+4. 背景干净，颜色克制；
+5. 角色尺寸在小屏上依然可读；
+6. 地块不能出现过多文字、按钮或装饰信息；
+7. 不能把运行态做成重 UI 面板。
+
+建议的背景策略：
+
+1. 以静态浅色渐变或纯色背景为主；
+2. 不把背景也做成每次都生成的重资产；
+3. 让地块和角色成为画面的第一视觉焦点。
+
+## 13. 发布后体验
+
+发布后的作品必须支持：
+
+1. 进入作品架和公开展示；
+2. 分享；
+3. 试玩；
+4. 重新进入结果页编辑。
+
+发布后的卡片封面应优先由角色图和地块图合成，不要求单独再生成封面图。
+
+首版不新增排行榜、回放和对局对抗。后续如要扩展排行，可另起版本，不要塞进首版模板范围。
+
+## 14. 验收
+
+1. 创作入口能看到 `跳一跳` 模板；
+2. 创作者可以填写主题、角色描述、风格和难度；
+3. 提交后只生成一次角色图和一次地块图集；
+4. 结果页能看到角色图、地块图集和路径预览；
+5. 结果页可单独重生成角色或地块；
+6. 试玩进入跳一跳运行态；
+7. 长按蓄力、松手起跳、落点判定、失败和通关都可用；
+8. 作品可以保存、发布和分享；
+9. 前端不直接读取或暴露生图密钥；
+10. 发布后的封面不依赖第三次额外生图。
+11. `npm run check:spacetime-schema` 在 schema 变更后通过；
+12. `npm run check:encoding` 通过。
--- a/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
+++ b/docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md
@@ -101,7 +101,7 @@ npm run check:server-rs-ddd
 - `server-rs/crates/api-server/src/match3d/handlers.rs` 承接 Axum handler，负责 extract、鉴权上下文、调用 SpacetimeDB facade / 编排 helper，并返回 HTTP 响应。
 - `server-rs/crates/api-server/src/match3d/draft.rs` 承接 Agent session、草稿编译、题材 / 难度 / 物品计划和草稿持久化编排。
 - `server-rs/crates/api-server/src/match3d/works.rs` 承接作品 CRUD、封面 / 背景 / 容器资产生成入口、发布 / Remix / 点赞 / 游玩记录和作品级 helper。
- `server-rs/crates/api-server/src/match3d/item_assets.rs` 承接物品 sheet 生成、绿幕 / 近白底透明化、切图、append / replace / delete / sort / merge 和素材持久化。
+- `server-rs/crates/api-server/src/match3d/item_assets.rs` 承接物品生成批次编排、append / replace / delete / sort / merge、计费外层和草稿素材映射；sheet prompt、绿幕 / 近白底透明化、切图和切片持久化复用 `generated_asset_sheets` 通用模块。
 - `server-rs/crates/api-server/src/match3d/vector_engine_gemini.rs` 承接 VectorEngine Gemini 请求体、响应解析、base64 图片下载和上游错误归一。
 - `server-rs/crates/api-server/src/match3d/runtime.rs` 保留运行态轻量归一 helper；`mappers.rs` / `tags.rs` / `tests.rs` 分别承接 DTO 映射、标签 / 通用错误 helper 和原有单测。

@@ -114,6 +114,7 @@ npm run check:server-rs-ddd
 3. Adapter 输出应保留 legacy public path、object key、asset object id、MIME、extension、task id 和实际 prompt。
 4. Adapter 不负责扣费、退款或钱包读取；计费仍由调用方显式包裹。
 5. Puzzle、Match3D、音频、GLB、视频等复杂媒体可以复用 OSS + asset object + binding 的底层持久化能力，但玩法专属处理规则留在各自编排层，不塞进公共接口。
+6. 系列素材图集使用 `server-rs/crates/api-server/src/generated_asset_sheets.rs`：调用方必须传入 `grid_size` 作为 `n*n` 的 `n`，可选传入物品名称 prompt 模板和特殊设定 prompt；模块负责 sheet prompt 组装、按 `n*n` 切片、透明化、PNG 输出、OSS private upload 请求构造和 sheet / item / special prompt 元数据持久化。玩法只负责规划 slot、调用具体生图 provider、计费、失败回写，以及把通用切片结果映射回自己的 DTO / 草稿 / runtime 字段。

 ## SpacetimeDB schema 变更规则

@@ -151,7 +152,7 @@ npm run check:server-rs-ddd

 - LLM：`GENARRATIVE_LLM_*`，创意 Agent 另用 `APIMART_BASE_URL` / `APIMART_API_KEY`。
 - 图片生成：VectorEngine / APIMart / DashScope，密钥只在后端环境变量中。
- Match3D 物品 sheet：VectorEngine Gemini `gemini-3-pro-image-preview` 原生 `generateContent`。
+- Match3D 物品 sheet：VectorEngine Gemini `gemini-3-pro-image-preview` 原生 `generateContent`；图集 prompt、切图、透明化和切片持久化走 `generated_asset_sheets` 通用模块，Match3D 只补题材 / 风格 / 五视角设定和字段映射。
 - Match3D 封面和 9:16 纯背景：VectorEngine `/v1/images/generations`。
 - Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。
 - Hyper3D / Rodin：只保留后端安全代理和旧数据兼容；新 Match3D 草稿和批量新增不再生成 GLB。
@@ -361,6 +362,40 @@ npm run check:server-rs-ddd
 - Rust 结构体：`InventorySlot`
 - 源码：`server-rs/crates/spacetime-module/src/gameplay.rs`

+### `jump_hop_agent_session`
+
+- Rust 结构体：`JumpHopAgentSessionRow`
+- 源码：`server-rs/crates/spacetime-module/src/jump_hop/tables.rs`
+
+### `jump_hop_event`
+
+- Rust 结构体：`JumpHopEventRow`
+- 源码：`server-rs/crates/spacetime-module/src/jump_hop/tables.rs`
+
+### `jump_hop_runtime_run`
+
+- Rust 结构体：`JumpHopRuntimeRunRow`
+- 源码：`server-rs/crates/spacetime-module/src/jump_hop/tables.rs`
+
+### `jump_hop_work_profile`
+
+- Rust 结构体：`JumpHopWorkProfileRow`
+- 源码：`server-rs/crates/spacetime-module/src/jump_hop/tables.rs`
+
+### SpacetimeDB view：`jump_hop_gallery_card_view`
+
+- Rust view：`jump_hop_gallery_card_view`
+- 返回类型：`Vec<JumpHopGalleryCardViewRow>`
+- 源码：`server-rs/crates/spacetime-module/src/jump_hop.rs`
+- 说明：跳一跳公开广场列表卡片投影，只暴露 `publication_status = Published` 的作品卡片字段；`api-server` 的 `spacetime-client` 长期订阅 `SELECT * FROM jump_hop_gallery_card_view` 后，从本地 cache 构造跳一跳公开列表响应。个人作品列表、详情、发布和运行态仍按 procedure 路径处理。
+
+### SpacetimeDB view：`jump_hop_gallery_view`
+
+- Rust view：`jump_hop_gallery_view`
+- 返回类型：`Vec<JumpHopGalleryViewRow>`
+- 源码：`server-rs/crates/spacetime-module/src/jump_hop.rs`
+- 说明：跳一跳公开详情兼容投影，包含作品、路径和素材字段；公开列表主路径优先使用 `jump_hop_gallery_card_view`。
+
 ### `match3d_agent_message`

 - Rust 结构体：`Match3DAgentMessageRow`
@@ -545,6 +580,7 @@ npm run check:server-rs-ddd
 - `SELECT * FROM square_hole_gallery_view`
 - `SELECT * FROM visual_novel_gallery_view`
 - `SELECT * FROM big_fish_gallery_view`
+- `SELECT * FROM jump_hop_gallery_card_view`

 下列订阅用于统计或配置缓存，订阅失败不会让公开列表连接整体不可用，调用方保留兼容兜底：

--- a/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
+++ b/docs/【开发运维】本地开发验证与生产运维-2026-05-15.md
@@ -40,10 +40,10 @@ npm run dev:web
 单独启动 Rust API server：

 ```bash
-npm run api-server
+npm run dev:api-server
 ```

-后端日志默认写入 `logs/api-server/`。后端 API smoke 使用 `npm run api-server` 并检查 `/healthz`；不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。
+后端日志默认写入 `logs/api-server/`。后端 API smoke 使用 `npm run dev:api-server` 并检查 `/healthz`；不要使用旧 `api-server:maincloud` 或任何 `GENARRATIVE_SPACETIME_MAINCLOUD_*` 口径。

 查看本地 Rust / SpacetimeDB 日志：

@@ -103,7 +103,7 @@ npm run spacetime:generate
 - `cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`
 - `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`
 - `npm run check:server-rs-ddd`
- `npm run api-server` 后请求 `/healthz`
+- `npm run dev:api-server` 后请求 `/healthz`

 涉及 SpacetimeDB schema 时必须补：

--- a/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
+++ b/docs/【玩法创作】平台入口与玩法链路-2026-05-15.md
@@ -10,6 +10,20 @@

 `PlatformEntryFlowShellImpl.tsx` 仍是平台入口编排壳，后续维护时应优先把独立 UI 片段、公开作品映射、草稿生成 notice 和运行态状态 helper 拆到 `src/components/platform-entry/PlatformEntryFlowShellImpl/` 或同目录紧邻 helper 文件。拆分只允许改变文件组织，不改变入口配置事实源、默认导出、props、页面阶段、UI 文案或现有交互；其中拼图首访 onboarding 已拆为 `PlatformEntryFlowShellImpl/PuzzleOnboardingView.tsx`。

+## 新增玩法创作工具平台 SOP
+
+新增玩法默认采用表单/图片输入创作工作台，链路为：
+
+```text
+创作入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态
+```
+
+默认工作台只提交结构化表单、图片槽位和配置 payload，不默认增加聊天输入区、流式消息区或轻输入 Agent。确需偏离该模式时，必须先在 PRD 和本文档写明例外原因、影响范围和回退方式，再进入编码。
+
+单图资产编辑统一通过 `CreativeImageInputPanel` 承载上传、AI 重绘、参考图、历史图和删除确认；新玩法页面不得重复手写这些交互。系列素材图集生成统一走“批量规划 -> sheet 生图 -> 后端切图 -> 透明化 -> OSS 持久化 -> 状态回写 -> 局部重生成”流程，玩法只提供 `sheetSpec`、`slotSpecs`、提示词和字段映射，不把任一玩法专属素材 DTO 当作平台通用模型。
+
+`api-server` 的 `generated_asset_sheets` 是当前通用系列素材图集模块：`n` 是必选参数，模块负责组装 `n*n` sheet prompt、按 `n*n` 切片、绿幕 / 近白底透明化、导出 PNG 和 OSS 持久化请求。物品名称 prompt 和特殊设定 prompt 是可选输入；调用方可传入类似“每个物品生成五个不同视图”的视角约束，通用模块会把 sheet prompt、物品行 prompt、特殊设定 prompt 编码写入 OSS 元数据。玩法仍负责计费、物品规划、slot 映射、失败回写和把通用切片结果映射回自己的草稿 / profile / runtime 字段。
+
 ## 草稿与作品架

 1. 草稿页作品卡对齐发现页列表卡风格：左侧信息，右侧封面图，移动端单列，桌面两到三列。
@@ -31,6 +45,7 @@
 当前口径：

 - 图像输入复用 `CreativeImageInputPanel`。
+- 结果页每关画面编辑和素材配置里的 UI 背景生成也复用 `CreativeImageInputPanel`；三处只共享受控 UI 模块，不共享数据源、状态、action 或存储位置：入口页继续写 `formDraft` 与草稿编译 payload，关卡画面写 `levels[].pictureReference/pictureDescription` 并触发 `generate_puzzle_images`，UI 背景写 `levels[0].uiBackgroundPrompt/uiBackgroundImage*` 并触发 `generate_puzzle_ui_background`。通用图片面板的展示图和 AI 重绘参考图能力必须分开控制：结果页正式关卡图只作为预览图，不因存在 `displayImageSrc` 自动暴露 AI 重绘开关；只有本地上传、历史选择或已保存 `pictureReference` 可作为重绘参考图时，才显示 AI 重绘开关并把状态带入 `generate_puzzle_images`。
 - 支持画面描述生图、多参考图生图、上传或历史生成主图后 AI 重绘、上传或历史生成主图后不重绘；关闭 AI 重绘时，前端可提交本地上传 Data URL 或历史 `/generated-*` 图片路径，后端统一解析为首关正式图后再持久化。
 - 草稿生成会先持久化 `generationStatus=generating` 的作品摘要，生成完成并回写关卡图、UI 背景后再变为 `ready`；首关关卡图和 UI 背景在命名稳定后并行启动，当前不自动生成背景音乐。
 - 作品架拼图草稿的“生成中”遮罩只表示初始草稿还没有可查看结果；只要作品摘要、首关封面或任一关卡候选图已经可用，后续 UI 背景重生成和追加关卡生图都必须作为结果页局部生成态处理，不能阻止打开草稿结果页。
@@ -50,6 +65,28 @@
 - 推荐页里的拼图作品如果从运行态进入“改造”结果页，返回平台后要清掉推荐嵌入态的 `activeRecommendEntryKey` / `activeRecommendRuntimeKind` / `isStartingRecommendEntry`，再重新按推荐页自动启动逻辑进入作品，不能复用已经被清空的旧 `puzzleRun`。
 - 拼图运行态允许前端低延迟交互表现，但通关、排行榜、奖励和作品状态仍以后端确认为准。

+## 跳一跳
+
+对外名称：`跳一跳`。工程域：`jump-hop`。PRD 见 `docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`。
+
+首版定位为俯视角 / 等距视角 2D 休闲跳跃模板，链路对齐拼图的创作闭环：
+
+```text
+创作入口 -> 模板输入 -> 生成过程页 -> 结果页 -> 试玩 -> 发布 -> 运行态
+```
+
+素材生成规则固定为：
+
+1. 初始草稿生成时，角色形象单独调用一次生图；
+2. 初始草稿生成时，地块单独调用一次生图，输出 3D 视图的 2D 图片图集；
+3. 地块图集由后端切分为起点、普通、目标、终点等透明 PNG；
+4. 封面和分享图由角色图与地块图轻量合成，不再额外调用第三次生图；
+5. 显式重生成角色或地块时，只重生成对应资产槽位。
+
+运行态规则真相必须沉到 `module-jump-hop`，前端只做蓄力表现、角色位移、投影和落地反馈。通关、失败、分数、combo、运行态快照和发布作品状态以后端为准。公开列表应走 `jump_hop_gallery_card_view` 订阅缓存，不要每次 HTTP 请求调用 procedure 组装全量列表。
+
+平台首页推荐、精选、最新、公开详情、搜索、已玩作品和公开试玩统一按 `sourceType='jump-hop'` 与 `JH-*` 公开作品号识别跳一跳作品；从公开详情或推荐流启动运行态时，若卡片摘要不足以携带角色图、地块图集和路径配置，必须先补读完整 work profile 再传入运行态。
+
 ## 抓大鹅 Match3D

 对外名称：`抓大鹅`。工程域：`match3d`。
@@ -75,12 +112,13 @@
 2. 先写入可恢复草稿 profile，再执行文本计划、图片生成、切图、OSS 上传、背景和容器生成；作品摘要在素材或背景未完整时下发 `generationStatus=generating`，素材和背景完整后下发 `ready`，草稿完成条件不包含 `backgroundMusic`。
 3. 物品素材不再调用 Hyper3D Rodin，不再生成 GLB。新草稿和批量新增固定生成 2D 五视角素材。
 4. 物品 sheet 走 VectorEngine Gemini `gemini-3-pro-image-preview` 原生 `generateContent`，单张 `1:1` 图固定 `5*5`，每张承载 `5` 个物品、每个物品 `5` 个视角。
-5. 切图前先在整张 sheet 上做绿幕 / 近白底透明化和边缘去污染，再按格子导出独立 PNG；每个视角图再以扩大的 PNG 边界带为种子，把连通的浅绿 / 近白抗锯齿边直接改为透明，并对贴透明背景的弱绿 / 暗绿轮廓像素做去绿污染处理，最后按剩余可见主体二次收紧；不要先裁剪单格再各自去绿。
-6. `generatedItemAssets[].imageViews[]` 是新素材主字段，`imageSrc/imageObjectKey` 只兼容首张视角。
-7. 文本生成物品名称时必须同时生成 `itemSize`，只允许 `大`、`中`、`小`。该字段随 `generatedItemAssets[].itemSize` 持久化并下发；历史缺失字段的素材按 `大` 兼容，模型缺失或非法值按物品名本地推断。
-8. 局内 `9:16` 纯背景图和 `1:1` 中心容器 UI 图分开生成。纯背景不得包含锅、盘、托盘、HUD、按钮、文字或物品，且入库前必须合成为全画幅不透明图片，不允许出现透明区域；容器图走 `/v1/images/edits` 参考透明容器图。
-9. 当前抓大鹅音频生成关闭：入口无 `生成音效`，草稿不生成背景音乐或点击音效，结果页不展示背景音乐 Tab 或点击音效生成入口。历史 `backgroundMusic` / `clickSound` 字段继续兼容传递。
-10. UI 背景和容器资产的持久化真相仍在 `generatedItemAssets[].backgroundAsset`；Agent session、work summary/detail、结果页和运行态入口都必须把该字段提升为 `backgroundImageSrc/backgroundImageObjectKey/generatedBackgroundAsset` 读取。草稿编译后的 `draftJson` 自身也必须携带 `generatedItemAssets` 快照；HTTP facade 不能只依赖 work detail 回读补齐 UI 资产，外部回读为空时也不得清空草稿内已有的背景 / 容器图。平台壳层从作品架、广场、生成完成回调、结果页保存 / 发布 / 试玩回调进入 Match3D profile 时也要先归一化并提升，避免首次试玩、手动试玩、推荐流或公开详情运行态退回默认背景 / 默认容器。
+5. 物品 sheet prompt、切图、透明化和五视角切片持久化复用 `generated_asset_sheets` 通用模块；Match3D 只传入题材 / 风格 subject、物品行 prompt 模板和“同一行五格必须是同一物品五个不同视角”的特殊设定，并把通用切片结果映射回 `generatedItemAssets[].imageViews[]`。
+6. 切图前先在整张 sheet 上做绿幕 / 近白底透明化和边缘去污染，再按格子导出独立 PNG；每个视角图再以扩大的 PNG 边界带为种子，把连通的浅绿 / 近白抗锯齿边直接改为透明，并对贴透明背景的弱绿 / 暗绿轮廓像素做去绿污染处理，最后按剩余可见主体二次收紧；不要先裁剪单格再各自去绿。
+7. `generatedItemAssets[].imageViews[]` 是新素材主字段，`imageSrc/imageObjectKey` 只兼容首张视角。
+8. 文本生成物品名称时必须同时生成 `itemSize`，只允许 `大`、`中`、`小`。该字段随 `generatedItemAssets[].itemSize` 持久化并下发；历史缺失字段的素材按 `大` 兼容，模型缺失或非法值按物品名本地推断。
+9. 局内 `9:16` 纯背景图和 `1:1` 中心容器 UI 图分开生成。纯背景不得包含锅、盘、托盘、HUD、按钮、文字或物品，且入库前必须合成为全画幅不透明图片，不允许出现透明区域；容器图走 `/v1/images/edits` 参考透明容器图。
+10. 当前抓大鹅音频生成关闭：入口无 `生成音效`，草稿不生成背景音乐或点击音效，结果页不展示背景音乐 Tab 或点击音效生成入口。历史 `backgroundMusic` / `clickSound` 字段继续兼容传递。
+11. UI 背景和容器资产的持久化真相仍在 `generatedItemAssets[].backgroundAsset`；Agent session、work summary/detail、结果页和运行态入口都必须把该字段提升为 `backgroundImageSrc/backgroundImageObjectKey/generatedBackgroundAsset` 读取。草稿编译后的 `draftJson` 自身也必须携带 `generatedItemAssets` 快照；HTTP facade 不能只依赖 work detail 回读补齐 UI 资产，外部回读为空时也不得清空草稿内已有的背景 / 容器图。平台壳层从作品架、广场、生成完成回调、结果页保存 / 发布 / 试玩回调进入 Match3D profile 时也要先归一化并提升，避免首次试玩、手动试玩、推荐流或公开详情运行态退回默认背景 / 默认容器。

 结果页当前结构：