merge master into codex/wechat-mini-program-virtual-payment

.hermes/shared-memory/development-workflow.md

@@ -95,6 +95,8 @@ npm run dev:admin-web
 
 开发态 `npm run dev` / `npm run dev:api-server` 默认打开 `GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=true`，密码入口可以直接注册未知手机号账号；生产默认仍关闭该开关。
 
+生产 `Genarrative-Stdb-Module-Publish` 的备份默认使用 `DATABASE_BACKUP_MODE=async`：流水线在 publish 前先生成本地冷备份，随后继续 publish，并把同一份发布前备份交给后台 Node 进程上传 OSS，避免低带宽 OSS 上传长时间占住部署窗口。需要强制在 publish 前等待打包和上传并让失败阻断发布时，手动选择 `DATABASE_BACKUP_MODE=sync`；已有其他备份窗口且明确接受风险时才选择 `skip`。
+
 查看本地 Rust/SpacetimeDB 日志：
 
 ```bash

.hermes/shared-memory/pitfalls.md

@@ -23,6 +23,14 @@
 - 验证：触发任一平台级异步失败时，页面应出现包含“错误来源”和“错误内容”的弹窗；复制内容应包含来源和错误正文；旧页面内错误 banner 不再重复出现。
 - 关联：`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`、`src/components/platform-entry/PlatformErrorDialog.tsx`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## VectorEngine 图片生成 SendRequest 超时要按传输失败排查
+
+- 现象：`external_api_call_failure` 里看到 `failureStage=request_send`、`timeout=true`、`statusCode=null`、`errorSource=client error (SendRequest)`，前端只知道图片生成失败。
+- 原因：`timeout=true` 来自 `reqwest::Error::is_timeout()`，不是业务代码固定写死；`SendRequest` 是 Hyper 发送请求阶段的错误来源标签，只说明请求未拿到可归类的 HTTP 响应，不会包含上游 JSON 错误体。
+- 处理：先按 `provider/failureStage/statusClass` 聚合，再用 `user_id` / `profile_id` 和 `metadata_json.userId/profileId` 定位触发者与草稿 / 作品；`request_send + timeout=true` 优先查请求体大小、参考图数量、出口网络、代理/Nginx、VectorEngine 当时可用性和同一 request_id 日志。若记录有 `502` 或 `429 moderation_blocked`，按上游网关或审核失败另行处理，不要归到传输超时。
+- 验证：`cargo check -p api-server --manifest-path server-rs/Cargo.toml`；查询 `tracking_event` 时失败记录应能看到触发者 `user_id` 和可用的 `profile_id`。
+- 关联：`server-rs/crates/api-server/src/external_api_audit.rs`、`server-rs/crates/api-server/src/openai_image_generation.rs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## “我的”页每日任务卡不要硬编码进度
 
 - 现象：用户完成或领取每日任务后，任务中心弹窗里的任务状态已经变化，但“我的”页卡片仍显示 `0 / 1` 和“去完成”。
@@ -910,6 +918,14 @@
 - 验证：运行 `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`。
 
+## 拼图图片生成失败后不要停在 ImageRefining
+
+- 现象：拼图图片生成失败后，会话仍停留在 `PuzzleAgentStage::ImageRefining`，用户从作品架或生成页恢复时容易被当成生成中/精修中状态，重试入口和失败承接不清晰。
+- 原因：`mark_puzzle_draft_generation_failed_tx` 只把 `PuzzleResultDraft.generation_status` 标成 `failed`，但 session stage 仍沿用旧的 `row.stage`；如果失败前已进入 `ImageRefining`，失败回写不会把会话带回结果草稿态。
+- 处理：失败回写后按失败草稿重新解析 session stage：已发布保持 `Published`，仍满足发布门禁则为 `ReadyToPublish`，否则回到 `DraftReady`；前端生成页文案用“拼图图片生成进度 / 重新生成图片”，避免把失败态误导成还在生成整份草稿。
+- 验证：运行 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`，以及拼图生成页恢复相关 `RpgEntryFlowShell.agent.interaction.test.tsx` 定向用例。
+- 关联：`server-rs/crates/spacetime-module/src/puzzle.rs`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`。
+
 ## 本地短信登录页签突然消失
 
 - 现象：登录弹窗只剩密码登录，短信登录页签看起来像被删掉，但 `LoginScreen` 中手机号验证码表单仍存在。