Merge pull request 'codex/frontend-error-dialogs' (#40) from codex/frontend-error-dialogs into master

Reviewed-on: #40

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

@@ -16,6 +16,30 @@
 
 ---
 
+## 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-25 抓大鹅发现页官方 demo 使用静态资源与本地运行态
 
 - 背景：本轮抓大鹅资源管线已经生成完整 `level-scene`、背景、UI spritesheet、物品 spritesheet 和切片资源，需要放入发现页作为可试玩验证入口，但不应把一次性本地资源包装成后端正式作品。
@@ -144,6 +168,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，但服务端抠图后处理在玉米等主题上误伤过主体像素。
@@ -172,11 +204,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 过大。

.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 协议真相源。
-- 验证：`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。
-- 关联：`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/`：`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 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/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