Merge remote-tracking branch 'origin/master' into codex/wechat-mini-program-virtual-payment

# Conflicts:
#	.hermes/shared-memory/decision-log.md

.hermes/shared-memory/decision-log.md

@@ -24,12 +24,45 @@
 - 验证方式：泥点和会员商品在小程序运行态都请求 `wechat_mp_virtual`；小程序页能按 payload 调用 `wx.requestVirtualPayment` / `wx.requestPayment`；`cargo check -p api-server --manifest-path server-rs/Cargo.toml` 与支付相关前端测试通过。
 - 关联文档：`docs/【技术方案】微信虚拟支付接入-2026-05-26.md`。
 
+## 2026-05-26 平台跨流程错误统一用可复制来源弹窗展示
+
+- 背景：拼图等生成链路可能同时存在多个草稿或游玩实例，页面内裸错误 banner 容易让用户误以为当前正在看的拼图失败，也不方便复制完整错误给开发排查。
+- 决策：平台入口、生成页、结果页、作品详情、作品架和运行态的跨流程错误统一收口到 `PlatformErrorDialog`；弹窗必须带错误来源，例如某个草稿、生成会话、作品详情或游玩实例，并提供复制按钮复制来源与错误内容。页面内旧的裸错误 banner、创作入口 modal 错误、生成页错误徽标等不再重复展示；表单校验和发布确认弹窗里的局部业务错误仍可保留在原弹窗内。
+- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/PlatformErrorDialog.tsx`、`src/components/CustomWorldGenerationView.tsx`、`src/components/custom-world-home/CustomWorldCreationHub.tsx`、`src/components/custom-world-home/CustomWorldCreationStartCard.tsx`、`src/components/platform-entry/PlatformWorkDetailView.tsx`、`src/components/platform-entry/PlatformEntryCreationTypeModal.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`。
+- 验证方式：`npm run test -- src/components/platform-entry/PlatformErrorDialog.test.tsx src/components/platform-entry/PlatformEntryCreationTypeModal.test.tsx`、`npm run typecheck`、`npm run check:encoding` 通过；手测时异步失败应弹出包含“错误来源”和“错误内容”的弹窗，复制按钮应复制完整诊断文本。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-26 生成任务完成在离开生成页后弹独立完成弹窗
+
+- 背景：抓大鹅、拼图等生成任务完成时，用户如果已经离开生成页，草稿页的未读红点不足以表达“这次生成已完成”；但如果用户仍停留在生成页，结果页或试玩页本身就是完成反馈，不需要再叠一个成功提示。
+- 决策：平台壳层在 `markDraftReady(..., viewedImmediately=false)` 时额外弹出 `PlatformTaskCompletionDialog`，完成弹窗必须带来源和复制按钮；如果 `viewedImmediately=true`，只保留结果页 / 试玩页本身的完成反馈和草稿未读态，不重复弹窗。
+- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/PlatformTaskCompletionDialog.tsx`、`src/components/platform-entry/PlatformErrorDialog.test.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+- 验证方式：`npm run test -- src/components/platform-entry/PlatformErrorDialog.test.tsx`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "completed match3d draft"` 通过后，离开生成页再完成的草稿应出现“生成完成”弹窗，且复制内容包含来源与状态。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-26 “我的”页任务卡读后端任务摘要并移除常驻填邀请码入口
+
+- 背景：移动端“我的”页每日任务卡曾硬编码 `0 / 1`，任务领取完成后只刷新弹窗内任务中心，卡片本身不更新；页面底部还保留旧的“填邀请码”次级按钮，和当前五项常用功能宫格口径重复。
+- 决策：`RpgEntryHomeView` 的每日任务卡以 `/api/profile/tasks` 返回的任务中心为事实源，展示当前可操作任务的奖励、进度和状态；领取成功后同步使用 claim 响应里的 `center` 刷新卡片。移动端“我的”页不再渲染常驻“填邀请码”次级入口，邀请码填写仅保留邀请链接 query 自动打开弹窗和其它明确引导。
+- 影响范围：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。
+- 验证方式：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx` 应断言任务卡显示 `1 / 1`、领取后显示已完成，且新用户账号也没有 `次级入口` / `填邀请码` 常驻按钮；`npm run typecheck`、`npm run check:encoding` 通过。
+- 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。
+## 2026-05-26 生成页总进度圆弧逆时针回调 5 度
+
+- 背景：创作生成页的总进度圆弧在 `160deg` 位置仍需轻微向左微调，用户要求向左逆时针回调 `5deg`。
+- 决策：共用 `GenerationProgressHero` 的 SVG 圆弧起始角从 `160deg` 调整为 `155deg`，track 和 fill 都使用同一个 `rotate(155 200 200)` 变换；仍保持 `270deg` 扫描角和正下方 `90deg` 留空。
+- 决策：总进度标题与百分比数字在 `GenerationProgressHero` 中显式提升到圆环之上，圆环 SVG 维持背景层级。
+- 决策：总进度标题与百分比数字的内容区上边距从 `pt-[4%]` 收紧到 `pt-[2%]`，桌面端使用 `sm:pt-[1.5%]`，进一步拉开与圆环弧线的距离。
+- 影响范围：`src/components/GenerationProgressHero.tsx`、共用 `CustomWorldGenerationView`、汪汪声浪 `BarkBattleGeneratingView` 以及生成页圆环布局文档。
+- 验证方式：`CustomWorldGenerationView` 和 `BarkBattleGeneratingView` 测试断言 `data-ring-start-degrees=155` 且 track / fill transform 都是 `rotate(155 200 200)`。
+- 关联文档：`docs/【玩法创作】生成页圆环布局口径-2026-05-23.md`。
+
 ## 2026-05-25 抓大鹅发现页官方 demo 使用静态资源与本地运行态
 
-- 背景：本轮抓大鹅资源管线已经生成完整 `level-scene`、背景、UI spritesheet、物品 spritesheet 和切片资源，需要放入发现页作为可试玩验证入口，但不应把一次性本地资源包装成后端正式作品。
+- 背景：本轮抓大鹅资源管线曾生成一套官方静态 demo，用于验证生图、切图和运行态资源闭环，但该 demo 已被移除，不再作为发现页入口。
-- 决策：发现页官方抓大鹅 demo 固定 profileId 为 `match3d-demo-20260525`、公开作品号为 `M3-20260525`，资源读取 `public/match3d-demo/undersea-candy-market/` 下的静态文件。公开卡片、作品号搜索和详情页沿用平台公开作品详情链路；启动运行态时用 `createLocalMatch3DRuntimeAdapter`，不调用正式 Match3D runtime 后端、不新增 SpacetimeDB schema、不写正式作品统计。
+- 决策：发现页不再挂载前端固定官方抓大鹅 demo；公开卡片、作品号搜索、详情页和运行态启动全部来自后端真实 profile / gallery 投影，正式作品统一走 server runtime adapter。
-- 影响范围：`src/data/match3dDemoGalleryCard.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、发现页公开卡片、作品号搜索、Match3D 本地 runtime adapter、玩法链路文档。
+- 影响范围：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、原前端 demo 数据文件（已删除）、Match3D 相关测试与原静态资源目录（已删除）。
-- 验证方式：搜索 `M3-20260525` 能打开“海底糖果集市”并启动本地抓大鹅运行态；正式 Match3D 公开作品仍走 server runtime adapter。
+- 验证方式：发现页不再出现原固定 demo；Match3D 公共详情只从真实后端作品数据读取。
 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
 ## 2026-05-25 抓大鹅运行态 HUD 收敛为拼图同款低遮挡样式
@@ -152,6 +185,14 @@
 - 验证方式：执行 `cargo test -p api-server wooden_fish --manifest-path server-rs/Cargo.toml`、`cargo test -p spacetime-client wooden_fish --manifest-path server-rs/Cargo.toml`、`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run typecheck`。
 - 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 2026-05-25 通用系列素材图集实现下沉到 platform-image
+
+- 背景：`generated_asset_sheets` 同时承载 sheet prompt、切图、绿幕去背、边缘 matte 清理和 OSS 持久化准备，长期放在 `api-server` 会把多个玩法的图片 seam 继续绑死在 HTTP crate 上。
+- 决策：通用系列素材图集的实现真值源下沉到 `platform-image::generated_asset_sheets`，`api-server::generated_asset_sheets` 只保留 `AppState` / `AppError` 适配与调用方兼容导出，不再承载图像处理和 OSS 请求构造细节。
+- 影响范围：`server-rs/crates/platform-image/src/generated_asset_sheets/`、`server-rs/crates/api-server/src/generated_asset_sheets.rs`、`server-rs/crates/api-server/src/match3d/item_assets.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+- 验证方式：`cargo test -p platform-image --test generated_asset_sheets --manifest-path server-rs/Cargo.toml` 与 `cargo check -p api-server --manifest-path server-rs/Cargo.toml` 通过；调用方继续通过 `api-server` 的薄包装访问同一组能力。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 2026-05-22 敲木鱼敲击物暂不做服务端抠图后处理
 
 - 背景：gpt-image-2 偶尔会把木鱼图直接回成带黑底或其它实底背景的 PNG，但服务端抠图后处理在玉米等主题上误伤过主体像素。
@@ -180,11 +221,19 @@
 ## 2026-05-25 VectorEngine 图片 provider 收到 platform-image
 
 - 背景：`api-server` 里原本同时混着 VectorEngine 创建 / 编辑协议、响应解析、远端图片下载、失败日志和审计落库逻辑，Puzzle / Match3D 还各自藏着一份近似实现，导致“provider 协议”和“业务编排”边界不清。
-- 决策：把 VectorEngine `gpt-image-2` 图片 provider 协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志统一收口到 `server-rs/crates/platform-image`。`api-server` 只保留配置校验、玩法 prompt 编排、OSS / asset object / binding 持久化、计费和外部 API 失败审计桥接；旧 `openai_image_generation.rs` 只作为兼容转接层，不再承担 provider 实现。
+- 决策：把 VectorEngine `gpt-image-2` 图片 provider 协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志统一收口到 `server-rs/crates/platform-image/src/vector_engine/`，并按 `client.rs`、`transport.rs`、`request.rs`、`payload.rs`、`response.rs`、`image_source.rs` 等小模块拆分，避免把大文件从 `api-server` 平移到平台 crate。`api-server` 只保留配置校验、玩法 prompt 编排、OSS / asset object / binding 持久化、计费和外部 API 失败审计桥接；旧 `openai_image_generation.rs` 只作为兼容转接层，不再承担 provider 实现。
 - 影响范围：`server-rs/crates/platform-image`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`server-rs/crates/api-server/src/puzzle/vector_engine.rs`、`server-rs/crates/api-server/src/external_api_audit.rs`、后端架构与运维文档。
-- 验证方式：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo test -p api-server puzzle --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
+- 验证方式：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-image --test vector_engine --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## 2026-05-26 音频 provider 协议收口到 platform-audio，Hyper3D 继续保持薄代理
+
+- 背景：`api-server/src/vector_engine_audio_generation.rs` 和 `api-server/src/hyper3d_generation.rs` 仍然承担太多 provider 细节，容易把外部协议、下载、解析和 BFF 编排混在一起。
+- 决策：VectorEngine Suno/Vidu 音频协议、任务提交/轮询、下载和 OSS 持久化请求准备收口到 `platform-audio`，并继续按 `client.rs`、`request.rs`、`response.rs`、`download.rs`、`persist.rs`、`error.rs` 拆小模块；`api-server` 只保留路由、配置、计费、asset_object confirm、entity binding 和错误映射。Hyper3D 维持后端安全代理和旧数据兼容，`platform-hyper3d` 承接 Rodin 的协议与解析，`api-server` 仅做薄 wrapper。
+- 影响范围：`server-rs/crates/platform-audio/`、`server-rs/crates/platform-hyper3d/`、`server-rs/crates/api-server/src/vector_engine_audio_generation.rs`、`server-rs/crates/api-server/src/hyper3d_generation.rs`、相关后端架构文档。
+- 验证方式：`cargo test -p platform-audio --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-hyper3d --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml` 通过；`api-server` 不再包含音频 provider 协议和 Hyper3D parser 主实现。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【后端架构】复杂媒体资产链路Adapter扩展计划-2026-05-14.md`。
+
 ## 2026-05-21 拼图参考图主链改为 OSS assetObjectId 与只读签名 URL
 
 - 背景：release 上拼图图生图生成草稿时，旧链路把上传图转成 Data URL/base64 放进创作 action JSON body，容易先触发 Nginx `413 Request Entity Too Large`，也让外部模型调用前的 HTTP body 过大。
@@ -540,6 +589,13 @@
 - 验证方式：执行 `npm run check:encoding`、`node scripts/check-wechat-miniprogram-auth-smoke.mjs`、`cargo test -p shared-contracts wechat_bind_phone_request_accepts_mini_program_phone_code --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server wechat_miniprogram_bind_phone_code_activates_pending_user --manifest-path server-rs/Cargo.toml -- --nocapture`。
 - 关联文档：`docs/technical/WECHAT_MINIPROGRAM_WEB_VIEW_SHELL_2026-05-03.md`。
 
+## 2026-05-26 微信小程序进入即开 H5，登录按需走原生手机号授权
+
+- 背景：当前产品要求微信小程序进入后不再立刻取手机号，而是默认直接进入 `web-view`，登录状态与 Web 端统一；只有 H5 触发受保护操作时才走微信手机号授权。
+- 决策：小程序壳首次进入只打开 H5，不再把登录态当作启动前置条件；H5 侧在小程序运行态触发登录时，不展示普通登录弹窗，而是跳转到小程序原生手机号授权流程，授权结果再回灌到 H5。未触发登录时保持游客态，与 Web 端一致。
+- 影响范围：`miniprogram/pages/web-view/index.*`、`src/components/auth/AuthGate.tsx`、`src/components/auth/LoginScreen.tsx`、`src/services/authService.ts`、相关测试与说明文档。
+- 验证方式：执行 `npm run check:encoding`、`npm run typecheck`、`npx vitest run src/components/auth/AuthGate.test.tsx src/services/authService.test.ts scripts/miniprogram-web-view-auth.test.ts`。
+
 ## 2026-05-13 宝贝爱画先作为寓教于乐独立本地 Demo 落地
 
 - 背景：第三关 `宝贝爱画` 需要默认出现在“发现 / 寓教于乐”板块下方，但本阶段只验证画板、手部绘制、绘画魔法和本地保存闭环，不进入创作模板、公开作品或正式持久化。
@@ -957,6 +1013,14 @@
 - 验证方式：从平台推荐或公开详情进入跳一跳作品时，路由 source type 为 `jump-hop`、public code 为 `JH-*`，运行态启动消费后端返回的完整 profile / run 数据；后端 smoke 统一使用 `npm run dev:api-server` 启动并检查 `/healthz`。
 - 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
 
+## 2026-05-26 跳一跳地块图集改为专用 2x3 六格切分
+
+- 背景：跳一跳创作在地块生图阶段误用了通用系列素材图集 helper，`item_names.len() > grid_size` 的校验会让 6 个地块类型在 `grid_size = 3` 时直接失败；即使绕过校验，通用 helper 仍以“每物品多视图”语义切图，不符合跳一跳地块的一次性六格资产模型。
+- 决策：跳一跳地块图集固定采用专用 `2行*3列` 六格布局，按 `start / normal / target / finish / bonus / accent` 顺序切分并分别持久化为独立 PNG 资产；图集 prompt 不再调用通用系列素材 `build_generated_asset_sheet_prompt`。
+- 影响范围：`server-rs/crates/api-server/src/jump_hop.rs`、`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+- 验证方式：`cargo test -p api-server jump_hop_tile_atlas -- --nocapture` 通过；六张切片都应有独立 OSS 对象与 `JumpHopTileAsset` 记录，不再只有 atlas 预览路径。
+- 关联文档：`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`。
+
 # 2026-05-20 陶泥儿主视觉配色回收为暖白/陶土橙
 
 - 背景：用户要求只替换产品各界面的 UI 颜色，不改布局，并以两张陶泥儿主视觉图作为配色依据。
@@ -1000,3 +1064,18 @@
 - 影响范围：`WoodenFishWorkspace`、`WoodenFishResultView`、`PlatformEntryFlowShellImpl`、敲木鱼 PRD 和平台入口链路文档。
 - 验证方式：工作台首屏不再出现标题 / 简介 / 标签输入；结果页修改后点试玩或发布会先写回当前作品信息。
 - 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-26 前端不外露图片模型名
+
+- 背景：拼图与相关结果页、生成进度和错误提示里直接显示 `gpt-image-2`、`gemini-3.1-flash-image-preview`、`image-2` 等名称，会把内部模型路由暴露给普通用户。
+- 决策：前端展示层统一改用产品化名称，如“标准模式”“创意模式”，以及“素材”“图片生成模式”等中性文案；内部 `imageModel`、`generationProvider` 和后端契约值保留不变，只改 UI 文案与错误提示。
+- 影响范围：拼图图片模型选择器、拼图结果页关卡重生成面板、拼图生成进度文案、宝贝识物结果页占位提示和相关错误提示。
+- 验证方式：前端可见文本中不再出现 `gpt-image-2` / `gemini-3.1-flash-image-preview` / `image-2 资源`；相关交互测试改为断言产品化模式名，但提交 payload 仍保持原有模型 ID。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+## 2026-05-26 敲木鱼发布后作品架与推荐流刷新口径
+
+- 背景：敲木鱼已具备公开广场投影，但草稿 Tab 的作品架没有当前用户作品列表接口，导致已发布作品在发布后不能立即出现在“已发布”筛选和推荐流里。
+- 决策：新增 `GET /api/creation/wooden-fish/works` 作为当前用户木鱼作品架事实源，返回 `WoodenFishWorksResponse.items` 摘要；平台壳在发布成功后必须同时刷新作品架和公开广场列表。
+- 影响范围：`server-rs/crates/api-server/src/wooden_fish.rs`、`server-rs/crates/api-server/src/modules/wooden_fish.rs`、`src/services/wooden-fish/woodenFishClient.ts`、`src/components/custom-world-home/creationWorkShelf.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`。
+- 验证方式：发布一个木鱼作品后，草稿 Tab 的已发布筛选应立刻出现 `WF-*` 作品卡，推荐 / 最新流也应立即刷新出公开卡片。
+- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`。

.hermes/shared-memory/pitfalls.md

@@ -15,6 +15,30 @@
 - 关联：相关文件、文档、提交或 Issue
 ```
 
+## 平台异步错误必须带来源弹窗，不要只显示裸错误
+
+- 现象：用户先后触发多个拼图或草稿生成时，旧请求失败后会在当前页面显示“图片生成失败”等裸错误，容易误判为当前正在看的拼图失败；错误文本也不便复制给开发排查。
+- 原因：不同入口、生成页、结果页、作品详情和运行态各自渲染局部错误，没有统一携带草稿、生成会话、作品或游玩来源。
+- 处理：跨流程错误统一由 `PlatformEntryFlowShellImpl` 汇总为 `PlatformErrorDialog`，来源使用玩法、草稿 / session / work / run 标识组成；弹窗提供复制按钮。关闭弹窗时只清理可安全清理的错误状态；恢复类错误用 dismiss key 防止反复弹出但不擅自改底层状态。
+- 验证：触发任一平台级异步失败时，页面应出现包含“错误来源”和“错误内容”的弹窗；复制内容应包含来源和错误正文；旧页面内错误 banner 不再重复出现。
+- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/PlatformErrorDialog.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## “我的”页每日任务卡不要硬编码进度
+
+- 现象：用户完成或领取每日任务后，任务中心弹窗里的任务状态已经变化，但“我的”页卡片仍显示 `0 / 1` 和“去完成”。
+- 原因：卡片首版只写了静态展示文案，没有读取 `/api/profile/tasks` 返回的 `ProfileTaskCenterResponse`，领取接口返回的新 `center` 也只用于弹窗。
+- 处理：进入“我的”页时读取任务中心，卡片用当前可操作任务或已领取任务派生奖励、进度条和操作状态；`claimRpgProfileTaskReward(...)` 成功后用响应里的 `center` 覆盖本地任务中心。
+- 验证：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx` 应覆盖卡片从后端任务摘要显示 `1 / 1`，领取后显示已完成。
+- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。
+
+## “我的”页不要恢复旧的填邀请码次级按钮
+
+- 现象：移动端“我的”页在五项常用功能和设置入口下方又出现一个“填邀请码”按钮，看起来像旧入口残留。
+- 原因：邀请码流程迁移后仍按新用户窗口保留 `canShowReferralRedeemShortcut` 次级入口；但当前页面口径已经固定为五项常用功能宫格，邀请码填写应由邀请链接 query 或明确引导打开弹窗。
+- 处理：移除常驻 `次级入口` / `填邀请码` 渲染，不删除 `ProfileReferralModal` 的 `redeem` 面板，也不破坏 `?inviteCode=` / `?invite_code=` 自动打开填写弹窗。
+- 验证：新用户账号打开“我的”页时没有 `次级入口` 和 `填邀请码` 按钮；带 `?inviteCode=spring-2026` 的登录用户仍自动打开邀请码弹窗并预填 `SPRING2026`。
+- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`.hermes/skills/genarrative-profile-invite-flow/SKILL.md`。
+
 ## 创作卡片点击要直达已有入口表单，别再保留空白入口页
 
 - 现象：创作 Tab 模板卡点击后如果仍然停留在创作大厅，或者先进入“X 创作入口”这种空白页，就会让用户多走一层，还可能被错误的 stage 白名单拉回平台。
@@ -126,6 +150,14 @@
 - 验证：`npm run test -- src/components/match3d-runtime/Match3DRuntimeShell.test.tsx` 应覆盖“运行态不把兼容写入的UI spritesheet当中心容器图”。
 - 关联：`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`server-rs/crates/api-server/src/match3d/mappers.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 通用系列素材图集先看 platform-image，不要先翻 api-server 大文件
+
+- 现象：排查跳一跳、抓大鹅或其它玩法的系列素材图集切片 / 去绿 / 持久化时，最容易先打开 `api-server/src/generated_asset_sheets.rs`，结果在一个 60KB+ 大文件里找实现、测试和辅助函数，定位很慢。
+- 原因：这条通用图片 seam 已经下沉到 `server-rs/crates/platform-image/src/generated_asset_sheets/`，`api-server` 只剩薄包装和调用方兼容；继续把 `api-server` 当真值源会把理解路径拉回旧位置。
+- 处理：先看 `server-rs/crates/platform-image/src/generated_asset_sheets/mod.rs`、`prompt.rs`、`sheet.rs`、`alpha.rs`、`persist.rs` 和 `error.rs`，再看 `api-server/src/generated_asset_sheets.rs` 的 AppError / AppState 适配和玩法调用点。
+- 验证：`cargo test -p platform-image --test generated_asset_sheets --manifest-path server-rs/Cargo.toml` 通过，且 `cargo check -p api-server --manifest-path server-rs/Cargo.toml` 保持绿灯。
+- 关联：`server-rs/crates/platform-image/src/generated_asset_sheets/`、`server-rs/crates/api-server/src/generated_asset_sheets.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## UI spritesheet 不要依赖模型直接生成透明背景
 
 - 现象：拼图或抓大鹅运行态解析 UI spritesheet 时，把整张背景图、棋盘格、叶子或装饰图也当作 UI 素材区域，按钮映射错乱；截图里常表现为底部按钮区只剩透明棋盘格或素材碎片。
@@ -293,9 +325,25 @@
 
 - 现象：排查拼图或其它玩法的生图失败时，如果直接在 `api-server` 的大文件里找 `images/generations`、`images/edits`、base64 解码或下载逻辑，会看到很多历史 helper 和测试桥，看起来像每个玩法都自带一份 provider 实现。
 - 原因：旧实现把 VectorEngine 图片 provider 协议、响应解析、下载和日志混在 `api-server` 里，后来虽然迁出到 `platform-image`，但兼容层和测试 helper 仍会让人误判真相源位置。
-- 处理：先看 `server-rs/crates/platform-image/src/lib.rs` 的 provider 协议和结构化日志，再看 `server-rs/crates/api-server/src/openai_image_generation.rs` 的兼容桥和 `external_api_audit.rs` 的落库映射；`puzzle/vector_engine.rs` 只保留玩法编排，不再作为 provider 协议真相源。
+- 处理：先看 `server-rs/crates/platform-image/src/vector_engine/`：`request.rs` 查路径和请求体，`client.rs` 查生成 / 编辑编排，`transport.rs` 查 HTTP client 与 reqwest 错误归一，`payload.rs` 查响应字段提取，`response.rs` 查上游状态、解析、缺图和下载分流，`image_source.rs` 查参考图和远端图片下载。再看 `server-rs/crates/api-server/src/openai_image_generation.rs` 的兼容桥和 `external_api_audit.rs` 的落库映射；`puzzle/vector_engine.rs` 只保留玩法编排，不再作为 provider 协议真相源。
-- 验证：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml -- --nocapture`、`cargo test -p api-server puzzle --manifest-path server-rs/Cargo.toml -- --nocapture` 通过时，排障先按 `platform-image` 的日志字段查 provider / endpoint / failure_stage。
+- 验证：`cargo test -p platform-image --manifest-path server-rs/Cargo.toml`、`cargo test -p platform-image --test vector_engine --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml -- --nocapture` 通过时，排障先按 `platform-image` 的日志字段查 provider / endpoint / failure_stage。
-- 关联：`server-rs/crates/platform-image/src/lib.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/puzzle/vector_engine.rs`。
+- 关联：`server-rs/crates/platform-image/src/vector_engine/`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/puzzle/vector_engine.rs`。
+
+## 音频 provider 协议先看 platform-audio，不要先翻 api-server 大文件
+
+- 现象：排查 Visual Novel 或通用创作音频生成失败时，如果直接打开 `api-server/src/vector_engine_audio_generation.rs`，会同时看到路由、计费、asset binding、下载、解析和 provider 协议，定位时很容易在同一个文件里来回跳。
+- 原因：音频 provider 已经迁到 `server-rs/crates/platform-audio/`，但 `api-server` 仍保留薄 wrapper；如果把 wrapper 当真值源，就会误判边界。
+- 处理：先看 `server-rs/crates/platform-audio/src/client.rs`、`request.rs`、`response.rs`、`download.rs`、`persist.rs`、`error.rs`，再看 `api-server/src/vector_engine_audio_generation.rs` 的路由、配置、计费、asset object confirm 和 entity binding 包裹。
+- 验证：`cargo test -p platform-audio --manifest-path server-rs/Cargo.toml` 通过，且 `cargo check -p api-server --manifest-path server-rs/Cargo.toml` 保持绿灯。
+- 关联：`server-rs/crates/platform-audio/`、`server-rs/crates/api-server/src/vector_engine_audio_generation.rs`。
+
+## Hyper3D 现在只剩后端薄代理，不要再把协议解析写回 api-server
+
+- 现象：排查 Hyper3D/Rodin 时，如果继续在 `api-server/src/hyper3d_generation.rs` 里扩协议解析、请求体构造或下载列表处理，文件会重新变厚。
+- 原因：`platform-hyper3d` 已经承接 Rodin 的提交、状态和下载协议解析；`api-server` 只是薄 wrapper 和错误 envelope 映射。
+- 处理：新增或修改 Hyper3D 协议时优先放到 `server-rs/crates/platform-hyper3d/` 的 `client.rs`、`request.rs`、`response.rs`、`transport.rs` 和子模块，`api-server` 只保留鉴权、配置校验和错误映射。
+- 验证：`cargo test -p platform-hyper3d --manifest-path server-rs/Cargo.toml` 通过后再看 `cargo check -p api-server --manifest-path server-rs/Cargo.toml`。
+- 关联：`server-rs/crates/platform-hyper3d/`、`server-rs/crates/api-server/src/hyper3d_generation.rs`。
 
 ## release 创作接口 413 先查是否还在提交 Data URL
 
@@ -1090,6 +1138,22 @@
 - 验证：`PuzzleResultView` 单测覆盖发布弹窗内展示 `泥点余额不足`。
 - 关联：`src/components/puzzle-result/PuzzleResultView.tsx`、`docs/technical/PUZZLE_RESULT_AUTOSAVE_AND_TAG_GATE_FIX_2026-04-28.md`、`docs/technical/ASSET_GENERATION_POINTS_CONSUMPTION_2026-04-27.md`。
 
+## 拼图发布检查阶段会在事件落库时炸 wasm
+
+- 现象：拼图发布在“发布检查”环节直接报 `The module instance encountered a fatal error`，wasm backtrace 指向 `spacetime_module::puzzle::publish_puzzle_work`，并停在 `procedure_commit_mut_tx` 的 commit 阶段。
+- 原因：`publish_puzzle_work_tx` 会无条件调用 `emit_puzzle_work_published_event` 写入 `puzzle_event`；该表的 `event_id` 是主键，而事件 ID 由 `profile_id + published_at_micros` 组成。只要同一发布动作被重复执行、重放，或极端情况下发生时间戳碰撞，commit 时就会因主键冲突触发 fatal error。
+- 处理：待修复。发布事件写入需要改成幂等，或在重复发布时显式跳过已存在的 `event_id`；发布动作本身也应补一层更明确的幂等键，避免把重复提交直接推到事务提交阶段。
+- 验证：对同一 `session_id/profile_id/published_at_micros` 重复调用 `publish_puzzle_work` 时，不应再在 commit 阶段炸 wasm；正常发布仍应生成作品、更新 session，并可进入公开详情。
+- 关联：`server-rs/crates/spacetime-module/src/puzzle.rs`、`server-rs/crates/api-server/src/puzzle/handlers.rs`、`server-rs/crates/spacetime-client/src/module_bindings/puzzle_event_table.rs`。
+
+## 拼图会过早进入待发布态，结果页可能空图但仍显示可发布
+
+- 现象：拼图创作有时刚结束就跳到“待发布”结果页，但结果页里的正式图还是空的，发布检查随后又会拦住，用户会感觉“已经完成了却又不能发布”。
+- 原因：拼图的待发布判定太弱，`build_result_preview` / `validate_publish_requirements` 和 `is_puzzle_session_snapshot_publish_ready` 只检查了作品名、简介、标签、关卡名和 cover 图，没有要求 `level_scene_image_src`、`ui_spritesheet_image_src`、`level_background_image_src` 等完整资产都齐；前端恢复链路里的 `hasRecoverableGeneratedPuzzleDraft` / `normalizeRecoveredPuzzleDraftSession` 也只要有 cover 或候选图就会把草稿当成已完成。
+- 处理：待修复时要把“待发布”门槛收紧到整套拼图资产包完整，再让恢复逻辑只在完整草稿下抬高为完成态，避免半成品直接进入结果页。
+- 验证：当某个拼图草稿只补齐首图、但关卡背景或 UI spritesheet 仍缺失时，不应再进入 `ready_to_publish`；结果页也不应把这类草稿误判为已完成。
+- 关联：`server-rs/crates/module-puzzle/src/application.rs`、`server-rs/crates/api-server/src/puzzle/tags.rs`、`server-rs/crates/api-server/src/puzzle/draft.rs`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`。
+
 ## WebGL 画布在高 DPR 移动端放大溢出
 
 - 现象：抓大鹅试玩入口进入后，3D 锅体和物体从中心圆形区域向右下溢出，顶部状态和底部备选栏也可能看起来被右侧裁切。
@@ -1460,6 +1524,14 @@
 - 验证：`npm run typecheck`，并跑 `npm test -- src/routing/appPageRoutes.test.ts` 覆盖 JumpHop 阶段路径。
 - 关联：`src/components/platform-entry/platformEntryTypes.ts`、`src/routing/appPageRoutes.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 跳一跳地块图集不要套通用系列素材 n 行模型
+
+- 现象：跳一跳初始草稿生成时报 `系列素材图集的物品行数不能超过 n。`，或者即使绕过报错也只生成了 atlas 预览路径，地块切片没有真正落盘。
+- 原因：跳一跳地块只有 6 个固定 tileType，但旧实现把它塞进通用系列素材 helper，并使用 `grid_size = 3` / `item_names = 6` 的语义冲突模型；随后又只保留 atlas 资产与模拟路径，没把六个切片逐一上传并确认到 `JumpHopTileAsset`。
+- 处理：跳一跳地块改用专用 `2行*3列` 图集 prompt，按 `start / normal / target / finish / bonus / accent` 顺序切 6 张 PNG，并对每张切片各自走 OSS 上传、asset_object 确认和 entity bind。
+- 验证：`cargo test -p api-server jump_hop_tile_atlas -- --nocapture` 通过后，再看 `jump_hop.rs` 不应再调用 `build_generated_asset_sheet_prompt` 处理地块图集；公开结果里应能拿到 6 个独立 `JumpHopTileAsset`。
+- 关联：`server-rs/crates/api-server/src/jump_hop.rs`、`docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## image2 dry-run 带参考图时不要直接打印 data URL
 
 - 现象：使用 VectorEngine `gpt-image-2-all` 生成带参考图的概念图时，如果 dry-run 直接打印完整请求体，参考图会被转成超长 `data:image/png;base64,...`，终端日志会被数百万字符淹没。
@@ -1535,3 +1607,11 @@
 - 处理：后续如果需要重新暴露存档入口，优先评估是否应回到“玩过”或别的独立弹窗流程，不要默认把存档再塞回常用功能宫格或设置列表。
 - 验证：`npm test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "mobile profile page matches the reference layout sections|profile scan action opens camera scanner instead of recharge panel"`。
 - 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 访客推荐页上下滑不要绑定登录态
+
+- 现象：访客模式进入移动端推荐页后，推荐内容可展示和点击底部“下一个”，但在作品信息区域上下滑不会切换推荐作品，表现为推荐页不能上下滑动。
+- 原因：推荐页滑动切换逻辑 `beginRecommendDrag(...)` 误把 `isAuthenticated` 作为启用条件；访客态虽然允许浏览和通过底部按钮切换，却无法触发同一套拖拽切换。
+- 处理：推荐页拖拽只校验当前是否有作品、多作品可切换以及是否正在提交动画，不再要求登录；登录态相关操作仍由点赞、改造等按钮自身权限控制。
+- 验证：`npx vitest run src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx` 覆盖访客态纵向滑动不弹登录且触发下一条推荐。
+- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`。

docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md

@@ -276,6 +276,7 @@ HTTP 路由：
 POST /api/creation/wooden-fish/sessions
 GET  /api/creation/wooden-fish/sessions/{sessionId}
 POST /api/creation/wooden-fish/sessions/{sessionId}/actions
+GET  /api/creation/wooden-fish/works
 GET  /api/creation/wooden-fish/works/{profileId}
 POST /api/creation/wooden-fish/works/{profileId}/publish
 GET  /api/runtime/wooden-fish/works/{profileId}
@@ -304,6 +305,8 @@ finish
 
 敲木鱼创作请求在前端必须使用长等待窗口，避免 `createSession` 或 `executeAction` 仍沿用共享创作工厂默认的 15 秒超时。因为 `compile-draft` 会串行等待敲击物、背景、返回按钮三次 image2 和 OSS 落库，木鱼 client 需要单独配置与整条 image2 链路匹配的超时。本地测试中该 action 可能达到数分钟级；生成页进度必须按“整理草稿 -> 生成敲击物 -> 生成背景环境图 -> 生成返回按钮图 -> 写入正式草稿”展示，不展示“提示词生成音效”阶段，因为当前木鱼音效只支持上传、录音或默认音。
 
+作品架使用 `GET /api/creation/wooden-fish/works` 读取当前用户草稿和已发布摘要，前端发布成功后必须刷新该列表和 `GET /api/runtime/wooden-fish/gallery` 公开列表，使刚发布作品立即出现在草稿 Tab 的已发布筛选和推荐 / 最新流中。
+
 ## 9. SpacetimeDB 表和 view
 
 新增表：

docs/prd/【玩法创作】跳一跳俯视角玩法模板PRD-2026-05-19.md

@@ -168,7 +168,7 @@ jump-hop-gallery-detail
 
 ### 6.2 地块只生一次图集
 
-地块必须只调用一次生图，输出一张 3D 视图的 2D 图片图集，再由后端切成运行态可用的地块资产。
+地块必须只调用一次生图，输出一张 3D 视图的 2D 图片图集，再由后端切成运行态可用的地块资产。该图集使用跳一跳专用 `2行*3列` 六格布局，不套用通用“每个物品一行、每行 n 个不同视图”的系列素材模型。
 
 地块图集要求：
 
@@ -176,17 +176,24 @@ jump-hop-gallery-detail
 2. 必须表现出顶面、侧面和投影；
 3. 必须与角色图保持同一光向；
 4. 必须有清晰的立体层次，但仍然是 2D 图片；
-5. 必须包含至少以下地块类型：
+5. 六格必须按固定顺序包含以下地块类型：
    - 起点地块；
    - 普通地块；
    - 目标地块；
-   - 终点地块。
+   - 终点地块；
+   - 奖励地块；
+   - 视觉强调地块。
 
-建议额外包含：
+固定格位为：
 
-1. 奖励地块；
+| 格位 | tileType | 语义 |
-2. 视觉强调地块；
+| --- | --- | --- |
-3. 风格化变体地块。
+| 第 1 行第 1 列 | `start` | 起点地块 |
+| 第 1 行第 2 列 | `normal` | 普通地块 |
+| 第 1 行第 3 列 | `target` | 目标地块 |
+| 第 2 行第 1 列 | `finish` | 终点地块 |
+| 第 2 行第 2 列 | `bonus` | 奖励地块 |
+| 第 2 行第 3 列 | `accent` | 视觉强调地块 |
 
 图集生成后按地块类型切分并去掉背景，运行态直接消费切好的 PNG，不在前端做复杂拼接。只有用户在结果页明确点击“重生成地块”时，才允许再调用一次地块图集生图。
 

docs/technical/【后端架构】复杂媒体资产链路Adapter扩展计划-2026-05-14.md

@@ -88,6 +88,10 @@ Adapter 只负责媒体持久化和资产绑定，不负责：
 | Custom World opening CG video | `custom_world_ai.rs` 或后续分层文件 | video | Ark/火山视频 task 结果 URL | 视频下载、OSS、confirm、binding | storyboard->video 顺序、固定点数计费、超时错误 | storyboard 图片仍走图片 Adapter，最终视频走 media persist |
 | Character visual reference/workflow | `character_visual_assets.rs` | image/cache metadata | GPT image helper、workflow cache | 可复用 media persist 的 source/OSS/confirm/binding；图片生成 provider 不迁入复杂媒体 | 角色 workflow cache 可空继续生成 | 角色视觉发布链路回包字段不变 |
 | Character animation publish/import | `character_animation_assets.rs` | video / image sequence | data:video base64、remote video、阶段占位 | data URL/base64 解码、视频 OSS、confirm、binding | stage1 placeholder 语义、import-video contract | 导入视频和发布视频都不再复制 OSS/confirm 代码 |
+
+2026-05-26 补充：图片生成 provider 不再作为复杂媒体 Adapter 的实现细节散落在 `api-server`。VectorEngine `gpt-image-2` 创建 / 编辑协议、响应解析、URL / base64 图片归一、远端下载和 provider 侧结构化失败日志已经收口到 `server-rs/crates/platform-image/src/vector_engine/`；`api-server/src/openai_image_generation.rs` 只保留配置、兼容调用面和外部失败审计桥接。后续扩展视频、音频或 Hyper3D 时，可以复用“platform crate 承接 provider 协议，api-server 承接 HTTP/BFF、计费、OSS 绑定和失败审计桥接”的分层方式，但不得把新的 provider 协议塞回 `api-server` 大文件。
+2026-05-26 补充：音频生成 provider 协议也不应继续挤在 `api-server/src/vector_engine_audio_generation.rs`。VectorEngine Suno/Vidu 的任务提交、轮询、下载、MIME/extension 归一和 OSS 持久化请求准备已经收口到 `server-rs/crates/platform-audio/`，并继续按 `client.rs`、`request.rs`、`response.rs`、`download.rs`、`persist.rs`、`error.rs` 拆成小模块；`api-server` 只保留路由、配置、计费、asset object confirm、entity binding 和错误 envelope 映射，不再承担 provider 协议和下载细节。后续若再增加音频子能力，也必须优先放进平台 crate，而不是扩张 `api-server`。
+2026-05-26 补充：Hyper3D 只保留后端安全代理和旧数据兼容，`api-server/src/hyper3d_generation.rs` 应保持薄 wrapper，`platform-hyper3d` 承接 Rodin 的提交、状态和下载协议解析。若未来要继续压缩这一条线，应优先继续下沉协议解析与 transport helper，而不是把 provider 逻辑回流到 `api-server`。
 | Match3D 背景音乐 | `match3d.rs` | audio | 现有生成/上传链路 | 仅复用音频持久化 | 不恢复 Rodin/GLB 新草稿回退 | 图片素材仍按图片 Adapter 计划处理 |
 | Puzzle 背景音乐 | `puzzle.rs` | audio | 现有生成/上传链路 | 仅复用音频持久化 | puzzle 运行态和排行榜语义不变 | `puzzle_background_music` kind/binding 不变 |
 | Hyper3D/GLB 历史代理 | `hyper3d.rs` | model/glb | Hyper3D Rodin status/download | 如存在转存需求，仅复用 media persist | Match3D 新草稿禁止回退 Rodin/GLB | 历史代理 route contract 不变 |

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

@@ -119,10 +119,10 @@ npm run check:server-rs-ddd
 2. Adapter 输入应显式包含 provider、prompt、reference images、OSS prefix/path/file name、asset kind、entity kind/id、slot、owner/profile/source job、metadata 和可选透明背景后处理。
 3. Adapter 输出应保留 legacy public path、object key、asset object id、MIME、extension、task id 和实际 prompt。
 4. Adapter 不负责扣费、退款或钱包读取；计费仍由调用方显式包裹。
-5. 图片 provider 协议不再放在玩法模块里实现。VectorEngine `gpt-image-2` 创建 / 编辑协议、URL / base64 图片解析、远端图片下载、请求超时 / 上游状态 / 响应解析 / 缺图 / 下载失败的结构化日志统一在 `server-rs/crates/platform-image`；`api-server` 只负责配置校验、玩法 prompt 编排、OSS / asset object / binding 持久化、计费和外部 API 失败审计落库。
+5. 图片 provider 协议不再放在玩法模块里实现。VectorEngine `gpt-image-2` 创建 / 编辑协议、URL / base64 图片解析、远端图片下载、请求超时 / 上游状态 / 响应解析 / 缺图 / 下载失败的结构化日志统一在 `server-rs/crates/platform-image/src/vector_engine/`；其中 `client.rs` 只保留 provider 调用编排，`transport.rs` 负责 HTTP client 与 reqwest 错误归一，`request.rs` 负责请求体和路径，`payload.rs` 负责响应 JSON 字段提取，`response.rs` 负责响应状态分流和图片结果归一。`api-server` 只负责配置校验、玩法 prompt 编排、OSS / asset object / binding 持久化、计费和外部 API 失败审计落库。
 6. Puzzle、Match3D、音频、GLB、视频等复杂媒体可以复用 OSS + asset object + binding 的底层持久化能力，但玩法专属处理规则留在各自编排层，不塞进公共接口。
 7. 拼图入口页与结果页新增关卡的本地参考图不走浏览器直传 OSS，前端读取为 Data URL 后随创作 action 提交，并在读取前限制 6MB、显示“图片≤6MB”。`api-server` 必须对 Data URL 实际字节数再次校验；历史图片才提交 `referenceImageAssetObjectId(s)`，后端校验 `asset_object` 的 bucket、kind、图片 MIME、大小和 owner 后签发只读 URL 给 VectorEngine 读取。
-8. 系列素材图集使用 `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 字段。
+8. 系列素材图集实现真相源在 `server-rs/crates/platform-image/src/generated_asset_sheets/`：调用方必须传入 `grid_size` 作为 `n*n` 的 `n`，可选传入物品名称 prompt 模板和特殊设定 prompt；模块负责 sheet prompt 组装、按 `n*n` 切片、透明化、PNG 输出、OSS private upload 请求构造和 sheet / item / special prompt 元数据持久化。`server-rs/crates/api-server/src/generated_asset_sheets.rs` 只保留 `AppState` / `AppError` 适配和兼容导出。玩法只负责规划 slot、调用具体生图 provider、计费、失败回写，以及把通用切片结果映射回自己的 DTO / 草稿 / runtime 字段。
 
 ## SpacetimeDB schema 变更规则
 
@@ -164,8 +164,8 @@ npm run check:server-rs-ddd
 - Match3D UI spritesheet 和背景派生图：关卡整图作为参考图并发生成 `1K 1:1` UI spritesheet 与 `1K 9:16` 背景图，模型均为 `gpt-image-2`。UI spritesheet prompt 固定要求纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；背景图必须合成为全画幅不透明 PNG。
 - Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。该容器参考图是后端生图协议输入，必须通过 `include_bytes!` 随 `api-server` 编译进二进制，避免 API 单独发布或运行目录缺少 `public/` 时生成失败。
 - 敲木鱼敲击物和背景环境图：VectorEngine `/v1/images/edits`，模型固定 `gpt-image-2`。敲击物支持 multipart 多参考图，第一张固定为后端内嵌默认木鱼图，用户上传图只作为新主题参考；prompt 必须要求 `1:1` 真实透明 alpha PNG 并禁止黑底、白底、棋盘格和任何实底背景。当前敲击物上传 OSS 前不做服务端抠图后处理，避免误伤玉米等主体像素。背景环境图只使用第一步抠图完成后的透明敲击物图作为参考，prompt 必须要求中央主体预留区保持干净，中央 40% 区域禁止出现主题主体、主体局部特写、轮廓影子或重复元素，主题元素只能作为外围氛围，且必须显式声明不继承任何绿色底色、绿幕底色或纯绿色画布。
-- Hyper3D / Rodin：只保留后端安全代理和旧数据兼容；新 Match3D 草稿和批量新增不再生成 GLB。
+- Hyper3D / Rodin：只保留后端安全代理和旧数据兼容；Rodin 提交、状态、下载和响应解析归属 `platform-hyper3d`，`api-server/src/hyper3d_generation.rs` 只做路由、配置和错误 envelope 映射；新 Match3D 草稿和批量新增不再生成 GLB。
-- 音频：视觉小说专用音频路由保留；拼图、抓大鹅和敲木鱼提示词生成音效入口暂时关闭，通用 `/api/creation/audio/*` 对这些目标返回 `410 Gone`。敲木鱼创作只接收上传 / 录音音频资产；未提供时由 `api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。
+- 音频：视觉小说专用音频路由保留；VectorEngine Suno/Vidu provider 协议、任务提交/查询、音频 URL 提取、下载、MIME/extension 归一和 OSS put 请求准备归属 `platform-audio`。`api-server/src/vector_engine_audio_generation.rs` 只做路由、配置、计费、asset object confirm、entity binding 和错误 envelope 映射；拼图、抓大鹅和敲木鱼提示词生成音效入口暂时关闭，通用 `/api/creation/audio/*` 对这些目标返回 `410 Gone`。敲木鱼创作只接收上传 / 录音音频资产；未提供时由 `api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。
 - OSS：私有 generated legacy path 进入浏览器前必须通过 `/api/assets/read-url` 换签；不要裸请求 `/generated-*`。
 - 外部 API 失败审计：外部供应商调用未成功时，`api-server` 必须发送 OTLP 失败事件并写入 `tracking_event`。VectorEngine 图片 provider 在 `platform-image` 内输出结构化日志和 `PlatformImageFailureAudit`，覆盖 `request_send`、`response_body`、`upstream_status`、`response_parse`、`missing_image` 和 `image_download` 阶段；`api-server` 只把该 audit 映射成 `external_api_call_failure`，`scope_kind = module`、`scope_id = provider`、`module_key = external-api`。metadata 固定包含 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel 和 rawExcerpt。入库优先复用 tracking outbox，outbox 不可写或保护阈值拒绝时回退同步写 SpacetimeDB；不得新增前端兜底或在 SpacetimeDB reducer 内做外部 I/O。
 

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

@@ -12,6 +12,10 @@
 
 创作表单提交前的泥点余额前置校验只允许用独立弹窗提示失败原因，不得把用户退回创作入口或玩法模板列表，也不得清空当前表单状态。当前适用拼图、抓大鹅和汪汪声浪等会在前端提交前校验泥点的生成入口；余额不足、余额读取失败都应停留在当前工作台，由用户关闭提示后继续编辑或自行补足泥点。
 
+平台入口、生成页、结果页、作品详情、作品架和运行态的跨流程错误统一收口到 `PlatformErrorDialog`。弹窗必须带明确错误来源，例如某个草稿、某次生成、作品详情或某个游玩实例，并提供复制按钮复制“错误来源 + 错误内容”。页面内不再重复渲染裸错误 banner；表单校验、发布确认弹窗里的局部业务错误可以保留在原弹窗内。
+
+生成任务在用户离开生成页后异步完成时，平台壳层必须弹出 `PlatformTaskCompletionDialog`。完成弹窗同样要带来源，例如某个草稿或生成会话，并提供复制按钮复制“来源 + 状态”；如果用户仍停留在生成页并被自动带入结果页或试玩页，生成页 / 结果页本身即为完成反馈，不再额外叠加完成弹窗。
+
 `PlatformEntryFlowShellImpl.tsx` 仍是平台入口编排壳，后续维护时应优先把独立 UI 片段、公开作品映射、草稿生成 notice 和运行态状态 helper 拆到 `src/components/platform-entry/PlatformEntryFlowShellImpl/` 或同目录紧邻 helper 文件。拆分只允许改变文件组织，不改变入口配置事实源、默认导出、props、页面阶段、UI 文案或现有交互；其中拼图首访 onboarding 已拆为 `PlatformEntryFlowShellImpl/PuzzleOnboardingView.tsx`。
 
 `platformEntryCreationTypes.ts` 只做前端展示派生，分组时必须把后端 `creationTypes` 里的 `categoryId` / `categoryLabel` 当作可缺失字段处理，空值统一回退到 `recent` / `最近创作`，避免旧数据、局部 mock 或异常返回把创作入口初始化直接打崩。
@@ -30,7 +34,7 @@
 
 单图资产编辑统一通过 `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 字段。
+通用系列素材图集能力的实现真相源在 `platform-image::generated_asset_sheets`：`n` 是必选参数，模块负责组装 `n*n` sheet prompt、按 `n*n` 切片、绿幕 / 近白底透明化、导出 PNG 和 OSS 持久化请求。`api-server::generated_asset_sheets` 只保留 `AppError` / `AppState` 适配，不再承载图像处理和 OSS 请求构造细节。物品名称 prompt 和特殊设定 prompt 是可选输入；调用方可传入类似“每个物品生成五个不同视图”的视角约束，通用模块会把 sheet prompt、物品行 prompt、特殊设定 prompt 编码写入 OSS 元数据。玩法仍负责计费、物品规划、slot 映射、失败回写和把通用切片结果映射回自己的草稿 / profile / runtime 字段。
 
 当前所有玩法生成页 UI 统一收敛为圆环主视觉：`media/create_bg_video.mp4` 作为生成页固定全屏背景层循环静音播放，主进度圆环居中覆盖在背景之上，围绕陶泥儿视觉展示；页面只保留当前步骤名称和当前步骤进度，不再渲染步骤列表块。视频层需要显式触发播放，不能只依赖 `autoPlay/loop/muted` 属性。共用生成页 `CustomWorldGenerationView` 和汪汪声浪生成页都必须遵循这一口径。
 
@@ -44,8 +48,9 @@
 6. 点击 `generationStatus=generating` 的草稿卡必须恢复对应玩法的生成进度页，不能进入空白结果页或普通工作区；恢复生成页的 `startedAtMs` 使用进入生成页的当前时间，作品摘要 `updatedAt` 只用于排序和摘要展示，不参与假进度起算。
 7. 从草稿 Tab 作品架打开草稿工作区、生成页或结果页时，返回按钮必须回到草稿 Tab 的同一作品架语境；从创作 Tab 新建或直接进入创作链路时才回到创作 Tab。平台壳层需要显式记录本次创作流的返回来源，不能让结果页返回动作固定跳到创作入口。
 8. 私有 generated 图片必须通过 `ResolvedAssetImage` / `/api/assets/read-url` 换签读取。
+9. 敲木鱼作品架读取当前用户作品列表时走 `GET /api/creation/wooden-fish/works`；发布成功后平台壳必须同时刷新作品架与公开广场，避免作品刚发布时仍停留在旧列表。
 
-发现 Tab、创作 Tab 与草稿 Tab 的页面根内容区不再套 `platform-page-stage` 外层全局卡片壳，让列表、筛选和玩法卡获得更宽的横向空间；推荐页和我的页仍按各自页面设计保留原有全局卡片口径。移动端“我的”页仍按顶部头像 / 昵称 / 陶泥号、会员横幅、三张统计卡、每日任务、五项常用功能宫格、设置入口、次级入口带和法律信息组织，但字号必须维持平台普通 UI 档位，不能因为窄屏把卡片标题、功能 label 或法律信息撑成展示级字号；最后一屏内容必须能在底部 dock 上方完整滚动露出，不得被固定底部导航遮挡。
+发现 Tab、创作 Tab 与草稿 Tab 的页面根内容区不再套 `platform-page-stage` 外层全局卡片壳，让列表、筛选和玩法卡获得更宽的横向空间；推荐页和我的页仍按各自页面设计保留原有全局卡片口径。移动端“我的”页仍按顶部头像 / 昵称 / 陶泥号、会员横幅、三张统计卡、每日任务、五项常用功能宫格、设置入口和法律信息组织，不保留旧的底部“填邀请码”次级入口；每日任务卡必须读取 `/api/profile/tasks` 的当前任务摘要并在领取后同步刷新卡片进度。字号必须维持平台普通 UI 档位，不能因为窄屏把卡片标题、功能 label 或法律信息撑成展示级字号；最后一屏内容必须能在底部 dock 上方完整滚动露出，不得被固定底部导航遮挡。
 
 ## RPG / 自定义世界
 
@@ -73,7 +78,7 @@ RPG 从作品架、广场详情或作品号搜索点击“启动”前，入口
 
 RPG 运行态的战斗终局、继续冒险、继续探索和切场景都属于服务端 runtime 快照真相：`module-runtime-story` 必须在终局战斗 action 后调用 post-battle finalization，持久写入 `story_continue_adventure`、`deferredOptions`、`deferredRuntimeState.storyEngineMemory.currentSceneActState` 和清理后的战斗状态；`idle_travel_next_scene` / `camp_travel_home_scene` 必须由后端写入新的 `currentScenePreset`、`currentSceneActState`、`currentEncounter` 和 `runtimeStats.scenesTraveled`。前端只播放退场、进场和继续按钮表现，不能用默认 `观察/试探/调息` fallback 或本地动画假装推进剧情。旧 bootstrap 快照可能只有 `connectedSceneIds` / `forwardSceneId` 而没有 `connections`，后端生成战后旅行选项时必须兼容这些字段。
 
-RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列表为真相，恢复动作继续走对应恢复接口，但移动端“我的”页已经不再提供独立的 `次级入口 > 存档` 和设置入口存档按钮；“玩过”弹窗可以继续合并展示可继续存档，个人中心只保留设置、扫码、常用功能和条件性次级入口。移动端“我的”页的五项常用功能宫格只放泥点充值、邀请好友、兑换码、玩家社区、反馈与建议，避免把存档挤入主宫格破坏参考图布局。前端只展示 `/api/profile/save-archives` 返回的列表并在用户选择后调用对应恢复接口，不能本地拼装或筛选正式存档真相。
+RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列表为真相，恢复动作继续走对应恢复接口，但移动端“我的”页已经不再提供独立的 `次级入口 > 存档` 和设置入口存档按钮；“玩过”弹窗可以继续合并展示可继续存档，个人中心只保留设置、扫码和五项常用功能。移动端“我的”页的五项常用功能宫格只放泥点充值、邀请好友、兑换码、玩家社区、反馈与建议，避免把存档或填邀请码挤入主宫格破坏参考图布局。前端只展示 `/api/profile/save-archives` 返回的列表并在用户选择后调用对应恢复接口，不能本地拼装或筛选正式存档真相。
 
 ## 拼图
 
@@ -90,7 +95,8 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 - 支持画面描述生图、多参考图生图、上传或历史生成主图后 AI 重绘、上传或历史生成主图后不重绘；主链要求浏览器先经 `/api/assets/direct-upload-tickets` 直传 OSS 并确认 `asset_object`，创作 action 只提交 `referenceImageAssetObjectId(s)`，由后端校验 owner / bucket / kind / MIME / size 后签发 OSS 只读 URL 并下载为 VectorEngine `/v1/images/edits` 的 multipart `image` part。本地上传 Data URL 与历史 `/generated-*` 图片路径仅保留为旧草稿、旧入口或未迁移客户端的兼容输入；关闭 AI 重绘时，后端统一解析为首关或当前关卡正式图后再持久化，不调用第一段拼图首图生成。
 - 草稿生成会先持久化 `generationStatus=generating` 的作品摘要，生成完成并回写关卡拼图画面、关卡画面参考图、UI spritesheet 和关卡背景图后再变为 `ready`；当前不自动生成背景音乐。生成页步骤推进必须跟随后端 session `progressPercent` 的真实里程碑：`88` 表示草稿编译完成并进入出图步骤，`94` 表示生成图已保存并进入 UI / 背景步骤，`96` 表示正式图与 UI 背景已确认并进入写入步骤，最终 action 成功或发布才进入完成态；每个步骤内部可以按实际等待时间使用假进度平滑推进，总进度按 `0-88`、`88-94`、`94-96`、`96-98` 的真实里程碑区间平滑推进。任一同步 action 回包到达时立即以真实完成/失败结果冻结进度。
 - 作品架拼图草稿的“生成中”遮罩只表示初始草稿还没有可查看结果；只要作品摘要、首关封面或任一关卡候选图已经可用，后续 UI 背景重生成和追加关卡生图都必须作为结果页局部生成态处理，不能阻止打开草稿结果页。
-- 拼图草稿编译是长耗时 action，前端 action 请求默认等待 `1_800_000ms`（30 分钟）且不自动重试。每次 `gpt-image-2` 调用的预期用时按 90 秒计算，但 `生成拼图首图` 单独按 4 分钟展示；完整 AI 重绘路径为 `编译首关草稿` 8 秒、`生成关卡名称` 10 秒、`生成拼图首图` 4 分钟、`生成关卡画面` 90 秒、`生成UI与背景` 90 秒、`写入正式草稿` 10 秒，合计约 448 秒。上传图且关闭 AI 重绘时必须跳过 `生成拼图首图`，直接进入 `生成关卡画面` 和 `生成UI与背景`，合计约 208 秒。生成页恢复时必须使用进入生成页的当前时间作为原始 `startedAtMs`；失败/完成态用 `finishedAtMs` 冻结耗时。未收到对应后端里程碑前，后续步骤保持待处理；即使当前步骤预计时长耗尽，也只能让当前步骤内部进度停在 `98%` 内，不能自动完成当前步骤或跳到后续步骤。生成页每个步骤只展示标题和进度，不展示步骤详细描述。
+- 拼图草稿编译是长耗时 action，前端 action 请求默认等待 `1_800_000ms`（30 分钟）且不自动重试。每次图片生成调用的预期用时按 90 秒计算，但 `生成拼图首图` 单独按 4 分钟展示；完整 AI 重绘路径为 `编译首关草稿` 8 秒、`生成关卡名称` 10 秒、`生成拼图首图` 4 分钟、`生成关卡画面` 90 秒、`生成UI与背景` 90 秒、`写入正式草稿` 10 秒，合计约 448 秒。上传图且关闭 AI 重绘时必须跳过 `生成拼图首图`，直接进入 `生成关卡画面` 和 `生成UI与背景`，合计约 208 秒。生成页恢复时必须使用进入生成页的当前时间作为原始 `startedAtMs`；失败/完成态用 `finishedAtMs` 冻结耗时。未收到对应后端里程碑前，后续步骤保持待处理；即使当前步骤预计时长耗尽，也只能让当前步骤内部进度停在 `98%` 内，不能自动完成当前步骤或跳到后续步骤。生成页每个步骤只展示标题和进度，不展示步骤详细描述。
+- 前端创作、结果页、生成页和错误提示不展示 GPT / Gemini 等具体模型名称；如需在内部保留模型路由，UI 只使用“标准模式”“创意模式”等产品化名称。
 - 若浏览器锁屏、息屏或网络切换导致 compile 请求失败，前端在标记失败前必须先复读 `getPuzzleAgentSession(sessionId)`；只有最新 session 仍缺 `draft.coverImageSrc`、首关 `coverImageSrc` 或候选图时才展示失败，复读到已生成草稿时按成功收尾、刷新作品架并继续自动试玩/结果页链路。
 - 拼图参考图 AI 重绘走 VectorEngine `/v1/images/edits`；无参考图时走 `/v1/images/generations`。两者模型都使用 `gpt-image-2`，参考图由后端作为 multipart `image` part 传入编辑接口。
 - 每次新建关卡生成或重新生成关卡图都必须由 `api-server` 串起当前关卡资产包：AI 重绘开启时第一段沿用草稿生成第一关的拼图主图提示词配置和模型 / 尺寸 / 参考图规则生成 `coverImageSrc/coverAssetId` 作为关卡拼图画面和结果页预览图，提示词来源同样按显式画面描述、关卡画面描述、草稿摘要顺序回退，且固定要求输出画面比例为 `1:1`；上传图且关闭 AI 重绘时跳过这一段，把上传图或历史图持久化为 `sourceType=uploaded` 的正式候选。随后用正式候选图作为参考，`9:16` 生成完整拼图游戏关卡画面并写入 `levelSceneImageSrc/levelSceneImageObjectKey`，提示词必须要求道具按钮上不要显示次数标注，且返回按钮和设置按钮旁禁止标注文字；UI spritesheet 与关卡纯背景在关卡画面完成后并发生成，spritesheet 用 `1:1`、`1k` 先生成纯绿色绿幕背景图，后端上传 OSS 前必须把绿幕扣成透明 PNG，再写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`，按钮顺序固定为返回、设置、下一关、提示、原图、冻结，按钮素材自身保留对应中文文字，返回和设置按钮不得额外生成白色外圈、白底圆环或浮雕外框；纯背景用 `9:16`、`1k` 写入 `levelBackgroundImageSrc/levelBackgroundImageObjectKey`，提示词必须包含“禁止在背景中出现人像或和拼图画面中主体一致的内容”。运行态不直接使用第二段完整关卡画面，但必须持久化它用于追踪和后续再生成。结果页局部关卡生成进度按 AI 重绘开启约 270 秒、关闭 AI 重绘约 180 秒展示。
@@ -126,7 +132,7 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 
 1. 初始草稿生成时，角色形象单独调用一次生图；
 2. 初始草稿生成时，地块单独调用一次生图，输出 3D 视图的 2D 图片图集；
-3. 地块图集由后端切分为起点、普通、目标、终点等透明 PNG；
+3. 跳一跳地块图集使用专用 `2行*3列` 六格布局，后端按 `start / normal / target / finish / bonus / accent` 顺序切分为透明 PNG；
 4. 封面和分享图由角色图与地块图轻量合成，不再额外调用第三次生图；
 5. 显式重生成角色或地块时，只重生成对应资产槽位。
 
@@ -223,7 +229,7 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 - 抓大鹅运行态不渲染右上角设置入口，也不在局内直接暴露重新开始按钮；结算弹层仍保留结果态的再来一局动作。
 - 高 DPR 移动端 WebGL canvas 必须锁定 CSS 尺寸，避免右下溢出。
 
-发现页可挂载官方抓大鹅静态 demo，用于验证生图、切图和运行态资源闭环。当前 demo profile 固定为 `match3d-demo-20260525`，公开作品号为 `M3-20260525`，静态资源位于 `public/match3d-demo/undersea-candy-market/`；公开卡片、作品号搜索和详情启动都走平台现有公开作品详情，不新建页面。demo 运行态使用前端本地 `createLocalMatch3DRuntimeAdapter`，不调用正式 Match3D runtime 后端、不新增 SpacetimeDB schema，也不写正式作品统计；后续若要把 demo 资源转成正式公开作品，必须改为后端 profile / gallery 投影真相后再接正式 runtime。
+发现页不再挂载前端固定官方抓大鹅静态 demo；公开卡片、作品号搜索、详情页和运行态启动只能来自后端真实 profile / gallery 投影。正式公开作品统一走 server runtime adapter，前端不得再用本地 demo profile 绕过后端统计和运行态链路。
 
 ## 视觉小说
 

docs/【玩法创作】生成页圆环布局口径-2026-05-23.md

@@ -13,6 +13,9 @@
 - 预计等待 / 已耗时信息卡要压缩为更轻的半透明窄卡，标签使用 `9px-10px`，数值使用 `12px-13px`，字号对齐其他生成页 UI 的小字号，不再使用偏大的提示文本；卡片标题和时间值都居中显示，两个数值只展示时间本身，调用侧不要再拼接“预计还需”或“已耗时”前缀。圆环中心不再保留独立白底块，空心圆环只保留条状进度，圆弧半径继续加大，进度数字与“总进度”标题整体上移，靠近圆环上半区。
 - 顶部导航区采用“返回创作中心 / 状态胶囊”结构，返回按钮使用左箭头图标，字号使用 `text-xs-sm`，状态胶囊使用 `11px-12px`，展示 `素材生成中`、`草稿生成中` 等调用侧传入文案。
 - 圆弧区域不再包独立大卡片，左右悬浮信息卡只展示“预计等待”和“已耗时”；总进度数值放在圆弧内侧偏上的位置并保持更小字号。当前圆环外径以 `w-[min(35rem,94vw)] sm:w-[52rem]` 为基准，圆弧使用 `r=166`、`strokeWidth=18` 的 SVG 描边，不再使用 `conic-gradient + mask`，避免进度条边缘模糊。
+- 圆弧描边以圆心为中心整体按 `155deg` 起始；在当前 SVG 坐标系下，这相对 `160deg` 会向左逆时针回调 `5deg`。track 和 fill 都必须共用同一个 `rotate(155 200 200)` 变换，避免只改视觉起点却让填充和轨道错位。
+- 总进度标题和百分比数字必须显式高于 SVG 圆环层级渲染，避免被圆环边缘压住；圆环本身只做背景层，不抢文字层。
+- 总进度标题和百分比数字要比圆环再上移一点，当前内容区上边距以 `pt-[2%]` 为准，桌面端可进一步微调到 `sm:pt-[1.5%]`，确保数字不与进度条弧线重合。
 - 从作品架或刷新后的持久化生成中草稿进入生成页时，前端必须重置“展示态 startedAtMs”为进入生成页的当前时间；后端 `progressPercent` 只用于后续真实步骤推进，不得参与首帧总进度展示，避免恢复生成页首帧直接显示 `80%+`。
 - 生成页只展示半透明“当前步骤”单卡，卡片内只保留步骤名称、步骤状态、步骤进度条和轻量加载指示；“当前步骤”标签使用 `10px-11px`，步骤名称使用 `14px-15px`，状态使用 `11px-12px`，不再渲染步骤列表或步骤详情。
 - 当前作品信息放在圆角信息卡中，标题固定使用 `13px`；有结构化字段时以两列信息块展示，例如“题材 / 素材数量”，无结构化字段时才展示纯文本设定。

docs/【项目基线】当前产品与工程约束-2026-05-15.md

@@ -44,6 +44,8 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台。当
 1. 主站登录弹窗必须稳定展示 `短信登录` 与 `密码登录` 两个核心入口；`GET /api/auth/login-options` 只能补充微信等环境相关入口，不能决定是否隐藏短信或密码登录。
 2. `login-options` 为空、失败、只返回 `phone` 或只返回 `password` 时，前端仍要同时展示验证码登录页签和密码登录页签；短信能力真实可用性由发送验证码接口返回结果表达。
 3. 登录弹窗继续复用现有独立 modal 和页签结构，不在页面中新增功能说明类文案，也不把邀请码输入放回登录面板。
+4. 微信小程序 `web-view` 外壳默认不预登录，首次进入直接打开 H5，并保持与 Web 端一致的未登录状态；只有 H5 触发 `openLoginModal` / `requireAuth` 等受保护入口时，才跳转小程序原生授权态。
+5. 小程序内需要登录时不展示 H5 登录弹窗，也不走手输手机号 / 短信验证码流程；统一通过原生 `button open-type="getPhoneNumber"` 获取微信手机号授权，再调用 `/api/auth/wechat/miniprogram-login` 与 `/api/auth/wechat/bind-phone` 换取系统登录态。
 
 ## 账户与充值
 
@@ -93,11 +95,12 @@ server-rs + Axum + SpacetimeDB
 7. 主站入口已锁定移动端页面级缩放；单个游戏页面不要再重复实现整页缩放锁定。
 8. 图像输入通用 UI 统一走 `src/components/common/CreativeImageInputPanel.tsx`。外层页面持有业务状态，组件只承担上传卡、预览、参考图缩略图、AI 重绘开关、错误展示和提交按钮。
 9. 发现页 `分类` 子频道的筛选必须打开独立 dialog / drawer / modal，至少支持玩法类型过滤与排序切换；筛选结果为空时显示空状态，不把筛选内容展开在当前列表下方。
-10. 移动端“我的”页顶部品牌行承载扫码和设置入口，正文按参考图顺序组织为头像 / 昵称 / 陶泥号、会员横幅、三张统计卡、每日任务、五项常用功能宫格、设置入口、可选次级入口和法律信息；`media/profile/` 中的陶泥素材作为该页图形资产。常用功能宫格固定承载泥点充值、邀请好友、兑换码、玩家社区、反馈与建议；页面不再提供独立存档按钮入口，填邀请码仅在新用户可填写窗口内展示为次级入口。
+10. 移动端“我的”页顶部品牌行承载扫码和设置入口，正文按参考图顺序组织为头像 / 昵称 / 陶泥号、会员横幅、三张统计卡、每日任务、五项常用功能宫格、设置入口和法律信息；`media/profile/` 中的陶泥素材作为该页图形资产。常用功能宫格固定承载泥点充值、邀请好友、兑换码、玩家社区、反馈与建议；页面不再提供独立存档按钮入口，也不在底部保留旧的填邀请码次级入口。填邀请码只由邀请链接 query 或其它明确引导打开独立弹窗，不作为“我的”页常驻按钮。
-11. “我的”页泥点、游戏时长、已玩游戏数量三张统计卡只展示各自标签和值，三个统计 icon 使用小尺寸普通 UI 档位，内容不换行，不在统计区底部展示“更新于”时间；移动端昵称、会员卡、每日任务、常用功能和法律信息也应保持 `10px` 到 `14px` 的普通 UI 字号区间，避免展示级字号挤压内容。
+11. “我的”页每日任务卡必须展示后端 `/api/profile/tasks` 返回的当前任务摘要，包括奖励泥点数、进度和领取 / 去完成 / 已完成状态；任务领取成功后，卡片摘要必须跟随返回的任务中心数据同步刷新，不能继续硬编码 `0 / 1` 或只更新弹窗内任务列表。
-12. 移动端“我的”页需要兼容窄屏：头像 / 昵称 / 陶泥号、三张统计卡、每日任务、五项常用功能、可选次级入口和法律信息都必须能在底部固定 TabBar 上方完整滚动露出，不得与底部 dock、刘海 safe-area 或相邻 UI 元素遮挡重叠。
+12. “我的”页泥点、游戏时长、已玩游戏数量三张统计卡只展示各自标签和值，三个统计 icon 使用小尺寸普通 UI 档位，内容不换行，不在统计区底部展示“更新于”时间；移动端昵称、会员卡、每日任务、常用功能和法律信息也应保持 `10px` 到 `14px` 的普通 UI 字号区间，避免展示级字号挤压内容。
-13. RPG 等运行态的战斗飘字、血量变化和即时反馈必须在暗色、噪声高的场景背景上保持可读：使用高亮文字、深色描边、强阴影或小面积半透明底，不只依赖红/绿文字本身表达伤害或治疗。
+13. 移动端“我的”页需要兼容窄屏：头像 / 昵称 / 陶泥号、三张统计卡、每日任务、五项常用功能和法律信息都必须能在底部固定 TabBar 上方完整滚动露出，不得与底部 dock、刘海 safe-area 或相邻 UI 元素遮挡重叠。
-14. 平台亮色 UI 配色以陶泥儿主视觉为准：暖白 / 米杏底、陶土橙主按钮、深棕正文与浅杏边框；新增界面优先复用 `src/index.css` 的 `--platform-*` 主题变量和 `apps/admin-web/src/styles/admin.css` 的同系色值，不再引入粉红、蓝绿等独立主色方案。
+14. RPG 等运行态的战斗飘字、血量变化和即时反馈必须在暗色、噪声高的场景背景上保持可读：使用高亮文字、深色描边、强阴影或小面积半透明底，不只依赖红/绿文字本身表达伤害或治疗。
+15. 平台亮色 UI 配色以陶泥儿主视觉为准：暖白 / 米杏底、陶土橙主按钮、深棕正文与浅杏边框；新增界面优先复用 `src/index.css` 的 `--platform-*` 主题变量和 `apps/admin-web/src/styles/admin.css` 的同系色值，不再引入粉红、蓝绿等独立主色方案。
 
 ## 文案与编码
 

miniprogram/pages/web-view/index.js

@@ -1,3 +1,6 @@
+/* global Page, wx */
+/* eslint-disable no-console */
+
 const {
   API_BASE_URL,
   MINI_PROGRAM_APP_ID,
@@ -10,6 +13,8 @@ const MINI_PROGRAM_CLIENT_TYPE = 'mini_program';
 const MINI_PROGRAM_CLIENT_RUNTIME = 'wechat_mini_program';
 const CLIENT_INSTANCE_STORAGE_KEY = 'genarrative:mini-program-client-instance-id';
 const PAY_RESULT_STORAGE_KEY = 'genarrative:wechat-pay-result';
+const AUTH_RESULT_STORAGE_KEY = 'genarrative:mini-program-auth-result';
+const AUTH_ACTION_LOGIN = 'login';
 
 function isConfiguredEntryUrl(value) {
   const trimmed = String(value || '').trim();
@@ -57,6 +62,18 @@ function appendHashParams(url, params) {
   return `${baseUrl}#${rawHash}${separator}${pairs.join('&')}`;
 }
 
+function parseBooleanQueryFlag(value) {
+  return value === true || value === '1' || value === 'true' || value === 'yes';
+}
+
+function shouldStartAuthFromQuery(query) {
+  return String((query && query.authAction) || '').trim() === AUTH_ACTION_LOGIN;
+}
+
+function shouldReturnToPreviousPage(query) {
+  return String((query && query.returnTo) || '').trim() === 'previous';
+}
+
 function resolveWebViewUrl(authResult) {
   const entryUrl = String(WEB_VIEW_ENTRY_URL || '').trim();
   if (!isConfiguredEntryUrl(entryUrl)) {
@@ -75,6 +92,38 @@ function resolveWebViewUrl(authResult) {
   });
 }
 
+function persistAuthResult(authResult) {
+  wx.setStorageSync(AUTH_RESULT_STORAGE_KEY, JSON.stringify(authResult));
+}
+
+function consumeAuthResult() {
+  const rawValue = wx.getStorageSync(AUTH_RESULT_STORAGE_KEY);
+  if (!rawValue) {
+    return null;
+  }
+
+  wx.removeStorageSync(AUTH_RESULT_STORAGE_KEY);
+  try {
+    const parsed = JSON.parse(String(rawValue));
+    if (!parsed || typeof parsed !== 'object') {
+      return null;
+    }
+
+    const token = String(parsed.token || '').trim();
+    if (!token) {
+      return null;
+    }
+
+    return {
+      token,
+      bindingStatus: String(parsed.bindingStatus || 'pending_bind_phone'),
+    };
+  } catch (error) {
+    console.error('[web-view] parse auth result failed', error);
+    return null;
+  }
+}
+
 function getClientInstanceId() {
   const stored = wx.getStorageSync(CLIENT_INSTANCE_STORAGE_KEY);
   if (stored) {
@@ -217,10 +266,12 @@ Page({
     errorMessage: '',
     loading: true,
     phoneBindingRequired: false,
+    returnToPreviousPage: false,
     webViewUrl: '',
   },
 
-  async onLoad() {
+  async onLoad(query = {}) {
+    this._lastLaunchQuery = query;
     // 中文注释：web-view 只能打开已配置业务域名；未配置时展示本地提示，避免空白页误判。
     if (!isConfiguredEntryUrl(WEB_VIEW_ENTRY_URL)) {
       this.setData({
@@ -231,6 +282,20 @@ Page({
       return;
     }
 
+    const forcedPhoneBinding = parseBooleanQueryFlag(query.phoneBindingRequired);
+    const returnToPreviousPage = shouldReturnToPreviousPage(query);
+    if (!shouldStartAuthFromQuery(query) && !forcedPhoneBinding) {
+      this.setData({
+        authResult: null,
+        errorMessage: '',
+        loading: false,
+        phoneBindingRequired: false,
+        returnToPreviousPage: false,
+        webViewUrl: resolveWebViewUrl(null),
+      });
+      return;
+    }
+
     if (!isConfiguredApiBaseUrl(API_BASE_URL)) {
       this.setData({
         errorMessage: '请先在 miniprogram/config.js 填写 API_BASE_URL。',
@@ -240,6 +305,14 @@ Page({
       return;
     }
 
+    this.setData({
+      loading: true,
+      phoneBindingRequired: false,
+      returnToPreviousPage,
+      errorMessage: '',
+      webViewUrl: '',
+    });
+
     try {
       const authResult = await resolveAuthResult();
       if (authResult.bindingStatus === 'pending_bind_phone') {
@@ -248,44 +321,56 @@ Page({
           errorMessage: '',
           loading: false,
           phoneBindingRequired: true,
+          returnToPreviousPage,
           webViewUrl: '',
         });
         return;
       }
 
+      if (returnToPreviousPage) {
+        persistAuthResult(authResult);
+        wx.navigateBack();
+        return;
+      }
+
       this.setData({
         authResult,
         errorMessage: '',
         loading: false,
         phoneBindingRequired: false,
+        returnToPreviousPage,
         webViewUrl: resolveWebViewUrl(authResult),
       });
     } catch (error) {
       this.setData({
         authResult: null,
         errorMessage:
-          error && error.message
+          error && error.message ? error.message : '微信登录失败，请稍后重试。',
-            ? error.message
-            : '微信登录失败，请稍后重试。',
         loading: false,
         phoneBindingRequired: false,
+        returnToPreviousPage,
         webViewUrl: '',
       });
     }
   },
 
   onShow() {
-    const result = wx.getStorageSync(PAY_RESULT_STORAGE_KEY);
+    const authResult = consumeAuthResult();
-    if (!result || !this.data.webViewUrl) {
+    if (authResult) {
-      return;
+      this.setData({
+        webViewUrl: resolveWebViewUrl(authResult),
+      });
     }
 
+    const result = wx.getStorageSync(PAY_RESULT_STORAGE_KEY);
+    if (result && this.data.webViewUrl) {
       wx.removeStorageSync(PAY_RESULT_STORAGE_KEY);
       this.setData({
         webViewUrl: appendHashParams(this.data.webViewUrl, {
           wx_pay_result: result,
         }),
       });
+    }
   },
 
   async handleGetPhoneNumber(event) {
@@ -318,6 +403,17 @@ Page({
         token: response.token,
         bindingStatus: 'active',
       };
+      if (this.data.returnToPreviousPage) {
+        persistAuthResult(nextAuthResult);
+        this.setData({
+          bindingPhone: false,
+          errorMessage: '',
+          loading: false,
+          phoneBindingRequired: false,
+        });
+        wx.navigateBack();
+        return;
+      }
       this.setData({
         authResult: nextAuthResult,
         bindingPhone: false,
@@ -344,9 +440,10 @@ Page({
       errorMessage: '',
       loading: true,
       phoneBindingRequired: false,
+      returnToPreviousPage: false,
       webViewUrl: '',
     });
-    this.onLoad();
+    this.onLoad(this._lastLaunchQuery || { authAction: AUTH_ACTION_LOGIN });
   },
 
   handleWebViewLoad(event) {

miniprogram/pages/web-view/index.wxml

@@ -1,5 +1,6 @@
 <block wx:if="{{webViewUrl}}">
   <web-view
+    id="genarrative-web-view"
     src="{{webViewUrl}}"
     bindload="handleWebViewLoad"
     binderror="handleWebViewError"
@@ -19,6 +20,9 @@
     <view wx:if="{{errorMessage}}" class="setup-text setup-text--danger">
       {{errorMessage}}
     </view>
+    <view wx:if="{{returnToPreviousPage}}" class="setup-text">
+      登录完成后将自动返回。
+    </view>
     <button
       class="retry-button"
       open-type="getPhoneNumber"

packages/shared/src/contracts/woodenFish.ts

@@ -134,6 +134,10 @@ export interface WoodenFishWorkProfileResponse {
   floatingWords: string[];
 }
 
+export interface WoodenFishWorksResponse {
+  items: WoodenFishWorkSummaryResponse[];
+}
+
 export interface WoodenFishWorkDetailResponse {
   item: WoodenFishWorkProfileResponse;
 }