# 踩坑与排障记录

> 用途：记录已验证、未来很可能再次遇到的问题。每条都应包含现象、原因、处理方式和验证方式。

## 记录格式

```md
## 问题标题

- 现象：看到什么错误或异常行为
- 原因：确认后的根因
- 处理：具体修复步骤
- 验证：如何确认修复有效
- 关联：相关文件、文档、提交或 Issue
```

## 抓大鹅新 UI spritesheet 不要回退成中心容器图

- 现象：新素材流程生成后，运行态棋盘中心可能叠出一整张 UI spritesheet，导致按钮素材、方格和空白图集覆盖容器区域。
- 原因：为了兼容旧 DTO，后端可能把 `uiSpritesheetImage*` 同步写入历史 `containerImage*` 字段；旧前端只看 `containerImage*`，会误把 UI 图集当透明中心容器。
- 处理：读取中心容器图时先比较归一化后的 `containerImage*` 与 `uiSpritesheetImage*`。两者同源时忽略 `containerImage*`，只把它作为旧数据兼容字段；新流程背景图本身已经保留容器，运行态只需加载背景和解析 UI / 物品 spritesheet。
- 验证：`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`。

## UI spritesheet 不要依赖模型直接生成透明背景

- 现象：拼图或抓大鹅运行态解析 UI spritesheet 时，把整张背景图、棋盘格、叶子或装饰图也当作 UI 素材区域，按钮映射错乱；截图里常表现为底部按钮区只剩透明棋盘格或素材碎片。
- 原因：前端解析依赖 alpha 连通域检测，透明背景是前提；但生图模型收到“透明背景 spritesheet”提示后仍可能输出带实景背景或伪透明棋盘格的普通不透明 PNG，OSS 中保存的图没有真实 alpha。
- 处理：UI spritesheet 提示词应要求统一纯绿色绿幕背景，而不是让模型直接产透明背景；后端在上传 OSS 前复用 `generated_asset_sheets::apply_generated_asset_sheet_green_screen_alpha(...)` 把绿幕扣成真实透明 PNG，再把透明图写入 `uiSpritesheetImageSrc/uiSpritesheetImageObjectKey`。
- 验证：`cargo test -p api-server puzzle_ui_spritesheet_postprocess_turns_green_screen_transparent --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server puzzle_level_scene_spritesheet_and_background_requests_use_references --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server match3d_derived_asset_prompts_match_three_sheet_pipeline --manifest-path server-rs\Cargo.toml`。
- 关联：`server-rs/crates/api-server/src/puzzle/generation.rs`、`server-rs/crates/api-server/src/match3d/works.rs`、`server-rs/crates/api-server/src/generated_asset_sheets.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 拼图 UI spritesheet 运行态不要二次包圆底或拉伸比例

- 现象：拼图运行态左上返回和右上设置按钮外面出现白色圆圈；底部“提示 / 原图 / 冻结”三枚素材被压扁、拉宽或拉成正圆，和图集原始按钮比例不一致。
- 原因：UI spritesheet 已经包含按钮视觉本体，但运行态仍给顶部按钮套默认圆形 icon 容器；底部三枚素材用 `h-full w-full rounded-full` 铺满按钮格，覆盖了自动检测矩形的真实宽高比。
- 处理：有 `uiSpritesheetImage*` 时，顶部返回 / 设置按钮容器只保留透明点击区和 focus 状态，不再叠加默认圆形底；`buildPuzzleUiSpriteBackgroundStyle(...)` 对检测到的矩形写入 `aspectRatio`，底部三枚素材按原始宽高比和最大尺寸渲染，不强制 `w-full`。
- 验证：`npm run test -- src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx`、`npm run test -- src/services/puzzle-runtime/puzzleUiSpritesheetParser.test.ts`。
- 关联：`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`src/services/puzzle-runtime/puzzleUiSpritesheetParser.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

2026-05-22 补充：展示矩形和点击热区要分开处理。`puzzleUiSpritesheetParser` 的 `regions` 保留完整视觉裁切矩形，`hitRegions` 用较高 alpha 阈值只包住实心按钮主体；运行态底部 spritesheet 道具按钮启用 `puzzle-runtime-sprite-tool-button--precise-hit`，父按钮不吃整块透明留白，内部 `puzzle-runtime-ui-sprite-hit-zone` 才接收指针事件，避免透明区域成为点击热区。

## 图像输入组件不要把业务状态藏在页面内联实现里

- 现象：拼图页把参考图上传、缩略图、主图删除确认和 AI 重绘开关内联实现后，后续想复用到其它创作页时，页面级状态和通用 UI 状态混在一起，容易出现多套上传卡和参考图展示口径。
- 原因：通用图像输入是受控输入面板，不是只服务单页的临时实现；图片、提示词、参考图数组、重绘开关等业务真相应由外层页面持有，组件最多持有参考图预览、删除确认这类短生命周期 UI 状态。
- 处理：抽 `CreativeImageInputPanel` 时，保留上传卡、参考图入口、缩略图、预览弹层、删除确认和提交按钮的统一壳，但把主图文件读取、裁剪、历史素材、计费确认和具体提交动作留给外层页面；后续页面接入时只传业务回调和文案。
- 验证：拼图入口测试仍可通过，且新组件可通过不同页面复用而不需要复制上传卡实现。
- 关联：`src/components/common/CreativeImageInputPanel.tsx`、`src/components/puzzle-agent/PuzzleAgentWorkspace.tsx`。

## RPG 发布不能只依赖 agent session seed_text

- 现象：RPG 结果页 `publish_world` 返回 `UPSTREAM_ERROR`，details 为 `custom_world.setting_text 不能为空`；同一 session 的 `result-view` 日志显示 `publish_ready=true`。
- 原因：前端发布动作只提交 `{ action: 'publish_world' }`，旧 agent 会话的 `seed_text` 可能为空；如果后端只从 action payload 或 `seed_text` 取 `setting_text`，就会在最终 compile / publish 校验阶段失败。
- 处理：`module-custom-world::resolve_custom_world_publish_setting_text(...)` 以当前 `draft_profile_json` 为草稿真相，优先读取 `settingText`、`creatorIntent.rawSettingText`、`creatorIntent.worldHook`、`worldHook`、`anchorContent.worldPromise(.hook)`、`summary`、`name/title`，最后才回退 `seed_text`。
- 验证：`cargo test -p module-custom-world publish_setting_text --manifest-path server-rs\Cargo.toml`；`cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml`。
- 关联：`server-rs/crates/module-custom-world/src/application.rs`、`server-rs/crates/spacetime-module/src/custom_world.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## RPG 已发布结果页进入世界不能重复 publish_world

- 现象：RPG 草稿发布成功后，按钮文案已变为“进入世界”，但点击仍请求 `POST /api/runtime/custom-world/agent/sessions/{sessionId}/actions` 且 payload 为 `{"action":"publish_world"}`，后端返回 `publish_world is only available during object_refining, visual_refining, long_tail_review or ready_to_publish`。
- 原因：按钮文案依据 agent session `stage === 'published'` 切换，但点击处理仍走发布协调路径；如果前端只依赖草稿同步回包判断是否已发布，回包为空或缺少可进入状态时就会继续重复发送 `publish_world`。
- 处理：进入世界协调器接收当前 agent session stage；当 stage 已为 `published` 时，只调用 `result-view` 回读已发布 profile 并启动运行态，不再调用 `sync_result_profile` 或 `publish_world`。
- 验证：`npm run test -- src/components/rpg-entry/useRpgCreationEnterWorld.test.tsx`；确认已发布场景下 `syncAgentDraftResultProfile` 与 `executePublishWorld` 均未被调用。
- 关联：`src/components/rpg-entry/useRpgCreationEnterWorld.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## RPG 点击启动黑屏 / 默认 profile 先查 profile 归一化和摘要覆盖

- 现象：作品详情点击“启动”后页面切到 RPG runtime，但用户只看到黑屏、空白，或进入默认角色 / 默认 profile；从作品详情点“作品编辑”后开局 CG、封面、角色图、技能动作预览、初始物品图标或场景背景图丢失；DevTools 里可能同时看到旧自动存档 `/api/runtime/save/snapshot` 被主动 cancel。
- 原因：`/custom-world-library` / `/custom-world-gallery` 详情接口可能返回历史或摘要式 `profile`，缺少 `playableNpcs`、`storyNpcs`、`landmarks`、`attributeSchema` 等运行态字段；前端 client 若直接把该对象传给 runtime，角色选择首屏会在 `buildCustomWorldPlayableCharacters(profile)` 或后续属性解析处抛错。另一类常见原因是详情接口已回读完整 profile 后，`savedCustomWorldEntries` 里的列表摘要又把 `selectedDetailEntry` 覆盖回空 profile，导致启动或编辑时只剩卡片摘要。发布 / 回读 result-view 若返回字段更少的旧视图，也可能把当前结果页已编辑资产降级掉。`save/snapshot (canceled)` 通常是切 runtime 或卸载时 `AbortController` 取消旧自动存档，不是黑屏根因。
- 处理：RPG 入口作品库 client 在所有返回 `CustomWorldLibraryEntry<CustomWorldProfile>` 的接口边界统一调用 `normalizeCustomWorldProfileRecord`，并用 `profileId/worldName/subtitle/summaryText` 补齐旧数据缺字段；详情页已拿到运行态字段或资产槽位更多的完整 profile 时，不允许列表摘要覆盖当前详情；同一 `profile.id` 下，正式进入世界发布 / 回读不得用字段更少的后端旧视图降级当前结果页 profile。`normalizeCustomWorldProfileRecord` 必须近似无损保留 `cover`、`openingCg`、`camp.narrativeResidues`、`landmark.visualDescription/narrativeResidues`、`skills[].actionPreviewConfig`、`initialItems[].iconSrc`、`attributeSchema`、角色 `attributeProfile` 和 `sceneChapterBlueprints[].acts[]` 的背景与结构字段；只有背景资产的 act 也不能被过滤。角色选择页对角色生成异常或空数组回退默认角色，并保留返回按钮/轻量空态；顶层 runtime 懒加载 fallback 不使用纯 `null`。
- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "creation hub published work start uses loaded detail profile instead of library summary|creation hub published work edit keeps loaded detail profile assets instead of library summary"`；`npm run test -- src/data/customWorldLibrary.test.ts -t "保留结果页封面和关键图片资产槽位|近似无损保留编辑态和运行态结构字段|保留只有背景资产的场景幕"`；`npm run test -- src/components/rpg-entry/useRpgEntryAgentDraftRestore.test.tsx -t "默认封面和角色编辑结构差异也不能被列表摘要覆盖"`；`npm run test -- src/components/rpg-entry/useRpgCreationEnterWorld.test.tsx -t "正式进入世界回读结果页字段更少时不降级当前完整 profile"`；`npm run typecheck`。
- 关联：`src/components/rpg-entry/useRpgEntryLibraryDetail.ts`、`src/components/rpg-entry/useRpgCreationEnterWorld.ts`、`src/data/customWorldLibrary.ts`、`src/services/rpg-entry/rpgEntryLibraryClient.ts`、`src/components/rpg-entry/RpgEntryCharacterSelectView.tsx`、`src/App.tsx`、`src/components/rpg-runtime-shell/RpgRuntimeShell.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## RPG 战后一轮战斗后卡在观察/试探/调息先查 post-battle finalization

- 现象：RPG 一轮战斗胜利后，运行态只显示默认 `观察周围迹象 / 主动出声试探 / 原地调息`，这些按钮只有文字反馈；点“继续冒险”后又回到同样选项，点探索只播退场/进场动画，场景和剧情不推进。
- 原因：终局战斗 action 如果只走通用 `resolve_story_runtime_action` fallback，而没有在后端调用 `finalize_post_battle_resolution(...)`，就不会持久写入 `story_continue_adventure`、`deferredOptions` 和下一幕 `currentSceneActState`。另外旧 bootstrap 快照可能只有 `connectedSceneIds` / `forwardSceneId`、没有 `connections`，战后选项生成若只读 `connections` 也会退回 `idle_explore_forward` 循环。
- 处理：`module-runtime-story` 在 story action 投影后统一调用 post-battle finalization；`idle_explore_forward` 清理战斗态并生成下一段遭遇预览；`idle_travel_next_scene` / `camp_travel_home_scene` 由后端写入新 `currentScenePreset`、场景 act 状态、遭遇预览和 `runtimeStats.scenesTraveled`。前端只负责播放继续、探索和切场景动画，不承接正式剧情推进真相。
- 验证：`cargo test -p module-runtime-story --manifest-path server-rs\Cargo.toml battle_tests -- --nocapture` 应覆盖战斗终局持久化 `story_continue_adventure`、`deferredOptions`、下一幕 act，以及 `idle_travel_next_scene` 真正切换场景。
- 关联：`server-rs/crates/module-runtime-story/src/session_action.rs`、`server-rs/crates/module-runtime-story/src/post_battle.rs`、`server-rs/crates/module-runtime-story/src/battle_tests.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## RPG 战斗飘字不要只靠低对比红绿文字

- 现象：暗色或棕黑噪声背景下，战斗伤害飘字看起来像背景纹理，尤其是远端敌人头顶的小号红字几乎不可读。
- 原因：旧 `CombatFloatingNumber` 主要依赖 `text-rose-200` / `text-emerald-200` 和 8px 同色 glow；在暗红、棕黑、像素噪声背景上，颜色与背景混在一起，1px 深色描边也不足以形成轮廓。
- 处理：飘字本体使用高亮近白文字、小面积半透明深色底、明显深色描边和多层黑色阴影；只增强瞬时反馈，不新增说明面板，不遮挡主要战斗画面。
- 验证：`npm run test -- src/components/game-canvas/GameCanvasEntityLayer.test.tsx` 覆盖伤害/治疗飘字样式策略；运行态截图中敌方头顶伤害数字应能在暗场景上辨认。
- 关联：`src/components/game-canvas/GameCanvasEntityLayer.tsx`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`。

## 弹窗里复用 CreativeImageInputPanel 要保留画面卡高度

- 现象：拼图草稿结果页的关卡详情弹窗中仍能看到“画面图”标题、画面描述和生成按钮，但实际画面图卡片视觉上消失。
- 原因：`CreativeImageInputPanel` 内部依赖 `flex-1`、`h-full` 和 `max-h-full` 撑开正方形画面卡；放进弹窗里的普通 `section` 后，父级没有可计算高度，卡片会被压到不可见。
- 处理：通用画面卡 `puzzle-image-upload-card` 保持 `aspect-square` 的同时设置稳定 `min-height`，让入口页和关卡详情弹窗都能显示主图/上传区。
- 验证：`npm run test -- src/components/puzzle-result/PuzzleResultView.test.tsx -t "opens an independent level detail dialog"` 应断言关卡详情中的 `.puzzle-image-upload-card` 具备最小高度类；`npm run test -- src/components/common/CreativeImageInputPanel.test.tsx` 应继续通过。
- 关联：`src/components/common/CreativeImageInputPanel.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`src/components/puzzle-result/PuzzleResultView.test.tsx`。

## Windows provision 下载截断要断点续传而不是回退目标机下载

- 现象：`Genarrative-Server-Provision` 在 `Download Provision Tool Archives` 阶段出现 `curl: (18) end of response ... bytes missing`，常见于 `otelcol-contrib_0.151.0_linux_amd64.tar.gz` 等 GitHub release 大文件。
- 原因：这是 Windows Jenkins 节点到 GitHub 的响应体被截断；若每轮都删除 `.download` 临时文件，就会丢掉已下载部分，下一次又从头开始。
- 处理：Windows 下载函数保留 `${Output}.download`，`curl` 失败时下一轮使用 `-C -` 断点续传；最终只以 GitHub release asset 的 SHA256 `digest` 作为放行条件，完整返回但 digest 不匹配才删除临时文件重新下载。不要把 SpacetimeDB 或 `otelcol-contrib` 下载挪回 Linux 目标机。
- 验证：日志应显示 `curl 断点续传 ... resumeBytes=...`，最终出现 `已下载 ... bytes=...`；目标 Linux 阶段只消费 `stash/unstash` 带过去的下载件。
- 关联：`jenkins/Jenkinsfile.production-server-provision`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## OTLP 端点只填 Collector HTTP base endpoint

- 现象：生产或容器 env 里把 `OTEL_EXPORTER_OTLP_ENDPOINT` 填成 `4317`、Rider 端口或别的非 HTTP base endpoint 后，api-server 发不出 OTLP，或者链路被错误转发。
- 原因：api-server 当前走 OTLP HTTP，不是 gRPC；Collector 才是接收和转发边界。
- 处理：生产模板用 `http://127.0.0.1:4318`，容器模板用 `http://otelcol:4318`；需要关闭时显式设 `GENARRATIVE_OTEL_ENABLED=false`，不要通过改 endpoint 绕开 Collector 语义。
- 验证：检查 env 模板和运行态配置都指向 Collector HTTP base endpoint，日志仍通过 `journalctl` / 文件日志保留。
- 关联：`deploy/env/api-server.env.example`、`deploy/container/api-server.env.example`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## tracking outbox 到批量阈值后先封存再异步 flush

- 现象：route tracking 高峰时如果主请求线程要等 SpacetimeDB 批量入库，接口延迟会被 outbox 写入链路拖长。
- 原因：outbox 的职责是把普通 HTTP route tracking 从请求线程切走，不能把 flush 结果回写成同步阻塞。
- 处理：达到 `BATCH_SIZE` 立即封存 active 文件并切新 active，`FLUSH_INTERVAL_MS` 只做兜底封存，后台 worker 异步 flush sealed 文件；成功删文件，失败保留重试，坏文件隔离为 `corrupt-*`，`MAX_BYTES` 只做磁盘保护。
- 验证：普通 route 请求在 SpacetimeDB 不可用时仍能返回，恢复后 sealed 文件会继续被清理。
- 关联：`server-rs/crates/api-server/src/tracking_outbox.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## release tracking outbox 权限错误先查 env 缺失

- 现象：release 机器 `journalctl -u genarrative-api.service` 每秒刷 `tracking outbox 定时封存 active 文件失败 error=Permission denied (os error 13)` 和 `tracking outbox 批量写入 SpacetimeDB 失败`。
- 原因：旧 `/etc/genarrative/api-server.env` 没有 `GENARRATIVE_TRACKING_OUTBOX_DIR` 时，api-server 会回退到本地开发默认相对路径 `server-rs/.data/tracking-outbox`；systemd 工作目录是只读发布目录 `/opt/genarrative/releases/<version>`，`genarrative` 用户不能在其中创建 `server-rs`。
- 处理：补齐 `GENARRATIVE_TRACKING_OUTBOX_DIR=/var/lib/genarrative/tracking-outbox` 及 batch/flush/max 配置，创建并授权 `/var/lib/genarrative/tracking-outbox` 给 `genarrative:genarrative`，再重启 `genarrative-api.service`。Server-Provision 与 API-Deploy 会保留旧 env 但自动补缺这些运行态路径。
- 验证：`tr '\0' '\n' < /proc/$(systemctl show genarrative-api.service -p MainPID --value)/environ | grep GENARRATIVE_TRACKING_OUTBOX_DIR` 应指向 `/var/lib/genarrative/tracking-outbox`；重启后当前 PID 不再出现 `Permission denied (os error 13)`。
- 关联：`scripts/deploy/production-api-deploy.sh`、`scripts/jenkins-server-provision.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 外部 API 失败没法追溯先查 external_api_call_failure

- 现象：VectorEngine 图片生成 / 编辑接口对前端只表现为 `502` / `504` 或“上游服务请求失败”，但难以区分是请求发送失败、上游 429/5xx、响应解析失败、未返回图片，还是下载图片失败。
- 原因：外部 API 失败如果只靠普通日志，不一定能和 OTLP 指标、trace 与 SpacetimeDB 历史查询稳定关联；重启后也容易丢失上下文。
- 处理：先查 OTLP 指标 `genarrative.external_api.failures{provider,failure_stage,status_class,retryable}`，再查 `tracking_event` 中 `event_key = 'external_api_call_failure'` 的 `metadata_json`。当前通用 VectorEngine `gpt-image-2-all` 适配器会记录 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel 和 rawExcerpt。
- 验证：`SELECT event_id, scope_id AS provider, metadata_json, occurred_at FROM tracking_event WHERE event_key = 'external_api_call_failure' ORDER BY occurred_at DESC LIMIT 50;`；如果查不到同时看 tracking outbox 目录权限和 sealed 文件是否堆积。
- 关联：`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## release 创作接口 413 先查是否还在提交 Data URL

- 现象：release 上 `POST /api/runtime/puzzle/agent/sessions/{session_id}/actions` 携带参考图 Data URL 时返回 `413 Request Entity Too Large`，access log 显示 `request_time=0.000`、`upstream_status=-`。
- 原因：Nginx 默认 `client_max_body_size` 只有 1 MiB，请求在反代层被拒绝，根本没有到达 `api-server`；即使模板放宽到 `64m`，把图片 base64 放进创作 JSON body 仍会放大请求体并把上限问题推给下一层。
- 处理：长期修复不是继续调大 Nginx，而是让浏览器先走 `/api/assets/direct-upload-tickets` 直传 OSS，再 `/api/assets/objects/confirm` 确认 `asset_object`，拼图 action 只提交 `referenceImageAssetObjectId(s)`；后端校验 owner / bucket / kind / MIME / size 后签只读 URL 给 VectorEngine。Nginx `client_max_body_size 64m` 只保留为旧客户端和兼容输入兜底，发布后仍需 `nginx -t && nginx -s reload`。
- 验证：前端 action payload 不应再出现大段 `data:image/...;base64`；`nginx -T 2>/dev/null | grep client_max_body_size` 可确认反代兜底；再次提交参考图时 access log 应有正常 `upstream_status`，后端测试 `puzzle_reference_image_sources_prefer_asset_object_ids` / `puzzle_asset_object_reference_requires_matching_owner` 应通过。
- 关联：`src/services/puzzle-works/puzzleAssetClient.ts`、`server-rs/crates/api-server/src/puzzle/vector_engine.rs`、`deploy/nginx/genarrative.conf`、`deploy/nginx/genarrative-dev-http.conf`、`deploy/container/nginx.conf`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 汪汪声浪入口不要再回到独立配置阶段

- 现象：汪汪声浪入口如果继续切换到独立配置阶段，会和拼图、抓大鹅的创作页内嵌结构不一致，用户会感觉入口跳页。
- 原因：旧实现把 `bark-battle` 单独挂到 `bark-battle-config` selectionStage，而不是复用创作 Tab 里的模板区。
- 处理：入口点击只设置 `activeCreationFormType = 'bark-battle'` 并回到创作 Tab；`BarkBattleConfigEditor` 作为内嵌表单使用，默认隐藏返回按钮和页面标题；runtime `onExit` 重新回到创作 Tab 的汪汪声浪模板。
- 验证：点击汪汪声浪后直接看到创作页内嵌表单，不再出现独立配置页；测试应覆盖内嵌表单与 runtime 返回路径。
- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/bark-battle-creation/BarkBattleConfigEditor.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`。

## 抓大鹅批量重新生成物品不要新增 itemId

- 现象：结果页批量重新生成物品后，试玩或正式运行态的物品类型和图片对应关系漂移，或者用户输入一个不存在名称后被当作新物品追加。
- 原因：重新生成和批量新增共用 `item-assets` 接口，如果前端不传 `mode = "replace"`，或后端替换时重新分配 `itemId` / 追加未匹配名称，就会破坏 `generatedItemAssets` 顺序和运行态类型映射。
- 处理：批量重新生成只提交当前素材列表中能匹配到的名称，并传 `mode = "replace"`；后端只对同名已有素材生成新图片，合并时保留原 `itemId`、`itemName`、模型兼容字段、UI 背景和历史音频字段，未匹配名称直接忽略且不计费。
- 验证：`npm run test -- src\components\match3d-result\Match3DResultView.test.tsx` 覆盖前端提交口径，`cargo test -p api-server match3d_item_asset --manifest-path server-rs\Cargo.toml` 和 `cargo test -p api-server match3d_regenerated_asset --manifest-path server-rs\Cargo.toml` 覆盖后端替换计划与身份保留。
- 关联：`src/components/match3d-result/Match3DResultView.tsx`、`server-rs/crates/api-server/src/match3d.rs`、`packages/shared/src/contracts/match3dWorks.ts`、`server-rs/crates/shared-contracts/src/match3d_works.rs`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 抓大鹅生成封面图不要覆盖物品素材或配置

- 现象：结果页生成封面图后，`素材配置 > 物品` 中已有物品素材被清空、回退旧快照，或难度 / 消除次数被改回旧值。
- 原因：封面生成属于定向图片槽位更新；若后端复用草稿编译写回，可能按 session config 重算作品行。即使后端已修正，前端若直接把封面接口返回的整份 `item` 当成最新 profile，也可能用旧回包里的空 `generatedItemAssets` 覆盖当前页面素材。
- 处理：`POST /api/creation/match3d/works/{profileId}/cover-image` 只保存 `coverImageSrc` / `coverAssetId` 等封面字段，保留当前 `generated_item_assets_json`、难度、消除次数、题材和描述；前端收到回包后只合并 `coverImageSrc`，继续保留当前可见 `generatedItemAssets`、`clearCount` 和 `difficulty`。
- 验证：`npm run test -- src\components\match3d-result\Match3DResultView.test.tsx` 覆盖旧回包不覆盖物品素材和配置；`cargo test -p api-server match3d_cover --manifest-path server-rs\Cargo.toml` 覆盖封面提示词与参考图链路。
- 关联：`src/components/match3d-result/Match3DResultView.tsx`、`server-rs/crates/api-server/src/match3d.rs`、`server-rs/crates/spacetime-module/src/match3d.rs`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## OSS V4 签名时间和 bucket/object_key 兼容

- 现象：OSS V4 私有读签名在部分时间点失败，可能出现 `OSS V4 签名时间格式化失败` 或服务端判定签名格式错误；排查用例中 bucket 为 `xushi-dev`，object_key 为 `generated-square-hole-assets/.../image.png`。
- 原因：旧逻辑依赖 `time::Time::to_string()` 再去掉冒号，小时小于 10 时输出不稳定补零；同时排查时容易把 bucket 名误当成 object_key 的一部分。
- 处理：OSS V4 `x-oss-date` 使用固定宽度 `yyyyMMdd'T'HHmmss'Z'` 格式化；调用读签名或 `HEAD Object` 时只传 object_key，不要传 `bucket/object_key` 拼接路径。
- 验证：运行 `cd server-rs && cargo test -p platform-oss -- --nocapture`，并用 bucket=`xushi-dev`、object_key=`generated-square-hole-assets/square-hole-session-546d881972684be2980a2a882cd0cc71/square-hole-profile-134411276ce1469cbe398f946a25d7f8/square-hole-shape-image/rabbit-option/asset-1777979289912039/image.png` 覆盖签名生成。
- 关联：`server-rs/crates/platform-oss/src/lib.rs`、`server-rs/crates/platform-oss/README.md`。

## generated 音频路径进运行态前要先换签

- 现象：草稿页 audio 控件能播放背景音乐，但拼图或抓大鹅运行态开局后背景音乐不响，Network 可能出现裸 `/generated-*-assets/...mp3` 私有路径 403。
- 原因：生成音乐转存到 OSS 私有对象后，`audioSrc` 是 generated legacy path；浏览器 `<audio>` 不能像公开静态资源一样直接请求裸路径。另一个常见误判是浏览器拒绝自动播放，资源已经进入运行态但开局第一次 `audio.play()` 被拦截。
- 处理：结果页试听控件和运行态隐藏 `<audio>` 设置 `src` 前，都先通过 `useResolvedAssetReadUrl` 或 `resolveAssetReadUrl` 换签；签名未就绪时不要回退请求裸 generated 路径。运行态自动播放失败只静默兜底，但玩家首次按下拼图块或点击抓大鹅物品时要重试同一个背景音乐播放函数。拼图读取 `currentLevel.backgroundMusic.audioSrc`，抓大鹅读取 `generatedItemAssets[].backgroundMusic.audioSrc`。
- 验证：结果页试听和运行态 `<audio loop>` 的 `src` 为签名 URL 或公开 URL；拼图/抓大鹅运行态首次局内交互后会再次尝试播放背景音乐；`npm run typecheck` 不报契约字段缺失，后端 run response 带 `backgroundMusic`。
- 关联：`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md`。

## 抓大鹅背景音乐是作品级字段但暂存在首个物品素材

- 现象：抓大鹅草稿生成日志和 work detail 中已有背景音乐，但结果页 `素材配置 > 背景音乐` 显示“暂无音乐”，点击试玩后局内也不播放生成音乐。
- 原因：当前表结构没有作品级音频字段，背景音乐暂存在 `generatedItemAssets[]`。如果 action response 的 draft assets 缺音乐，前端又优先用它覆盖 work detail，或音乐落在非首个素材而结果页只读 `assetDrafts[0].backgroundMusic`，就会丢掉已生成音乐。
- 处理：前端统一使用 `normalizeMatch3DGeneratedItemAssetsForRuntime` / `mergeMatch3DGeneratedItemAssetsForRuntime`：把任意素材上的 `backgroundMusic` 与音乐元信息迁移到首个素材，清空其它素材上的作品级音乐字段；action draft assets 与 work detail assets 按 `itemId` 合并，保留详情里的音乐、UI 背景和点击音效。
- 验证：`npm run test -- src\services\match3dGeneratedModelCache.test.ts src\components\match3d-result\Match3DResultView.test.tsx src\components\match3d-runtime\Match3DRuntimeShell.test.tsx`；平台推荐流定向跑 `RpgEntryFlowShell.agent.interaction.test.tsx` 中的 Match3D runtime assets 用例；`npm run typecheck`。
- 关联：`src/services/match3dGeneratedModelCache.ts`、`src/components/match3d-result/Match3DResultView.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 中文乱码与编码风险

- 现象：中文文案、注释、剧情或文档显示为乱码，或被改写成英文。
- 原因：Windows/PowerShell/终端编码不一致，或整文件重写导致编码变化。
- 处理：
  - 不要直接沿用乱码文本。
  - 不要用英文替换中文，除非用户明确要求翻译。
  - 在 PowerShell 5.1 中显式使用 UTF-8。
  - 优先用 Python/Node 或 `Get-Content -Encoding UTF8` 核对原文。
  - 修改中文文件时优先局部补丁，避免无关内容重写。
- 验证：运行仓库已有编码检查；人工抽查修改文件中的中文内容。
- 关联：`AGENTS.md`、`npm run check:encoding`。

## SpacetimeDB 运行态查询不要绕过已有索引或用 procedure JSON 回传

- 现象：运行态接口看起来只查当前用户、作品或任务，却在 `spacetime-module` 中使用 `ctx.db.<table>().iter().filter(...)` 整表遍历；或者 procedure result 返回 `items_json/run_json/work_json` 等 JSON 字符串，`spacetime-client` mapper 再反序列化成旧兼容结构。
- 原因：新增索引或 typed snapshot 后，没有同步清理旧 mapper / 测试兼容层，也没有用静态检查拦截回退写法。
- 处理：表上已有主键、unique 或 `#[index]` 覆盖查询前缀时，先用对应 accessor `.find(...)` / `.filter(...)`，只对索引无法覆盖的条件做内存残余过滤；procedure result 返回 typed snapshot / typed value，不再跨层传 `*_json: Option<String>` 作为 payload。
- 验证：执行 `npm run check:spacetime-runtime-access`、`npm run check:server-rs-ddd`，涉及绑定变化时先执行 `npm run spacetime:generate` 和 `npm run check:spacetime-schema`。
- 关联：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`scripts/check-spacetime-runtime-access.mjs`、`server-rs/crates/spacetime-module/src/*`、`server-rs/crates/spacetime-client/src/mapper.rs`。

## 拼图广场列表不要每次 HTTP 请求调用 SpacetimeDB procedure

- 现象：`/api/runtime/puzzle/gallery` 每个请求都走 `spacetime-client.list_puzzle_gallery()` 调用 SpacetimeDB procedure，导致 SpacetimeDB WASM 侧重复组装全量列表，客户端再映射一遍；历史实现还出现过 procedure JSON 字符串往返。
- 原因：`api-server` 的服务器端 `spacetime-client` 没有订阅可公开读取的 gallery 投影，虽然 SDK 支持 client cache，但请求路径仍把列表读取当作 procedure 调用。
- 处理：`spacetime-module` 中用 public view `puzzle_gallery_card_view` 暴露已发布拼图作品的列表卡片字段，不携带 `levels` / `anchor_pack` 等详情级载荷；`spacetime-client` 建连接后订阅 `SELECT * FROM puzzle_gallery_card_view` 和 `SELECT * FROM public_work_play_daily_stat WHERE source_type = 'puzzle'` 并等待 `on_applied`。HTTP gallery 通过 `PuzzleGalleryCache` 缓存最终 `PuzzleGalleryResponse` DTO：`items` 返回前 10 个完整卡片，`previewRefs` 返回后 10 个作品号引用，cache miss / TTL 过期时单飞重建，后台 cleanup task 周期清理旧响应。旧 `list_puzzle_gallery` procedure 只作兼容，不再作为 HTTP gallery 主路径。
- 验证：搜索 `server-rs/crates/spacetime-client/src/puzzle.rs` 不应再出现 gallery 主路径调用 `list_puzzle_gallery_then`；搜索 `server-rs/crates/spacetime-client/src/lib.rs` 应订阅 `puzzle_gallery_card_view`；执行 `npm run spacetime:generate`、`cargo check --manifest-path server-rs/Cargo.toml -p spacetime-client`、`cargo check --manifest-path server-rs/Cargo.toml -p api-server` 和 schema/runtime access 检查。
- 关联：`server-rs/crates/spacetime-module/src/puzzle.rs`、`server-rs/crates/spacetime-client/src/lib.rs`、`server-rs/crates/spacetime-client/src/puzzle.rs`、`server-rs/crates/api-server/src/puzzle_gallery_cache.rs`、`/api/runtime/puzzle/gallery`。

## Windows 本地直连高 VU 压测不要误判成业务内存泄漏

- 现象：本地 Windows release `api-server` 直连 K6 压测时，250 RPS、`PREALLOCATED_VUS=300` 能把进程 private memory 瞬时推到约 7GB；同样配置打 `/healthz` 小响应也能复现，压测结束后回落到 100MB 级。
- 原因：高水位主要来自本机直连的 K6 VU / 长连接 / Hyper 发送链路和 Windows 连接缓冲，不是 SpacetimeDB procedure、拼图 JSON 缓存或 OTEL exporter。降低到接近真实并发的 VU 后，同样 250 RPS 拼图广场 p95 约 9ms，峰值约 600MB。
- 处理：本地容量判断时让 `PREALLOCATED_VUS` / `MAX_VUS` 接近真实并发，不要把过高 VU 预分配当作默认吞吐测试；同时观察 `process.memory.*`、`process.windows.handle.count`、`genarrative.http.server.response_bodies.in_flight`、`genarrative.http.server.request_permits.available`、`genarrative.puzzle_gallery.cache.*` 和 `genarrative.spacetime.read.*`。如果内存高但 body in-flight、背压 permit、cache rebuild 和 SpacetimeDB read 都不显示积压，优先按连接 / 发送链路高水位处理。
- 验证：对照打 `/api/runtime/puzzle/gallery` 与 `/healthz`；对比 `PREALLOCATED_VUS=300 MAX_VUS=800` 和 `PREALLOCATED_VUS=20 MAX_VUS=40`；压测结束后继续采样 10 秒确认 private memory 回落。
- 关联：`scripts/loadtest/README.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`server-rs/crates/api-server/src/process_metrics.rs`、`server-rs/crates/api-server/src/telemetry.rs`。

## 容器高 VU 下 `/healthz` RSS 尖峰先查 Axum state 深拷贝

- 现象：容器 Linux release `api-server` 打 `/healthz`，500 HTTP req/s、`PREALLOCATED_VUS=100` 只跑 1 秒也能把 RSS 推到约 1 GiB；同样问题与作品列表、SpacetimeDB procedure、业务 cache 和请求日志等级无关。
- 原因：`AppState` 曾直接 `#[derive(Clone)]` 大结构体，里面包含配置、SpacetimeDB client、平台服务、认证服务和多组 cache。Axum/Hyper 会在 router/service/connection 路径频繁 clone state，高并发 keepalive 下会放大为状态深拷贝高水位。
- 处理：`server-rs/crates/api-server/src/state.rs` 的 `AppState` 必须保持 `Arc<AppStateInner>` 浅拷贝壳；新增共享状态字段时放入 `AppStateInner`，不要把外层改回大结构体 clone。
- 验证：用容器内 k6 直连 `api-server:8082/healthz`，500 HTTP req/s、`PREALLOCATED_VUS=100`、30 秒压测后采样 `/proc/$pid/status`、`/proc/$pid/smaps_rollup` 和 cgroup `memory.current/memory.peak`。2026-05-18 修复后结果为 `15001` 请求、`http_req_failed=0`、`dropped_iterations=0`，RSS 约 18 MiB -> 52 MiB，cgroup peak 约 47 MiB。
- 关联：`server-rs/crates/api-server/src/state.rs`、`deploy/container/README.md`、`deploy/container/api-server.Dockerfile`。

## Gallery 压测延迟升高先查入口过量放行和 TTL 边界刷新

- 现象：公开作品列表在 500-1000 HTTP req/s 附近可能吞吐没有明显提升，但 p95 变高、VU 上升，甚至出现排队和 dropped iterations。
- 原因：Nginx、Axum 和缓存刷新边界如果同时允许过多请求进入，压力会先堆在连接、service 和 cache rebuild 周围；这类延迟不等同于数据库连接池不足。
- 处理：Nginx 按 endpoint 使用 `limit_req` 快拒绝，api-server 按 `default/gallery/detail/admin` 分组 semaphore 快拒绝；拼图广场 TTL 过期时已有缓存先返回 stale 响应，只允许一个后台 refresh 任务重建，冷启动无缓存时才同步构建。
- 验证：OTLP 看 `genarrative.http.server.request_permits.available{pool=...}`、`genarrative.puzzle_gallery.cache.stale_hits`、`refreshes_started`、`refreshes_failed`，Nginx access log 看 `request_time` 与 `upstream_response_time` 是否同步收敛；超过容量时应明确 429，而不是长时间排队或新增 502。
- 关联：`deploy/nginx/genarrative.conf`、`deploy/container/nginx.conf`、`server-rs/crates/api-server/src/backpressure.rs`、`server-rs/crates/api-server/src/puzzle_gallery_cache.rs`。

## 多玩法公开广场列表优先订阅 public view / read model

- 现象：抓大鹅、方洞挑战、视觉小说、大鱼吃小鱼等公开列表如果沿用 `list_*_works` procedure，即使只读已发布作品，也会在每个 HTTP 请求里回到 SpacetimeDB WASM 侧扫描、反序列化配置并组装列表，50RPS 以上容易变成热点。
- 原因：个人作品列表和公开广场列表复用了同一套 procedure 输入，导致公开列表为了通过 owner 校验传固定占位 owner，并把可长期同步的公开读模型当成请求期查询。
- 处理：每个公开广场新增或复用专用 public view / public read model：`match_3_d_gallery_view`、`square_hole_gallery_view`、`visual_novel_gallery_view`、`big_fish_gallery_view`。`spacetime-client` 建连接后订阅这些 view 和对应 `public_work_play_daily_stat` source_type 桶，HTTP gallery 只读本地 cache。个人作品列表、详情、发布、点赞、游玩记录和 Remix 仍走原有 procedure / reducer。
- 验证：搜索 `server-rs/crates/spacetime-client/src/{match3d,square_hole,visual_novel,big_fish}.rs`，公开 gallery 主路径应读取 `connection.db().*_gallery_view()`，不应调用 `list_*_works_with_input`；执行 `npm run spacetime:generate`、`cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`。
- 关联：`server-rs/crates/spacetime-module/src/match3d.rs`、`server-rs/crates/spacetime-module/src/square_hole.rs`、`server-rs/crates/spacetime-module/src/visual_novel.rs`、`server-rs/crates/spacetime-module/src/big_fish/session.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 自定义世界广场和创作入口配置不要每次 HTTP 请求调用只读 procedure

- 现象：`/api/runtime/custom-world-gallery` 每次请求调用 `list_custom_world_gallery_entries` procedure；入口熔断中间件每个玩法请求调用 `get_creation_entry_config` procedure，50RPS 以上会把 SpacetimeDB procedure 调用变成热点。
- 原因：`custom_world_gallery_entry`、`creation_entry_config` 和 `creation_entry_type_config` 已经是可订阅读模型或配置表，但 HTTP 路径仍按“请求到来再查 procedure”处理。
- 处理：`spacetime-client` 长连接订阅 `custom_world_gallery_entry`、`public_work_play_daily_stat` 的 `custom-world` 桶、`creation_entry_config` 和 `creation_entry_type_config`；custom-world gallery 从本地 cache 排序并聚合 7 日播放数；入口配置优先读订阅 cache，cache 缺失时用最近一次成功内存快照，再兜底调用 `get_creation_entry_config` 完成旧库兼容。旧 `list_custom_world_gallery_entries` procedure 只允许作为旧库缺少 gallery 行时的一次性同步兜底。
- 验证：搜索 `server-rs/crates/spacetime-client/src/custom_world.rs`，gallery 主路径应是 `read_after_connect` 读取 `custom_world_gallery_entry()`；搜索 `server-rs/crates/spacetime-client/src/runtime.rs`，`get_creation_entry_config` 应优先读取 `creation_entry_config()` 和 `creation_entry_type_config()`。执行 `cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`。
- 关联：`server-rs/crates/spacetime-client/src/lib.rs`、`server-rs/crates/spacetime-client/src/custom_world.rs`、`server-rs/crates/spacetime-client/src/runtime.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

## 陶泥儿 logo 生图慢请求先缩短 prompt 并单张串行

- 现象：使用 VectorEngine `gpt-image-2` 生成陶泥儿 logo 概念图时，部分 prompt 会超过 10 分钟仍无响应，或返回 `429` / `当前分组上游负载已饱和`；同一批次里后续图片会被前面的慢请求拖住。
- 原因：复杂抽象 logo prompt 同时包含品牌解释、禁用元素、中文结构和多重隐喻时，上游排队与生成时长不稳定；并发或批量运行会放大单条慢请求的影响。
- 处理：先 `--dry-run` 看请求体；真实生成时优先短 prompt、单一造型、单张串行或小批量。失败后不要反复重试同一长 prompt，先压缩到“一个主体 + 一个负形 + 颜色 + 禁用文字/播放键/聊天气泡”再跑。联系表中的中文标签不要通过 PowerShell 管道内联 Python 写入，容易因编码链路显示为问号，可改用英文标签或脚本文件方式。
- 验证：生成文件落在 `public/branding/taonier-logo-*/`，用 Pillow 检查图片尺寸和非空；执行 `node --check scripts/generate-taonier-logo-concepts.mjs`、`npm run check:encoding`、`git diff --check`。
- 关联：`scripts/generate-taonier-logo-concepts.mjs`、`docs/design/TAONIER_BRAND_LOGO_CONCEPTS_2026-05-13.md`。

## 忘记密码后仍提示手机号或密码错误先查认证快照同步

- 现象：用户通过“忘记密码”重设密码后，接口返回成功或页面进入登录态，但再次使用新密码登录仍提示“手机号或密码错误”；重启后还可能出现 `Bearer JWT 版本已失效`，日志里的 token version 与本地快照不一致。
- 原因：重置/修改密码会更新 `password_hash`、`password_login_enabled` 和 `token_version`，如果 API 层只更新本地 `InMemoryAuthStore`，没有调用 `sync_auth_store_snapshot_to_spacetime()`，`api-server` 重启时可能从旧的 SpacetimeDB 表或旧快照恢复账号状态。
- 处理：`POST /api/auth/password/change` 与 `POST /api/auth/password/reset` 成功后必须同步认证快照；启动恢复时从 SpacetimeDB 表、SpacetimeDB 快照记录和本地 `GENARRATIVE_AUTH_STORE_PATH` 文件中选择可判断的最新快照，本地文件更新时尝试回写 SpacetimeDB。
- 验证：执行 `cargo test -p module-auth password --manifest-path server-rs/Cargo.toml` 与 `cargo test -p api-server password --manifest-path server-rs/Cargo.toml`；手测时重设密码后旧密码应失败，新密码应成功，重启后仍应保持。
- 关联：`server-rs/crates/api-server/src/password_management.rs`、`server-rs/crates/api-server/src/state.rs`、`docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md`。

## 抓大鹅生成页只显示服务暂不可用先查 reason 和外部服务配置

- 现象：点击生成抓大鹅草稿后，页面只提示“服务暂不可用”，或者本地 `npm run dev:api-server` 看似启动但生成接口不可用。
- 原因：配置缺失类错误通常在后端 `error.details.reason` 中给出具体缺项，前端如果只读 `details.message` 会吞掉原因；本地只配置 `ALIYUN_OSS_BUCKET` / `ALIYUN_OSS_ENDPOINT` 时，旧逻辑还会在启动期构造空 AccessKey 的 OSS 客户端并失败。抓大鹅新链路仍是 2D 生图切割，不需要也不应回退 Rodin/GLB。
- 处理：前端 API 错误展示优先读取 `details.reason`，再读取 `details.message`，避免底层 `error sending request` 覆盖真正可操作的配置或网络原因；`api-server` 只有在 OSS 四件套齐全时初始化 OSS 客户端，部分缺失只记 warning 并让具体 generated 上传/换签接口返回 `OSS 未完成环境变量配置`。抓大鹅素材、封面和背景生成在调用 VectorEngine 前先预检 OSS，并通过 `details.missingEnv` 列出缺项；真实生成需补齐 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和完整 `ALIYUN_OSS_*` 四件套。抓大鹅 UI spritesheet 和物品 spritesheet 的提示词必须要求纯绿色绿幕背景，后端上传 OSS 前统一扣成透明 PNG，避免运行态 alpha 连通域解析失败。
- 验证：`npm run test -- src/services/apiClient.test.ts` 覆盖 `details.reason`；`cargo test -p api-server state --manifest-path server-rs/Cargo.toml` 覆盖半配置 OSS 不阻断启动；`npm run dev:api-server` 后按实际 `GENARRATIVE_API_PORT` 请求 `/healthz`，不要默认打 `3100`。
- 关联：`packages/shared/src/http.ts`、`server-rs/crates/api-server/src/state.rs`、`docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md`、`docs/technical/AUTH_SNAPSHOT_AND_MATCH3D_LOCAL_DEV_FIX_2026-05-01.md`。

2026-05-22 补充：抓大鹅“物品 spritesheet”不再按旧 Gemini `generateContent` / `5*5` sheet 路径排查；当前链路先用 `gpt-image-2` 无参考图生成 `9:16` 关卡整图，再以该关卡整图作为 multipart `image` 参考并发编辑生成 `1K 1:1` UI spritesheet、`1K 9:16` 背景图和 `2K 1:1` 物品 spritesheet。UI 与物品 spritesheet 都要求纯绿色绿幕背景，上传 OSS 前通过后端透明化处理写入真实 alpha PNG。

## 抓大鹅发布按钮要先开发布面板，封面编辑收口到发布面板内

- 现象：抓大鹅结果页发布按钮看起来点不了，或者封面编辑仍然分散在作品信息 Tab 里，和拼图发布体验不一致。
- 原因：发布按钮被 `publishReady` 直接禁用，导致未满足门槛时无法进入发布检查面板；封面编辑仍挂在作品信息 Tab，不能和发布检查一起收口。
- 处理：发布按钮只受忙碌态控制，点击后始终打开独立发布面板；发布面板内先展示阻断项，再承载封面图上传 / AI 重绘 / 参考图编辑，满足条件后再点击 `发布到广场`。
- 验证：`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`；`npm run typecheck`。
- 关联：`src/components/match3d-result/Match3DResultView.tsx`、`src/components/match3d-result/Match3DResultView.test.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## `.hermes` 只放共享内容，不放个人 Hermes 配置

- 现象：团队成员误把个人 Hermes 配置、会话或密钥复制进仓库。
- 原因：仓库 `.hermes/` 与个人 `~/.hermes/` 名称相似。
- 处理：仓库 `.hermes/` 只放 Markdown 共享记忆、计划和可公开 skills；不提交 `.env`、`config.yaml`、`sessions/`、`auth.json`。
- 验证：提交前检查 `git diff -- .hermes`，确认没有密钥、会话记录或个人路径敏感信息。
- 关联：`.hermes/README.md`。

## 儿童动作 Demo 卡在摄像头不可用或挥手不推进先查 mocap 消费链路

- 现象：`/child-motion-demo` 打开后即使 `http://127.0.0.1:8876/` 已启动，页面仍提示“摄像头暂不可用”，或到“打个招呼”、左右手挥动、站位步骤时真实硬件动作无法检测通过，只能用鼠标拖拽或键盘调试继续。
- 原因：浏览器摄像头视频流只是舞台背景；如果热身关把 `getUserMedia` 状态当成主动作数据源，或只在 gesture 阶段消费 `useMocapInput`，就会错过 mocap 的身体中心、动作名和手部坐标。
- 处理：确认 `src/components/child-motion-demo/ChildMotionWarmupDemo.tsx` 全热身流程启用 `useMocapInput`，页面主提示展示 mocap 动作数据源状态而不是浏览器摄像头状态；确认 `src/services/useMocapInput.ts` 能解析 `/stream` 包里的 `general.body.center_norm`、`actions/action/gesture/gestures/event/name/type`、`hands[]`、`leftHand/rightHand`、`left_hand/right_hand`、左右手标记和 `open_palm/grab` 状态。`/stream` 是 WebSocket，普通 HTTP 访问返回 404 不能当成服务不可用。
- 验证：运行 `npx vitest run src\services\useMocapInput.test.ts src\components\child-motion-demo\ChildMotionWarmupDemo.test.tsx`，并在本地硬件服务启动后进入 `/child-motion-demo` 实测站位、招手、左右手挥动和跳跃阶段。
- 关联：`src/services/useMocapInput.ts`、`src/components/child-motion-demo/ChildMotionWarmupDemo.tsx`、`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。

## 儿童动作 Demo 左右手阶段误通过先查身体侧映射和手臂展开阈值

- 现象：热身关“挥动左手 / 挥动右手”阶段，用户只是手自然下垂、横向小幅抖动，或挥了相反侧手，也可能被判定通过。
- 原因：本地 mocap 的 handedness 当前按摄像头视角输出，不能直接当作用户身体左/右；同时左右手阶段的目标是确认现实空间安全，需要验证手臂向外打开和上下摆动角度，不能只看手部 `x` 轨迹范围。
- 处理：热身关中用户左手应消费 camera-right，用户右手应消费 camera-left；左右手阶段只在同侧肩肘腕外展、手腕非自然下垂、连续有效帧、横向范围、上下摆动范围、肩腕角度范围和上下方向变化全部达标时完成，并记录轨迹空间包络、角度范围和最大外展距离。
- 验证：运行 `npx vitest run src\components\child-motion-demo\ChildMotionWarmupDemo.test.tsx src\components\child-motion-demo\childMotionWarmupModel.test.ts`，确认相反侧手、自然下垂、单纯横向轨迹不会完成，真实展开上下摆动可以完成。
- 关联：`src/components/child-motion-demo/ChildMotionWarmupDemo.tsx`、`src/components/child-motion-demo/childMotionWarmupModel.ts`、`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。

## 儿童动作 Demo 角色轮廓抽搐先查 mocap 坐标防抖和渲染分层

- 现象：`/child-motion-demo` 中间半透明小人在真实硬件驱动下左右轻微来回摆，移动过程中看起来忽大忽小，用户很难稳定停在目标圆环内。
- 原因：`general.body.center_norm.x` 原始值逐包直接写入 `avatarX` 时，硬件坐标小噪声会直接驱动位置保持判定和 CSS 动画；如果角色外层同时承担横向定位和跳跃 `transform`，半透明 PNG 在移动时也更容易出现重采样抖动观感。
- 处理：mocap 身体中心进入角色位置前必须先 clamp，再经过小幅死区、低通阻尼和单包最大步长限制；键盘 A/D 调试输入仍保持即时。角色 DOM 外层只负责横向定位，内层 sprite 负责轮廓图和跳跃位移，避免同一层 `transform` 同时表达多种运动。
- 验证：运行 `npx vitest run src\components\child-motion-demo\ChildMotionWarmupDemo.test.tsx src\components\child-motion-demo\childMotionWarmupModel.test.ts src\services\useMocapInput.test.ts src\services\child-motion-demo\childMotionDebugInput.test.ts`，并用真实硬件进入站位阶段观察小幅身体晃动不会导致角色频繁左右跳动。
- 关联：`src/components/child-motion-demo/ChildMotionWarmupDemo.tsx`、`src/index.css`、`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。

## 宝贝识物选篮误触发先查多套判定和残余轨迹

- 现象：`宝贝识物` 运行态打开礼物盒或反馈结束后，当前物品被连续送入左侧或右侧篮子，或硬件动作名偶发命中导致未做明确横移动作也触发选篮。
- 原因：选篮如果同时消费 `wave_left_hand` / `wave_right_hand` / `wave` 动作名、连续横向轨迹和左右手固定篮子规则，或在 `correct` / `wrong` 反馈阶段继续累计手部状态，会把反馈期间残留移动或未知侧别手部误算成下一次选篮。
- 处理：宝贝识物当前选篮只允许“手先触碰中央物品 UI，物品绑定到该手，随后拖入左侧或右侧篮子区域”这一套路径；侧别为 `unknown` 的手部不参与抓取或选篮；反馈阶段清空持有状态，不在非 `active` 阶段累计输入。进入关卡和每次正确反馈结束后自动弹出物品，不再用 `open_palm -> grab` 抓握序列激活礼物盒。
- 补充：当前本地 mocap 的 handedness 是摄像头视角，宝贝识物仍需换算为用户身体视角以展示左右手：`rightHand` 坐标代表玩家左手，`leftHand` 坐标代表玩家右手。换算不再决定只能选择哪侧篮子；任意一只手都可以拖物品到任意篮子。键鼠调试保持鼠标左键=左手位置、右键=右手位置，也必须先触碰中央物品再拖入篮子。
- 验证：运行 `npm run test -- src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.test.tsx src/services/useMocapInput.test.ts`，确认动作名负向测试、未知侧别负向测试、触碰前不能选篮和任意手拖入任意篮子用例通过。
- 关联：`src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.tsx`、`docs/technical/BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md`。

## 宝贝爱画左右手反了先查 mocap 摄像头视角换算

- 现象：`宝贝爱画` 中真实硬件下左手指示器和右手画笔表现反向，用户抬右手却出现左手选色指示器，或抬左手却驱动画笔 / 橡皮。
- 原因：本地 mocap 的 handedness 当前按摄像头视角输出，不能直接当成用户身体左 / 右；宝贝爱画初版直接消费 `latestCommand.leftHand/rightHand`，漏做摄像头视角到用户身体视角的换算。
- 处理：宝贝爱画运行态消费 mocap 前先换算：`rightHand` 作为用户左手，用于颜色悬停和左手指示器；`leftHand` 作为用户右手，用于画笔 / 橡皮光标、绘制、擦除和工具切换。键鼠调试输入不做该换算，继续保持鼠标左键为左手、右键为右手。
- 验证：运行 `npm run test -- src/components/edutainment-runtime/BabyLoveDrawingRuntimeShell.test.tsx src/components/edutainment-runtime/babyLoveDrawingModel.test.ts`，确认 camera-left 驱动用户右手画笔、camera-right 渲染用户左手选色指示器。
- 关联：`src/components/edutainment-runtime/BabyLoveDrawingRuntimeShell.tsx`、`docs/technical/BABY_LOVE_DRAWING_RUNTIME_DEMO_IMPLEMENTATION_2026-05-13.md`。

## 宝贝识物创作卡在准备结果页先查长耗时 image-2 请求

- 现象：`/creation/baby-object-match` 创作生成停在“准备结果页”，约 3 分钟后显示“生成失败 / 请求超时”；后端日志可能出现同一路由 `status=502 latency_ms=231291`，或前端已失败但后端稍后返回 200。
- 原因：宝贝识物创作属于长耗时 image-2 链路。旧前端只等待 180 秒并对长耗时 POST 自动重试，容易在 VectorEngine 仍在生成时先 abort，再重复发起第二次生成；上游某张图超过后端 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 或返回 5xx 时会表现为 502。2026-05-14 后，新链路已从“2 张物品图 + 5 张视觉包装图”收敛为“1 张 `2x2` 素材 sheet + 1 张场景背景图”，左右手位置指示器改为运行态默认静态素材，不再每次创作生成，但仍需要按长耗时链路排查。
- 处理：`babyObjectMatchClient` 对 `/api/creation/edutainment/baby-object-match/assets` 使用 10 分钟超时并取消自动重试；后端并发启动 `2x2` 素材 sheet 和场景背景生成，并把该路由的 VectorEngine 单图请求等待预算提升到至少 8 分钟，按资源类别输出开始、完成和耗时日志。`2x2` sheet 固定包含物品 A、物品 B、篮子和礼物盒，服务端按格切图并转透明 PNG；`ui-frame` / `smoke-puff` / `left-hand` / `right-hand` 不再作为新生成必需资源。
- 验证：运行 `npm run test -- src/services/edutainment-baby-object/babyObjectMatchClient.test.ts src/services/miniGameDraftGenerationProgress.test.ts`、`cargo test -p api-server edutainment_baby_object --manifest-path server-rs/Cargo.toml` 和编码检查；真实联调时查看 `宝贝识物 image-2 2x2 素材 sheet 生成完成`、`宝贝识物 image-2 场景资源生成完成` 和整体 `宝贝识物 image-2 资源生成完成` 耗时是否小于前端超时，若仍 502 再看 `VectorEngine 图片生成上游错误` 的 `upstreamStatus/raw_excerpt`。
- 关联：`src/services/edutainment-baby-object/babyObjectMatchClient.ts`、`src/services/miniGameDraftGenerationProgress.ts`、`server-rs/crates/api-server/src/edutainment_baby_object.rs`、`docs/technical/BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md`。

## 宝贝识物篮子手柄白底先查 sheet 切图后处理

- 现象：`宝贝识物` 新生成的主题篮子在左右手柄、篮口镂空或边缘处仍出现白底块或白色毛边，尤其是 2x2 sheet 背景被抠透明后，封闭镂空区域可能没有被通用边缘连通抠图清理掉。
- 原因：宝贝识物为了降低 image-2 成本，把物品 A、物品 B、篮子和礼物盒放在同一张 `2x2` sheet。通用背景透明处理主要从单格边缘连通背景开始，封闭在篮子手柄内部的近白区域不一定与边缘连通，因此会残留；如果把强力近白清理应用到物品格，又可能误伤白色物品主体。
- 处理：后端 `slice_baby_object_match_sheet` 只在 `BabyObjectMatchSheetSlot::Basket` 编码前执行近白、低饱和 matte 清理；物品格和礼物盒格继续只走通用背景透明处理。sheet prompt 同步要求篮子手柄和篮口镂空处不要留下白底描边或毛边。运行态左右篮子的物品图标和名称 UI 以篮子中心线对齐，避免素材放大后看起来偏移。
- 验证：运行 `cargo test -p api-server edutainment_baby_object --manifest-path server-rs/Cargo.toml` 与 `npm run test -- src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.test.tsx`；真实联调需要重新生成宝贝识物资源，旧草稿中已保存的 base64 篮子图不会自动被新后处理改写。
- 关联：`server-rs/crates/api-server/src/edutainment_baby_object.rs`、`src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.tsx`、`src/index.css`、`docs/technical/BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md`。

## 宝贝识物物品框被长条素材拉伸先查固定槽位

- 现象：用户用手机、筷子等长条关键词生成素材后，中央物品 UI 或篮子上方物品图标看起来被拉成长框，圆形 UI 失去固定比例。
- 原因：运行态如果让图片固有宽高或外层自适应内容，就会把长条透明 PNG 的主体比例传导到 UI 容器。
- 处理：中央物品 UI 和篮子物品图标都必须使用固定正方形槽位，外层尺寸由 CSS 变量控制；生成素材图片只在槽位内 `object-fit: contain` 等比缩放，不改变外层圆形 UI 框尺寸。
- 验证：用长条物品草稿进入宝贝识物运行态，中央物品框和篮子图标框仍为正圆，长条主体在框内缩小显示。
- 关联：`src/index.css`、`src/components/edutainment-runtime/BabyObjectMatchRuntimeShell.tsx`、`docs/technical/BABY_OBJECT_MATCH_CREATION_PUBLISH_IMPLEMENTATION_2026-05-11.md`。

## 寓教于乐作品和宝贝识物模板同时消失先查入口种子

- 现象：发现页“寓教于乐”分类下已发布的宝贝识物作品突然消失，同时创作界面模板选项中也看不到或无法正常展示 `宝贝识物`。
- 原因：创作入口配置事实源已迁到 SpacetimeDB `creation_entry_type_config`；前端用 `baby-object-match` 入口可见性同时控制创作模板展示和发现页宝贝识物公开作品合入。若默认种子或后台配置缺少 `baby-object-match` 行，两条链路会一起被判定为不可见。
- 处理：确认 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs` 默认种子包含 `id=baby-object-match`、`title=宝贝识物`、`visible=true`、`open=true`、`sort_order=90`；api-server 测试降级配置也要同步包含该类型。入口图片路径需指向真实存在资源，避免卡片图片 404。
- 验证：运行 `cargo test -p module-runtime default_creation_entry_types_include_baby_object_match --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server test_creation_entry_config_response_keeps_baby_object_match_visible --manifest-path server-rs/Cargo.toml`、`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 和 `npm run test -- src/components/platform-entry/platformEntryCreationTypes.test.ts`。
- 关联：`server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs`、`server-rs/crates/api-server/src/creation_entry_config.rs`、`docs/technical/NEW_WORK_ENTRY_CONFIG_2026-05-01.md`。

## 儿童动作 Demo 绘本风资源未生成先查 VectorEngine 配置

- 现象：`/child-motion-demo` 已经呈现绘本草地风格，但 `public/child-motion-demo/picture-book-grass-stage.png`、`picture-book-grass-floor.png`、`picture-book-ground-ring.png`、`picture-book-character-outline.png`、`picture-book-ui-panel.png` 或 `picture-book-ui-button.png` 不存在，Network 里对应图片返回 404，或运行 `npm run assets:child-motion-demo -- --live` 返回缺少 VectorEngine 配置。
- 原因：儿童动作 Demo 的真实背景、地面、UI、地面指示环和角色轮廓资源都使用 VectorEngine `gpt-image-2` 生成，脚本只读取 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和可选 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；仓库内不能提交真实 key，缺配置时页面只能使用 CSS 草地绘本兜底。
- 处理：在本地私密环境补齐 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai` 与 `VECTOR_ENGINE_API_KEY`，不要把 key 写入 Git；先运行 `npm run assets:child-motion-demo -- --dry-run` 核对 prompt，再运行 `npm run assets:child-motion-demo -- --live` 或 `npm run assets:child-motion-demo -- --live --only ui-panel` 等小批量命令生成资源。透明资源的品红底源图写入 `tmp/child-motion-demo-assets/`，不要把源图或预览图放入 `public/child-motion-demo/` 作为正式资产。
- 验证：生成后确认 `public/child-motion-demo/` 只保留页面引用的最终 PNG，重新打开 `/child-motion-demo` 可看到真实绘本草地背景、地面、圆环、角色轮廓和 UI 资源；`npm run check:encoding` 仍通过。
- 关联：`scripts/generate-child-motion-demo-assets.mjs`、`src/index.css`、`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。

## 儿童动作 Demo 绘本资源变形先查用途拆分和透明后处理

- 现象：`/child-motion-demo` 背景风格正确，但底部草坪被拉成厚色块、顶部 HUD 或右下状态条像方形面板被横向拉伸，或旧 `picture-book-ui-panel.png` 与新资源叠在一起。
- 原因：早期资源中 `picture-book-ui-panel.png` 是接近方形画布，`picture-book-grass-floor.png` 也含大量透明边界；若 CSS 用 `background-size: 100% 100%` 把同一资源强行铺成 HUD、状态条、开始面板或底部地板，就会出现变形和层叠观感。
- 处理：使用用途专属资源：`picture-book-foreground-grass-v2.png`、`picture-book-ground-ring-v3.png`、`picture-book-character-outline-v4.png`、`picture-book-hud-strip-v2.png`、`picture-book-calibration-strip-v2.png`、`picture-book-start-panel-v2.png`、`picture-book-ui-button-v2.png`；CSS 按资源比例等比缩放，底部草坪只覆盖下沿，HUD / 状态条 / 开始托盘分别引用各自资源。角色指示器使用 v4 更细白色描边资源，内部透明且显示尺寸相对上一版放大 50%；若只需修透明裁切、品红边或纯描边后处理，运行 `npm run assets:child-motion-demo -- --live --postprocess-only --force --only <asset-id>`，不重新请求 image-2。
- 验证：用横屏截图检查没有新旧资源叠加、没有方形面板拉成长条、角色和地面指示环不被前景草坪埋住；同时运行 `npm run check:encoding`。
- 关联：`scripts/generate-child-motion-demo-assets.mjs`、`src/index.css`、`public/child-motion-demo/`、`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。

## 儿童动作 Demo 猫咪挥手拆件错位先查动画父级和肩部挂点

- 现象：`/child-motion-demo` 打个招呼阶段的猫咪图和风格正确，但挥手时左右手臂像漂浮在身体旁边，视频里能看到肢体没有稳定接在肩膀上。
- 原因：猫咪身体和手臂如果分别做上下浮动，或手臂使用透明方形画布的默认中心/底部旋转轴，就会在摆动极值时放大肩点偏差；镜像左臂还需要把资源内部连接点换算到镜像后的坐标。
- 处理：`.child-motion-gesture-guide__wave-cat` 父级统一承接 bob 动画，身体层保持静态贴底且层级低于手臂；左右手臂作为同一父级下的兄弟层，只做旋转动画并显示在身体前方。身体使用去掉左右小圆点的 `picture-book-wave-cat-body-guide-v7.png`；手臂 v7 资源当前按身体外缘摆放，圆猫爪掌面朝向玩家；左右侧距为 `12%`，左臂使用原图层与 `60% 78%` 旋转轴，右臂使用镜像图层与 `40% 78%` 旋转轴，动画周期为 `0.47s`，左右手臂不设置错峰延迟；不要把 `scaleX(...)` 和 rotate 放在同一个手臂 wrapper 上。
- 验证：用用户录屏关键帧或离线合成预览检查摆动两端的手臂根部仍贴住肩点；再运行儿童动作 Demo 定向组件测试、ESLint 和 `npm run check:encoding`。
- 关联：`src/index.css`、`public/child-motion-demo/picture-book-wave-cat-body-guide-v7.png`、`public/child-motion-demo/picture-book-wave-cat-arm-guide-v7.png`、`docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md`。

## GPT-image-2 不再读 APIMart 图片配置

- 现象：配置了 `APIMART_BASE_URL` / `APIMART_API_KEY` 后，RPG、拼图或方洞的 GPT-image-2 生图仍返回缺配置，或请求体里还出现 `official_fallback` / `image_urls`。
- 原因：2026-05-21 后 GPT-image-2 图片生成按 VectorEngine 创建/编辑接口分流，APIMart 只保留给创意 Agent 的 `gpt-5` Responses 文本/多模态链路。
- 处理：为图片生成配置 `VECTOR_ENGINE_BASE_URL=https://api.vectorengine.ai`、`VECTOR_ENGINE_API_KEY`、`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`；排查请求体时确认无参考图路径为 `/v1/images/generations`、有参考图路径为 `/v1/images/edits`，模型为 `gpt-image-2`。
- 验证：运行 `cargo test -p api-server openai_image --manifest-path server-rs/Cargo.toml` 和相关玩法图片生成测试；真实联调只在本地私密环境放置 VectorEngine key。
- 关联：`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`、`server-rs/crates/api-server/src/openai_image_generation.rs`。

## 拼图参考图没有影响生成时先查 action payload 和阶段日志

- 现象：拼图上传参考图后生成出的画面明显不像参考图，或结果页重新生成没有按保存的参考图走图生图。
- 原因：首图生成只通过 `compile_puzzle_draft.referenceImageSrc` 临时传 Data URL，不持久化到 SpacetimeDB；结果页重新生成则要把当前上传图或关卡 `pictureReference` 作为 `generate_puzzle_images.referenceImageSrc` 继续传给后端。
- 处理：浏览器 Network 里确认 action payload 带 `referenceImageSrc`；api-server 日志按同一 `session_id` 查看 `拼图参考图解析完成`、`拼图 VectorEngine 图片生成 HTTP 返回`、`拼图 VectorEngine 图片下载完成`、`拼图生成图片已写入 OSS 与资产索引`，可定位慢在参考图读取、VectorEngine、下载或 OSS。
- 验证：前端测试覆盖上传图 + AI 重绘、结果页保存的 `pictureReference` 重新生成；后端单测覆盖 VectorEngine 请求体 `image` 字段。
- 关联：`src/components/puzzle-agent/PuzzleAgentWorkspace.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`server-rs/crates/api-server/src/puzzle.rs`。

## 拼图首图生成后要把入口参考图写回 `pictureReference`

- 现象：入口页上传图后，首图看着像没吃到参考图；结果页重新生成时默认只沿用关卡旧图，没有继续带入口上传图。
- 原因：首图生成请求虽然已经把 `referenceImageSrc` 传给 VectorEngine，但如果后端只更新 `cover_image_src` / `selected_candidate_id` 而不回写首关 `pictureReference`，结果页后续重绘就会丢失参考图。
- 处理：在 `compile_puzzle_draft` 和 `generate_puzzle_images` 的成功与 SpacetimeDB 降级快照路径里，都把本次入口参考图写入首关 `pictureReference`。
- 验证：后端单测覆盖 `build_puzzle_levels_with_primary_update` 和 `apply_generated_puzzle_candidates_to_session_snapshot`；结果页重新生成应在未重新上传时继续带入 `level.pictureReference`。
- 关联：`server-rs/crates/api-server/src/puzzle.rs`、`src/components/puzzle-result/PuzzleResultView.tsx`。

## 拼图参考图不像时先看 edits multipart image

- 现象：Network payload 已带 `referenceImageSrc`，但 VectorEngine 生成结果仍明显不像上传图。
- 原因：参考图只在 `aiRedraw = true` 时由后端解析并传给 `gpt-image-2` `/v1/images/edits` 的 multipart `image` part；若前端没传 `referenceImageSrc`、后端解析失败或 prompt 缺少参考图强约束，生成会退化为纯文生图。
- 处理：`referenceImageSrc` 存在且 `aiRedraw = true` 时走 edits multipart，prompt 保留参考图强约束；入口页关闭 AI 重绘时直接应用上传图，不调用图片生成；前端把参考图压到单边 1024 内，后端解析后拒绝超过 8MB 的参考图字节。
- 验证：后端单测应覆盖 `/v1/images/edits` 路由、`b64_json` 响应解码和参考图强提示；真实联调看日志里是否命中 `拼图 VectorEngine 图片编辑 HTTP 返回`。
- 关联：`server-rs/crates/api-server/src/puzzle.rs`、`src/services/puzzleReferenceImage.ts`、`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`。

## 拼图 edits 报 error sending request 先看网络分类

- 现象：拼图有参考图时返回 `拼图图片生成失败：创建拼图 VectorEngine 图片编辑任务失败：error sending request for url (https://api.vectorengine.ai/v1/images/edits)`，后端没有 `拼图 VectorEngine 图片编辑 HTTP 返回` 日志。
- 原因：这是 `reqwest` 在 `send()` 阶段失败，尚未收到 VectorEngine HTTP 响应；常见原因是服务器网络 / DNS / 防火墙 / 代理问题，或上游网关中断 multipart 连接。
- 处理：查看错误响应和 `拼图 VectorEngine 图片编辑` 相关日志；若请求发送阶段失败，先查网络出口、DNS、防火墙、代理、参考图大小和 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`。
- 验证：`curl --http1.1 -i -X POST https://api.vectorengine.ai/v1/images/edits -H "Authorization: Bearer invalid" -F "model=gpt-image-2" -F "prompt=test" -F "n=1" -F "size=1024x1024" -F "image=@public/match3d-background-references/pot-fused-reference.png;type=image/png"` 至少应返回 HTTP `401`，说明域名、TLS、路径和 multipart 上传可达；执行 `cargo test -p api-server puzzle_vector_engine --manifest-path server-rs/Cargo.toml`。
- 关联：`server-rs/crates/api-server/src/puzzle.rs`、`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`、`docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md`。

## 拼图 UI 背景缺失先区分生成失败和消费链路丢字段

- 现象：拼图草稿生成完成后，素材配置页没有展示生成的 UI 背景，或结果页能看到背景但自动试玩 / 结果页“试玩”进入局内仍只显示封面模糊背景。
- 原因：`compile_puzzle_draft` 设计上会在首图后生成 UI 背景，且缺 `uiBackgroundImageSrc/uiBackgroundImageObjectKey` 会让自动草稿失败；若草稿已成功，通常不是“没生成”，而是前端消费链路漏了 `levels[].uiBackgroundImageObjectKey` 回退，或本地 `startLocalPuzzleRun(...)` 只把 `coverImageSrc` 带入 `currentLevel`。
- 处理：结果页预览、运行态和本地运行态统一用 `resolvePuzzleUiBackgroundSource`，优先 `uiBackgroundImageSrc`，为空时把 `uiBackgroundImageObjectKey` 规范成 `/generated-...` 路径并交给 `/api/assets/read-url` 换签；`startLocalPuzzleRun` 与本地下一关 handoff 都要从 `PuzzleWorkSummary.levels[]` 复制 `uiBackgroundImageSrc/uiBackgroundImageObjectKey/backgroundMusic` 到 `currentLevel`。结果页 `UI背景提示词` 输入框不得把本地兜底 prompt 直接显示成已保存提示词，避免误判为后端已生成。
- 验证：`npm run test -- src/components/puzzle-result/PuzzleResultView.test.tsx src/services/puzzle-runtime/puzzleLocalRuntime.test.ts src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx`，以及 `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "puzzle draft generation auto starts trial"`；后端用 `cargo test -p api-server puzzle_ui_background --manifest-path server-rs\Cargo.toml` 确认生成 / 序列化链路。
- 关联：`src/services/puzzle-runtime/puzzleUiBackgroundSource.ts`、`src/services/puzzle-runtime/puzzleLocalRuntime.ts`、`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md`。

## 拼图草稿生成后音乐/UI 又变空先查结果页回包合并

- 现象：拼图草稿生成完成后，音乐面板曲名有值但音频槽仍显示“暂无音乐”，UI 仍展示默认预览；试玩进入局内也没有生成音乐或 UI 背景。
- 原因：结果页若已有本地 `generationStatus = generating` 编辑态，后端生成完成回包会走 `mergeDraftEditStateWithIncomingState(...)` 合并。该合并必须把生成候选图、正式图、`uiBackground*` 和 `backgroundMusic` 作为同一批生成资产处理；漏掉 `backgroundMusic` 时，随后自动保存会把空音乐写回 `levels_json`。
- 处理：`PuzzleResultView` 合并生成完成回包时同步保留 `backgroundMusic`，并用回归测试覆盖 UI 预览、音乐试听和试玩 payload 都读取最新 `levels[]` 资产。
- 验证：`npm run test -- src/components/puzzle-result/PuzzleResultView.test.tsx`，以及自动试玩入口测试 `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "puzzle draft generation auto starts trial"`。
- 关联：`src/components/puzzle-result/PuzzleResultView.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`docs/technical/PUZZLE_MATCH3D_RESULT_AUDIO_TAB_2026-05-11.md`。

## 自动草稿成功但缺音乐或 UI 先查后端吞错

- 现象：拼图或抓大鹅生成页提示完成，但草稿页仍显示“暂无音乐”，拼图 UI 仍是默认预览，试玩局内也没有生成音乐或 UI 背景。
- 原因：自动草稿阶段如果把 VectorEngine / Suno / OSS / 资产绑定错误记录为 warning 后继续返回成功，前端只能拿到缺关键资产的成功 draft，随后保存和试玩都会消费这份空资产状态。
- 处理：自动草稿必须把必需生成资产当作后端完成条件：拼图首关需同时具备 `levels[0].backgroundMusic.audioSrc` 和 `levels[0].uiBackgroundImageSrc/uiBackgroundImageObjectKey`；抓大鹅需在 `generatedItemAssets[]` 中具备非空 `backgroundMusic.audioSrc`。缺失或上游失败时返回错误并停留在生成页，结果页手动重新生成只作为已有草稿补救入口。
- 验证：`cargo test -p api-server puzzle_initial_draft_assets_must_include_music_and_ui_background match3d_background_music_ready_requires_audio_src match3d_background_music_title_is_required_for_auto_draft --manifest-path server-rs\Cargo.toml`，并重启 `npm run dev:api-server` 后检查 `/healthz`。
- 关联：`server-rs/crates/api-server/src/puzzle.rs`、`server-rs/crates/api-server/src/match3d.rs`、`docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 拼图草稿生成 180 秒后 502/504 先查 VectorEngine 超时与前端重试

- 现象：点击“生成拼图游戏草稿”后，`POST /api/runtime/puzzle/agent/sessions/{sessionId}/actions` 等待约 180 秒返回 `502 Bad Gateway` 或 `504 Gateway Timeout`；钱包流水里同一 session 可能出现连续两组 `puzzle_initial_image` 扣费后退款。
- 原因：首图生成走 VectorEngine `gpt-image-2`，默认 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS=1000000`；若上游在该窗口内未返回，后端退款并返回超时错误。旧前端 action 写请求会对 502/503/504 自动重试一次，导致同一次点击重复触发生图与扣退费。
- 处理：拼图/创作 Agent 的 `executeAction` 默认不做前端自动重试；后端将 VectorEngine / 图片请求超时映射为 `504 Gateway Timeout`，`error.details.provider=vector-engine` 且 `timeout=true`。真实排障按日志同一 `session_id` 查 `拼图 VectorEngine 图片生成 HTTP 返回` 是否缺失，以及钱包流水扣费到退款的时间差是否接近 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`。
- 验证：运行 `npm run test -- src/services/creation-agent/creationAgentClientFactory.test.ts src/services/apiClient.test.ts`、`cargo test -p api-server puzzle_vector_engine --manifest-path server-rs/Cargo.toml`，真实联调重启 `npm run dev:api-server` 后检查 `/healthz`。
- 关联：`src/services/creation-agent/creationAgentClientFactory.ts`、`server-rs/crates/api-server/src/puzzle.rs`、`docs/technical/API_SERVER_EXTERNAL_SERVICE_ENV_CONFIG_2026-05-07.md`。

## 开局 CG 故事板生图失败先查 VectorEngine 请求预算和旧进程

- 现象：RPG 结果页点击开局 CG 后，`POST /api/runtime/custom-world/opening-cg` 在较长等待后返回“开局 CG 故事板生成失败：创建图片生成任务失败：error sending request for url (https://api.vectorengine.ai/v1/images/generations)”。
- 原因：该故事板会把角色图和首幕背景图作为参考图一起传给 VectorEngine `gpt-image-2-all`，请求体和上游生成耗时都比普通单图更大；若运行中的 `api-server` 仍沿用旧 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`，或者参考图过大，会在请求发送/等待阶段被 reqwest 截断。日志里 `timeout=false connect=false request=true body=false source=client error (SendRequest)` 表示还没拿到上游 HTTP 响应，通常优先怀疑大 JSON 请求体、上游网关中断或 HTTP 协议兼容，而不是业务响应解析失败。直接请求 VectorEngine 若无效 token 可快速返回 401，不能据此判断真实生图不会超时。
- 处理：开局 CG 参考图入参先压到单边 768 的 JPEG；`/v1/images/generations` 保持 reqwest 默认 HTTP 协商，只有 multipart `/v1/images/edits` 单独强制 HTTP/1.1。后端图片 helper 将 `request_body_bytes`、每张参考图 Data URL 长度、`timeout/connect/body/source/rootSource/sourceChain/endpoint` 分类写入日志和 `error.details`，前端优先展示 `details.reason`。修改 `.env.secrets.local` 后必须重启 `api-server`，`npm run dev` 终端用 `rs api-server`，否则旧进程仍按旧超时运行。
- 验证：分别运行 `cargo test -p api-server custom_world_ai --manifest-path server-rs/Cargo.toml` 和 `cargo test -p api-server openai_image_generation --manifest-path server-rs/Cargo.toml`；真实联调重启后再触发开局 CG，若仍失败看返回的 `details.reason/source/rootSource/sourceChain/timeout/connect/body/endpoint` 和 `logs/api-server/` 同一 request_id。
- 关联：`server-rs/crates/api-server/src/custom_world_ai.rs`、`server-rs/crates/api-server/src/custom_world_ai/opening_cg.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 开局 CG 成功后又变空白要保留 profile.openingCg

- 现象：RPG 结果页里的开局 CG 成功显示一瞬后，窗口又退回空白占位。
- 原因：`openingCg` 只存在于结果页 profile 槽位，如果父层在 `onProfileChange` 后重新同步了 profile，却经过 `normalizeCustomWorldProfileRecord` 或作品库写回时丢掉 `openingCg`，预览就会从视频 / 故事板回退为空白。
- 处理：`src/data/customWorldLibrary.ts` 的 profile 归一化必须透传 `openingCg`；结果页和父层后续同步都应把它当作受控资产槽位，而不是临时 UI 状态。
- 验证：`npm run test -- src/data/customWorldLibrary.test.ts src/components/CustomWorldResultView.test.tsx`，确认生成后即使父层做一次归一化回写，开局 CG 仍继续显示。
- 关联：`src/data/customWorldLibrary.ts`、`src/components/rpg-creation-result/RpgCreationResultViewImpl.tsx`、`src/components/CustomWorldEntityCatalog.tsx`。

## RPG 发布报 legacy_result_profile_json 非法先查 null 兼容

- 现象：RPG 结果页发布动作返回 `UPSTREAM_ERROR`，SpacetimeDB details 里是 `custom_world.compile.legacy_result_profile_json 不是合法 JSON object`。
- 原因：`publish_world` 前端契约只要求 `{ action: 'publish_world' }`；`ExecuteCustomWorldAgentActionRequest.legacy_result_profile` 是可选字段，经 HTTP / serde / SpacetimeDB payload 传递时可能显式成为 JSON `null`。旧的编译器只接受 object 或缺省，把 `Some("null")` 当成非法 legacy JSON。
- 处理：`module-custom-world` 的 optional JSON object 解析要把 `null` 视为未提供，仍拒绝数组、字符串、数字和坏 JSON；正式发布继续以 session `draft_profile_json` 为草稿真相。
- 验证：`cargo test -p module-custom-world published_profile_compile --manifest-path server-rs/Cargo.toml`。
- 关联：`server-rs/crates/module-custom-world/src/application.rs`、`server-rs/crates/spacetime-module/src/custom_world.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 本地脚本调 VectorEngine 生图卡住先区分 fetch 首部超时

- 现象：用 Node `fetch` 直接请求 `POST /v1/images/generations`，已经设置较长的 AbortController 超时，但仍在约 180 到 300 秒后抛 `AbortError`、`TypeError: fetch failed` 或 `UND_ERR_HEADERS_TIMEOUT`；同一 prompt 改用原生 `https.request` 可以在较短时间内成功返回图片。
- 原因：Node/Undici 的默认 headers timeout 可能早于业务脚本期望的长生图等待窗口触发，表现上容易被误判成 VectorEngine 上游本身超时。
- 处理：长期脚本优先复用后端 reqwest 或项目已有生成脚本；临时本地工具若必须用 Node，可改用原生 `http`/`https.request` 并显式设置 socket timeout，或为 Undici 单独配置 headers timeout。仍需隐藏 `VECTOR_ENGINE_API_KEY`，只报告配置是否存在。
- 验证：同一 `gpt-image-2` 请求体、同一环境变量下，原生 HTTP 请求能返回 `url` / `b64_json` 并落盘；失败时错误里能区分请求发送、首部等待、下载和解码阶段。
- 关联：`.codex/skills/gpt-image-2-apimart/SKILL.md`、`server-rs/crates/api-server/src/openai_image_generation.rs`。

## 旧后端路线文档造成判断漂移

- 现象：开发时参考到 Express、Node、PostgreSQL 或 Go 方向旧文档，导致接口、数据真相或部署路径与当前主线不一致。
- 原因：项目历史文档较多，部分旧方案仍保留作迁移参考。
- 处理：涉及服务端、数据真相、SpacetimeDB、运行时状态时，先看 `CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`，再看 DDD 总纲和具体技术方案。
- 验证：代码改动应落在 `server-rs + Axum + SpacetimeDB` 主线；旧路线只作为迁移参考，不作为兼容目标。
- 关联：`docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`、`AGENTS.md`。

## SpacetimeDB 表结构变更不能按 PostgreSQL 迁移直觉处理

- 现象：发布时 schema 冲突、自动迁移拒绝、旧客户端调用 reducer 失败、private 表数据迁移遗漏。
- 原因：SpacetimeDB 对字段删除、类型变化、索引/主键/RLS/reducer 变化有不同自动迁移边界。
- 处理：变更前阅读 `SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`；已有表新增字段必须放在 Rust 表结构体最后并设置明确默认值；需要修改字段名时，先询问用户并确认迁移计划；涉及表变化时同步 `migration.rs`、`SPACETIMEDB_TABLE_CATALOG.md` 和 bindings；必要时走 JSON 导入导出与分片导入迁移流程。
- 验证：发布前运行 `npm run check:spacetime-schema`，完成 schema 检查、bindings 生成、表目录更新和相关 smoke。
- 关联：`docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。

## SpacetimeDB publish 报 wasm-bindgen 时先查 shared-contracts feature

- 现象：发布 `spacetime-module` 时报 `wasm-bindgen detected`，提示 `wasm-bindgen is only for webassembly modules that target the web platform`。
- 原因：SpacetimeDB module 的 wasm32 构建树被间接带入原生/网页依赖；已验证链路是 `reqwest -> platform-oss -> shared-contracts -> module-runtime -> spacetime-module`，由共享契约默认启用资产 OSS 契约触发。
- 处理：让 `shared-contracts` 的 OSS 资产契约走 `oss-contracts` feature，workspace 根依赖保持 `default-features = false`；`api-server` 这类原生后端需要资产 DTO 时在自身 `Cargo.toml` 显式启用 `features = ["oss-contracts"]`。
- 验证：执行 `cargo tree -i wasm-bindgen --manifest-path server-rs\crates\spacetime-module\Cargo.toml --target wasm32-unknown-unknown` 应显示 nothing to print；再执行 `cargo check -p spacetime-module --manifest-path server-rs\Cargo.toml --target wasm32-unknown-unknown`。
- 关联：`server-rs/crates/shared-contracts/Cargo.toml`、`server-rs/crates/api-server/Cargo.toml`、`docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md`。

## 本地 SpacetimeDB replica identity 不匹配

- 现象：本地 standalone 启动时报 `mismatched database identity`。
- 原因：本地 SpacetimeDB 数据目录中的 replica 数据残留与当前数据库身份不一致。
- 处理：按本地 replica identity mismatch 文档进行备份、重建和脚本诊断。
- 验证：本地 SpacetimeDB 可正常启动并 publish / 访问。
- 关联：`docs/technical/SPACETIMEDB_LOCAL_REPLICA_IDENTITY_MISMATCH_FIX_2026-04-30.md`。

## 本地 SpacetimeDB publish 403 优先查 CLI 身份和目标库

- 现象：`spacetime publish` 在 `Pre-publish check` 阶段返回 `403 Forbidden`，提示当前 identity 无权对目标 database identity 执行 `update database`。
- 原因：当前 CLI 登录态不是目标数据库的创建者或授权身份，或 `.env.local` / publish 命令指向了另一个数据库或 SpacetimeDB 服务。
- 处理：除 CI/CD 脚本内部受控用法外，不再使用 `spacetime --root-dir` 排障或发布。先执行 `spacetime login show`、`spacetime server list`，再用 `spacetime list --server http://127.0.0.1:3101` 或实际 `--server-url` 确认当前身份是否能看到目标库；本地开发发布优先使用 `npm run dev:spacetime` 或从 `server-rs` 目录执行显式 `--server` 的 `spacetime publish`。如果身份不对，重新登录正确身份、使用项目脚本重新生成本地库，或在 SpacetimeDB 侧补授权。
- 验证：`spacetime list --server http://127.0.0.1:3101` 能看到目标库；重新发布不再使用无权限 identity。
- 关联：`scripts/dev.mjs`、`docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md`。

## `npm run dev` 本地 SpacetimeDB 401 / 403 可重置默认 local 身份

- 现象：`npm run dev` 启动本地开发栈时，SpacetimeDB 在登录、发布或预检查阶段返回 `401` / `403`，清理后仍像在使用旧 token 或旧本地库。
- 原因：本机 `spacetime` CLI 保存的旧 token、默认 server、正在运行的 standalone 进程或默认 local 数据库与当前发布身份不一致。
- 处理：确认只是本地测试库且数据可丢弃后，先查看并停止本地 `spacetimedb-standalone`，执行 `spacetime logout`，确认并设置 `spacetime server set-default local`，停 server 后用 `spacetime server clear -y` 清空默认本地库，再 `spacetime start`，另开终端执行 `spacetime login --server-issued-login local`，最后用 `spacetime publish --server local A` 或项目脚本重新发布。
- 验证：`spacetime server list` 默认目标为 local；重新登录后发布不再返回 `401` / `403`；`npm run dev` 可以完成 SpacetimeDB publish 并继续启动 `api-server`。
- 关联：`docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md`、`scripts/dev.mjs`。

## 本地 SpacetimeDB 联调可按阶段跳过宿主或发布

- 现象：本地 `npm run dev` 因 `3101` 已占用、重复发布 SpacetimeDB wasm 编译太慢，或只想检查 `spacetime-module` 语法而被完整联调链路拖慢。
- 原因：`npm run dev` 默认同时启动 SpacetimeDB standalone、发布 `server-rs/crates/spacetime-module`、启动 Rust `api-server`、主站 Vite 与后台 Vite；并非每个阶段都需要完整重启和重新发布。
- 处理：`npm run dev` 启动后会把实际 SpacetimeDB URL 记录到 `server-rs/.spacetimedb/local/data/dev-spacetime-url`，并同步写旧兼容文件 `dev-rust-spacetime-url`。下次启动即使没有传 `--skip-spacetime`，调度器也会先检查该 URL 旁边的 `spacetime.pid` 和 `/v1/ping` 是否可复用；在线则直接复用现有宿主。确认需要新启动 SpacetimeDB 时，脚本先检测 `3101`，被占用则选择最近可用端口，保证 publish 与 `api-server` 都连接同一个实际 SpacetimeDB URL。显式传 `--skip-spacetime` 时表示复用既有宿主，脚本不再对 SpacetimeDB 端口做可用性漂移；`--spacetime-port 3101` 就是后端要连接的实际端口，避免被误改到空闲但未启动的 `3102`。`api-server`、主站 Vite 和后台 Vite 启动前也会解析可用端口。`spacetime-module` 改动后只重新 publish，不重启 standalone 宿主；未修改 `spacetime-module` 时使用 `npm run dev -- --skip-publish`；只查模块语法时执行 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`。`npm run dev` 会在启动前检查 SpacetimeDB、api-server、主站 Vite、后台 Vite 端口，不可用时自动寻找后续可用端口，并把实际端口传给 publish、后端环境变量和前端代理目标。
- 验证：`--skip-spacetime` 后脚本复用现有 `http://127.0.0.1:3101`；日志中的 `[dev] spacetime:` 不应漂移到没有服务的 `3102`；`GET /api/creation-entry/config` 不应返回连接空端口导致的 `502`。`3101` 或 `8082` 被其他进程占用时，脚本使用最近可用端口；`--skip-publish` 后不再进入 publish 阶段；`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 能完成 Rust 语法和类型检查。端口漂移时控制台会打印 `[dev:ports] ... 不可用，改用 ...`，后续 `[dev] web/admin web/api-server/spacetime` 地址应与实际端口一致。`spacetime-module` 变更后只应看到重新发布日志，不应看到 standalone 重启日志。
- 关联：`docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`、`scripts/dev.mjs`。

## `npm run dev -- --watch` 前端无限重启先查外层 watcher

- 现象：开启 `npm run dev -- --watch` 后，后台 Vite 或主站 Vite 反复退出重启，即使没有手动修改源码。
- 原因：Vite 本身会监听源码并写入 `node_modules/.vite` 等缓存；外层调度器如果再递归监听前端目录并重启 dev server，就可能把 Vite 自己的缓存写入当成源码变化，形成循环重启。
- 处理：外层 watcher 只负责后端侧：`spacetime-module` 改动后重新 publish，`api-server` 改动后重启 Rust 进程。主站 Vite 和后台 Vite 的源码变化交给 Vite HMR；需要进程级重启时在 `npm run dev` 终端手动输入 `rs web` 或 `rs admin-web`。
- 验证：`npm run dev -- --watch` 下修改 `apps/admin-web/src/**` 应由 Vite HMR 处理，不应出现连续 `[dev] 重启 admin-web`；`scripts/dev.test.ts` 覆盖 web/admin-web 不注册外层 watch。
- 关联：`scripts/dev.mjs`、`docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`。

## 本地 SpacetimeDB publish 401 可清本地库重发

- 现象：本地 `spacetime publish` 显示 `401` 无权限，或重新发布仍像是在更新旧库。
- 原因：本地开发数据目录中保留的数据库、控制库身份或发布身份与当前目标不一致。
- 处理：确认本地开发数据可以丢弃后，停止本地 SpacetimeDB，备份或删除 `server-rs/.spacetimedb/local/data`，再重新运行 `npm run dev` 或本地 publish；不要用 `--root-dir` 手工清库。
- 验证：重新发布日志应显示创建新的数据库，而不是更新旧数据库；若仍显示更新或继续 `401`，继续检查数据目录、库名和 CLI 身份。
- 关联：`docs/technical/RUST_LOCAL_AND_REMOTE_DEPLOYMENT_SCRIPTS_2026-04-22.md`、`docs/technical/SPACETIMEDB_START_SH_PUBLISH_403_IDENTITY_FIX_2026-04-26.md`。

## SpacetimeDB 模块 publish 报 `wasm-bindgen detected`

- 现象：`spacetime publish` 已经完成 Rust 编译，但随后报 `wasm-bindgen detected`，提示依赖树里有面向 Web 平台的 wasm-bindgen。
- 原因：SpacetimeDB 模块是数据库内 WASM，不允许拉入 Web/HTTP client 链路；常见误因是 `spacetime-module -> module-* -> shared-contracts -> platform-* -> reqwest -> wasm-bindgen` 这类反向依赖。
- 处理：执行 `cargo tree -i wasm-bindgen --manifest-path server-rs/Cargo.toml -p spacetime-module --target wasm32-unknown-unknown` 找到链路；把平台实现类型从 `shared-contracts` 或 `module-*` 中移除，只保留公开 DTO，平台响应到 DTO 的转换放回 `api-server` 等 adapter 层。
- 验证：上述 `cargo tree` 输出 `warning: nothing to print`；`cargo check -p shared-contracts`、`cargo check -p api-server` 通过；重新 `spacetime publish ... --module-path server-rs/crates/spacetime-module` 不再报 wasm-bindgen。
- 关联：`docs/technical/RUST_WORKSPACE_DEPENDENCY_CONSOLIDATION_2026-05-07.md`、`server-rs/crates/shared-contracts/src/assets.rs`、`server-rs/crates/api-server/src/assets.rs`。

## Vite SPA fallback 吞掉 API 请求

- 现象：本地请求 `/api/profile/*` 等接口时返回 HTML，被前端当 JSON 解析报错。
- 原因：Vite 代理缺少对应 `/api/*` 前缀，API 请求落到 SPA fallback。
- 处理：补齐 Vite 代理，让 API 请求转发到 Rust `api-server`。
- 验证：请求返回 JSON，相关页面不再出现 HTML parse 错误。
- 关联：`docs/technical/PROFILE_MAIN_ROUTE_VITE_PROXY_FIX_2026-05-02.md`。

## `npm run build` 因 Vite warning 被 build-gate 判失败

- 现象：主站或后台 Vite 已经输出 `built in ...`，但根命令最后仍失败并打印 `Build gate failed because warnings were emitted`。
- 原因：`scripts/build-gate.mjs` 会收集 stdout / stderr 中的 warning 行并作为硬失败；常见触发是产物 chunk 超过 `vite.config.ts` 或 `apps/admin-web/vite.config.ts` 的 `chunkSizeWarningLimit`。
- 处理：先看 warning 原文确认来源。若是合理的入口级 chunk 体积增长，调整对应 Vite 配置阈值或做真实拆包；不要把这类失败按 Rust / SpacetimeDB 编译错误排查。
- 验证：重新执行 `npm run build`，主站与后台均构建完成且没有 build-gate warning 汇总。
- 关联：`scripts/build-gate.mjs`、`vite.config.ts`、`apps/admin-web/vite.config.ts`。

## 反馈页清空 file input 前必须先拷贝 FileList

- 现象：点击上传凭证会打开文件选择框，但选择图片后页面没有展示预览，提交时也没有携带图片凭证。
- 原因：浏览器传入的 `FileList` 可能跟 `<input type="file">` 保持 live 绑定；如果先执行 `input.value = ''`，再从参数里的 `FileList` 读取文件，列表可能已经为空。
- 处理：在清空 file input 前先执行 `const selectedFiles = files ? Array.from(files) : []`，后续图片类型、大小、Data URL 读取和预览都基于这个普通数组。
- 验证：`PlatformFeedbackView.test.tsx` 用 mock `FileReader` 断言选择图片后出现 `反馈凭证预览`，且提交 payload 带 `evidenceItems[].dataUrl`。
- 关联：`src/components/platform-entry/PlatformFeedbackView.tsx`、`docs/technical/PROFILE_FEEDBACK_BACKEND_INTEGRATION_2026-05-08.md`。

## 拼图 VectorEngine 图片生成密钥不能复用 DashScope / ARK key

- 现象：拼图新手引导或拼图创作点击生成后返回 `VectorEngine 图片生成密钥未配置`。
- 原因：拼图 `gpt-image-2` / 历史 `nanobanana2` 图片生成已统一走 VectorEngine；后端只读取 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY`、`VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS`，不会用 `DASHSCOPE_API_KEY`、`LLM_API_KEY`、`ARK_API_KEY` 或 `APIMART_API_KEY` 兜底。
- 处理：在本机私密配置 `.env.secrets.local` 或进程环境中配置真实 `VECTOR_ENGINE_API_KEY`，不要提交到 Git；填入后必须重启 `api-server` / `npm run dev`，运行中的进程不会自动加载新 env。
- 验证：不打印密钥内容，只检查 `VECTOR_ENGINE_API_KEY` 非空；重启后触发拼图生成不再返回本地配置缺失的 503。
- 关联：`docs/technical/VECTOR_ENGINE_GPT_IMAGE_2_GENERATION_2026-05-09.md`、`.codex/skills/gpt-image-2-apimart/SKILL.md`。

## `npm run dev:api-server` 读取 env 的顺序必须让 `.env.secrets.local` 最后覆盖

- 现象：`POST /api/assets/hyper3d/text-to-model` 在本地返回 503，详情里提示 `HYPER3D_API_KEY 未配置`，但开发者明明已经在本地私密文件里写了 key。
- 原因：`scripts/dev-utils.mjs` 之前按 `.env.secrets.local → .env.local → .env` 合并，结果仓库里的 `.env` 空示例值会把前面已经设置好的私密 key 覆盖掉。
- 处理：`npm run dev:api-server` / `npm run dev:spacetime` / `npm run dev` 统一按“外层 shell 变量优先，其后 `.env`、`.env.local`、`.env.secrets.local` 逐层覆盖”的顺序加载；真实密钥优先放 `.env.secrets.local`。本地认证开关例外：`SMS_AUTH_ENABLED`、`SMS_AUTH_PROVIDER` 等以本地 env 文件为准，避免父进程继承的旧开关值长期压过 `.env.local`。
- 验证：本地加入临时测试后，`HYPER3D_API_KEY` 应能被 `.env.secrets.local` 覆盖，真实密钥 shell 变量仍然最高优先级；`mergeApiServerEnv(..., { SMS_AUTH_ENABLED: "false" })` 在 `.env.local` 写 `SMS_AUTH_ENABLED=true` 时应返回 true。
- 关联：`scripts/dev-utils.mjs`、`server-rs/crates/api-server/src/hyper3d_generation.rs`、`docs/technical/HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md`。

## OSS 密钥键名不要把字母 O 写成数字 0

- 现象：`.env.secrets.local` 看起来已经配置 OSS AccessKey Secret，但拼图或抓大鹅生成仍返回 `OSS 未完成环境变量配置`。
- 原因：后端只读取 `ALIYUN_OSS_ACCESS_KEY_SECRET`。如果写成 `ALIYUN_0SS_ACCESS_KEY_SECRET`，中间是数字 `0`，配置合并检查会显示正确键缺失，`api-server` 不会初始化 OSS 客户端。另一个常见原因是外层 shell / IDE 预置了空的 `ALIYUN_OSS_*`，旧启动脚本会把空值当作最高优先级，导致 `.env.local` 或 `.env.secrets.local` 的真实值被跳过。
- 处理：只改键名为 `ALIYUN_OSS_ACCESS_KEY_SECRET`，保留原值；不要在日志、文档或对话里输出密钥内容。本地启动脚本应只保护非空外层环境变量，空字符串或全空白值不得遮蔽本地 env 文件。
- 验证：运行 `npm run check:api-server-env`，确认 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY`、`ALIYUN_OSS_BUCKET`、`ALIYUN_OSS_ENDPOINT`、`ALIYUN_OSS_ACCESS_KEY_ID`、`ALIYUN_OSS_ACCESS_KEY_SECRET` 都是 `present`，再重启 `npm run dev:api-server` 或 `npm run dev`。

## 拼图图片生成 98% 后报 OSS V4 签名时间格式化失败

- 现象：拼图创作表单生成进度卡在 98%，`POST /api/runtime/puzzle/agent/sessions/{sessionId}/actions` 返回 `502 Bad Gateway`，前端提示 `拼图图片生成失败：OSS V4 签名时间格式化失败`。
- 原因：`platform-oss` 曾用 `OffsetDateTime::time().to_string()` 拼接 `x-oss-date`，UTC 小时、分钟或秒为个位数时可能缺少前导零，导致 V4 签名时间不是固定 `YYYYMMDDTHHMMSSZ`。
- 处理：OSS V4 签名日期统一显式补零格式化；签名 scope 用 `YYYYMMDD`，完整签名时间用 `YYYYMMDDTHHMMSSZ`，不要再依赖 `time().to_string()`。
- 验证：运行 `cargo test -p platform-oss` 和 `cargo check -p api-server`；重启 `npm run dev:api-server` 后检查 `/healthz`，再重新触发拼图生成。
- 关联：`server-rs/crates/platform-oss/src/lib.rs`、`server-rs/crates/api-server/src/assets.rs`、`docs/technical/M6_OSS_SERVER_UPLOAD_AND_STS_POLICY_2026-04-21.md`。

## 拼图生成完成后图片只显示破图或 alt 文案

- 现象：拼图结果页生成完成后，“画面图”区域出现破图图标和作品名，图片无法正常预览；但打开历史拼图素材时同一张图可能可以正常预览。
- 原因：拼图正式图保存为 `/generated-puzzle-assets/*` 兼容标识，旧 `/generated-*` 直读代理已删除；如果前端没有通过 `ResolvedAssetImage` / `/api/assets/read-url` 换签，或收到无前导斜杠的 `generated-puzzle-assets/*` object key 后未识别为 generated 私有资源，浏览器会直接请求裸路径并失败。生成完成后的结果图还会传入 `refreshKey`，它只能用于重新请求 `/api/assets/read-url`，不能给 OSS V4 签名 URL 追加 `_v`；OSS 会把 query 纳入签名，额外参数会让签名失效，历史素材常因未传 `refreshKey` 而表现正常。
- 处理：拼图结果页、发布预览、运行态和历史素材预览都走 `ResolvedAssetImage` 或 `useResolvedAssetReadUrl`；`isGeneratedLegacyPath(...)` 必须同时识别 `/generated-*` 和 `generated-*`；`refreshKey` 只绕过前端签名缓存并重新换签，不修改已返回的 OSS 签名 URL；禁止恢复 `/generated-puzzle-assets` 直读代理。
- 验证：运行 `npm run test -- src\services\assetReadUrlService.test.ts src\hooks\useResolvedAssetReadUrl.test.tsx src\components\puzzle-result\PuzzleResultView.test.tsx`，再触发一次真实生成确认 Network 中先请求 `/api/assets/read-url`，图片 `src` 为未追加 `_v` 的签名 URL。
- 关联：`src/services/assetReadUrlService.ts`、`src/components/ResolvedAssetImage.tsx`、`docs/technical/PUZZLE_IMAGE_ASSET_PROXY_FIX_2026-04-27.md`。

## 本地短信登录页签突然消失

- 现象：登录弹窗只剩密码登录，短信登录页签看起来像被删掉，但 `LoginScreen` 中手机号验证码表单仍存在。
- 原因：历史实现曾根据 `GET /api/auth/login-options` 返回的 `availableLoginMethods` 渲染页签；接口返回空、失败或只返回 `["password"]` 时，`AuthGate` 会降级成只显示密码。
  - 本地启动脚本没有让 `.env.local` 覆盖 `.env`，`SMS_AUTH_ENABLED=true` 不生效，后端只返回 `["password"]`。
  - Rust API 直连已返回 `["phone","password"]`，但 Vite 代理目标指向未监听端口，导致 3000 域名下的 `login-options` 返回 `500`，`AuthGate` 降级成 `["password"]`。
  - 3000 端口被旧 `dev:web` 占用后，新的完整栈 Vite 自动漂移到 3001/3002；浏览器仍打开旧 3000 页面，旧页面继续代理到已经下线的端口。
  - 生成页 UI 改动看起来“完全没变化”时，也要先确认当前浏览器打开的 Vite 进程正在返回最新源码；例如直接请求 `http://127.0.0.1:3000/src/components/CustomWorldGenerationView.tsx` 检查是否包含本次新增类名或关键字。
  - 单独 `npm run dev:web` 启动瞬间另一个临时 API 端口可用，脚本若自动切过去，之后临时 API 停掉也会让 3000 继续代理到空端口。
- 处理：当前口径是登录弹窗永远展示 `短信登录` 与 `密码登录` 两个核心入口；`login-options` 只补充微信等环境相关入口，不能隐藏短信或密码页签。如果“获取验证码”点击后失败，再按短信 provider / API 代理问题排查：优先用 `npm run dev:api-server`、`npm run dev:spacetime` 或 `npm run dev` 启动，确认 `.env.local` 覆盖 `.env`、`RUST_SERVER_TARGET` 没有指向旧端口，并分别请求 3000 域名和 Rust API 目标。
- 验证：即使 `/api/auth/login-options` 返回空、失败或只返回 `["password"]`，登录弹窗也应同时显示 `短信登录`、`密码登录`、`验证码` 输入和“获取验证码”按钮；短信发送真实可用性再通过 `POST /api/auth/phone/send-code` 验证。
- 关联：`src/components/auth/AuthGate.tsx`、`src/components/auth/LoginScreen.tsx`、`src/components/auth/AuthGate.test.tsx`、`scripts/dev-utils.mjs`、`scripts/dev.mjs`。

## 本地短信收不到验证码先查 provider

- 现象：登录弹窗可以进入短信页签，但点击“获取验证码”后，手机没有收到短信。
- 原因：本地 `.env.local` 里如果是 `SMS_AUTH_PROVIDER="mock"`，后端不会发真实短信，只会返回固定 mock 验证码；真实阿里云链路已经改为普通短信 `SendSms`，验证码由当前 `api-server` 进程本地生成、哈希存储和校验，旧 `SendSmsVerifyCode` / `CheckSmsVerifyCode` 托管验证码参数不再参与真实校验。若接口直接返回“手机号登录暂未启用”，说明当前运行中的 `api-server` 进程内 `sms_auth_enabled=false`：常见原因是修改 `.env.local` 后没有重启后端，或外层 shell 已经设置了非空 `SMS_AUTH_ENABLED` 导致 dotenv 不覆盖。历史上 cmd 里 `set SMS_AUTH_ENABLED="true"` 会把引号也传进进程，Rust bool 解析失败后保持默认 false。
- 处理：真实短信联调时把 `.env.local` 的 `SMS_AUTH_ENABLED=true`、`SMS_AUTH_PROVIDER=aliyun` 显式打开，并确认 `ALIYUN_SMS_ENDPOINT=dysmsapi.aliyuncs.com`、`ALIYUN_SMS_SIGN_NAME=北京亓盒网络科技`、`ALIYUN_SMS_TEMPLATE_CODE=SMS_506245486`、`ALIYUN_SMS_TEMPLATE_PARAM_KEY=code` 后重启 `api-server`；如果只想验证 UI 和账号链路，则保留 `mock` 并使用 `SMS_AUTH_MOCK_VERIFY_CODE`。Shell 临时覆盖时 PowerShell 用 `$env:SMS_AUTH_ENABLED="true"`，cmd 用 `set SMS_AUTH_ENABLED=true`，不要把引号作为值的一部分。`api-server` 重启会清掉未校验的本地验证码。
- 验证：分别请求浏览器域名和 Rust API 直连的 `/api/auth/login-options`，都应返回 `["phone","password"]`；`api-server` 日志里 `provider=aliyun` 才说明真实短信链路已生效。需要直接确认平台层真实调用阿里云时，配置 `ALIYUN_SMS_ACCESS_KEY_ID`、`ALIYUN_SMS_ACCESS_KEY_SECRET` 和 `ALIYUN_SMS_REAL_TEST_PHONE_NUMBER` 后手动执行 `cargo test -p platform-auth --manifest-path server-rs/Cargo.toml aliyun_send_sms_real_provider_sends_verify_code -- --ignored --nocapture`。
- 关联：`server-rs/crates/api-server/src/config.rs`、`scripts/dev-utils.mjs`、`docs/technical/AUTH_LOGIN_OPTIONS_DESIGN_2026-04-21.md`、`docs/technical/PHONE_SMS_REAL_PROVIDER_MANUAL_VERIFICATION_RUNBOOK_2026-04-23.md`。

## 手机验证码登录 500 先查短信 provider 语义

- 现象：登录弹窗手机号验证码登录失败，浏览器看到 `POST /api/auth/phone/login 500`，后端日志里同时出现阿里云短信 `UNKNOWN`、`biz.FREQUENCY` 或 `check frequency failed`。
- 原因：真实短信 provider 的配置错误或上游失败曾被 `module-auth` 折叠成 `PhoneAuthError::Store`，HTTP 层只能按内部错误返回 `500`，掩盖了 provider 失败。当前验证码校验已经改成本地哈希校验，登录阶段的验证码错误不会再调用阿里云校验接口；若登录前的发送阶段失败，应优先看 `SendSms` 返回的 `Code/Message`。
- 处理：保留 provider 错误语义，配置错误映射 `503 Service Unavailable`，上游短信失败映射 `502 Bad Gateway`；本地只验证 UI/账号链路时可用 shell 临时覆盖 `SMS_AUTH_PROVIDER=mock` 后启动 `npm run dev:api-server`。
- 验证：`cargo test -p api-server phone_auth_sms_provider_errors_keep_upstream_http_semantics --manifest-path server-rs/Cargo.toml`，真实 provider 频控时接口不再返回 `500`。
- 关联：`server-rs/crates/module-auth/src/errors.rs`、`server-rs/crates/api-server/src/phone_auth.rs`、`docs/technical/PHONE_SMS_PROVIDER_ERROR_HTTP_MAPPING_FIX_2026-05-08.md`。

## 手机验证码登录成功后又瞬间回到未登录

- 现象：手机号验证码登录先成功，随后 UI 又闪回“未登录”，登录弹窗可能重新出现。
- 原因：`AuthGate` 首次 hydrate 会异步轮换 refresh cookie 并请求 `/api/auth/me`。如果用户在 hydrate 完成前已经登录，晚到的旧 hydrate 仍可能把刚写入的 `user` 覆盖成 `null`。
- 处理：给 `AuthGate` 的 hydrate 增加版本号保护；登录成功、退出登录和全局 auth 事件都会推进版本号，旧 hydrate 结果到达后直接丢弃。
- 验证：`npm run test -- src/components/auth/AuthGate.test.tsx`，新增用例应覆盖“旧 guest hydrate 不覆盖新登录态”。
- 关联：`src/components/auth/AuthGate.tsx`、`src/components/auth/AuthGate.test.tsx`、`docs/technical/AUTH_GATE_LOGIN_RACE_GUARD_FIX_2026-05-09.md`。

## 刷新网页后登录态失效

- 现象：刷新网页后，用户明明有本地 access token，却回到未登录状态。
- 原因：`AuthGate` hydrate 曾先强制调用 `refreshStoredAccessToken()`；当 refresh cookie 临时失效、代理错配或后端返回 `401` 时，该方法会先清空本地 access token，随后 `/api/auth/me` 只能恢复成未登录。
- 处理：`refreshStoredAccessToken()` 增加 `clearOnFailure` 选项；`AuthGate` 在已有本地 access token 时先用 `/api/auth/me` 确认用户，确认成功后再后台 refresh 续期与写每日登录埋点，后台 refresh 失败不清 token。
- 验证：`npm run test -- src/services/apiClient.test.ts src/components/auth/AuthGate.test.tsx -t "explicit refresh opts out|auth gate keeps a valid local token login"`。
- 关联：`src/services/apiClient.ts`、`src/components/auth/AuthGate.tsx`、`docs/technical/AUTH_RESTORE_AND_RECOMMEND_LOADING_FIX_2026-05-09.md`。

## 登录后推荐页加载出作品又回到未登录

- 现象：前端登录成功后进入推荐页，推荐页自动加载出一个作品，随后瞬间回到未登录；停留在其他页面或推荐页没加载出作品时不复现。
- 原因：推荐页 embedded 运行态会自动发起受保护写请求。若这些卡片级后台请求遇到 `401` 或 refresh 失败，默认请求层曾清空 access token 并广播全局 auth 事件，导致 `AuthGate` 重新 hydrate 成未登录态。更隐蔽的是，`refreshAccessToken()` 自身曾在 refresh 失败时静默清 token，即便调用方关闭了 `clearAuthOnUnauthorized`，也可能让后续 hydrate 变成未登录。
- 处理：请求层统一使用 `authImpact: 'global' | 'local'` 区分账号权威请求与局部后台请求；推荐页自动运行态、图片换签、公开拼图运行态和平台 bootstrap 私有投影刷新统一使用 `BACKGROUND_AUTH_REQUEST_OPTIONS` / `RUNTIME_BACKGROUND_AUTH_OPTIONS`，并等 `canReadProtectedData` 为 true 后再启动；用户主动点击的账号动作仍保留默认全局鉴权失败处理。
- 追加处理：generated 私有图片换签 `/api/assets/read-url` 也属于展示层后台请求；推荐页拼图运行态挂载后会立即解析封面图，若换签 401 触发全局鉴权事件，也会表现成“进入拼图作品后瞬间未登录”。资源换签失败只应让当前图片为空，不应清 token、广播 auth 事件或主动 refresh。
- 追加处理：从推荐页点进公开拼图作品并启动完整运行态后，`startPuzzleRun`、通关自动 `submitPuzzleLeaderboard`、下一关 `advancePuzzleNextLevel` 和重开同样属于当前玩法局部同步；这些请求失败时只应留在拼图错误态，不应清 token 或广播 auth 事件。
- 追加处理：通关后 `refreshSaveArchives()`、首屏 bootstrap 的个人看板/作品架/浏览历史读写也只是平台投影刷新，失败应显示局部错误，不能充当全局登录态判定。
- 验证：`npm run test -- src/services/apiClient.test.ts src/services/assetReadUrlService.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation starts embedded puzzle"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "formal puzzle runtime uses frontend move merge logic and backend leaderboard"`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "formal puzzle similar work keeps current run level progression"`。
- 关联：`src/services/apiClient.ts`、`src/services/assetReadUrlService.ts`、`src/services/puzzle-runtime/puzzleRuntimeClient.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/technical/RECOMMEND_RUNTIME_AUTH_FAILURE_ISOLATION_FIX_2026-05-09.md`。

## 推荐页作品卡一直显示加载中

- 现象：推荐页有公开作品，但主视口一直停在“加载中...”，没有进入作品，也没有显示可操作错误。
- 原因：推荐页自动启动嵌入运行态时先设置 `activeRecommendEntryKey` / `activeRecommendRuntimeKind` / `isStartingRecommendEntry`，但失败或并发切换时外层缺少稳定错误态和请求版本保护，旧启动请求可能晚到覆盖新状态。
- 处理：`selectRecommendRuntimeEntry` 使用启动请求版本号丢弃旧请求；启动失败统一设置 `activeRecommendRuntimeError = "作品暂时无法进入，请稍后再试。"` 并关闭 `isStartingRecommendEntry`。
- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "home recommendation surfaces start failure"`。
- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`docs/technical/AUTH_RESTORE_AND_RECOMMEND_LOADING_FIX_2026-05-09.md`。

## 推荐页未登录入口误打开公开详情

- 现象：新用户默认在发现页，但点击推荐页或推荐封面后，如果复用公开作品详情入口，可能绕过推荐页“登录后游玩”的产品门禁。
- 原因：`RpgEntryHomeView` 曾只有 `onOpenGalleryDetail` 一个回调，同时服务发现页公开详情和推荐页作品入口；一旦为发现页保留公开浏览能力，推荐页也会跟着打开详情。
- 处理：公开详情与推荐页入口分离为 `onOpenGalleryDetail` 和 `onOpenRecommendGalleryDetail`。发现页、搜索和排行榜保留公开详情；推荐 Tab、推荐封面、推荐运行态错误重试和桌面推荐模块统一走登录门禁。未登录推荐页只显示封面，点击封面只弹登录窗，不携带登录后自动打开详情的回调。
- 验证：`npm run test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "logged out recommend"`。
- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/technical/AUTH_RESTORE_AND_RECOMMEND_LOADING_FIX_2026-05-09.md`。

## Rust 冷编译导致 api-server 健康检查误超时

- 现象：旧 `npm run dev:rust` 在 Windows 冷编译/链接阶段误判 `/healthz` 等待超时并杀掉 `cargo run`；现入口为 `npm run dev` 或 `npm run dev:api-server`。
- 原因：脚本把 SpacetimeDB 与 api-server 等待窗口混在一起，未考虑 Rust 冷编译耗时。
- 处理：按冷编译超时修复文档拆分等待窗口。
- 验证：冷启动时不再误杀仍在编译的 api-server。
- 关联：`docs/technical/API_SERVER_DEV_STACK_COLD_BUILD_TIMEOUT_FIX_2026-04-25.md`。

## Windows debug api-server 主线程栈溢出

- 现象：`cargo check -p api-server` 和 `build_router` 测试通过，但 `npm run dev:api-server` 在 Windows debug 启动时 `thread 'main' has overflowed its stack`。
- 原因：`api-server` Axum 路由树已经很深，debug 主线程默认栈偏小，初始化状态和构造路由时容易触顶。
- 处理：入口 `main` 用显式 16MB 栈线程启动 Tokio runtime，并把实际服务逻辑放入 `run_server()`；新增路由时优先用小 router `.merge()`，避免继续拉长主链。
- 验证：`npm run dev:api-server` 后 `/healthz` 返回 200，相关路由冒烟通过。
- 关联：`server-rs/crates/api-server/src/main.rs`、`server-rs/crates/api-server/src/app.rs`。

## Windows debug api-server.exe 锁文件与强杀退出码容易混淆

- 现象：`cargo run -p api-server` 或 `npm run dev:api-server` 报 `failed to remove file ... target\debug\api-server.exe`；清理旧进程后，旧终端可能继续打印 `process didn't exit successfully: server-rs\target\debug\api-server.exe (exit code: 0xffffffff)`。
- 原因：Windows 不能覆盖仍在运行的 exe；通常是上一条 `npm run dev:api-server` 链路仍在运行，进程树为 `npm run dev:api-server -> node scripts/dev.mjs api-server -> cargo run -> api-server.exe`。`0xffffffff` 常见于排障时用 `Stop-Process -Force` 强制结束旧 `api-server.exe` 后由 Cargo 回显，不一定代表新启动失败。
- 处理：先按目标路径确认并停止本仓库的旧 `api-server.exe` 及其父级 `cargo/node/cmd` 启动链路，再重新启动；不要同时开多个 `npm run dev:api-server`。
- 验证：确认没有匹配 `C:\Genarrative\server-rs\target\debug\api-server.exe` 的进程后，`Remove-Item` 能删除旧 exe；随后 `npm run dev:api-server` 启动并访问 `/healthz` 返回 200。
- 关联：`scripts/dev.mjs`、`server-rs/crates/api-server/src/main.rs`。

## dev scheduler 端口被旧进程占用时会误判健康检查

- 现象：旧本地 dev 链路可能输出 `Port 3000 is in use, trying another one...`，随后 `api-server.exe` 报 `AddrInUse` / `code: 10048`。
- 原因：旧 `api-server` 仍监听默认 `8082` 时，脚本的 `/healthz` 探测会命中旧进程并误判新服务已就绪；旧 Vite 占住 `3000` 时，Vite 默认漂移到新端口，浏览器仍可能打开旧页面。
- 处理：`scripts/dev.mjs` 已在 publish / 编译前解析 SpacetimeDB、`api-server`、主站 Vite、后台 Vite 端口，并让 Vite 使用 `--strictPort`；遇到端口占用时会自动选择后续可用端口，也可显式传入 `--api-port` / `--web-port` / `--admin-web-port`。
- 验证：默认端口被占用时，完整栈应打印 `[dev:ports] ... 不可用，改用 ...` 并把实际端口传给后续 publish、健康检查和 Vite 代理；清理端口后重新启动不再命中旧 `/healthz`。
- 关联：`scripts/dev.mjs`、`docs/technical/DEV_RUST_STACK_PORT_CONFLICT_PRECHECK_2026-05-09.md`。

## Windows debug 长 SSE Future 触发 api-server 断连

- 现象：前端 Vite 代理请求 `/api/runtime/creative-agent/sessions/{sessionId}/messages/stream` 报 `read ECONNRESET`，随后 `api-server.exe` 以 `0xffffffff` 退出，`dev:spacetime` 回收 SpacetimeDB、Vite 和后台 Vite。
- 原因：单个 `async_stream::stream!` 中塞入 Agent 执行、外部模型请求、会话更新和大量 SSE 事件，会在 Windows debug 下生成很大的 Future；真实消费 SSE body 时容易触发 worker 线程栈压力或进程级中断，单元测试若只测函数和路由状态会漏掉。
- 处理：长 SSE 路由优先使用 `tokio::spawn` 跑业务流程，通过 `mpsc` + `UnboundedReceiverStream` 向 Axum 返回轻量 stream；失败时更新会话为 `failed` 并发送 SSE `error`，不要把大段执行逻辑内联到路由返回的 stream future 中。
- 验证：补充实际 `collect()` SSE body 的路由测试，确认首轮包含 `stage`、`puzzle_template_catalog` 和 `done`，且不会提前发送 `puzzle_template_selection` / `puzzle_cost_range`；再执行 `cargo check -p api-server`、`cargo test -p api-server creative_agent`，联调时用 `npm run dev:api-server` 检查 `/healthz`。
- 关联：`server-rs/crates/api-server/src/creative_agent.rs`、`server-rs/crates/api-server/src/app.rs`。

## creative-agent 过程项不要把历史事件渲染成运行中

- 现象：智能创作页过程中多个阶段从一开始同时转圈，生成结束或进入模板确认后仍有过程项保持转圈。
- 原因：前端把历史 `stage`、`tool_started` 和 `thought_summary_delta` 都按 active 渲染；后端工具开始/完成事件如果 `toolCallId` 不一致，也会导致开始事件无法收口。
- 处理：
  - 只有最新且仍在执行的 stage 可为 active；等待确认、等待用户、target ready 和 failed 都是静态状态。
  - 工具开始事件必须等同一 `toolCallId` 的 `tool_completed` 收口；兼容旧流时可按后续同名完成事件兜底。
  - 思考摘要只展示用户可见摘要，且流结束或会话进入等待/完成/失败态后必须改成 done。
- 验证：前端测试断言完成后 `CreativeAgentProcessItem` 不再存在 `tone === 'active'`；后端测试确认工具开始/完成事件使用相同 `toolCallId`。
- 关联：`src/components/creative-agent/creativeAgentViewModel.ts`、`server-rs/crates/api-server/src/creative_agent.rs`、`docs/prd/CREATIVE_INTERACTIVE_AGENT_PHASE1_LANGCHAIN_RUST_PUZZLE_LOOP_PRD_2026-05-05.md`。

## creative-agent 会话切换要清理本地待确认模板

- 现象：用户在一个智能创作会话中点开模板确认面板后，立即切到另一条创作会话，可能看到上一会话的确认面板残留。
- 原因：模板确认面板的 `pendingSelection` 是 `CreativeAgentWorkspace` 本地 UI 状态，不属于后端 session 快照；组件复用时如果不监听 `sessionId` 清理，会跨会话泄漏。
- 处理：工作区以 `session?.sessionId` 为边界清空 `pendingSelection`；服务端仍以 `puzzleTemplateSelection` / `targetBinding` 作为正式业务状态。
- 验证：前端测试先点开模板确认面板，再 rerender 到另一 session，断言确认面板消失。
- 关联：`src/components/creative-agent/CreativeAgentWorkspace.tsx`、`src/components/creative-agent/CreativeAgentWorkspace.test.tsx`。

## 视觉小说 VN-10 不要绕过平台资产引用

- 现象：文档、封面、场景背景、角色立绘或音乐为了预览方便被写成 Data URL、裸对象路径、外部 URL 或本地临时文件路径。
- 原因：前端上传与预览容易混在一起，若不走平台资产对象，SpacetimeDB 和长期草稿会被大文本或大二进制污染。
- 处理：VN 资产统一用 `/api/assets/direct-upload-tickets`、OSS 直传、`/api/assets/objects/confirm`，长期状态只保存 `assetObjectId` 和 `/generated-*` 引用；运行时图片用 `ResolvedAssetImage` 换签。
- 验证：文档模式 `sourceAssetIds` 为平台资产 id；草稿中不出现 `data:`；图片和音乐字段为平台 generated 引用或 null。
- 关联：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`src/services/visual-novel-creation/visualNovelAssetClient.ts`。

## 视觉小说 VN-13 交接时不要再回头找旧迁移方案

- 现象：接手视觉小说的人容易重新打开旧 TXT 迁移文档，把“外部平台工程迁入”误当成当前实现目标。
- 原因：视觉小说历史资料里保留了很多迁移阶段的讨论，而当前真正的实现口径已经收口到 PRD、表目录、Prompt 工具说明、实现收口文档和负向扫描报告。
- 处理：维护视觉小说时优先看 `AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`SPACETIMEDB_TABLE_CATALOG.md`、`VISUAL_NOVEL_PROMPT_AND_LLM_TOOLS_VN03_2026-05-05.md`、`VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`、`VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md` 和 `VN11_NEGATIVE_SCAN_REPORT_2026-05-07.md`。
- 验证：新开发者只读这组文档即可继续维护，不需要把旧 TXT 迁移方案重新当作编码依据。
- 关联：`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`、`docs/technical/VISUAL_NOVEL_IMPLEMENTATION_HANDOFF_2026-05-07.md`、`docs/experience/VISUAL_NOVEL_HANDOFF_AND_MAINTENANCE_2026-05-07.md`。

## 视觉小说公开广场不要触发登录刷新

- 现象：未登录用户进入平台公开广场或从推荐流读取视觉小说公开作品时，前端可能先尝试 `/api/auth/refresh`，失败后再读取公开列表，导致无意义的鉴权噪声或 401 状态刷新。
- 原因：公开只读接口如果复用默认 `requestJson` 选项，缺少 access token 时会先走静默 refresh。
- 处理：视觉小说公开广场列表使用 `skipAuth: true` 与 `skipRefresh: true`；鉴权 mutation 仍保持默认鉴权链路。
- 验证：执行 `src/services/visual-novel-runtime/visualNovelRuntimeClient.test.ts`，确认 `/api/runtime/visual-novel/gallery` 请求携带 `skipAuth` / `skipRefresh`，而 run、重生成和存档 mutation 仍走受保护路由。
- 关联：`src/services/visual-novel-runtime/visualNovelRuntimeClient.ts`、`docs/prd/AI_NATIVE_VISUAL_NOVEL_TEMPLATE_PRD_2026-05-05.md`。

## 创作 Tab 语义迁移后，旧“新建作品”测试要改看智能创作首页

- 现象：把 `create` 从旧创作中心切到 `CreativeAgentHome` 后，旧测试仍尝试在创作页找“新建作品”类型卡，导致用例失败或定位不到元素。
- 原因：产品语义已经变成“创作 = 智能创作首页，草稿 = 旧作品架”，但测试夹具和 helper 还沿用旧入口。
- 处理：把这类测试改成验证智能创作首页、快捷胶囊、抽屉与草稿 Tab；同时给 `useRpgEntryLibraryDetail` 这类恢复路径补上 `setPlatformTabToDraft`。
- 验证：定向 `vitest`、`eslint`、`typecheck`、`check:encoding` 都通过。
- 关联：`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`src/components/rpg-entry/useRpgEntryAgentDraftRestore.test.tsx`、`src/components/rpg-entry/useRpgEntryLibraryDetail.ts`。

## server-rs 默认 cargo build 不能等同于构建 SpacetimeDB 模块

- 现象：在 `server-rs` 下无参数 `cargo build` 期望同时构建 `spacetime-module`，导致链接或构建范围误判。
- 原因：workspace default-members 当前只包含 `crates/api-server`；SpacetimeDB module 有独立构建/发布方式。
- 处理：默认 Rust 构建只覆盖原生 `api-server`；本地模块发布继续走 `spacetime publish --module-path ... --build-options="--debug"` / bindings 生成流程。
- 验证：查看 `server-rs/Cargo.toml` default-members，并按相关 SpacetimeDB 文档执行模块构建。
- 关联：`server-rs/Cargo.toml`、`docs/technical/RUST_WORKSPACE_DEFAULT_BUILD_SCOPE_FIX_2026-04-25.md`。

## Windows 原生 `spacetime-module` 单测会链接缺失 SpacetimeDB 宿主符号

- 现象：在 Windows 上执行 `cargo test -p spacetime-module --manifest-path server-rs/Cargo.toml` 可能编译到链接阶段后失败，出现 `LNK2019` / `LNK1120`，缺失 `datastore_insert_bsatn`、`procedure_start_mut_tx`、`console_log` 等 SpacetimeDB 宿主符号。
- 原因：`spacetime-module` 依赖的 SpacetimeDB runtime API 面向 wasm 宿主环境，原生 test exe 链接不到这些宿主导出。
- 处理：日常语法和类型验证使用 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`；需要验证模块行为时走 SpacetimeDB publish/dev 或模块域纯 Rust crate 的单测，不把该原生链接错误当作业务测试失败。
- 验证：`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 能通过；原生 `cargo test` 若仍报上述宿主符号缺失，按当前限制记录为未执行。
- 关联：`server-rs/crates/spacetime-module`、`docs/technical/SPACETIMEDB_SCHEMA_CHANGE_CONSTRAINTS.md`。

## Rust 构建不要让不可用的 sccache 阻断 rustc

- 现象：Cargo 报 `could not execute process sccache ... rustc.exe -vV (never executed)`、`sccache: error: Timed out waiting for server startup`，或 `sccache: caused by: Failed to send data to or receive data from server / Failed to read response header / failed to fill whole buffer`；真实 `rustc -Vv` 可以执行，但构建在调用包装器时失败。
- 原因：环境、Jenkinsfile 或 `server-rs/.cargo/config.toml` 启用了 `sccache` wrapper，但当前 agent 没有可执行的 `sccache`、PATH 中 shim 损坏，或本地 sccache server/client 通道状态损坏。Windows 本机若配置了 `SCCACHE_OSS_*`，sccache daemon 冷启动会先经 OSS/本机代理完成缓存读写检查，再监听 `127.0.0.1:4226`；代理或 OSS 链路慢时，Cargo 的 `sccache rustc -vV` 可能先超时。
- 处理：保留 `server-rs/.cargo/config.toml` 的 `rustc-wrapper = "sccache"`；Windows 本机优先在 `%APPDATA%\Mozilla\sccache\config\config` 写入 `server_startup_timeout_ms = 60000`，拉长 client 等待 daemon 完成 OSS 初始化的时间，然后删除 `server-rs/target/.rustc_info.json` 里缓存的失败探测结果并重跑原始 Cargo 命令。冷启动验证优先用 `sccache --stop-server`，不要在另一个 `cargo` / `rustc` 仍在编译时 `taskkill /F /IM sccache.exe /T`，否则 proc-macro crate 可能被打断并表现为 `serde_derive` / `spacetimedb-bindings-macro` 的 `sccache ... exit code: 1`。若只做临时排障，可在 Git Bash 中执行 `RUSTC_WRAPPER= CARGO_BUILD_RUSTC_WRAPPER= cargo build ...`，或在 PowerShell 用 `cargo check -p api-server --config "build.rustc-wrapper=''"` 一次性绕过 wrapper；生产流水线必须先实际执行 `sccache --version`，失败时移除 `RUSTC_WRAPPER` 并回退到直接 `rustc`。
- 验证：`rustc -Vv` 能输出版本；冷启动后原始 `cargo check -p api-server` 和 `cargo check -p spacetime-module` 能通过；`sccache --show-stats` 显示 `Cache location oss, name: genarrative-sccache`，证明仍在使用 sccache/OSS 缓存；Jenkins 日志出现“未找到可用 sccache，改用 rustc 直接构建”后仍继续真实构建。
- 关联：`scripts/dev.mjs`、`jenkins/Jenkinsfile.production-stdb-module-build`、`docs/technical/SPACETIMEDB_PUBLISH_SCCACHE_FALLBACK_2026-05-09.md`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。

## 生产发布入口不要沿用旧 Jenkinsfile / 一体化脚本

- 现象：部署、回滚或 Jenkins Job 重建时参考旧发布文档，导致 systemd、Nginx、SpacetimeDB 自托管和生产包拆分不一致。
- 原因：旧 Jenkins / 旧本地远端部署脚本文档仍作为历史经验保留。
- 处理：生产相关操作先看 `PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`，再按需追溯旧文档。
- 验证：发布链路使用当前 `deploy/systemd`、`deploy/nginx`、`scripts/deploy` 和 `jenkins/Jenkinsfile.production-*`。
- 关联：`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。

## Release Web 产物通过内网 rsync 拉取

- 现象：`Genarrative-Web-Deploy` 发布到 `release` 目标时，release agent 本地没有 `/var/cache/genarrative-build/web-artifacts/<job>/<build>/<version>/web.tar.gz`，但 Jenkins controller 又只归档轻量元数据，导致发布阶段找不到 Web 大包。
- 原因：Web 大包为了避免从 Linux 构建机拉回 Jenkins controller，默认留在构建机稳定缓存目录；development 目标与构建机同机可直接读取，release 目标是独立机器，需要内网同步。
- 处理：release 服务器的 Jenkins 运行用户配置 SSH Host `genarrative-build-internal` 指向构建机内网地址，`Genarrative-Web-Deploy` 在 `DEPLOY_TARGET=release` 且本地缺少大包时默认执行 `rsync` 拉取同一路径内容；真实内网 IP、用户和私钥路径只放在服务器本机 SSH config，不写入 Jenkinsfile。
- 验证：在 release 服务器上先手工跑通 `rsync -av --progress "genarrative-build-internal:${SRC}/" "${DST}/"`，再运行 Web Deploy；流水线会继续执行 `web.tar.gz.sha256` 校验。
- 关联：`jenkins/Jenkinsfile.production-web-deploy`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。

## Jenkins 生产流水线拉 Git 先本机再域名备用

- 现象：生产发布、数据库导入导出、服务器配置、构建或 `Genarrative-Full-Build-And-Deploy` 流水线执行 `GitSCM checkout` 时，如果 Jenkins 生成的 fetch 是 `+refs/heads/*:refs/remotes/origin/*`，公网 Git 链路可能在收包阶段以 `git-remote-https died of signal 15`、`curl 56 GnuTLS recv error (-9)`、`early EOF`、`invalid index-pack output` 失败；发布类流水线还可能先遇到 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git` 不可达。
- 原因：`127.0.0.1` 只代表当前执行阶段的 agent 自身；当 release agent 与 Git 服务不在同一台机器，或本机 Git/Web 服务临时不可用时，固定写死 localhost 会阻断 Jenkinsfile 内部源码/脚本 checkout。即使只使用域名 Git，如果 `GitSCM` 没有显式 refspec 并开启 `CloneOption honorRefspec=true`，Jenkins Git 插件也会拉取所有分支。
- 处理：Jenkins Job 的 `Pipeline script from SCM` 由 Windows controller 执行，SCM URL 使用公网域名 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。运行于 Linux agent 的 Jenkinsfile 首次 `checkout([$class: 'GitSCM', ...])` 层先尝试 `GIT_REMOTE_URL=http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后直接尝试 `GIT_REMOTE_FALLBACK_URL=https://git.genarrative.world/GenarrativeAI/Genarrative.git`，不再配置内网 IP fallback；所有生产 Jenkinsfile 的首次 checkout 都必须使用目标分支 refspec、`CloneOption shallow=true depth=1 noTags=true honorRefspec=true`。后续统一走 `scripts/jenkins-checkout-source.sh`，该脚本也按主地址、域名备用地址顺序重新 fetch 并把 `origin` 切到实际可用地址；`COMMIT_HASH` 为空时继续 `--depth=1 --no-tags`，只有指定 commit 时才允许加深历史做分支归属校验。
- 验证：扫描本地 Jenkins live job `config.xml`，确认 SCM `<url>` 都是 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；扫描所有生产 Jenkinsfile 的首次 `GitSCM checkout`，确认 `userRemoteConfigs` 带 `+refs/heads/${params.SOURCE_BRANCH}:refs/remotes/origin/${params.SOURCE_BRANCH}`，`CloneOption` 带 `honorRefspec: true`；运行 `bash -n scripts/jenkins-checkout-source.sh`。
- 关联：`jenkins/Jenkinsfile.production-full-build-and-deploy`、`jenkins/Jenkinsfile.production-web-build`、`jenkins/Jenkinsfile.production-api-build`、`jenkins/Jenkinsfile.production-stdb-module-build`、`jenkins/Jenkinsfile.production-web-deploy`、`jenkins/Jenkinsfile.production-api-deploy`、`jenkins/Jenkinsfile.production-stdb-module-publish`、`jenkins/Jenkinsfile.production-server-provision`、`jenkins/Jenkinsfile.production-database-export`、`jenkins/Jenkinsfile.production-database-import`、`scripts/jenkins-checkout-source.sh`、`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`。

## Jenkins 可选参数在 set -u 下不能裸读

- 现象：数据库导入或导出流水线报 `INCLUDE_TABLES: unbound variable`，或其它可选参数在 Bash 中未定义即退出。
- 原因：Jenkins string/boolean 参数留空时不一定会导出同名环境变量，而生产数据库导入导出脚本块启用了 `set -u`。
- 处理：进入 Bash 执行块后先使用 `${VAR:-}` 或 `${VAR:-默认值}` 收敛成本地变量；必填项使用 `${VAR:?中文错误}` 明确失败原因。
- 验证：扫描 `jenkins/Jenkinsfile.production-database-export` 与 `jenkins/Jenkinsfile.production-database-import`，确认 `INCLUDE_TABLES`、`CHUNK_SIZE`、`SERVER_BACKUP_DIRECTORY`、`SMOKE_HEALTH_URL` 等可选参数不再裸读。
- 关联：`docs/technical/PRODUCTION_DEPLOYMENT_PLAN_2026-05-02.md`、`jenkins/Jenkinsfile.production-database-export`、`jenkins/Jenkinsfile.production-database-import`。

## Jenkins 二次 checkout 后脚本执行位会被 Git 还原

- 现象：`Genarrative-Server-Provision` 已在 shell 块前面对脚本执行 `chmod +x`，但进入 `Prepare Provision Tools` 后仍报 `scripts/prepare-server-provision-tools.sh: Permission denied` / `exit code 126`。
- 原因：该阶段会先运行 `scripts/jenkins-checkout-source.sh`，脚本内部执行 `git reset --hard HEAD` 和 `git clean -fd`，会把前面临时 `chmod` 的执行位还原为 Git 记录的 mode；若被直接执行的脚本在仓库里是 `100644`，二次 checkout 后仍不可执行。
- 处理：需要直接以 `scripts/*.sh` 方式执行的 Jenkins 脚本应提交为 Git `100755`；如果只想临时授权，必须放在 `scripts/jenkins-checkout-source.sh` 完成之后。
- 验证：运行 `git ls-files --stage scripts/prepare-server-provision-tools.sh`，确认 mode 为 `100755`；重新跑 `Genarrative-Server-Provision` 时应进入工具下载/打包日志，而不是停在 `Permission denied`。
- 关联：`jenkins/Jenkinsfile.production-server-provision`、`scripts/prepare-server-provision-tools.sh`、`scripts/jenkins-checkout-source.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## Server-Provision 下载阶段不要放回 genarrative-build-01

- 现象：`Genarrative-Server-Provision` 日志里 `Prepare Provision Tools` 显示 `Running on genarrative-build-01 in /root/...`，随后在该节点上下载 GitHub release 或 `install.spacetimedb.com` 失败。
- 原因：`genarrative-build-01` 在当前 provision 流程里是 Linux 目标发布机/目标 agent，不是用户本地 Windows 下载环境；把下载阶段放在 `linux && genarrative-build` 等于让目标机自己外连。
- 处理：下载必须发生在 Jenkins `windows` 节点的 `Download Provision Tool Archives` 阶段，先下载 SpacetimeDB Linux release tarball 和 `otelcol-contrib` Linux amd64 包，再 `stash/unstash` 到目标 Linux 节点。目标机执行 `scripts/prepare-server-provision-tools.sh` 时设置 `PROVISION_REQUIRE_LOCAL_DOWNLOADS=true`，缺少下载件直接失败，不回退联网下载。
- 验证：Jenkins 日志应先出现 `Running on ... windows` 和 `[prepare-provision-downloads] 下载 ...`，目标节点只出现 `[prepare-provision-tools] 使用已下载的 ...`；如果目标节点出现 `下载 otelcol-contrib:` 或 `下载 SpacetimeDB 官方安装器脚本:`，说明又回退到错误路径。
- 关联：`jenkins/Jenkinsfile.production-server-provision`、`scripts/prepare-server-provision-tools.sh`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## 个人任务 scope 不得扩成 work/site/module

- 现象：个人任务配置为 `work` / `site` / `module` 后进度串桶或静默按 0 处理。
- 原因：首版个人任务只支持用户维度，非 user scope 会造成任务进度读取语义错误。
- 处理：Admin 任务配置页不展示范围选择，保存时固定 `scopeKind: 'user'`；API 和领域构造层拒绝非 `User`。
- 验证：非 `user` scope 返回错误；相关测试覆盖 `Site` / `Module` / `Work` 被拒绝。
- 关联：`docs/technical/RUNTIME_PROFILE_TASK_SCOPE_2026-05-04.md`、`docs/technical/ANALYTICS_DATE_DIMENSION_IMPLEMENTATION_2026-05-04.md`。

## 拼图发布 409 不一定是接口故障

- 现象：拼图结果页点击发布后，控制台出现 `POST /api/runtime/puzzle/agent/sessions/{sessionId}/actions 409 (Conflict)`，用户只看到发布失败。
- 原因：`publish_puzzle_work` 是资产操作发布入口，发布前会预扣 `1` 枚泥点；余额不足时后端按业务冲突返回 `409 CONFLICT`，`details.message` 为 `泥点余额不足`。
- 处理：前端发布弹窗在用户点击发布后必须保留并展示后端业务错误，不能只把错误写到弹窗背后的页面 banner。
- 验证：`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`。

## WebGL 画布在高 DPR 移动端放大溢出

- 现象：抓大鹅试玩入口进入后，3D 锅体和物体从中心圆形区域向右下溢出，顶部状态和底部备选栏也可能看起来被右侧裁切。
- 原因：`WebGLRenderer.setPixelRatio(...)` 会把绘图缓冲区乘上设备 DPR；如果没有给 `renderer.domElement` 单独设置 CSS `width/height: 100%` 和绝对铺满，浏览器可能把高 DPR 缓冲区尺寸当成页面显示尺寸。
- 处理：中心棋盘和托盘预览的 WebGL canvas 统一套用 `position:absolute; inset:0; width:100%; height:100%; display:block`，`renderer.setSize(..., false)` 只负责同步绘图缓冲区。
- 验证：强制移动端 `390x844`、DPR 2 截图，确认棋盘左右边界在视口内，canvas CSS 尺寸等于容器尺寸，内部 `width/height` 属性可大于 CSS 尺寸。
- 关联：`src/components/match3d-runtime/Match3DPhysicsBoard.tsx`、`docs/technical/MATCH3D_RUNTIME_3D_GEOMETRY_EXPERIMENT_2026-05-02.md`。

## Hyper3D subscriptionKey 不要按固定短文本限长

- 现象：抓大鹅生成草稿时，内联 Rodin 图生 3D 模型提交成功后，状态轮询报 `subscriptionKey 超过 256 字符`，导致 `/api/creation/match3d/sessions/{sessionId}/actions` 返回 400。
- 原因：`subscriptionKey` 是 Hyper3D 返回的 opaque token，长度由上游决定；后端状态查询曾复用普通文本校验，把它限制在 256 字符。
- 处理：`query_task_status` 对 `subscriptionKey` 只做 trim 和非空校验，不做固定长度限制；前端临时任务和 Match3D 草稿响应可继续展示该 token，但不要把它当作可编辑短文本。
- 验证：`cargo test -p api-server accepts_opaque_subscription_key_without_length_cap --manifest-path server-rs/Cargo.toml`。
- 关联：`server-rs/crates/api-server/src/hyper3d_generation.rs`、`docs/technical/HYPER3D_RODIN_GEN2_MODEL_GENERATION_2026-05-08.md`。

## 抓大鹅新草稿不要再接回 Rodin 或 GLB 生成

- 现象：修改抓大鹅素材时容易沿用旧 Rodin/GLB 方案，导致新草稿生成耗时变长、进度停在模型阶段，或运行态等待不存在的 GLB。
- 原因：仓库里保留了 Hyper3D 通用代理和历史模型字段，旧文档也曾要求草稿阶段同步生成 GLB。当前产品口径已经改为 2D 多视角素材。
- 处理：新 `match3d_compile_draft` 与批量新增只生成 2D 图片：每个物品 5 个形态，单张 `2K 1:1` 物品 spritesheet 固定 `10*10`，每行承载两种物品、每种五个形态，单张最多承载 20 种物品。素材图 prompt 固定要求纯绿色绿幕背景，上传 OSS 前先把整张 spritesheet 绿幕处理为透明 alpha，再由运行态和编辑器按 alpha 连通域解析；`generatedItemAssets[].status` 使用 `image_ready`，发布校验看 `imageViews[]`、首图引用或可解析的物品 spritesheet。`generated-models` 仅用于历史外部模型链接转存，不能作为新生产链路。
- 验证：`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`npm run test -- src\services\miniGameDraftGenerationProgress.test.ts src\components\match3d-result\Match3DResultView.test.tsx src\components\match3d-runtime\Match3DRuntimeShell.test.tsx`。
- 关联：`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 抓大鹅切图路径不能只用中文物品名

- 现象：草稿页 `素材配置 > 物品` 中多个素材名称不同，但预览图片完全一样。
- 原因：中文物品名经过 OSS 路径段清洗后都可能退化成 `item`，多张切割图片写到同一个 object key，后写入覆盖先写入。
- 处理：切割图上传路径必须带稳定唯一 `itemId` 前缀，例如 `items/match3d-item-1-item/views/view-01.png`；运行态读取 generated 私有图片时通过同源 `/api/assets/read-url` 换签，不直接请求裸 OSS 路径。
- 验证：后端单测覆盖中文名路径唯一，前端运行态测试覆盖 generated 图片源解析。
- 关联：`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-result/Match3DResultView.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 抓大鹅生成素材不能只挂在 compile response

- 现象：抓大鹅草稿生成完成后停留在结果页能看到切割好的物品图片；退出后从草稿 Tab 重新进入同一草稿，素材列表变回默认占位或为空，已生成的物品名称和图片丢失。
- 原因：`generatedItemAssets` 如果只附加在 `match3d_compile_draft` 的 HTTP response draft 上，刷新或重进时 `getMatch3DWorkDetail` 只能读取 SpacetimeDB 中的 `match3d_work_profile`；旧 mapper 返回空数组，自然无法恢复素材。拼图链路已经通过 `save_puzzle_generated_images` 把候选图和 levels 写回 work profile，抓大鹅也必须同样写持久字段。
- 处理：compile 成功时把独立物品图片列表序列化写入 `match3d_work_profile.generated_item_assets_json`；`update_match3d_work` / `publish_match3d_work` 保留该字段；API work summary/detail 映射反序列化为 `generatedItemAssets`。前端保持“本次 draft 优先，重进 profile 兜底”的读取顺序。
- 验证：`cargo test -p spacetime-client match3d --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server match3d --manifest-path server-rs/Cargo.toml`、`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`。
- 关联：`server-rs/crates/spacetime-module/src/match3d/*`、`server-rs/crates/spacetime-client/src/mapper.rs`、`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-result/Match3DResultView.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 抓大鹅试玩和正式运行态不要只读草稿页本地素材预览

- 现象：结果页能看到生成的物品图片，但点击试玩或从推荐 / 公开作品进入正式抓大鹅时，局内仍显示默认积木素材。
- 原因：结果页本地 `assetDrafts` 和作品 profile 的 `generatedItemAssets` 可能不同步；推荐流内嵌运行态若只读卡片摘要，卡片缺素材时会把已持久化 profile 素材丢掉；点击试玩时 React state 异步更新也可能让运行态第一帧读取旧 `match3dProfile`。
- 处理：删除、批量新增、音效生成或封面引用物品素材后，都把当前 `generatedItemAssets` 写回作品 profile；`Match3DResultView` 合并同 `itemId` 的 draft/profile 素材，用 profile 已有 `imageViews[]`、首图引用、`backgroundMusic` 或 `backgroundAsset` 补齐旧 draft；点击试玩前把试玩可用物品种类通过 `itemTypeCountOverride` 降到已生成 2D 素材数量；推荐流内嵌运行态启动前若卡片摘要没有物品图片素材，补读 `getMatch3DWorkDetail(profileId)` 并把详情资产传给 `Match3DRuntimeShell`。`PlatformEntryFlowShellImpl` 需要维护 `match3dRuntimeProfile`，在 `startMatch3DRunFromProfile` 创建 run 后立即锁定本次完整 profile，runtime 渲染时优先按 `run.profileId` 使用这份 profile，而不是等待普通 `match3dProfile` state 下一轮刷新。同 profile 下已有 `generatedItemAssets` 时不能因为图片完整性判断失败就覆盖为空数组。判断是否需要补读详情时只看 `imageViews[]` 或 `imageSrc/imageObjectKey`；背景、音乐、容器 UI 是附属运行态资产，不能单独证明物品素材已完整。
- 验证：执行 `npm run test -- src/components/match3d-result/Match3DResultView.test.tsx`、`npm run test -- src/components/match3d-runtime/Match3DRuntimeShell.test.tsx`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`，并检查历史草稿和公开 M3 作品的 Network 响应里 `generatedItemAssets[].imageViews/imageSrc/imageObjectKey`。
- 关联：`src/components/match3d-result/Match3DResultView.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/match3d-runtime/Match3DPhysicsBoard.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 抓大鹅 UI 背景和容器只在顶层字段时也要传进运行态

- 现象：抓大鹅草稿 / 推荐卡片响应里已有 `generatedBackgroundAsset`，结果页 UI 预览能看到纯背景图和容器图，但进入试玩或正式局内仍显示默认渐变背景和默认圆形容器。
- 原因：部分链路把 UI 资产只放在作品顶层 `generatedBackgroundAsset` / `backgroundImageObjectKey`，没有同步放进首个 `generatedItemAssets[].backgroundAsset`；如果运行态入口只传 `generatedItemAssets` 和 `backgroundImageSrc`，`Match3DRuntimeShell` 就拿不到 `containerImageObjectKey`。
- 处理：`PlatformMatch3DGalleryCard`、`mapPublicWorkDetailToMatch3DWork`、`resolveMatch3DRuntimeGeneratedBackgroundAsset` 和 `Match3DRuntimeShell` 都必须保留并传递顶层 `generatedBackgroundAsset`；运行态背景读取顺序为 `backgroundImageSrc` / 顶层 `generatedBackgroundAsset.image*` / `generatedItemAssets[].backgroundAsset.image*`，容器读取顺序为顶层 `generatedBackgroundAsset.containerImage*` / `generatedItemAssets[].backgroundAsset.containerImage*`。
- 验证：执行 `npm run test -- src/components/match3d-runtime/Match3DRuntimeShell.test.tsx` 和 `npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "Match3D runtime"`；浏览器 Network 中背景和容器 generated path 应先请求 `/api/assets/read-url` 换签，局内出现 `match3d-background-image` 和 `match3d-container-image` 对应图片。
- 关联：`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/rpgEntryWorldPresentation.ts`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 抓大鹅容器参考图必须进入 edits multipart image 并接管棋盘外观

- 现象：抓大鹅结果页看似有容器生成入口，但真实生成出的局内容器不像 `pot-fused-reference.png`，或进入试玩后仍被默认圆形锅壳、金色边框和径向底色覆盖/裁切。
- 原因：容器参考图必须进入 `gpt-image-2` `/v1/images/edits` multipart `image` part，并配合强 prompt 锁定大尺寸轻俯视容器构图；即使生成了容器图，如果运行态继续保留默认 `rounded-full` 锅壳和 `overflow-hidden`，生成图也会被默认视觉覆盖或裁掉。
- 处理：抓大鹅 `1:1` 容器 UI 图统一调用 VectorEngine `POST /v1/images/edits`，参考 `public/match3d-background-references/pot-fused-reference.png` 的透明容器图由后端作为 `image` part 上传；该参考图属于后端生图协议输入，需通过 `include_bytes!` 编译进 `api-server`，不能在运行时按当前工作目录读取 `public/`。`Match3DRuntimeShell` 在容器图换签并成功加载后，把棋盘外壳切为透明和 `overflow-visible`，只在容器缺失或加载失败时使用默认圆形容器。
- 验证：执行 `cargo test -p api-server vector_engine --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server match3d_background --manifest-path server-rs/Cargo.toml`、`npm run test -- src/components/match3d-runtime/Match3DRuntimeShell.test.tsx src/components/match3d-result/Match3DResultView.test.tsx`；真实联调看容器生成请求是否命中 `/v1/images/edits`，局内 `match3d-container-image` 是否渲染且 `match3d-board` 不再含默认 `rounded-full`。
- 关联：`server-rs/crates/api-server/src/openai_image_generation.rs`、`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-runtime/Match3DRuntimeShell.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 抓大鹅结果页音频试听也要先换签

- 现象：抓大鹅草稿生成完成后，背景音乐已写在 `generatedItemAssets[0].backgroundMusic.audioSrc`，但 `素材配置 > 背景音乐` 或物品详情音效 `<audio>` 不能播放，Network 可能请求裸 `/generated-match3d-assets/...mp3` 并返回 403。
- 原因：结果页试听控件和运行态一样运行在浏览器里，不能直接读取 generated 私有对象；只在运行态换签会造成“运行态可能有声，结果页不能预览”的割裂。
- 处理：结果页音频控件统一通过 `useResolvedAssetReadUrl` / `/api/assets/read-url` 取得签名 URL 后再传给 `<audio>`；换签失败时只显示“音频已绑定”，不要回退请求裸 generated path。
- 验证：`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx` 覆盖背景音乐和点击音效试听使用签名 URL。
- 关联：`src/components/match3d-result/Match3DResultView.tsx`、`src/services/assetReadUrlService.ts`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 法律文档弹窗通过 portal 挂载时要显式带平台主题

- 现象：登录弹窗内点击协议链接打开法律文档时，弹窗可能继承不到 `platform-theme--light/dark` 变量，或者层级低于登录遮罩导致不可见。
- 原因：`UnifiedModal` 默认通过 portal 挂到 `document.body`，不再处于原页面的主题容器内；登录弹窗自身又使用较高 z-index。
- 处理：法律文档弹窗组件应支持传入 `platformTheme`，overlay 上显式挂 `platform-theme platform-theme--*`，并使用高于登录遮罩的层级。法律内容必须作为独立面板打开，不要在当前个人页或登录面板下方内联展开。
- 验证：登录页协议链接、个人页法律入口均能打开可滚动 `LegalDocumentModal`，亮色 / 暗色主题文本和按钮可读。

## 生成页完成回调不能只依赖异步 React state

- 现象：抓大鹅或拼图点击生成后，进度页已经显示 100% / 生成完成，但没有自动进入试玩或结果页。
- 原因：完成回调用 `selectionStageRef.current` 判断用户是否仍在生成页；如果执行 compile 前只调用 `setSelectionStage('*-generating')`，action 很快返回时 ref 仍可能是旧 stage。
- 处理：进入各玩法生成页时同步写 `selectionStageRef.current = '*-generating'`，再调用 `setSelectionStage('*-generating')`。这不是为渲染服务，而是给同一异步链路里的完成回调提供即时事实。
- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx` 覆盖抓大鹅和拼图生成后自动试玩 / 返回结果页。
- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 微信支付回调验签不要用商户私钥

- 现象：微信小程序支付下单能返回 `prepay_id`，但真实支付通知验签失败，或者本地实现误把商户 API 私钥当作回调验签 key。
- 原因：商户私钥只用于商户请求微信支付和生成小程序 `paySign`；微信支付通知的 `Wechatpay-Signature` 需要使用微信支付平台公钥或平台证书公钥验签，并按通知头里的平台序列号匹配。
- 处理：api-server 真实微信支付配置同时需要商户私钥与微信平台公钥：`WECHAT_PAY_PRIVATE_KEY_*` 用于签名，`WECHAT_PAY_PLATFORM_PUBLIC_KEY_*` 与 `WECHAT_PAY_PLATFORM_SERIAL_NO` 用于通知验签，`WECHAT_PAY_API_V3_KEY` 只用于解密通知 resource。支付成功后只通过通知里的 `out_trade_no` 确认本地 pending 订单，并保存 `transaction_id` 到 `profile_recharge_order.provider_transaction_id`。
- APIv3 通知成功应答使用 HTTP `204 No Content`，不要沿用 V2 XML 成功报文；失败仍返回 4XX/5XX 让微信重试。
- 验证：mock 通知测试只能覆盖本地回调推进；真实环境还需用微信支付平台公钥、真实通知头和 API v3 密钥验证签名与解密链路。
- 关联：`server-rs/crates/api-server/src/wechat_pay.rs`、`docs/technical/MY_TAB_ACCOUNT_RECHARGE_IMPLEMENTATION_2026-04-25.md`。

## 微信支付 JSAPI 下单必须显式带 User-Agent

- 现象：调用 `/v3/pay/transactions/jsapi` 失败，微信返回“Http头缺少Accept或User-Agent”。
- 原因：`reqwest` 请求即使已设置 `Accept: application/json`，也不会默认附带业务侧 `User-Agent`；微信支付网关会校验这两个头。
- 处理：`api-server` 的 JSAPI 下单请求统一通过 `with_wechat_pay_jsapi_headers(...)` 设置 `Accept: application/json`、`Content-Type: application/json` 和 `User-Agent: Genarrative-WechatPay/1.0`。
- 验证：执行 `cargo test -p api-server jsapi_order_request_sets_wechat_required_http_headers --manifest-path server-rs/Cargo.toml`。
- 关联：`server-rs/crates/api-server/src/wechat_pay.rs`、`docs/technical/MY_TAB_ACCOUNT_RECHARGE_IMPLEMENTATION_2026-04-25.md`。

## 容器公开列表压测不要靠继续抬并发吃满 CPU

- 现象：2C / 2G 容器压测公开 gallery list 时，`api-server` CPU 仍有余量，看起来像可以继续提高 `GENARRATIVE_API_GALLERY_MAX_CONCURRENT_REQUESTS` 或 Nginx `limit_conn`。
- 原因：当前瓶颈不是 Tokio worker 线程数。`/api/runtime/puzzle/gallery` 和 `/api/runtime/custom-world-gallery` 成功响应后会走全局 route tracking，继续向 SpacetimeDB 写 `record_tracking_event_and_return`；入口并发从 320 抬到 336 / 352 时，SpacetimeDB 内存先逼近 `896m` 容器上限，200 请求 p95 变差，429 比例没有改善。
- 处理：2C / 2G 容器模拟里公开 gallery list 暂以 `limit_conn=320`、`GENARRATIVE_API_GALLERY_MAX_CONCURRENT_REQUESTS=320` 作为稳定上限。若要继续提升吞吐，优先减少高频公开 GET 的 tracking 写入、做采样或改成批量/异步聚合；不要单纯放大入口并发。
- 验证：宿主机 k6 打 `http://127.0.0.1:18080`，`PEAK_RPS=1000` 等价约 2000 HTTP req/s；320 档无 dropped iterations、无 5xx、无 OOM，200 请求 `request_time p95` 约 0.292s。336 / 352 档 p95 升到约 0.31s / 0.32s，SpacetimeDB 内存尾部可到约 `880MiB / 896MiB`。
- 关联：`deploy/container/nginx.conf`、`deploy/container/api-server.env.example`、`deploy/container/README.md`、`server-rs/crates/api-server/src/tracking.rs`。

## tracking outbox 成功入库后删除 sealed 文件

- 现象：普通 route tracking 改为本机 outbox 后，容易误以为入库成功只需要清空文件内容。
- 原因：清空文件会扩大崩溃窗口，进程在 truncate 和确认之间异常退出时可能丢失未确认事件。
- 处理：当前 active NDJSON 达到数量或时间阈值后原子 rename 为 sealed 文件；后台批量 flush sealed 文件，SpacetimeDB 返回成功后直接删除该文件，失败则保留文件等待重试。sealed 文件如果出现无法解析的坏行，重命名为 `corrupt-*` 隔离并记录指标，避免阻塞后续批量入库。该路径是至少一次投递，重复事件由 `tracking_event.event_id` 幂等跳过。
- 验证：模拟 SpacetimeDB 不可用时 sealed 文件保留；恢复后批量 procedure 成功，sealed 文件消失，`tracking_event` 与 `tracking_daily_stat` 均更新。
- 关联：`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`、`server-rs/crates/api-server/src/tracking.rs`、`server-rs/crates/spacetime-module/src/runtime/profile.rs`。

## 后台表查询展示 SpacetimeDB 枚举时不要套用 Option 解码

- 现象：后台“表查询”查看 `profile_recharge_order` 时，`kind` 和 `status` 显示为空数组 `[]`，例如充值订单原始行里 `points_60` 的类型和状态都不可读。
- 原因：SpacetimeDB HTTP SQL 对无载荷枚举会返回 SATS 形态 `[variant_index, []]`；后台通用 normalizer 曾把任何 `[0, value]` 都当作 `Option::Some(value)` 展开，导致 `[0, []]` 最终只剩 `[]`。
- 处理：通用表查询解析应先按表名和列名识别已知业务枚举，再落回 Option / Timestamp 通用展开；例如 `profile_recharge_order.kind` 映射为 `points` / `membership`，`profile_recharge_order.status` 映射为 `pending` / `paid` / `failed` / `closed` / `refunded`。
- 验证：执行 `cargo test -p api-server admin_database -- --nocapture`，并确认后台详情弹层的 `raw` 与表格 `cells` 都显示业务字符串。
- 关联：`server-rs/crates/api-server/src/admin.rs`、`docs/technical/ADMIN_DATABASE_TABLE_QUERY_2026-05-08.md`。

## 抓大鹅历史草稿外部 Rodin GLB 链接必须转存后再试玩或发布

- 现象：草稿页预览模型失败并报 `GL_INVALID_ENUM: Invalid cap.`，或结果页能看到历史生成记录但试玩、发布和正式运行态仍显示默认积木。
- 原因：历史结果页手动 `重新生成` 会把 Hyper3D/Rodin 的外部 CDN 下载链接直接保存到 `generatedItemAssets[].modelSrc`，同时 `modelObjectKey` 为空。外部链接可能过期、跨域、返回 HTML 错误页或非 GLB 内容；前端预览和运行态不能把它当作稳定私有资产。
- 处理：该问题只适用于旧数据。结果页发现 `status = model_ready`、`modelSrc = https://...` 且无 `modelObjectKey` 时，可调用 `POST /api/creation/match3d/works/{profileId}/generated-models` 做一次性转存；新草稿和批量新增不得继续生成或依赖 GLB。若历史半修复数据同时保留外部 `modelSrc` 和平台 `modelObjectKey`，旧模型预览读取层优先用 `modelObjectKey`。
- 验证：`npm run test -- src\components\match3d-result\Match3DResultView.test.tsx`、`npm run test -- src\components\match3d-runtime\Match3DRuntimeShell.test.tsx`、`npm run test -- src\components\rpg-entry\RpgEntryFlowShell.agent.interaction.test.tsx`、`cargo test -p api-server match3d_model_download --manifest-path server-rs\Cargo.toml`，并检查修复后响应中的 `generatedItemAssets[].modelObjectKey` 不为空。
- 关联：`server-rs/crates/api-server/src/match3d.rs`、`src/components/match3d-result/Match3DResultView.tsx`、`src/components/match3d-result/Match3DModelPreview.tsx`、`src/components/match3d-runtime/Match3DPhysicsBoard.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 抓大鹅难度配置的物品种类和消除次数必须分离

- 现象：历史草稿选择标准 / 硬核难度后，系统可能把 `clearCount` 当成局内物品种类数量，导致标准需要 12 种、硬核需要 20/21 种；或者把第 11 到 20 个物品持久化为第 11 到 20 行，触发“系列素材图集持久化的行列索引必须落在 n*n 范围内”。
- 原因：旧运行态把消除次数和类型数量绑在一起，结果页文案又同时展示“素材图片 / 局内类型”，导致前端、发布校验和 run start 口径不一致。
- 处理：生成和持久化固定使用 20 个物品素材；运行态物品种类口径为轻松 3、标准 9、进阶 15、硬核 20，历史 `clearCount=20` 且难度为硬核的运行态仍可升为 21 组三消，但类型池不超过 20。10*10 sheet 每行两种物品、每种五个形态，持久化行列为 `row = itemIndex / 2 + 1`、`col = itemIndex % 2 * 5 + viewIndex + 1`。发布前按 `image_ready` 且有 `imageViews[]` 或 `imageSrc/imageObjectKey` 的生成素材数量阻断不足难度；试玩不阻断，但通过 `itemTypeCountOverride` 自动降到已生成 2D 素材数量。重启从已有 run 快照反推实际物品种类，保持同一局重开不变。
- 验证：`npm run test -- src\components\match3d-result\Match3DResultView.test.tsx`、`cargo test -p module-match3d --manifest-path server-rs\Cargo.toml`，涉及发布 reducer 时补跑 `cargo test -p spacetime-module match3d --manifest-path server-rs\Cargo.toml`。
- 关联：`src/components/match3d-result/Match3DResultView.tsx`、`src/services/match3d-runtime/match3dRuntimeClient.ts`、`server-rs/crates/module-match3d/src/application.rs`、`server-rs/crates/spacetime-module/src/match3d.rs`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 抓大鹅标签清洗不要把 `3D素材` 当编号剥掉

- 现象：AI 或兜底生成的 `3D素材` 标签在后端规范化后变成 `D素材`。
- 原因：标签清洗在去掉编号列表前缀后，又无条件剥离开头数字和标点，把合法标签中的 `3D` 当成列表编号处理。
- 处理：只移除明确的编号列表前缀，例如 `1. 标签`、`1、标签`、`1) 标签`；不要对普通标签开头数字做二次剥离。
- 验证：`cargo test -p api-server match3d_tag_normalization --manifest-path server-rs/Cargo.toml`，并保留 `normalize_match3d_tag("3D素材") == "3D素材"` 的单测。
- 关联：`server-rs/crates/api-server/src/match3d.rs`。

## 抓大鹅物品切图白边或绿幕残留先查后端透明化

- 现象：抓大鹅生成的物品视角图裁剪后仍带白边，或者整块纯绿色绿幕背景没有被透明化，运行态看到绿色方块。
- 原因：素材 sheet 可能是“每格内部绿幕、整张图外圈近白底”，内部绿幕不一定连通到 sheet 外边缘；旧 flood fill 只从外边缘找背景会漏掉这种绿幕块。白底抗锯齿如果不纳入抠像和边缘去污染，也会随裁剪输出成一圈白边。即使顺序已是先整张 sheet 去绿再裁剪，较厚的半透明或混色软绿边仍可能低于高置信绿幕阈值，被当作前景带进独立 PNG。
- 处理：`api-server` 的 `slice_match3d_material_sheet` 必须先在整张 sheet 上做透明背景后处理：外边缘连通绿幕/近白底清 alpha，非连通但高置信纯绿块也清 alpha，沿整张 sheet 透明背景继续吃掉软绿边，边缘近白和绿幕抗锯齿做透明或去污染；同时保护不够纯的绿色主体像素。不要改成先裁剪单格再去绿。
- 验证：`cargo test -p api-server match3d_material_sheet_slicing --manifest-path server-rs\Cargo.toml` 覆盖非连通绿幕、白边、贴边主体保留和固定 `10*10` 切图；`cargo test -p api-server match3d_spritesheet_green_screen_postprocess_turns_background_transparent --manifest-path server-rs\Cargo.toml` 覆盖完整 spritesheet 上传前绿幕透明化。
- 关联：`server-rs/crates/api-server/src/match3d.rs`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 抓大鹅物品详情大方格只做单张大图查看

- 现象：结果页 `素材配置 > 物品` 打开详情后，上方大方格仍显示横向五图带、焦点内框或小缩略图边框，物品本体看起来偏小且像带着素材自带边框。
- 原因：旧预览把上方区域当作横向视角带，当前焦点只是带内缩略图的一张，视觉上不是“详细查看物品形象”的大图。
- 处理：上方方格只渲染当前选中的单张大图，使用 `object-contain` 和少量内边距放大查看；底部缩略图栏负责切换视角，缩略图可以保留选中态边框，但上方大图不渲染焦点内框或缩略图容器边框。
- 验证：`npm run test -- src/components/match3d-result/Match3DResultView.test.tsx` 覆盖上方大图、底部缩略图和视角切换。
- 关联：`src/components/match3d-result/Match3DResultView.tsx`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 草稿页卡片有真实素材但仍显示黑卡先查摘要字段

- 现象：草稿页拼图卡片没有关卡图背景，抓大鹅卡片没有背景图或物品图背景，甚至兜底视觉也退回黑色面板。
- 原因：拼图列表摘要若不下发 `levels`，前端拿不到关卡 `coverImageSrc` / 候选图；抓大鹅列表摘要若只提供公开 URL、不保留 `generatedBackgroundAsset` 或 `generatedItemAssets` 中的 object key，前端无法换签读取私有生成图。卡片封面组件如果自带暗色默认背景，也会让兜底失败时看起来仍是黑卡。
- 处理：拼图 `map_puzzle_work_summary_response` 必须保留 `levels`；草稿页优先用关卡 `coverImageSrc`，再用候选图。抓大鹅货架封面解析必须读取 `backgroundImageObjectKey`、`generatedBackgroundAsset.imageObjectKey/containerImageObjectKey`、`generatedItemAssets[].imageObjectKey` 和 `imageViews[].imageObjectKey`。图片渲染统一交给 `ResolvedAssetImage` 换签，并给卡片传入玩法参考图与暖色底兜底。
- 验证：执行 `npm run test -- src/components/custom-world-home/creationWorkShelf.test.ts src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/hooks/useResolvedAssetReadUrl.test.tsx`、`cargo test -p api-server puzzle_work_summary_response_keeps_levels_for_shelf_cover --manifest-path server-rs\Cargo.toml`、`npm run typecheck`。
- 关联：`src/components/custom-world-home/creationWorkShelf.ts`、`src/components/CustomWorldCoverArtwork.tsx`、`server-rs/crates/api-server/src/puzzle.rs`、`docs/technical/CREATION_WORK_SHELF_UNIFICATION_2026-04-25.md`。

## 用户标签不要直接外显，SpacetimeDB Vec 字段不要写 default 宏

- 现象：给 `user_account.user_tags` 或邀请码独立标签列写 `#[default(Vec::<String>::new())]` 时，SpacetimeDB WASM 构建报 `destructor of Vec<String> cannot be evaluated at compile-time`。
- 原因：SpacetimeDB 的 table default 宏会走编译期常量求值，不能直接使用有析构逻辑的堆分配类型默认值。
- 处理：`user_account.user_tags` 使用 `Option<Vec<String>>` + `#[default(None::<Vec<String>>)]` 表达数据库默认空，业务层统一把 `None` 归一化为空数组；邀请码授予标签复用 `metadata_json.userTags` 存储和解析，不再新增独立 Vec 列。用户标签原始值不得进入登录态、个人资料等通用响应，只能在明确业务白名单里投影，例如拼图排行榜 `visibleTags` 首版仅允许 `北科`。
- 验证：`npm run spacetime:generate -- --rust-only` 能通过；`user_account` 旧迁移 JSON 缺字段时能导入，`profile_invite_code` 缺 `metadata_json` 时按 `{}` 兼容。
- 关联：`docs/technical/USER_TAG_INVITE_AND_PUZZLE_LEADERBOARD_2026-05-10.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。

## 公开作品详情深链找不到作品不能停在空详情页

- 现象：直接访问 `/works/detail?work=PZ-...`，作品不存在或已下架时会弹出“作品不存在或已下架，将返回首页。”；关闭提示后仍可能停在大白屏。
- 原因：旧恢复逻辑只覆盖 `/runtime/...`，没有覆盖 `/works/detail`。同时 `selectionStage === 'work-detail'` 且 `selectedPublicWorkDetail === null` 时没有兜底渲染，详情数据为空就只剩空页面。
- 处理：公开详情失效统一走 `resolveWorkNotFoundRecoveryAction(...)`，覆盖 `/works/detail`、`/gallery/puzzle/detail` 和 `/gallery/visual-novel/detail`；搜索失败和拼图详情 404 分支清理详情/运行态临时状态并回首页；`work-detail` 空数据阶段显示轻量读取态，避免异步间隙白屏。
- 验证：`npm run test -- src/routing/runtimeNotFoundRecovery.test.ts`、`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "direct missing public work detail alert returns to platform home"`。
- 关联：`docs/technical/PUBLIC_WORK_DETAIL_NOT_FOUND_RECOVERY_2026-05-11.md`、`src/routing/runtimeNotFoundRecovery.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`。

## 拼图 UI 背景只有 objectKey 时不要回退默认 UI

- 现象：拼图草稿页、试玩和正式运行态都显示默认 UI，或者只在结果页看到生成图，进入试玩后又回到默认背景。
- 原因：`uiBackgroundImageSrc` 可能为空而真实生成结果只写了 `uiBackgroundImageObjectKey`；如果前端和运行态只读 `src`，或者本地试玩 / 正式 run 没把 `objectKey` 一起传递，就会丢掉已有背景。
- 处理：统一通过一个解析入口把 `uiBackgroundImageSrc || uiBackgroundImageObjectKey` 归一到可展示路径；本地试玩和正式运行态都要保留 `uiBackgroundImageObjectKey`，并在 `uiBackgroundImageSrc` 为空时换签读取。
- 验证：结果页 UI Tab、`startLocalPuzzleRun` 和 `PuzzleRuntimeShell` 都应在仅有 `objectKey` 时显示生成背景，不再回落默认 UI。
- 关联：`src/services/puzzle-runtime/puzzleUiBackgroundSource.ts`、`src/components/puzzle-result/PuzzleResultView.tsx`、`src/services/puzzle-runtime/puzzleLocalRuntime.ts`、`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`server-rs/crates/module-puzzle/src/application.rs`。

## 拼图 UI 背景提示词或作品元信息异常先查首关命名契约

- 现象：拼图草稿生成完成后，第一关名称或作品名称变成 `levelNam` / `levelName` 这类字段名片段，或 `素材配置 > UI` 里显示的 `UI背景提示词` 像前端或后端模板拼接，而不是 AI 生成的视觉提示词。
- 原因：首关命名 LLM 旧契约只返回 `levelName`，自动 UI 背景阶段只能用作品名、作品描述、关卡描述和标签拼接确定性兜底提示词；如果模型返回截断 JSON，解析层还可能把 `levelNam` 这类字段名片段当作普通英文关卡名归一化通过。
- 处理：首关命名 LLM 契约必须同时返回 `{"levelName":"...","workDescription":"...","workTags":["..."],"uiBackgroundPrompt":"..."}`；解析层必须拒绝 `levelNam`、`levelName`、`workDescription`、`workTags`、`uiBackgroundPrompt` 等字段名片段作为关卡名。草稿自动 UI 背景生成优先使用该 AI 提示词，作品描述和 6 个作品标签默认填入草稿；视觉精修请求若返回新提示词或作品元信息则覆盖文本请求结果，否则保留文本请求结果。前端文本框只展示已保存的 `uiBackgroundPrompt` 或用户编辑值，字段为空时不展示本地兜底模板。
- 验证：执行 `cargo test -p api-server puzzle_level_naming_parser --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server puzzle_first_level_name --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server puzzle_initial --manifest-path server-rs\Cargo.toml`、`npm run test -- src/components/puzzle-result/PuzzleResultView.test.tsx`。
- 关联：`server-rs/crates/api-server/src/prompt/puzzle/level_name.rs`、`server-rs/crates/api-server/src/puzzle.rs`、`src/components/puzzle-result/PuzzleResultView.tsx`、`docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md`。

## 拼图 / 抓大鹅 UI 背景重生成报 No such procedure 先查 SpacetimeDB 版本漂移

- 现象：拼图或抓大鹅结果页点击 `重新生成` UI 背景时报 `No such procedure`，常见位置是泥点预扣、`save_puzzle_ui_background` 或 Match3D 草稿写回。
- 原因：`api-server` 和 `spacetime-client` 已按新 bindings 调用 procedure，但目标 SpacetimeDB 数据库仍运行旧 wasm，尚未导出钱包扣退费、拼图 UI 背景保存或 Match3D 写回相关 procedure。
- 处理：临时容错是把这类 `No such procedure` 当作后端版本漂移：泥点预扣阶段跳过扣费，图片已经生成但保存失败时返回本次内存快照 / 内存 profile，避免草稿页直接报错。长期修复仍是发布最新 `spacetime-module`、重新生成 bindings，并用 `spacetime describe` 或定向 smoke 确认 procedure 已导出。
- 验证：`cargo test -p api-server asset_operation_billing_skips_spacetime_connectivity_errors --manifest-path server-rs\Cargo.toml`、`cargo test -p api-server match3d_fallback_work_profile_keeps_generated_background_asset --manifest-path server-rs\Cargo.toml`、`npm run dev:api-server` 后检查 `/healthz`。
- 关联：`server-rs/crates/api-server/src/asset_billing.rs`、`server-rs/crates/api-server/src/match3d.rs`、`docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md`、`docs/technical/MATCH3D_DRAFT_ASSET_GENERATION_PIPELINE_2026-05-10.md`。

## 拼图合并块拖起后原位置出现红色块先查选中态泄漏

- 现象：拼图运行态中，多个拼图片合并后拖起整体块，原位置会露出一块粉红 / 红色底色。
- 原因：合并块拖拽的可见层来自 `mergedGroups` 绝对定位整体层，但 `pointerdown` 会同步写入 `selectedPieceId`；若棋盘格里的底层单块 DOM 先匹配选中态，再匹配合并态，整体层移开后就会露出单块选中填充色。
- 处理：合并格底层 DOM 只作为透明定位占位，`isSelected` 必须排除 `isMerged`；合并格样式优先级高于单块选中态。
- 验证：运行 `npm run test -- src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx -t "拖拽合并大块时底层单格不显示选中色块"`，并确认合并块拖拽时底层 `[data-piece-id]` 仍为 `puzzle-runtime-piece--merged`。
- 关联：`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx`、`docs/technical/PUZZLE_FORM_CREATION_FLOW_2026-04-29.md`。

## 推荐页嵌入拼图通关结算不要放在运行态内部 absolute 层

- 现象：推荐页里玩拼图通关后，结算面板只显示上半部分，排行榜、下一关按钮或相似作品卡被截断。
- 原因：推荐页把运行态放在滑动作品卡的视觉区内，`platform-recommend-swipe-page`、`platform-recommend-swipe-card__visual` 和 `platform-recommend-runtime-viewport` 都是 `overflow: hidden`；拼图通关结算如果仍是运行态内部 `absolute inset-0` 弹层，就只能在半屏卡片区域里显示。
- 处理：`PuzzleRuntimeShell` 在 `embedded` 模式下把通关结算层通过 portal 挂到 `document.body`，使用 `puzzle-runtime-modal-overlay--fixed` 页面级 fixed 浮层；非嵌入态继续使用运行态内部覆盖层。
- 验证：运行 `npm run test -- src/components/puzzle-runtime/PuzzleRuntimeShell.test.tsx -t "推荐页嵌入拼图通关结算使用页面级浮层避免卡片裁剪"`，确认弹层不再位于 `.platform-recommend-runtime-viewport` 内。
- 关联：`src/components/puzzle-runtime/PuzzleRuntimeShell.tsx`、`src/index.css`、`src/components/rpg-entry/RpgEntryHomeView.tsx`。

## 拼图历史图片列表不要把账号归属当图片名

- 现象：拼图创作页或结果页打开“选择历史图片”后，历史列表显示 `账号 user-1` 之类归属文案而不是图片名；`1713686400.000000Z` 这类时间显示为未知；选中后预览或生成参考图可能被怀疑不可用。
- 原因：`/api/assets/history?kind=puzzle_cover_image` 返回的 `ownerLabel` 是资产归属账号，不是图片标题；`createdAt` 可能是 SpacetimeDB / shared-kernel 秒级时间字符串，不能只用浏览器 `new Date(value)` 解析。历史图的 `imageSrc` 是 `/generated-*` 私有兼容路径，浏览器预览必须换签。
- 处理：前端标题和选中标签从 `imageSrc` 路径末尾推导，例如 `image.png`；时间解析兼容 ISO 与 `1713686400.000000Z`；创作页主图、历史列表图和结果页参考图继续用 `ResolvedAssetImage`，提交给后端时仍保留原始 `imageSrc`。
- 验证：`npm run test -- src/components/puzzle-agent/PuzzleAgentWorkspace.interaction.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`，并执行 `npm run check:encoding`。
- 关联：`src/services/puzzle-works/puzzleHistoryAsset.ts`、`src/components/puzzle-agent/PuzzleHistoryAssetPickerDialog.tsx`、`docs/technical/ASSET_HISTORY_PUZZLE_COVER_KIND_FIX_2026-04-27.md`。

## 拼图历史图关闭 AI 重绘不要强制 Data URL

- 现象：拼图创作页从历史生成图片中选择主图，再关闭 AI 重绘生成草稿时，后端报“上传图必须是图片 Data URL”。
- 原因：历史图 `imageSrc` 是 `/generated-puzzle-assets/...` 私有兼容路径；AI 重绘开启时后端参考图分支会解析该路径，但关闭 AI 重绘的“直用上传图”分支旧实现只调用 `parse_puzzle_image_data_url`。
- 处理：关闭 AI 重绘时也复用拼图参考图解析入口，允许 Data URL 与 `/generated-*` 历史路径统一转成 `PuzzleDownloadedImage` 后持久化；前端不需要下载历史图再转 base64。
- 验证：`npm run test -- src/components/puzzle-agent/PuzzleAgentWorkspace.interaction.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`、`cargo test -p api-server puzzle_uploaded_cover_can_reuse_resolved_history_image --manifest-path server-rs\Cargo.toml`、`npm run dev:api-server` 后检查 `/healthz`。
- 关联：`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/vector_engine.rs`、`src/components/puzzle-agent/PuzzleAgentWorkspace.interaction.test.tsx`。

## 拼图结果页局部生图不要污染草稿生成态

- 现象：拼图草稿已经生成完成后，在结果页重新生成关卡图片或追加关卡生成图片，草稿页仍显示整卡“生成中”，点击草稿会回到生成过程页，无法查看已有结果；关卡图片生成中还会禁用“新增关卡”和其它关卡详情编辑。
- 原因：结果页局部 action 复用了全局 `isPuzzleBusy` / 持久化 `generationStatus=generating` 语义，作品架没有区分“初始草稿不可查看”和“已有结果上的局部关卡生成”。
- 处理：作品架只在拼图没有可用封面、首关候选图或任一可查看关卡时才把 `generationStatus=generating` 解释为初始草稿生成；结果页关卡图走 background action，不设置全局 busy，只标记对应关卡局部生成进度；SpacetimeDB/API mapper 读写时把已有图片但状态仍是 `generating` 的历史关卡归一为 `ready`。
- 验证：`npm run test -- src/components/custom-world-home/CustomWorldCreationHub.test.tsx src/components/puzzle-result/PuzzleResultView.test.tsx`、`cargo test -p api-server puzzle --manifest-path server-rs\Cargo.toml`。
- 关联：`src/components/custom-world-home/creationWorkShelf.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`server-rs/crates/api-server/src/puzzle/mappers.rs`、`server-rs/crates/spacetime-module/src/puzzle.rs`。

2026-05-22 补充：结果页关卡详情的“关卡测试”不能把单关 `draft` 传给父级再调用 `updatePuzzleWork`。`updatePuzzleWork` 会同步 `puzzle_work_profile.levels_json` 和 source session 草稿，单关快照会把整份多关卡草稿覆盖成一个关卡，退出重进后只剩最后测试的关卡且序号表现为第一关。修复口径是 `PuzzleResultView` 始终传完整 `syncedDraft`，额外用 `{ levelId }` 指定起始关卡；父级持久化完整 levels 后调用 `startLocalPuzzleRun(item, levelId)`。

## 拼图上传图关闭 AI 重绘不要走首图生图

- 现象：用户在拼图入口页或结果页关卡详情上传图片并关闭 AI 重绘后，生成页仍显示“生成拼图首图”，或者后端仍调用 `generate_puzzle_image_candidates` 生成第一张 1:1 候选图。
- 原因：上传图直用路径应把 Data URL 或 `/generated-*` 历史图解析后持久化为 `sourceType=uploaded` 的正式候选，再继续生成 9:16 关卡画面、UI spritesheet 和纯背景；如果只把 `aiRedraw=false` 当作“不参考图片生成”，就会误走首图生成。
- 处理：入口页用 payload 的 `aiRedraw` 写入生成页 metadata，`puzzleAiRedraw=false` 时进度跳过 `生成拼图首图`；后端 `compile_puzzle_draft` 和结果页 `generate_puzzle_images` 都在 `aiRedraw=false && referenceImageSrc 非空` 时走上传图直用候选。结果页关卡详情必须复用 `CreativeImageInputPanel`，不要把正式图当成可重绘参考图；本次上传或历史选择的图才显示 AI 重绘开关并可删除。
- 验证：`npm run test -- src/services/miniGameDraftGenerationProgress.test.ts src/components/puzzle-result/PuzzleResultView.test.tsx`、`cargo test -p api-server puzzle_result_level_direct_upload_skips_cover_image_generation --manifest-path server-rs\Cargo.toml`。
- 关联：`src/services/miniGameDraftGenerationProgress.ts`、`src/components/puzzle-agent/PuzzleAgentWorkspace.tsx`、`src/components/puzzle-result/PuzzleResultView.tsx`、`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/generation.rs`。

## Jenkins 数据库导入导出脚本先补 Node 工具链 PATH

- 现象：`Genarrative-Database-Import` 或 `Genarrative-Database-Export` 运行到迁移脚本时，`bash` 报 `node: command not found`，常见在日志里表现为某个 `sh` 块内第 61 行直接调用 `node` 失败。
- 原因：Jenkins 的非交互 shell 没有自动加载用户的 nvm/profile，数据库导入导出脚本又在 shell 里直接执行 `node scripts/spacetime-*.mjs`，因此只要 Jenkins agent 没把 Node 的 bin 目录放进 PATH，就会在迁移开始前失败。
- 处理：导入 / 导出流水线在调用迁移脚本前先 `source scripts/jenkins-prepare-toolchain-env.sh`；该脚本会把 `GENARRATIVE_JENKINS_TOOL_PATHS`、`/var/lib/jenkins/.nvm/versions/node/v22.22.2/bin`、`/var/lib/jenkins/.cargo/bin`、`/var/lib/jenkins/.local/bin` 和系统 PATH 前缀统一补齐，并在缺少 `node` 时尽早报错。
- 验证：重新跑 `Genarrative-Database-Import` 或 `Genarrative-Database-Export`，日志应先打印 `jenkins-toolchain` 的 `node=...` 解析结果，而不是在迁移中途报 `node: command not found`。
- 关联：`scripts/jenkins-prepare-toolchain-env.sh`、`jenkins/Jenkinsfile.production-database-import`、`jenkins/Jenkinsfile.production-database-export`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## Windows Jenkins `powershell` step 在 Stdb module 构建里曾触发 CreateProcess error=5

- 现象：`Genarrative-Stdb-Module-Build` 在 Windows Jenkins 节点上报 `java.io.IOException: Cannot run program "powershell" (in directory "C:\\Users\\DSK\\.jenkins-local\\workspace\\Genarrative-Stdb-Module-Build"): CreateProcess error=5, 拒绝访问。`；日志里能看到 `durable-task` 已写出 `powershellWrapper.ps1`，但在真正启动裸 `powershell` 子进程时失败。
- 原因：Jenkins durable-task 的 `powershell` step 依赖一个隐式命令解析/启动路径，在这台 Windows 本地 Jenkins 环境里会被拒绝。`powershell.exe` 本体和 workspace ACL 都是正常的，问题出在 Jenkins step 的启动方式，而不是 PowerShell 脚本内容。修复后若日志能打印 `[jenkins-powershell] exe:`，但随后仅报 `拒绝访问` / `script returned exit code 5`，通常已经不是 PowerShell 启动失败，而是 Checkout 脚本内部命令在 Windows workspace 里触发权限拒绝。若 `.jenkins-*.ps1` 里中文 `throw '[stdb-build] ...'` 报 `MissingArrayIndexExpression`，则是 Windows PowerShell 5.1 用 `-File` 解析无 BOM UTF-8 脚本时按本地 ANSI 误解码。
- 处理：把 `jenkins/Jenkinsfile.production-stdb-module-build` 的 `Checkout` 和 `Build Stdb Module` 两处 `powershell` step 收口成 `runWindowsPowerShell(...)` helper，先用 `writeFile` 写出临时 `.ps1`，再用显式 `powershell.exe` 把脚本重写成 UTF-8 with BOM，最后通过 `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -File ...` 执行。这个 helper 写在 Groovy GString 里时，PowerShell 的 `$path` / `$text` / `$true` 必须写成 `\$path` / `\$text` / `\$true`，否则 Jenkinsfile 会在 Groovy 编译阶段报 `unexpected token: true`。Checkout 阶段优先复用 Jenkins GitSCM 已完成的工作区结果；`COMMIT_HASH` 为空或已经等于当前 `HEAD` 时不再重复 `git fetch` / `git checkout` / `git clean`，只有确实要切到另一个指定 commit 时才补 fetch、归属校验和 checkout。
- 验证：检查 Jenkins build log 中是否出现 `[jenkins-powershell] user:` 和 `[jenkins-powershell] exe:`，以及 `[stdb-checkout] current HEAD:`。上游 Full Build 传下来的 `COMMIT_HASH` 若已等于当前 GitSCM checkout，日志应显示 `requested commit already matches Jenkins GitSCM checkout` 并继续进入构建阶段；同时确认 `builds/<n>/log` 不再停在 `PipelineNodeTreeScanner... Cannot run program "powershell"` 或 Checkout 内部 exit code 5。
- 关联：`jenkins/Jenkinsfile.production-stdb-module-build`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## Server-Provision Windows 下载 helper 不要原地重写临时 ps1

- 现象：`Genarrative-Server-Provision` 的 Windows 下载阶段已经打印了 `[jenkins-powershell] user:` 和 `[jenkins-powershell] exe:`，但在 `.ps1` 原地 BOM 重写前后仍然返回 `exit code 5` / `拒绝访问`，且下载目录还没创建。
- 原因：Jenkins `writeFile` 生成的临时 `.ps1` 正被同一个 workspace 里的 PowerShell 进程马上重写成 BOM 文件，这个原地改写在本地 Windows Jenkins 环境里比直接脚本执行更容易碰到 workspace 占用或 ACL 拒绝。对这条流水线来说，BOM 不是必须的执行条件。
- 处理：`runWindowsPowerShell(...)` 改成先 `writeFile`，再由显式 `powershell.exe` 读取脚本文本并用 `ScriptBlock::Create(...)` 直接在内存中执行，不再对同一个 `.ps1` 做 BOM 重写。Windows 下载脚本里先把 `PROVISION_DOWNLOADS_DIR` 归一到 workspace 绝对路径，并补 `Windows workspace` / `download dir` / `已创建下载目录` 三段日志，方便区分是路径问题还是下载问题。
- 验证：Jenkins log 应先出现 `[jenkins-powershell] workspace:`、`[jenkins-powershell] loaded bytes:`，再出现 `[prepare-provision-downloads] Windows workspace:` 和 `[prepare-provision-downloads] 已创建下载目录:`；如果下载 URL 故意指到不可达地址，应该只在 `curl 下载失败` 处结束，而不是卡在 BOM 重写前。
- 关联：`jenkins/Jenkinsfile.production-server-provision`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

## SpacetimeDB update installer 不要按带 host 后缀的下载文件名执行

- 现象：Server-Provision 目标机阶段已经显示“使用已下载的 SpacetimeDB Linux update installer”，随后报 `Error: unexpected argument '-y' found` 或前置 `unknown command name for spacetimedb-update multicall binary`。
- 原因：`spacetimedb-update-*` 不是当前离线交付的最终形态，GitHub release 页面真正可比较的缓存对象是 `spacetime-x86_64-unknown-linux-gnu.tar.gz` 这种 release tarball；GitHub release asset API 暴露的是 `digest` / SHA256，不是 MD5。
- 处理：Windows 下载阶段应直接缓存 release tarball 和 `otelcol-contrib_0.151.0_linux_amd64.tar.gz`，目标机 `scripts/prepare-server-provision-tools.sh` 只解压本地 tarball 生成 `bin/current/spacetimedb-cli` 与 `bin/current/spacetimedb-standalone`，不要再把 update installer 当成最终离线包执行。
- 验证：Jenkins 目标机日志不再出现 `unexpected argument '-y'`、`unknown command name for spacetimedb-update multicall binary`，后续应继续检查 `bin/current/spacetimedb-cli` 和 `bin/current/spacetimedb-standalone` 是否生成。
- 关联：`scripts/prepare-server-provision-tools.sh`、`jenkins/Jenkinsfile.production-server-provision`。

## QQ 浏览器发现页推荐封面全不显示先查 aspect-ratio 兜底

- 现象：发现页的“推荐”子频道作品卡标题、作者和数据正常，但所有封面图不显示，常见于 QQ 浏览器 / X5 等旧移动内核。
- 原因：公开作品卡封面内部图片是绝对铺满，容器原本主要依赖 Tailwind `aspect-video` / CSS `aspect-ratio` 撑高；旧内核不支持或实现异常时封面容器高度会坍缩为 0。若封面还是 `/generated-*` 私有资源，换签失败后没有玩法参考图兜底时会进一步表现成黑卡。
- 处理：`.platform-public-work-card__cover::before` 使用 `padding-top: 56.25%` 保留 16:9 高度，沉浸式卡片单独覆盖比例；公开作品卡通过 `resolvePlatformWorldFallbackCoverImage(...)` 给 `ResolvedAssetImage` 传入玩法参考图兜底，签名失败或图片加载失败时仍有可见封面。
- 验证：`npm run test -- src/components/rpg-entry/rpgEntryWorldPresentation.test.ts src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`、`npm run typecheck`、`npm run check:encoding`。
- 关联：`src/index.css`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/rpg-entry/rpgEntryWorldPresentation.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 生成中草稿刷新后不要只恢复作品架遮罩

- 现象：拼图或抓大鹅草稿生成中刷新网页后，作品架卡片能显示等待遮罩，但点击卡片会走普通草稿恢复，可能进入空白结果页或未完成工作区。
- 原因：前端只把内存 notice 当作“生成中点击恢复”的判断条件，没有把后端摘要里的 `generationStatus=generating` 纳入同一路径。
- 处理：打开草稿时把持久化 `generationStatus=generating` 等同于生成中 notice，恢复对应玩法生成进度页；恢复计时使用作品摘要 `updatedAt` 推导 `startedAtMs`。
- 验证：`npm test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "persisted generating"`。
- 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。

## 存档选择入口不要只藏在“玩过”弹窗里

- 现象：用户有 RPG / 拼图运行态存档，但平台底部 `草稿` Tab 只展示作品架，个人中心只有点击 `玩过` 后才可能看到“可继续”，导致看起来没有存档选择入口。
- 原因：`/api/profile/save-archives` 已在入口 bootstrap 加载，但前端只把 `saveEntries` 注入 `ProfilePlayedWorksModal`；没有独立的存档入口。
- 处理：个人中心 `常用功能` 必须保留 `存档` 快捷入口，点击后打开独立存档选择弹窗并复用 `SaveArchiveCard`；恢复仍走 `/api/profile/save-archives/{worldKey}`，拼图存档继续走拼图 resume 分支，RPG 走 `handleContinueGame(snapshot)`。
- 验证：`npm run test -- src/components/rpg-entry/RpgEntryFlowShell.agent.interaction.test.tsx -t "profile page exposes save archive picker"`。
- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/rpg-entry/useRpgEntryBootstrap.ts`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。