升级外部生成为正式任务列表
将 external_generation_job 扩展为含价格、确认时间、退款流水和事件审计的正式生成任务事实源 新增外部生成任务列表与确认 BFF，并让平台入口按后端任务补弹完成或失败提示 保护画布生成队列超时、快照回写和自动保存覆盖场景 将 worker 计费退款流水写入 externalGenerationJobId，并补充冷备份后 worker/controller 恢复守护
This commit is contained in:
@@ -16,6 +16,14 @@
|
||||
|
||||
---
|
||||
|
||||
## 2026-06-24 外部生成队列升级为正式生成任务列表
|
||||
|
||||
- 背景：外部生成队列已经承载画板和玩法的付费生成，但前端只展示排队概览，缺少可追溯任务列表、后端确认状态、完成提示补弹和退款记录到任务的追踪关系。
|
||||
- 决策：`external_generation_job` 同时作为正式生成任务列表事实源，保存 `price_mud_points`、`refund_ledger_id` 和 `notification_acknowledged_at`；新增 `external_generation_job_event` 追加状态转换审计。BFF 新增当前账号任务列表和 acknowledge 接口；前端只展示后端任务状态，完成 / 失败提示关闭时由后端写确认时间，未确认终态任务在下次登录后按列表集中弹出。任务触发的钱包扣费 / 退款流水 metadata 必须写 `externalGenerationJobId`，本机退款 outbox 重放也保留该任务 ID。
|
||||
- 影响范围：`spacetime-module` 外部生成 schema / procedure、`spacetime-client` bindings/facade、`api-server` 外部生成 BFF、worker 失败回写和资产计费退款链路、平台入口“我的”页任务卡和完成提示弹窗。
|
||||
- 验证方式：运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo test -p spacetime-module external_generation --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server wallet_refund_outbox --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
|
||||
- 关联文档：`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
|
||||
|
||||
## 2026-06-23 编辑器宣发素材固定 gpt-image-2
|
||||
|
||||
- 背景：画板宣发素材的游戏首图、详情五图和运营海报只应使用稳定的宣发图生成链路，不能被图片模型上次选择或旧请求切到 `nanobanana2`。
|
||||
|
||||
@@ -23,6 +23,14 @@
|
||||
- 验证：`ImageCanvasEditorModel.test.ts` 覆盖素材库 source resource 保留，`useImageCanvasAssetCanvasBridge.test.tsx` 覆盖资源 ID 级联清理，`ImageCanvasEditorAssetsIntegration.test.tsx` 覆盖删除后保存的新 layout 不再包含被删图层。
|
||||
- 关联：`src/components/image-editor/ImageCanvasEditorModel.ts`、`src/components/image-editor/useImageCanvasAssetCanvasBridge.ts`、`src/components/image-editor/ImageCanvasEditorAssetsIntegration.test.tsx`。
|
||||
|
||||
## 画板外部生成排队超时不是失败
|
||||
|
||||
- 现象：画板发起付费图片生成后，前端弹出 `生成任务仍在队列中,请稍后刷新画布查看结果`，但后端任务仍在队列或执行中，后续可能正常完成。
|
||||
- 原因：画板生成已经接入后端外部生成任务队列，`queued` / `running` 是正式任务状态；旧前端轮询等待窗口到期时直接抛错，导致正常排队被提交流程 catch 成失败 UI。
|
||||
- 处理：`waitForEditorGenerationQueue` 等待超时只返回“仍在后端继续执行”，调用方停止本次前端等待并保留生成中状态；只有后端任务终态为 `failed` 才展示失败。
|
||||
- 验证：画板生成 workflow 测试覆盖 queueState 持续 `running` 到前端等待窗口结束时，不进入 failed、不显示该排队文案、不添加本地临时结果层。
|
||||
- 关联：`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx`。
|
||||
|
||||
## 编辑器生成按钮显示泥点后仍要查真实钱包预扣
|
||||
|
||||
- 现象：画板生成按钮显示 `N泥点`，后端也能按模型配置计算出价格，但用户点击后钱包余额不变。
|
||||
@@ -319,12 +327,12 @@
|
||||
- 验证：`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server asset_operation_billing_does_not_refund_stale_worker_lease_errors --manifest-path server-rs/Cargo.toml`，并在 smoke 时确认 queued 任务被 worker 消费后 session 真实更新。
|
||||
- 关联：`server-rs/crates/api-server/src/puzzle/draft.rs`、`server-rs/crates/api-server/src/puzzle/generation.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`、`docs/technical/【后端架构】外部生成Worker化方案-2026-06-03.md`。
|
||||
|
||||
## 生产冷备份后 API 不能只依赖 SpacetimeDB 自恢复
|
||||
## 生产冷备份后 API 和外部生成 worker 不能只依赖 SpacetimeDB 自恢复
|
||||
|
||||
- 现象：release 机器 `03:20` 冷备份后，`spacetimedb.service` 已恢复，但作品列表、创作入口配置或公开 gallery 继续超时 / 502 / 504，`genarrative-api.service` 保持 stopped。
|
||||
- 原因：`genarrative-api.service` 配置了 `Requires=spacetimedb.service`，冷备份停止 `spacetimedb.service` 时 API 会被 systemd 依赖关系一并停止；如果 `genarrative-database-backup.service` 只传 `--stop-service spacetimedb.service` 而漏掉 `--restart-service-after genarrative-api.service`，备份脚本只会恢复数据库，不会再拉起 API。
|
||||
- 处理：生产冷备份 unit 和发布脚本必须带 `--restart-service-after genarrative-api.service`；仓库用 `npm run check:production-ops` 检查 systemd 模板、API build/deploy 归档和健康巡检链路。现场修复后执行 `systemctl daemon-reload`，但不要为了验证而手动触发冷备份。
|
||||
- 验证：`systemctl cat genarrative-database-backup.service` 应包含该参数；`systemctl is-active spacetimedb.service genarrative-api.service nginx.service` 全为 `active`；`curl -fsS http://127.0.0.1:3101/v1/ping`、`/healthz`、`/readyz` 和代表性 `/api/runtime/puzzle/gallery` 均成功。
|
||||
- 现象：release 机器 `03:20` 冷备份后，`spacetimedb.service` 已恢复，但作品列表、创作入口配置或公开 gallery 继续超时 / 502 / 504，`genarrative-api.service` 保持 stopped；或图片画布生成请求返回队列态后长期显示排队，`external_generation_job` 有 claimable pending，但 `genarrative-external-generation-worker@1.service` / controller 是 inactive。
|
||||
- 原因：`genarrative-api.service`、`genarrative-external-generation-worker@*.service` 和 `genarrative-external-generation-controller.service` 都配置了 `Requires=spacetimedb.service`，冷备份停止 `spacetimedb.service` 时这些服务会被 systemd 依赖关系一并停止；如果 `genarrative-database-backup.service` 只恢复数据库或只重启 API，外部生成队列就不会被消费。
|
||||
- 处理：生产冷备份 unit 和发布脚本必须带 `--restart-service-after genarrative-api.service`、`--restart-service-after genarrative-external-generation-worker@1.service` 和 `--restart-service-after genarrative-external-generation-controller.service`；仓库用 `npm run check:production-ops` 检查 systemd 模板、API build/deploy 归档和健康巡检链路。现场修复后执行 `systemctl daemon-reload`，但不要为了验证而手动触发冷备份。
|
||||
- 验证：`systemctl cat genarrative-database-backup.service` 应包含这些参数；`systemctl is-active spacetimedb.service genarrative-api.service genarrative-external-generation-worker@1.service genarrative-external-generation-controller.service nginx.service` 全为 `active`；`curl -fsS http://127.0.0.1:3101/v1/ping`、`/healthz`、`/readyz` 和代表性 `/api/runtime/puzzle/gallery` 均成功；`get_external_generation_queue_stats_and_return` 不应长期出现 claimable pending。
|
||||
- 关联：`deploy/systemd/genarrative-database-backup.service`、`scripts/database-backup-to-oss.mjs`、`scripts/ops/production-health-patrol.mjs`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
|
||||
|
||||
## Pingora Brotli 不能只看 Content-Encoding
|
||||
@@ -2619,6 +2627,14 @@
|
||||
- 验证：模拟首张 image2 超长耗时或超时重试时，生成页应显示真实阶段和可恢复状态；前端请求超时不应把最终成功草稿标记为失败；刷新 `/creation/jump-hop/generating?sessionId=<id>` 后应能恢复到后端真实状态；同一 session 重试不得重复生成已完成阶段。
|
||||
- 关联：`src/services/jump-hop/jumpHopClient.ts`、`src/services/miniGameDraftGenerationProgress.ts`、`server-rs/crates/api-server/src/jump_hop.rs`、`server-rs/crates/platform-image/src/vector_engine/client.rs`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
|
||||
|
||||
## 画布生成完成态不能被旧 autosave 覆盖
|
||||
|
||||
- 现象：release 外部生成 worker 补跑完成后，生成图已进入素材库或项目资源，但画布生成器仍显示 `generating`；刷新后可能仍看到历史生成框卡住。
|
||||
- 原因：画布前端在提交生成后会把 `generating` layout 放入 450ms 自动保存队列；worker 完成后后端会写入 `idle + generatedLayerId + 生成层`，但旧的 pending / in-flight layout save 可能晚到并覆盖完成态。另有历史 inline 请求在 api-server 重启时只留下前端已保存的 `generating` 框，没有终态任务或生成资源。
|
||||
- 处理：前端 `applyProjectSnapshot` 必须取消 pending layout save，并跳过一次由后端快照恢复触发的 autosave；后端 `save_editor_project_layout` 要保护已完成的 generation dialog，如果传入旧 `generating` 且无 `generatedLayerId`，而当前 layout 已有同一 dialog 的完成态，则保留完成态和生成层。线上脏数据只在确认无任务 / 无资源时标成 `failed` 并保留原 prompt 供用户重试。
|
||||
- 验证：`npm run test -- src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx src/components/image-editor/useImageCanvasProjectPersistence.test.tsx`；`cargo test -p spacetime-module --manifest-path server-rs/Cargo.toml editor_project_storage --lib`；release 排障用 `list_editor_projects_and_return` / `get_editor_project_and_return` 查 `generation-dialog` 状态，不要只看素材库。
|
||||
- 关联：`src/components/image-editor/useImageCanvasProjectPersistence.ts`、`server-rs/crates/spacetime-module/src/editor_project_storage.rs`、`server-rs/crates/api-server/src/external_generation_worker.rs`。
|
||||
|
||||
## Pingora 静态缓存不能只写 Cache-Control
|
||||
|
||||
- 现象：直连 Pingora 后，HTML 入口虽然是 `Cache-Control: no-cache`，但浏览器每次都重新下载完整入口页或普通静态文件；或者 Vite 指纹资源长期缓存正常，但旧标签页刷新时协商缓存行为和 Nginx 直连不同。
|
||||
|
||||
Reference in New Issue
Block a user