收口后端创作游玩流程主干

新增 play_flow 统一承接创作游玩与支撑路由
将 app.rs 的逐玩法挂载改为统一主干分发
将平台与资产及个人侧游玩支撑路由迁入 play_flow
抽出 visual_novel 路由模块并复用原有 handler
统一入口熔断路径解析并补充目标回归测试
更新后端契约、玩法链路和团队决策记录

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -56,10 +56,11 @@ npm run check:server-rs-ddd
 - 健康检查：`GET /healthz`。
 - 后台管理：`/admin/api/*`，包括登录、概览、HTTP debug、埋点、表查询、创作入口开关、作品可见性、兑换码、邀请码、任务配置和充值商品配置。
 - 认证与账号：`/api/auth/*`、`/api/profile/me`，包括短信、密码、微信、refresh session、多端会话和登出。
-- 个人中心：`/api/profile/*`，包括钱包流水、任务、领奖、充值、反馈、邀请、兑换、存档、历史浏览和游玩统计。
-- LLM 与语音：`/api/llm/*`、`/api/speech/volcengine/*`。
-- 资产：`/api/assets/*`，包括直传票据、STS、对象确认、实体绑定、读签名、读 bytes、历史资产、角色图像/动画和 Hyper3D 代理。
-- 创作入口配置：`/api/creation-entry/config`，后台 `/admin/api/creation-entry/config` 和 `/admin/api/creation-entry/config/banners`。
+- 个人中心：`/api/profile/*`，包括钱包流水、任务、领奖、充值、反馈、邀请和兑换等账号侧能力。
+- 平台基础能力：`/api/llm/*`、`/api/speech/volcengine/*`，只保留通用 LLM 和语音代理。
+- 资产基础能力：`/api/assets/direct-upload-tickets`、`/api/assets/sts-upload-credentials`、`/api/assets/objects/*`、`/api/assets/read-*`，负责直传、确认、绑定和读取。
+- 创作 / 游玩支撑能力：`/api/creation-entry/config`、`/api/ai/tasks*`、`/api/runtime/chat/*`、`/api/runtime/settings`、`/api/runtime/save/snapshot`、`/api/profile/browse-history`、`/api/profile/save-archives*`、`/api/profile/play-stats`、`/api/assets/history`、`/api/assets/character-visual/*`、`/api/assets/character-animation/*`、`/api/assets/character-workflow-cache*`、`/api/assets/hyper3d/*`、`/api/runtime/custom-world/asset-studio/*`。
+- 后台入口配置：`/admin/api/creation-entry/config` 和 `/admin/api/creation-entry/config/banners`。
 - 自定义世界 / RPG：`/api/runtime/custom-world*`、`/api/story/*`、`/api/runtime/chat/*`。
 - 拼图：`/api/runtime/puzzle/*`。
 - 抓大鹅 Match3D：`/api/creation/match3d/*`、`/api/runtime/match3d/*`。
@@ -70,9 +71,20 @@ npm run check:server-rs-ddd
 - 跳一跳：`/api/creation/jump-hop/*`、`/api/runtime/jump-hop/*`。
 - 汪汪声浪：`/api/runtime/bark-battle/*`。
 - 儿童向创作：`/api/creation/edutainment/*`。
-- AI task：`/api/ai/tasks*`。
 
-需要新增路由时，先确认玩法入口配置和 tracking 分类，不要绕过 `app.rs` 的统一中间件、鉴权和入口开关。
+需要新增路由时，先确认玩法入口配置和 tracking 分类，不要绕过 `app.rs` 的统一中间件、鉴权和入口开关。涉及创作、生成、作品、公开详情、试玩、正式运行态、运行态库存、运行态设置 / 存档、游玩历史、存档归档、游玩统计、AI task、角色资产工坊或玩法生成支撑资产的路由，不再直接在 `app.rs` 逐玩法 `.merge(...)`，也不挂到 `modules/platform.rs`；必须先进入 `server-rs/crates/api-server/src/modules/play_flow.rs` 的统一玩法流程主干，再由主干注册表分发到各领域 HTTP Adapter 或支撑能力 handler。
+
+### 创作 / 游玩统一流程主干
+
+`modules/play_flow.rs` 是后端创作与游玩流程的统一入口。现有外部 URL、DTO、错误 envelope、鉴权方式、入口开关语义和 SpacetimeDB schema 默认不变，但路由组织必须遵循：
+
+1. `app.rs` 只合并 `modules::play_flow::router(state)`，不直接合并 RPG、拼图、抓大鹅、跳一跳、敲木鱼、拼消消、汪汪声浪、视觉小说或儿童向创作等逐玩法模块。
+2. `play_flow` 统一注册每个玩法的 `playId`、领域模块 key、创作路由前缀和运行态路由前缀；后续新增玩法或迁移旧玩法时，先补这个注册表，再挂具体领域模块路由。
+3. 新建创作、首次生成和 Remix 成草稿等会产生新创作的入口开关匹配规则同样归 `play_flow` 管理；`creation_entry_config.rs` 只复用该规则执行 `open=false` 熔断，不再维护第二份路径判断。
+4. `play_flow` 在进入领域 handler 前先解析并挂载 `PlayFlowRequestContext`，统一标记请求处于 `Creation`、`Runtime`、`CreationEntryConfig`、`CreationSupport`、`RuntimeSupport`、`AiTask`、`PublicReadModel` 或 `RuntimeInventory` 阶段，并记录目标 `playId` / 领域模块 key；领域 handler 可以读取该上下文做后续收口，但不能绕过主干自建平行流程。
+5. `play_flow` 只做平台共性编排和领域 Adapter 组合，不下沉玩法规则；最后一步的草稿编译、资产生成、发布、运行态 start/action/finish、计分和排行榜仍交给对应 `module-*`、`spacetime-module` procedure 和玩法 HTTP handler 处理。
+6. 公开作品聚合、作品详情、运行态库存、运行态设置 / 存档、游玩历史、存档归档、游玩统计、历史素材、AI task、runtime chat、文档解析、角色资产工坊、角色图像 / 动画生成和 Hyper3D 代理属于跨玩法或玩法支撑流程，也从 `play_flow` 主干挂入；`modules/platform.rs` 只保留通用 LLM / 语音代理，不再承接创作 / 游玩支撑路由。
+7. 如果某个旧玩法仍使用历史 `/api/runtime/<play>/agent/*` 作为创作命名空间，只保留外部兼容路径；新增实现和文档仍按“统一主干 -> 领域 Adapter”的语义描述，不把历史路径当新架构模板。
 
 ### 认证态用户与会话摘要下发口径
 
@@ -87,8 +99,8 @@ npm run check:server-rs-ddd
 
 路由模块化规则：
 
-1. 每个能力 Module 只暴露 `router(state) -> Router<AppState>`，由 `app.rs` 统一 `.merge(...)`。
-2. `app.rs` 只保留全局 middleware、TraceLayer、request context、tracking middleware、入口开关和少量顶层 glue。
+1. 每个能力 Module 只暴露 `router(state) -> Router<AppState>`；平台创作 / 游玩相关 Module 和支撑能力由 `modules/play_flow.rs` 统一 `.merge(...)` 或在支撑 router 内挂载，其它账号、资产基础、后台和平台基础能力再由 `app.rs` 直接合并。
+2. `app.rs` 只保留全局 middleware、TraceLayer、request context、tracking middleware、入口开关和少量顶层 glue；不得重新恢复逐玩法 creation/runtime merge 列表。
 3. 能力 Module 可在路由内部用 `FromRef<AppState>` 派生自己的 Feature State，例如 `PuzzleApiState`。全局 `AppState` 仍作为进程组合根、鉴权层和全局中间件状态，但业务 handler 优先只提取对应 Feature State，不直接暴露完整 `AppState`。
 4. Feature State 只暴露该能力实际需要的 facade / adapter / 配置快照；若必须复用仍要求 `AppState` 的横切 helper（例如计费、外部失败审计或通用 tracking），应通过 Feature State 的窄方法或显式 `root_state()` 过渡，并在后续继续收窄。
 5. 路由迁移和业务重构分阶段处理；先移动路由装配，再拆 handler 内部实现，再收窄 handler 可见状态。

docs/【玩法创作】平台入口与玩法链路-2026-05-15.md

@@ -56,6 +56,8 @@ RPG Agent 结果页发布门禁展示由 `platformRpgAgentResultPreviewModel.ts`
 创作入口 -> 工作台 -> 生成页 -> 结果页 -> 试玩 -> 发布 -> 运行态
 ```
 
+后端链路也按同一条平台主干组织：所有创作、生成、作品回读、发布、试玩、正式 runtime、公开详情、作品架、运行态设置 / 存档、游玩历史、存档归档、游玩统计、历史素材、AI task、runtime chat、文档解析、角色资产工坊和玩法生成支撑资产相关 HTTP 路由，先注册到 `server-rs/crates/api-server/src/modules/play_flow.rs`，由主干在进入领域 handler 前统一解析 `PlayFlowRequestContext`，再在最后一步分发给对应领域模块或支撑能力 handler 处理。`app.rs` 不再逐玩法挂载创作 / 运行态路由，`modules/platform.rs` 只保留通用 LLM / 语音代理；新增玩法、补齐旧玩法或迁移旧路径时，必须先补 `play_flow` 的 `playId`、领域模块 key、创作路由前缀、运行态路由前缀和入口开关匹配规则，再补具体 handler。领域规则、胜负裁决、计分、发布状态、资产完整性和排行榜仍留在各自 `module-*` 与 SpacetimeDB procedure 中，不把平台主干写成某个玩法的新业务真相。
+
 默认工作台只提交结构化表单、图片槽位和配置 payload，不默认增加聊天输入区、流式消息区或轻输入 Agent。确需偏离该模式时，必须先在 PRD 和本文档写明例外原因、影响范围和回退方式，再进入编码。
 
 单图资产编辑统一通过 `CreativeImageInputPanel` 承载上传、AI 重绘、参考图、历史图、主图预览和删除确认；新玩法页面不得重复手写这些交互。主图已有图片时，默认点击图片打开全屏预览，上传 / 更换收口到右下角 `ImagePlus` 图标按钮；无图时仍允许点击空图卡上传。调用方只能通过 `canUploadMainImage`、`canUseImageHistory` 等受控参数开关上传和历史入口，不得用复制组件或样式遮挡改行为。系列素材图集生成统一走“批量规划 -> sheet 生图 -> 后端切图 -> 透明化 -> OSS 持久化 -> 状态回写 -> 局部重生成”流程，玩法只提供 `sheetSpec`、`slotSpecs`、提示词和字段映射，不把任一玩法专属素材 DTO 当作平台通用模型。