Merge remote-tracking branch 'origin/master' into editor-agent-refactored

# Conflicts: # server-rs/crates/api-server/src/editor_generation_queue.rs # src/components/image-editor/ImageCanvasEditorView.test.tsx # src/components/image-editor/ImageCanvasEditorView.tsx
2026-07-13 14:31:08 +08:00
parent 6edb826324 36a8719d0f
commit 7f6d5722be
486 changed files with 14293 additions and 4581 deletions
@@ -5,6 +5,7 @@
 ## 快速入口

 - [Agent 工作入口与执行准则](./%E3%80%90%E5%8D%8F%E4%BD%9C%E8%A7%84%E8%8C%83%E3%80%91Agent%E5%B7%A5%E4%BD%9C%E5%85%A5%E5%8F%A3%E4%B8%8E%E6%89%A7%E8%A1%8C%E5%87%86%E5%88%99-2026-06-22.md)：复杂任务前的 Agent 阅读顺序、执行边界、技能路由、文档规则和验证口径。
+- [官网 SEO 地基实施约定](./technical/【SEO】官网SEO地基实施约定-2026-07-10.md)：首页基础 head、robots/sitemap、唯一 H1、精确 SPA 路由与未知路径 404 的长期技术边界。
 - [经验沉淀](./experience/README.md)：项目开发经验、UI 交接、历史实现经验。
 - [审计与复盘](./audits/README.md)：工程审查、文本/乱码审计、专项落地审计。
 - [系统设计](./design/README.md)：玩法、关系、物品与对话设计。
@@ -23,6 +23,38 @@
 - 验证方式：`cargo test -p shared-contracts --manifest-path server-rs/Cargo.toml editor_agent`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml editor_agent`、`npm run test -- src/components/image-editor/EditorAgentConversation/EditorAgentConversationPanelView.test.tsx src/components/image-editor/EditorAgentConversation/useEditorAgentConversation.test.tsx src/services/image-editor/editorAgentClient.test.ts`、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【编辑器】画布Agent对话面板-2026-07-03.md`、`docs/adr/【ADR】画布Agent会话消息存OSS-2026-07-03.md`。

+## 2026-07-12 泥点充值收敛为四档并统一资产入口
+
+- 背景：主站与图片画板的泥点余额入口、余额明细和充值弹窗存在不同实现，旧充值口径仍展示六档泥点、首充双倍和会员购买 / 升级入口，容易让展示、商品资格与后端余额真相发生漂移。
+- 决策：主站与图片画板统一复用公共泥点资产入口，收起态展示总额与充值，展开态只展示不限时泥点、每日免费泥点和使用详情；充值中心 BFF 继续统一下发总额、三桶余额、限时到期时间、每日免费基础重置额及下次重置时间，前端不得自行相减推算，但会员周期限时泥点仅用于存量兼容和后端结算，当前版本不在前台展示。默认泥点商品收敛为 `60 / ¥6`、`180 + 90 / ¥18`、`300 + 150 / ¥30`、`680 + 340 / ¥68` 四档，`60` 档无赠送，后三档按现有 `user_id + product_id` 独立资格规则首次购买加赠 `50%`。当前版本关闭会员购买页签、会员商品和购买 / 升级入口。
+- 影响范围：`profile_recharge_product_config` 默认商品、充值中心 read model、共享前后端契约、主站与图片画板泥点资产入口、充值弹窗、后台充值商品默认值。
+- 验证方式：充值与统一入口定向前端测试、`npm run typecheck`、充值商品定向 Rust 测试、`cargo check -p spacetime-module -p spacetime-client -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-07-12 每日免费泥点独立于任务并按北京时间日切
+
+- 背景：现有“每日免费泥点”实际只是每日登录任务领取奖励，领取后进入普通永久余额，既不是独立余额桶，也不会在次日失效；同时主站仍展示每日任务卡片和任务中心入口，与新的产品口径不一致。
+- 决策：新增 `profile_daily_free_points` 作为每日免费泥点事实源，基础额度固定为 `20`，以北京时间 `day_key` 为业务日；跨日后的首次余额读取或扣费原子清除昨日剩余及退款叠加量，并把当日额度重置为 `20`，对外语义始终视为北京时间 `00:00` 已重置。扣费按“每日免费 -> 会员周期限时 -> 永久”顺序；资产退款在同一业务日恢复原每日免费额度，跨业务日时把原每日免费消费部分叠加到退款当日每日免费桶，当日允许超过 `20`，下一业务日仍统一重置为 `20`。每日任务系统和 `daily_task_reward` 保留为普通永久奖励，但主站隐藏每日任务卡片及任务中心入口。
+- 影响范围：`profile_daily_free_points`、`profile_wallet_ledger`、个人资金 read model、钱包扣费和退款 metadata、主站“我的”页、SpacetimeDB 迁移与生成绑定。
+- 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、钱包定向 Rust 测试、个人中心定向前端测试、`npm run typecheck`、`npm run check:encoding`、`git diff --check`。
+- 关联文档：`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
+## 2026-07-11 SpacetimeDB 工具链统一升级到 2.6.0
+
+- 背景：生产数据副本验证已使用 2.6.0 standalone，而仓库 Rust crate、本地 CLI、生成 bindings、容器与 server provision 仍锁定 2.5.0 或更早版本，继续混用会增加 BSATN / procedure 返回值与发布产物错配风险。
+- 决策：`server-rs/Cargo.toml` 的 `spacetimedb`、`spacetimedb-sdk`、`spacetimedb-lib` 精确锁定 2.6.0；本地 CLI / standalone、Rust bindings、worker smoke、容器压测镜像和生产 provision 下载根同步对齐 2.6.0。其它 crate 恰好出现的 2.4.1 / 2.5.0 不随本决策机械替换。
+- 影响范围：Rust workspace lockfile、SpacetimeDB bindings、本地 dev 版本门禁、容器 smoke / loadtest、server provision Jenkins 与项目 SpacetimeDB skills / 文档。
+- 验证方式：核对 `spacetime --version`，运行 `npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo check` / 定向测试、`npm run test -- scripts/dev.test.ts`、server provision 工具测试、production ops / encoding / diff 门禁。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
+## 2026-07-10 外部生成任务只持久化轻量媒体引用并独立维护摘要投影
+
+- 背景：编辑器 worker 化后直接把同步接口 payload 序列化进 `external_generation_job.request_payload_json`；前端又把已有 OSS `objectKey` 下载成 Data URL 再提交，导致单个任务 JSON 膨胀到数 MB，正式任务列表读取 20 条任务时同时搬运约 65 MB payload，并放大为 SpacetimeDB 与 api-server 的瞬时内存峰值。此前“禁止 Data URL 持久化”只覆盖工程、素材、图层和元数据，遗漏了正式生成任务表。
+- 决策：`external_generation_job.request_payload_json` / `result_payload_json` 同样属于正式持久化边界。对于本次事故涉及的 `source_module = editor-canvas` 任务，只允许普通业务参数和 `objectKey` / `resourceId` / `assetId` 等已登记轻量引用；任意层级 `data:` / `blob:` 与超限 JSON 必须由 api-server 和 SpacetimeDB 双重拒绝。编辑器已有媒体直接传正式引用，本地红框标记图先上传 OSS 后再入队，上传目录与文件名使用同一个强唯一 ID。其它玩法现存 Data URL 请求契约不在本次事故修复中被静默禁用，后续必须先完成各自资源化再扩大 DB 门禁。用户任务列表、单任务状态和 acknowledge 只读取不含 request/result payload 的 `external_generation_job_summary` 投影；acknowledge 只更新摘要小表并保留审计事件，不为确认通知加载 / 重写主任务 payload。提示词在入队时提前提取；错误摘要统一去除内联媒体并限制为 2048 字符；列表在单次 owner 扫描中只保留固定大小 top-N，不再收集全量历史后截断。历史终态 payload 仅允许迁移操作员通过默认 dry-run、`editor-canvas + job_id` B-tree cursor 显式分批压缩，pending / running 永不压缩；cursor 选择最多读取 `limit + 1` 行，apply 再逐条主键读取。首次发布默认 fail-closed 暂停在 Stdb 与 API 之间，保持维护模式并停止旧 API/controller/worker，完成压缩和摘要回填后才由指定审批人放行 API。
+- 影响范围：编辑器生成提交 workflow、`external_generation_job`、`external_generation_job_summary`、外部生成 procedure / typed client / BFF、SpacetimeDB bindings、历史数据维护流程和图片画布文档。
+- 验证方式：覆盖编辑器嵌套内联媒体与 payload 上限拒绝、非编辑器既有任务不被本轮门禁误伤、正式任务接口类型不含 payload、终态分批压缩不修改活动任务、已有 objectKey 不转 Data URL、本地标记图先上传再提交；运行外部生成定向 Rust / Vitest、`npm run spacetime:generate`、`npm run check:spacetime-schema`、`npm run typecheck`、`npm run check:encoding` 和 `git diff --check`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/technical/【前端架构】图片画布编辑器MVP接入方案-2026-06-11.md`、`docs/project-memory/shared-memory/pitfalls.md`。
+
 ## 2026-07-10 BgFilter segModel 保留内部字段，不进入外部 OpenAPI

 - 背景：`api-server` 的图片生成、图标 spritesheet 与 UI 素材提取请求仍可反序列化 `segModel`，并识别 `birefnet` / `anime-seg`，以兼容内部调用和既有任务；但 BgFilter 当前受服务进程内存与并发容量约束，不同分割模型的内存占用并非可由外部调用方自由选择的稳定契约。
@@ -50,7 +82,7 @@
 ## 2026-07-09 充值订单过期改为 SpacetimeDB scheduled 表触发

 - 背景：旧充值过期处理使用 api-server 后台轮询 worker claim 普通 schedule 表，非 HTTP 的 external-generation-worker / controller 进程也可能启动同一过期任务；扩外部生成 worker 会意外放大微信查单 / 关单流量，并且本地过期后若微信仍可支付，容易出现“微信扣款但本地拒绝入账”的风险。
- 决策：新建原生 scheduled 表 `profile_recharge_order_expiration_timer`，创建真实微信 pending 充值订单时写入 5 分钟 timer；scheduled reducer 到点只把仍为 `pending` 的订单改为 `expired` 并写 `expired_at`。HTTP `api-server` 订阅 `profile_recharge_order` 的 `Pending -> Expired` 更新并执行微信查单补偿；`SUCCESS` 允许 `Expired -> Paid` 入账，未支付或远端已终态只记录检查结果，本地保持 `expired`。`external-generation-worker` 和 controller 不处理充值过期。
+- 决策：新建原生 scheduled 表 `profile_recharge_order_expiration_timer`，创建真实微信 pending 充值订单时写入 5 分钟 timer；scheduled reducer 到点只把仍为 `pending` 的订单改为 `expired` 并写 `expired_at`。HTTP `api-server` 只订阅活跃 timer 表的删除事件，按 `order_id` 重新读取订单并仅对 `expired` 执行微信查单补偿；支付或主动关闭导致的 timer 删除会被状态判断忽略，断线窗口由未检查过期订单 catch-up 补齐，不订阅完整 `profile_recharge_order` 历史表。`SUCCESS` 允许 `Expired -> Paid` 入账，未支付或远端已终态只记录检查结果，本地保持 `expired`。`external-generation-worker` 和 controller 不处理充值过期。
 - 影响范围：`profile_recharge_order`、`profile_recharge_order_expiration_timer`、充值订单状态契约、`spacetime-client` bindings/facade、`api-server` 充值过期监听器、微信支付查单 / 关单、个人中心充值前端、后台表查询和运维文档。
 - 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、充值过期 listener / 微信支付 / shared contracts / 前端充值定向测试、`npm run check:encoding`、`git diff --check`。
 - 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
@@ -3946,3 +3978,51 @@
 - 性能：`api-server` 只在当前判定涉及的已启用 gate 配置了用户标签白名单时读取用户标签；不因无关 gate 或纯用户 ID / 百分比灰度触发额外标签读取。
 - 影响范围：`feature_gate_config`、`spacetime-client` runtime facade、`api-server` 创作入口配置与路由熔断、`apps/admin-web` 灰度发布页。
 - 验证方式：`npm run spacetime:generate`、`npm run check:spacetime-schema`、`cargo test -p module-runtime --manifest-path server-rs/Cargo.toml feature_gate`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml creation_entry_feature_gate`、`npm run admin-web:typecheck`、后台灰度页 Vitest、`npm run check:encoding`、`git diff --check`。
+
+## 2026-07-10 官网 SEO 与主站 SPA 404 边界
+
+- 背景：主站 Nginx 和 Pingora 原先会把任意未知路径回退到 `index.html`，导致 soft 404；共享 `index.html` 也缺少首页 SEO head，robots 和 sitemap 请求会落入 SPA fallback。
+- 决策：新增真实 `robots.txt` 和仅首页的 `sitemap.xml`，首页共享 head 提供基础 SEO/OG/JSON-LD 文本但不使用未确认的 image/logo URL；首页 DOM 只保留一个稳定产品定位 H1。Nginx 与 Pingora 只允许当前完整 SPA 路径回退 `index.html`，同前缀未知路径必须返回 404；`/admin` 继续走独立子应用。路由变化必须同步三套 Nginx、Pingora、route parity matrix 和自动门禁。
+- 影响范围：`index.html`、`public/robots.txt`、`public/sitemap.xml`、首页组件、三套 Nginx、Pingora 网关和路由 parity 门禁。
+- 验证方式：前端定向测试与构建、`npm run check:nginx-spa-routes`、`npm run check:pingora-route-parity`、`npm run check:pingora-gateway-smoke`、`npm run check:encoding`、`git diff --check`，部署后同时抽查根级未知路径和 `/creation/not-exist` 等同前缀未知路径。
+
+## 2026-07-11 Jenkins Secret File 默认值与 dev 定时发布
+
+- 背景：Stdb Build / Publish / Full Job 改用 Secret File 后，live Job UI 默认值为空且会被 SCM Jenkinsfile 覆盖；Full Job 的 04:00 timer 又与默认人工 rollout gate 冲突。dev 服务器不对外，允许定时完整发布。
+- 决策：三个 Jenkinsfile 将 `MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID` 默认固定为 `genarrative-spacetime-bootstrap-secret-dev-file`。Full Job 保留 04:00 timer，默认 `DEPLOY_TARGET=development`、`STDB_API_ROLLOUT_MODE=normal`，按 Stdb → API → Web 完整发布 dev；三个下游 Build 都显式传 `PUBLISH_AFTER_BUILD=false`，防止提前发布和顺序漂移。人工维护窗口才选择 `pause-after-stdb` 并强制校验 approvers。
+- 凭据边界：Secret 原文以 Jenkins Secret File 为事实源；credential ID 与参数行为以仓库 Jenkinsfile 为事实源。旧 Secret Text 继续服务 Database Import / Export，不原地改类型或删除。
+- 影响范围：`jenkins/Jenkinsfile.production-full-build-and-deploy`、`jenkins/Jenkinsfile.production-stdb-module-build`、`jenkins/Jenkinsfile.production-stdb-module-publish`、生产运维门禁与 live Job 参数 schema。
+- 验证方式：`node --check scripts/check-production-ops-guardrails.mjs`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`；推送后用首阶段 fail-closed 运行刷新三个 live Job 参数，再只读核对 credential 默认值、`normal` 默认值与 timer。
+
+## 2026-07-12 维护模式只拦截公网流量
+
+- 背景：此前维护 marker 只对内网放行后台，内网排障或人工维护仍无法访问主站、普通 API 和 SpacetimeDB 路由；当前维护目标是隔离公网访问，不应阻断可信内网流量。
+- 决策：Nginx 与 Pingora 允许 IPv4 loopback / RFC1918 / link-local 和 IPv6 loopback / ULA / link-local 来源在维护期间访问整站，包括主站页面与静态资源、普通 API、后台页面与 `/admin/api/**`、SpacetimeDB 路由。公网应用主站、普通 API、后台和 SpacetimeDB 路由继续维护响应，应用层鉴权不变。
+- 信任边界：Nginx 使用 TCP `$remote_addr`；Pingora 使用 TCP peer，只有同机 loopback Nginx 才可通过其强制覆盖的 `X-Real-IP` 传递原始地址，禁止使用 `X-Forwarded-For` 做维护放行判断。
+- 限制：网关放行不等于后端存活；`pause-after-stdb` 停止 api-server 时，内网普通 API 和后台 API 仍不可用。
+- 影响范围：生产 / dev Nginx 模板、维护 snippet、Pingora maintenance gate、Nginx 静态门禁与 Pingora smoke。
+- 验证方式：`npm run check:nginx-spa-routes`、`npm run check:pingora-route-parity`、`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml`、`npm run check:pingora-gateway-smoke`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`。
+
+## 2026-07-12 Full 发布显式控制成功后维护状态
+
+- 背景：Full Job 只能用 `STDB_API_ROLLOUT_MODE` 控制 Stdb 与 API 之间是否暂停，但 API Deploy 在 readiness 成功后固定执行 `maintenance-off.sh`，因此无法选择完整流水线结束后继续保留维护页。
+- 决策：Full Job 新增默认勾选的 `EXIT_MAINTENANCE_MODE_AFTER_COMPLETION`，并让 Stdb Publish、API Deploy 两个下游阶段固定保持维护；Web Deploy 成功后才由独立 `Exit Maintenance` 阶段按该参数决定是否调用 current release 随包 `maintenance-off.sh`。API Deploy Job 单独使用 `KEEP_MAINTENANCE_MODE`，将其转换为随包 `production-api-deploy.sh --keep-maintenance-mode`；默认仍退出维护，失败路径继续沿用 current 切换前后既有安全语义。
+- 参数刷新：Jenkinsfile 是参数事实源。推送后必须让 Full 与 API Deploy live Job 安全加载一次新 Jenkinsfile，再只读确认两个参数已进入 `config.xml`；只在 Jenkins UI 手工加参数不是持久修复。
+- 影响范围：Full / API Deploy Jenkinsfile、API 发布脚本、生产 API deploy fixture、生产运维门禁与 live Job 参数 schema。
+- 验证方式：`bash -n scripts/deploy/production-api-deploy.sh`、`npm run check:production-api-deploy`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`。
+
+## 2026-07-13 数据库冷备使用 OSS Multipart 上传并在清理前验真
+
+- 背景：SpacetimeDB 冷备归档已经超过 OSS 单次 PutObject 的 5 GiB 上限，单请求上传会稳定失败并让本地归档持续积压；网络中断还可能让 CompleteMultipartUpload 的客户端结果不确定。
+- 决策：`scripts/database-backup-to-oss.mjs` 对备份归档统一使用 OSS Multipart Upload，默认按 128 MiB 顺序分片；每个分片请求重新创建文件流、时间和 V4 签名，仅对网络错误、HTTP 408 / 429 / 5xx 做有限重试。V4 canonical query 必须同时支持无等号的 `uploads` 子资源和带值的 `partNumber` / `uploadId` 参数。
+- 验真与清理边界：Complete 后必须发送签名 HEAD，并严格核对 OSS `Content-Length` 与本地归档大小；Complete 响应不确定时也先用 HEAD 判定对象是否已经完整落盘。只有验真成功后才能把 manifest 标记为 `uploaded`，并按 `keepLocal` 决定是否删除本地归档；失败时 best-effort AbortMultipartUpload，不得提前更新 manifest 或清理本地文件。
+- 影响范围：数据库备份 OSS 上传实现、备份回归门禁、release 本地归档保留与 timer 恢复流程。
+- 验证方式：`npm run check:database-backup`、`npm run check:production-ops`、`npm run check:encoding`、`git diff --check`；线上先对既有归档使用 `--upload-archive ... --keep-local`，确认 OSS 对象长度和可恢复性后再清理积压并恢复 timer。
+
+## 2026-07-13 微信虚拟支付使用官方查单补偿
+
+- 背景：`wechat_mp_virtual` 原先被误认为没有服务端查单能力，导致消息推送遗漏后订单只能停在 pending / expired，历史订单也无法按微信真实状态核对。
+- 决策：`platform-wechat` 按官方协议调用 `POST /xpay/query_order`，使用小程序 `access_token` 与 `HMAC-SHA256(appKey, "/xpay/query_order&" + 实际 JSON body)` 支付签名。用户确认和订单到期补偿都可查虚拟支付订单，但只在单号、支付类型 `order_type=0/7`、金额、合法 `paid_time` 一致且微信状态为 `2/3/4` 时补入账；退款类型 `1/8` 不发放权益。`short_series_goods` 的 `status=2` 在本地入账后必须补调 `/xpay/notify_provide_goods`，失败可从本地 `paid` 状态只重试发货；token 明确失效时强制刷新并最多重放一次。
+- 边界：查单使用订单所属用户的小程序 `openid`，不把 AppKey、AppSecret、access token 或 `openid` 下发前端；虚拟支付不得误用微信支付 V3 查单。
+- 历史单：升级前遗留的 pending 订单不会被 expiration catch-up 覆盖，使用 `spacetime:wechat-virtual-payment:reconcile` 逐单 dry-run，再使用当次 `applyFingerprint` 明确 `--apply`。脚本每次重读本地订单与微信查单结果，指纹漂移、非 `2/3/4`、单号/金额/支付类型 `order_type=0/7` 不一致或非官方 endpoint 时默认拒绝入账。
+- 验证方式：`cargo test -p platform-wechat --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml virtual_payment_query`、`npm run check:wechat-virtual-payment-reconcile`、`npm run check:encoding`、`git diff --check`。
@@ -14,6 +14,15 @@
 - 关联：相关文件、文档、提交或 Issue
 ```

+## 禁止 Data URL 持久化时不要漏掉异步任务 JSON
+
+- 现象：工程、素材、图层和元数据都已禁止 Data URL 后，服务器仍在生成高峰出现 SpacetimeDB / api-server 内存急剧膨胀甚至 OOM；读取少量正式生成任务也会造成远大于响应体的瞬时内存增长。
+- 原因：同步接口 worker 化时把原请求整体序列化到 `external_generation_job.request_payload_json`，而前端又把已有 `objectKey` 下载成 Data URL 提交。任务表也是正式持久化边界；列表 procedure 若先收集完整任务行再截断，还会把 request/result 大字段在 SpacetimeDB、SDK mapper 和 BFF 多次持有。
+- 处理：先在事故涉及的编辑器持久任务 JSON 上由 api-server 与 SpacetimeDB 两层递归拒绝 `data:` / `blob:` 并限制字节数；已有媒体传 `objectKey` / `resourceId` / `assetId`，本地派生图先用强唯一 key 上传。其它玩法若仍以 Data URL 作为正式请求契约，必须先资源化，不能直接扩大门禁造成玩法回归。列表、详情和 acknowledge 只走无 payload 的摘要投影，ack 不能为了同步旧字段重写大任务行；摘要错误文本也必须清除内联媒体并设硬上限，列表只能维护有界 top-N，不能先收集 owner 全量历史再截断。历史只通过迁移操作员的 dry-run + B-tree cursor 分批 procedure 压缩 `editor-canvas` 终态任务，cursor 选择读取量必须受 limit 约束，绝不全表扫描、绝不处理 pending / running；dry-run 后 apply 同一批时保持输入 cursor 不变，最后一批即使 `has_more=false` 只要仍有命中也必须 apply，只有 apply 成功后才推进到返回 cursor。SpacetimeDB CLI 2.5 的 `Option<T>` 非空参数必须使用 SATS sum 编码；维护脚本要统一编码 `cursor_job_id`、`owner_user_id` 和 `completed_before_micros`，否则首批空 cursor 可运行，但第二批或带截止时间的调用会在写入前被拒绝。
+- 发布门禁：生产发布入口必须固定 `--delete-data=never` 与 scoped `--yes=migrate,break-clients`，普通 Jenkins 参数不得暴露清库开关；需要删数据的 schema 冲突必须直接阻断并重新检查 artifact/schema，不能靠裸 `--yes` 放行。
+- 验证：构造嵌套 Data URL、Blob URL 和超限 JSON 确认入队失败；检查正式 UI procedure / client record 不含 request/result payload；用 dry-run 和 apply 测试确认活动任务不变、终态普通提示词保留且内联媒体被替换；至少带一次非空 `--cursor-job-id` 与 `--completed-before-micros` 验证 CLI Option 编码，而不是只测首批空 cursor。
+- 关联：`server-rs/crates/api-server/src/editor_generation_queue.rs`、`server-rs/crates/spacetime-module/src/external_generation.rs`、`server-rs/crates/api-server/src/external_generation.rs`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。
+
 ## React 测试因内部状态或实现细节正常重构就碎

 - 现象：修改组件结构、按钮排序、图标库 class、提示文案或 hook 内部状态名后，React 测试大量失败，但真实用户流程和对外契约没有变化。
@@ -359,6 +368,14 @@
 - 验证：`npm run test -- src/services/image-editor/editorProjectClient.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx -- --runInBand`；后端验证至少覆盖 `editor_image_edit_request_omits_price_mud_points` 和 `editor_image_edit_can_complete_by_replacing_target_layer`。
 - 关联：`src/services/image-editor/editorProjectClient.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`server-rs/crates/api-server/src/editor_project.rs`。

+## 图片画布快速编辑尺寸要区分业务目标和 provider 对齐尺寸
+
+- 现象：原图经过快速编辑后 Resolution 变成近似比例的 1K / 2K 预设；原图或框选标记图宽高不是 16 的倍数时，VectorEngine edits 直接拒绝请求。
+- 原因：前端已有源图精确 `originalWidth/originalHeight`，提交时却按最近常用比例和 K 档重新计算 `size`；后端又把非 16 倍数的目标尺寸和原始参考图字节直接放进 multipart，并以 provider 回图宽高落库和覆盖画布图层。
+- 处理：画布快速编辑提交源图精确尺寸作为业务目标；api-server 只在 provider 边界向右、向下复制边缘像素，把每张参考图和目标尺寸临时补齐到 16 的倍数，收到回图后裁回业务目标尺寸再持久化。若上游异常返回其他尺寸，先按目标比例裁切缩放；临时对齐尺寸不能进入 OSS 元数据、`editor_project_resource`、`editor_asset` 或画布 Resolution。前端 inline 回填也保留源图显示尺寸和 Resolution，避免旧回包再次放大图层。
+- 验证：`npm run test -- src/components/image-editor/ImageCanvasGenerationSubmissionModel.test.ts src/components/image-editor/ImageCanvasGenerationLayerModel.test.ts src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.test.tsx` 覆盖 `1537x1025` 精确提交和源图回填；`cargo test -p api-server editor_image_edit_aligns_provider_images_and_restores_source_dimensions --manifest-path server-rs/Cargo.toml` 覆盖 provider `1552x1040`、额外参考图独立对齐和回图恢复。
+- 关联：`src/components/image-editor/ImageCanvasGenerationSubmissionModel.ts`、`src/components/image-editor/useImageCanvasGenerationSubmissionWorkflow.ts`、`src/components/image-editor/ImageCanvasGenerationLayerModel.ts`、`server-rs/crates/api-server/src/editor_project.rs`。
+
 ## 图片画布快速编辑元数据必须记录原图引用

 - 现象：快速编辑生成的新图可以替换画布，但打开图片信息时“生成输入”里看不到被修改的原图。
@@ -2043,10 +2060,10 @@

 - 现象：微信小程序支付下单能返回 `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`。
+- 处理：api-server 真实微信支付配置同时需要商户私钥与微信平台公钥：`WECHAT_PAY_PRIVATE_KEY_*` 用于签名，`WECHAT_PAY_PLATFORM_PUBLIC_KEY_*` 与 `WECHAT_PAY_PLATFORM_SERIAL_NO` 用于通知验签，`WECHAT_PAY_API_V3_KEY` 只用于解密通知 resource。微信平台 `PUBLIC KEY` PEM 的 DER 内容是 SPKI `SubjectPublicKeyInfo`，初始化时必须解析并提取其中的 PKCS#1 `RSAPublicKey` DER 后再交给 `ring::RSA_PKCS1_2048_8192_SHA256`；不能把整段 SPKI DER 直接传给 `ring`。支付成功后只通过通知里的 `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`。
+- 验证：mock 通知测试只能覆盖本地回调推进；`platform-wechat` 必须用标准 SPKI `PUBLIC KEY` 和匹配私钥生成真实 RSA-SHA256 签名，覆盖 SPKI 到 PKCS#1 的解析与生产验签 helper。真实环境还需用微信支付平台公钥、真实通知头和 API v3 密钥验证签名与解密链路。
+- 关联：`server-rs/crates/platform-wechat/src/pay.rs`、`server-rs/crates/api-server/src/wechat/pay.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

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

@@ -2080,14 +2097,29 @@
 - 验证：执行 `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`。

+## 后台通用表查询不能先按每页条数截断再筛选
+
+- 现象：后台“表查询”填写关键词或 JSON 条件后查不到确定存在的记录；把“条数”从 100 调到 500 只能偶尔缓解，而且页面没有继续翻页的入口。
+- 原因：旧实现先执行 `SELECT * FROM <table> LIMIT <limit>`，再对这批行做内存过滤；目标记录不在首批结果时永远无法命中，同时响应没有页码、匹配总数或扫描上限状态。
+- 处理：用户输入继续不进入通用 SQL。API Server 通过单次 `SELECT * ... LIMIT 50001` 读取哨兵行，最多保留前 50,000 条候选，先过滤，再按后端接收的列名 / 方向对完整候选集稳定排序，最后分页；`totalMatched`、`scannedCount` 和 `scanLimitReached` 都从同一份 SQL 结果计算。请求页码超过实际总页数时钳制到末页，零结果固定为第 1 页。响应统一返回 `page`、`totalMatched`、`scannedCount`、`scanLimit` 和 `scanLimitReached`，后台翻页栏固定在视口底部；达到扫描上限时明确提示结果可能不完整。32 MiB 是候选 SQL 响应体硬上限，宽表即使每页条数很小也可能整次拒绝，不返回部分结果。实时写入可能改变相邻请求之间的候选快照，精确审计使用专用业务查询。
+- 验证：执行 `cargo test -p api-server admin_database -- --nocapture`，覆盖第 101 行才命中、完整候选集排序后分页、哨兵截断、越界页码和响应体硬上限；前端测试覆盖下一页沿用已应用条件、后端排序参数 / 返回结果与扫描警告，并运行后台类型检查。
+- 关联：`server-rs/crates/api-server/src/admin.rs`、`server-rs/crates/shared-contracts/src/admin.rs`、`apps/admin-web/src/pages/AdminDatabaseTablesPage.tsx`。
+
 ## 充值订单过期补偿不要放进外部生成 worker

 - 现象：外部生成 worker/controller 扩容后，微信充值过期查单和关单流量也被同步放大；排查时还会误去外部生成 worker 日志里找支付过期任务。
 - 原因：支付过期是账户资金链路，不是外部内容生成队列；旧实现把充值过期轮询 worker 挂在通用后台任务启动函数里，非 HTTP 角色也会启动。
- 处理：充值订单过期由 SpacetimeDB 原生 `profile_recharge_order_expiration_timer` 到点把 `pending` 改为 `expired`，只有 HTTP `api-server` 订阅 `profile_recharge_order` 的 `Pending -> Expired` 更新并查微信补偿。未支付终态本地保持 `expired`，不要再改写成 `closed`；微信成功支付通知或补偿查单仍可把 `Expired -> Paid` 入账。
+- 处理：充值订单过期由 SpacetimeDB 原生 `profile_recharge_order_expiration_timer` 到点把 `pending` 改为 `expired`，只有 HTTP `api-server` 订阅活跃 timer 表的删除事件，按 `order_id` 重新读取订单并仅对 `expired` 查微信补偿；支付或主动关闭导致的删除信号会被状态判断忽略，断线窗口由未检查过期订单 catch-up 补齐。未支付终态本地保持 `expired`，不要再改写成 `closed`；微信成功支付通知或补偿查单仍可把 `Expired -> Paid` 入账。
 - 验证：确认 `GENARRATIVE_PROCESS_ROLE=external-generation-worker` / `external-generation-controller` 不启动充值过期监听；创建 pending 充值单后只由 scheduled reducer 产生 `expired`，HTTP api-server listener 记录 `expiration_checked_at` 或补入账。
 - 关联：`server-rs/crates/api-server/src/profile_recharge_expiration_listener.rs`、`server-rs/crates/spacetime-module/src/runtime/profile.rs`、`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`。

+## 充值订单状态枚举不能用字符串 SQL 字面量订阅
+
+- 现象：API 已 ready，但日志每 5 秒出现 `profile recharge expiration listener failed to subscribe`，并提示 `pending` 不能解析为 `profile_recharge_order.status` 的枚举类型；scheduled reducer 仍会把订单改成 `expired`，但微信查单补偿监听没有运行。
+- 原因：SpacetimeDB 2.6 不会把订阅 SQL 中的 `'pending'` / `'expired'` 字符串自动转换为生成绑定的 sum-type enum；两个按状态过滤的订阅都在应用阶段失败。
+- 处理：不要改成订阅完整 `profile_recharge_order` 历史表。后端订阅只保留活跃五分钟定时器的 `profile_recharge_order_expiration_timer`，监听 timer 删除后按 `order_id` 通过 procedure 读取订单，只处理当前状态为 `expired` 的记录；支付 / 关闭信号会被忽略，断线窗口继续由未检查过期订单 catch-up 补齐。这样既不依赖不受支持的枚举 SQL，也不会把充值历史常驻 API 客户端缓存。
+- 验证：运行 `cargo test -p spacetime-client profile_recharge_expiration --manifest-path server-rs/Cargo.toml`，发布后确认 API 日志不再出现订阅解析错误，并用真实 pending 订单验证 scheduled reducer 过期后写入 `expiration_checked_at`。
+
 ## 抓大鹅历史草稿外部 Rodin GLB 链接必须转存后再试玩或发布

 - 现象：草稿页预览模型失败并报 `GL_INVALID_ENUM: Invalid cap.`，或结果页能看到历史生成记录但试玩、发布和正式运行态仍显示默认积木。
@@ -2928,3 +2960,41 @@
 - 处理：产品 UI 不提供模型选择，应用内调用固定 `birefnet`；外部编辑器 OpenAPI 不声明 `segModel`，并保持相关请求 schema 的 `additionalProperties: false`，使外部请求携带该字段时被契约拒绝。只有维护 BgFilter 模型与容量的后端代码可使用该内部字段；若未来需要开放，先完成各模型的内存、并发和超时压测，再明确版本化外部契约。
 - 验证：检查 `docs/openapi/genarrative-external-v1.openapi.json` 的图片生成、图标 spritesheet 和 UI 素材提取请求 schema 均未包含 `segModel`，且均保持 `additionalProperties: false`。
 - 关联：`server-rs/crates/api-server/src/editor_project.rs`、`src/services/image-editor/editorProjectClient.ts`、`docs/project-memory/shared-memory/decision-log.md`。
+## SPA 路由白名单不能只按一级目录放行
+
+- 现象：`/not-exist` 已返回 404，但 `/creation/not-exist`、`/runtime/not-exist` 或 `/puzzle/not-exist` 仍返回 200 首页，搜索引擎继续判定为 soft 404。
+- 原因：Nginx 或 Pingora 使用 `/creation/*`、`/runtime/*` 等宽前缀作为 SPA fallback，前端对未知路径又回到平台首页；只验收根级未知 URL 无法发现该问题。
+- 处理：SPA fallback 必须精确匹配当前真实完整路径，同时允许前端已有的大小写归一和尾部斜杠；最终 catch-all 只提供真实静态文件，失败返回 404。路由增删同步三套 Nginx、Pingora、route parity matrix 和路由门禁。
+- 验证：除全部真实 SPA 路径外，至少检查 `/not-exist`、`/creation/not-exist`、`/runtime/not-exist` 和 `/puzzle/not-exist` 均返回 404；维护模式仍保持页面 503 优先语义。
+- 关联：`src/routing/appRoutes.tsx`、`src/routing/appPageRoutes.ts`、`deploy/nginx/`、`deploy/container/nginx.conf`、`server-rs/crates/pingora-gateway/src/main.rs`。
+
+## Jenkins Job UI 参数会被 SCM Jenkinsfile 覆盖
+
+- 现象：在 Jenkins Job 页面给 `MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID` 配了默认值，下一次加载 Declarative Pipeline 后又变空或恢复旧描述；04:00 Full Job 还可能因默认选择 `pause-after-stdb` 且 approvers 为空而失败。
+- 原因：这些 Job 使用 Pipeline script from SCM，`parameters {}` 和 `triggers {}` 会作为 Job property 回写现场配置；只改 UI 不是持久修复。构建编排如果不显式关闭下游 `PUBLISH_AFTER_BUILD`，还会受下游默认值漂移影响。
+- 处理：credential ID 和参数默认值写回三个 Jenkinsfile；仅供开发使用的 dev 定时 Full Job 默认 `STDB_API_ROLLOUT_MODE=normal`，三路 Build 调用显式传 `PUBLISH_AFTER_BUILD=false`，再由 Full Job 统一按 Stdb → API → Web 发布。Secret 原文只放 Jenkins Secret File，旧 Secret Text 保留给 Import / Export。
+- 验证：推送后让 Full / Stdb Build 用不存在的源码分支在 checkout 阶段 fail-closed，让 Stdb Publish 用空构建版本在 Prepare 阶段 fail-closed，以安全刷新参数 schema；随后只读检查三个 live `config.xml` 的参数描述和默认值，确认 Full timer 仍为 `0 4 * * *`、rollout 默认值为 `normal`，并确认刷新运行未进入 publish / deploy stage。
+- 关联：`jenkins/Jenkinsfile.production-full-build-and-deploy`、`jenkins/Jenkinsfile.production-stdb-module-build`、`jenkins/Jenkinsfile.production-stdb-module-publish`、`scripts/check-production-ops-guardrails.mjs`。
+
+## 维护模式内网全站放行不能信任 X-Forwarded-For
+
+- 现象：维护期间希望让内网继续访问整站，如果直接按 `X-Forwarded-For: 192.168.x.x` 放行，公网请求可伪造该头绕过维护闸；如果仍按路径只放行后台，又会让内网主站和普通 API 继续返回 503。
+- 原因：XFF 是客户端可提交的普通请求头，当前 Nginx 的 `$proxy_add_x_forwarded_for` 还会保留已有前缀；维护放行属于授权判断，必须建立在不可伪造的网络来源边界上，并在路由分类前按来源统一决定是否绕过维护闸。
+- 处理：Nginx 按 TCP `$remote_addr` 判断内网；Pingora 按 TCP peer 判断，只有 peer 为 loopback 的同机 Nginx 时才接受 Nginx 强制覆盖的 `X-Real-IP`。可信内网来源绕过整站维护响应，公网应用主站、普通 API、后台和 SpacetimeDB 路由仍保持维护响应；绝不能用 `X-Forwarded-For` 做放行判断。
+- 验证：Pingora smoke 同时覆盖公网主站、普通 API、后台为 503，以及内网对应路由为 200；Rust 单测覆盖 IPv4 / IPv6 内网、公网和空来源；Nginx 静态门禁反查两份模板的内网来源定义与全局维护变量清零逻辑。
+- 限制：如果发布门禁已经停止 api-server，网关放行后普通 API 和后台 API 仍会失败；需要调用后端时应确保对应服务仍运行，不能把维护页绕过误当作服务可用性保证。
+
+## Full 结束后保持维护不能只加一个 UI 参数
+
+- 现象：Full Job 参数页没有“完整发布成功后是否退出维护”选项，或者补了选项后 API readiness 一通过仍自动撤掉维护。
+- 原因：维护退出发生在随 API artifact 发布的 `production-api-deploy.sh` 内；Full、API Deploy Job 和脚本任一层没有透传，最终都会回到固定执行 `maintenance-off.sh`。Declarative Pipeline 参数还要等 live Job 加载新版 Jenkinsfile 后才会刷新。
+- 处理：Full 使用 `EXIT_MAINTENANCE_MODE_AFTER_COMPLETION` 表达产品选择，Stdb Publish 和 API Deploy 全程固定保持维护，Web Deploy 成功后才进入独立最终退出阶段；API Deploy 的独立 `KEEP_MAINTENANCE_MODE` 再转换为脚本 `--keep-maintenance-mode`。API deploy 还必须把 `production-api-deploy.sh`、`maintenance-on.sh` 和 `maintenance-off.sh` 从同一 build artifact 复制进 current release，否则 Full 最终阶段即使有选项也找不到随包退出脚本。默认值仍在 Full 结束时退出维护，避免定时 dev 发布行为变化。
+- 验证：API deploy fixture 必须覆盖成功发布并保留 marker，还要断言 current release 中三个部署 / 维护脚本存在；生产运维静态门禁同时反查 Full 参数、下游透传、API Deploy 参数和脚本 flag。推送后用 fail-closed 首阶段运行刷新 live Job 参数，再核对 `config.xml`，不能只看仓库文件。
+
+## 遮罩点击关闭必须校验完整指针序列
+
+- 现象：在弹窗内容内按下鼠标，拖到弹窗外的遮罩上松开时，弹窗被误关闭。
+- 原因：只在 `click` 阶段判断 `event.target === event.currentTarget` 不足以确认用户点击了遮罩；跨弹窗边界松开时，浏览器可能把合成点击的目标归到弹窗和遮罩的共同祖先。
+- 处理：共享弹窗统一记录 `pointerdown` 与 `pointerup` 的目标，只有按下和松开都发生在遮罩自身时才允许关闭。新增弹窗优先复用 `UnifiedModal`，不要继续复制只判断最终 `click` 目标的手写遮罩逻辑。
+- 验证：回归测试同时覆盖“弹窗内按下、遮罩松开不关闭”和“遮罩按下、遮罩松开正常关闭”。
+- 关联：`src/components/common/UnifiedModal.tsx`、`src/components/common/UnifiedModal.test.tsx`、`src/components/auth/PlatformAuthModalShell.test.tsx`。
@@ -36,7 +36,7 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台，把 A
 server-rs + Axum + SpacetimeDB
 ```

-当前 SpacetimeDB crate、SDK、CLI / standalone、生成 bindings 和容器压测镜像统一按 `2.5.0` 对齐；遇到版本不匹配时先升级到 `server-rs/Cargo.toml` 锁定版本，升级后重启对应 SpacetimeDB 进程再重试。
+当前 SpacetimeDB crate、SDK、CLI / standalone、生成 bindings 和容器压测镜像统一按 `2.6.0` 对齐；遇到版本不匹配时先升级到 `server-rs/Cargo.toml` 锁定版本，升级后重启对应 SpacetimeDB 进程再重试。

 职责边界：

@@ -0,0 +1,52 @@
+# 官网 SEO 地基实施约定
+
+更新时间：`2026-07-10`
+
+## 本轮边界
+
+本轮只建立陶泥儿中文首页的 SEO 基础设施，不新增英文站、长尾落地页、SSR、动态 sitemap、前端访问埋点或分享图。
+
+- `public/robots.txt` 是真实静态文件；非 SEO 产品路径本轮阻止抓取，但不把 `Disallow` 解释为保证不收录。
+- `public/sitemap.xml` 本轮只包含 `https://www.genarrative.world/`，不写难以持续维护的 `lastmod`。
+- `index.html` 提供首页 title、description、canonical、robots、基础 OG/Twitter 文本和 JSON-LD；没有正式分享图时不写 `og:image`、`twitter:image` 或 JSON-LD `logo`。
+- 桌面首页与 `/creation` 创作主页渲染后只有一个稳定、可见的产品定位 H1，固定为 `陶泥儿 · 开启全民精品游戏创作`；小眉题、产品说明、权益提示、动态作品名、卡片标题、按钮内部标题、弹窗标题和隐藏 Tab 不作为 H1。
+- H1 下方真实展示游戏美术 AI 工作台、美术 Agent、无限画布以及角色、场景、UI、宣发素材说明，不使用透明、极小、屏幕外或页面底部堆词文本；`游戏美术 AI 创作工具` 使用 H2，能力卡标题使用 H3。
+- 本轮可见首页文案调整不得删除或改写已经验收的 title、description、canonical、robots、OG/Twitter 文本和 JSON-LD。
+- Nginx 和 Pingora 只对当前已知完整 SPA 路径回退 `index.html`；未知路径以及 `/creation/not-exist` 等同前缀未知路径返回 HTTP 404。
+- Nginx access log 继续使用现有 `$http_referer`，本轮不新增前端 pageview 或用户身份采集。
+
+## 路由事实源
+
+主站 SPA 路由以以下源码为事实源：
+
+- `src/routing/appRoutes.tsx`
+- `src/routing/appPageRoutes.ts`
+
+`/creation/rpg/agent` 仍被现有刷新恢复链路使用，当前作为兼容深链保留。新增或删除前端路由时，必须同步三套 Nginx 配置、Pingora 路由、`deploy/pingora/nginx-route-parity.matrix.json` 和对应自动门禁。不得把 `/creation/*`、`/runtime/*` 等一级目录整体设为 SPA fallback。
+
+后续新增 SEO 落地页时，还必须同时满足：返回 200、不被 robots.txt 阻止抓取、加入 sitemap，并提供独立 title、description、canonical、H1、正文和内链入口。纯 SPA 页面需要独立 head 时，应评估构建时静态 HTML、预渲染或 SSR。
+
+## 验收口径
+
+```bash
+npm run build
+npm run typecheck
+npm run check:nginx-spa-routes
+npm run check:pingora-route-parity
+npm run check:pingora-gateway-smoke
+npm run check:encoding
+git diff --check
+```
+
+部署后至少验证：
+
+```bash
+curl -I https://www.genarrative.world/robots.txt
+curl -I https://www.genarrative.world/sitemap.xml
+curl -I https://www.genarrative.world/not-exist-test
+curl -I https://www.genarrative.world/creation/not-exist-test
+curl -I https://www.genarrative.world/runtime/not-exist-test
+curl -I https://www.genarrative.world/puzzle/not-exist-test
+```
+
+真实 SPA 路径不得误 404；以上未知路径必须返回 404。首页浏览器 DOM 应只有一个 H1，并确认桌面和移动端布局、导航、推荐流和创作入口没有因 SEO 文案变形。
@@ -9,7 +9,7 @@
 - 主站新增 `/editor/canvas` 路由，进入独立图片画布编辑器阶段。
 - 主站新增 `/project` 项目页，从“我的”页项目入口进入，展示当前用户所有图片画布工程；点击项目进入 `/editor/canvas?projectid=<projectId>`。
 - 创作 Tab 顶部提供编辑器入口，入口只负责跳转，不参与玩法创作链路。
- 编辑器顶部栏采用紧凑高度，项目标题和重命名入口贴近返回项目按钮；右侧常驻展示当前账号泥点余额，样式对齐创作主页顶部钱包 chip，点击后复用创作主页右上角泥点入口的账户充值 / 兑换码弹窗与支付确认反馈。
+- 编辑器顶部栏采用紧凑高度，项目标题和重命名入口贴近返回项目按钮；右侧复用与主站相同的公共泥点资产入口，并以充值中心 `mudPointBalance` 为余额真相源。余额区只展开不限时、每日免费及重置信息，会员周期限时泥点保留在后端 read model 中用于存量兼容和结算但不展示；独立“充值”按钮进入“购买更多泥点”弹窗，“使用详情”进入泥点账单。
 - 编辑器左侧为图片素材栏，可展开 / 收起；移动端优先保持素材栏可折叠。
 - 中央画布支持背景拖拽平移、滚轮缩放、缩放百分比菜单、显示所有元素和固定比例缩放。
 - 画布左下角提供 Lovart 式状态控件：背景色圆点、素材 / 图层入口、小地图开关；小地图显示图层缩略分布和当前视口框，点击小地图执行显示所有元素。
@@ -86,8 +86,8 @@
 - `POST /api/editor/images/generations`：按提示词调用 VectorEngine 生成图片；角色生成可携带 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize` 和 `referenceImageSrcs`，生成成功后 api-server 先保存带纯色背景源图，再调用 BgFilter 并传入 `screen_color=<screenColor>`、`seg_model=<segModel>` 生成透明 PNG。宣发素材携带 `kind: "publication-material"` 时固定归一为 `gpt-image-2`，不支持 `nanobanana2`。`nanobanana2` 参考图作为 `inline_data` 进入 `generateContent`，`gpt-image-2` 参考图进入 edits。普通重绘继续走该接口并把当前图层图片作为参考图；图片快速编辑不走该接口。请求可携带 `projectId`、`assetFolderId`、`assetKind`、`generationInputs` 和 `sourceResourceId`，后端生成成功后创建 project resource / 账号素材并在响应中返回 resource / asset 快照。
 - `POST /api/editor/images/background-removals`：接收当前图片源，校验登录态后由 api-server 解析为图片文件并转发到 BiRefNet 去背景服务；请求可携带 `projectId`、`targetLayerId`、`assetFolderId`、`assetLabel`、`sourceResourceId` 和 `canvasCompletion`，有 `canvasCompletion` 时完成后按生成占位写入结果图层，否则沿用旧的目标图层替换路径；响应返回 `imageSrc`、`objectKey`、`assetObjectId`、`width`、`height`、`taskId`、`elapsedMs`、`provider` 和可选 `project` 快照。服务地址由 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_BASE_URL` 配置，令牌只在服务端通过 `GENARRATIVE_EDITOR_BACKGROUND_REMOVAL_TOKEN` 注入。
 - `POST /api/editor/icon-spritesheets/generations`：按图标规范图和素材描述数组生成 spritesheet，生成成功后 api-server 先保存带纯色背景 spritesheet 源图，再调用 BgFilter 生成透明 spritesheet。请求支持 `model`、`screenColor`、`segModel`、`aspectRatio`、`imageSize`、`priceMudPoints`、`projectId`、`assetFolderId` 和 `generationInputs`；`priceMudPoints` 必须来自编辑器生成计费配置中对应生图模型的尺寸档位（如 `nanobanana2` 的 `0.5K / 1K / 2K` 或 `gpt-image-2` 的 `1K / 2K`），后端用 `editor_generation_config` 校验后才调用上游；`nanobanana2` 走原生 `generateContent` 并写入 `generationConfig.imageConfig.aspectRatio/imageSize`，`0.5K` 传 `"512"`；`gpt-image-2` 走 `/v1/images/edits`。后端保存透明 spritesheet project resource / 账号素材，并随响应返回对应快照。
- `POST /api/editor/ui-designs/assets/extractions`：以前端已绘入红色框选轮廓的 UI 设计图 Data URL 作为参考图，固定 `gpt-image-2` 和自动决策纯色背景素材提取提示词生成素材 spritesheet，生成成功后 api-server 先保存带纯色背景 spritesheet 源图，再调用 BgFilter 生成透明 spritesheet，并按连通域自动拆分为 `素材 1..N`，返回结构复用图标 spritesheet 响应。请求必须携带 `screenColor`、`segModel`、`aspectRatio: "1:1"`、`imageSize: "1K" | "2K"` 和 `priceMudPoints`；框选数量不超过 6 个时前端按 `1:1·1K` 与 gpt-image-2 1K 价格提交，超过 6 个时按 `1:1·2K` 与 2K 价格提交。后端必须在调用上游前校验比例、尺寸和泥点价格，只允许 `1:1 / 1K / 2K`。请求可携带 `projectId`、`assetFolderId`、`generationInputs` 和 `spritesheetLabel`，后端保存 spritesheet / 拆分素材并返回对应 resource / asset 快照；前端必须把 spritesheet 原图与拆分素材都加入画布。
- `POST /api/editor/images/edits`：按提示词和当前图片 Data URL 调用 VectorEngine edits，返回新的生成图片元数据；接口能力仍可接收明确参考图，但图片快速编辑当前只提交 `sourceImageSrc`，不提交隐藏的 `referenceImageSrcs`。请求携带 project / asset 上下文时由后端创建新 resource / asset，前端只消费响应快照。
+- `POST /api/editor/ui-designs/assets/extractions`：前端把红色框选轮廓绘入本地临时图后，先将该图上传 OSS 并确认 asset object，再以返回的 `objectKey` 作为参考图入队；Data URL / Blob URL 只允许停留在上传前的浏览器临时态。接口固定 `gpt-image-2` 和自动决策纯色背景素材提取提示词生成素材 spritesheet，生成成功后 api-server 先保存带纯色背景 spritesheet 源图，再调用 BgFilter 生成透明 spritesheet，并按连通域自动拆分为 `素材 1..N`，返回结构复用图标 spritesheet 响应。请求必须携带 `screenColor`、`segModel`、`aspectRatio: "1:1"`、`imageSize: "1K" | "2K"` 和 `priceMudPoints`；框选数量不超过 6 个时前端按 `1:1·1K` 与 gpt-image-2 1K 价格提交，超过 6 个时按 `1:1·2K` 与 2K 价格提交。后端必须在调用上游前校验比例、尺寸和泥点价格，只允许 `1:1 / 1K / 2K`。请求可携带 `projectId`、`assetFolderId`、`generationInputs` 和 `spritesheetLabel`，后端保存 spritesheet / 拆分素材并返回对应 resource / asset 快照；前端必须把 spritesheet 原图与拆分素材都加入画布。
+- `POST /api/editor/images/edits`：按提示词和当前图片的已登记 `objectKey` / `resourceId` 调用 VectorEngine edits，返回新的生成图片元数据；图片快速编辑当前只提交 `sourceImageSrc`，不提交隐藏的 `referenceImageSrcs`。画布快速编辑必须把源图精确 `originalWidth x originalHeight` 作为业务目标 `size` 提交，不能重新映射为近似比例或 1K / 2K 预设；api-server 在 VectorEngine provider 边界把目标尺寸和所有 multipart 参考图临时补齐到 16 的倍数，回图后恢复到业务目标精确尺寸，再落 OSS、project resource、账号素材和画布快照。16 对齐尺寸不得泄漏到响应、持久化资源或图层 Resolution。本地红框标记图必须先上传再提交 objectKey；请求携带 project / asset 上下文时由后端创建新 resource / asset，前端只消费响应快照。
 - `POST /api/editor/videos/generations`：按视频描述、模型、比例、时长、分辨率、模式、声音、默认联网搜索标记和泥点价格生成视频。前端可选模型为 `seedance2.0-fast`、`seedance2.0`、`kling3.0`、`kling3.0-omni`，默认 `seedance2.0-fast`；后端必须将 `seedance2.0-fast` 映射到 `doubao-seedance-2-0-fast-260128`，将 `seedance2.0` 映射到 `doubao-seedance-2-0-260128`，两者不得混用。后端允许 6 类比例、4 到 15 秒整数、`480p / 720p / 1080p`，并拒绝 `seedance2.0-fast + 1080p`；`sound=on/off` 映射 Ark `generate_audio=true/false`。后端复用 Ark / VectorEngine content generation task 轮询链路，下载最终视频并持久化到 OSS；请求携带 `projectId` / `assetFolderId` 时同步创建 project resource / 账号素材并返回 `project` / `asset` 快照，基础响应返回 `videoSrc`、尺寸、prompt、model、provider、taskId、durationSeconds、resolution 和 `priceMudPoints`。
 - `POST /api/editor/audios/sound-effects/generations` 与 `POST /api/editor/audios/background-music/generations`：按音效 / 背景音乐参数生成音频并持久化到 OSS；请求携带 `projectId` / `assetFolderId` 时同步创建 project resource / 账号素材并返回 `project` / `resource` / `asset` 快照，基础响应返回 `audioSrc`、prompt、model、provider、taskId、duration、歌词和 `priceMudPoints`。

@@ -128,7 +128,7 @@
 - 画布 Agent 会话刷新后能从后端恢复会话标题、消息、附件和生成记录；前端不得根据本地临时状态伪造会话持久化结果。
 - 图片选中后的浮动工具栏按钮顺序固定为：快速编辑、分割线、裁扩按钮、去除背景按钮、UI设计图专属提取素材、角色图专属生成动画、分割线、重绘、下载按钮。裁扩通过画布边界拖拉完成，不再展示四边数值输入；默认自由比例，选择固定比例后拖拉边界保持对应比例，完成后在原素材旁边新增裁扩结果图层，扩展区域透明填充。去除背景调用同源 BFF `POST /api/editor/images/background-removals`，由 api-server 代理远端 BiRefNet 服务并持久化结果；有项目上下文时先在画布创建关闭面板的去背景生成占位，完成后由后端通过 `canvasCompletion` 把新 project resource 写入该占位并返回快照，无占位上下文时才用新的 project resource 引用替换当前图层。画布任务侧栏按“排队/生成中”和“已完成”分页，生成中排在排队前，生成中耗时从任务开始时间戳实时计算，排队中不计时；进行中任务只显示阶段文本和已用时，不显示百分比；完成态生成任务副标题显示用户提示词并单行截断；点击任务只聚焦对应画布内容，不激活生成面板或改变任务顺序，聚焦时必须预留图片上方工具栏、底部工具栏和可见生成对话框空间。UI设计图的提取素材必须先进入红框素材框选状态，默认启用矩形框选，右侧框选工具与快速编辑统一且可再次点击取消启用态，当前启用工具按钮必须保持高亮。素材提取面板必须在素材下方，使用与生成新素材一致的面板宽度和底部模型 / 按钮样式，提示语显示 `使用框选工具框选你希望从画面中提取的素材`，并展示按原图坐标准确裁剪的框选区域截图预览、固定模型 `gpt-image-2`、左下角计划规格 `1:1·1K/2K` 和 `提取 · N泥点` 按钮，不显示额外取消按钮；点击素材和面板以外的画布区域即退出 UI 素材提取。至少框选一个区域后才可提交，前端把红色轮廓绘入原图后固定走 `gpt-image-2` 和自动决策纯色背景素材提取提示词；生成的透明 spritesheet 原图和拆分后的独立素材都作为画布图层保留。
 - 重绘生成资源后，右侧出现新生成结果图层，并自动 fit 原图 + 新图，且重绘面板保持打开。
- 快速编辑 / 重绘站内 public 示例图、历史 generated 图或 OSS generated 图时，前端先读取成 `data:image/*;base64,...` 再提交，后端不得再收到 `/creation-type-references/*`、`/generated-*` 或 OSS URL 作为 `referenceImageSrcs/sourceImageSrc`。
+- 快速编辑 / 重绘站内 public 示例图、历史 generated 图或 OSS generated 图时，优先复用当前图层已有 `objectKey` / `resourceId` / `sourceAssetId`；只有尚未登记的浏览器本地图片才先上传并取得 objectKey。前端不得再把正式对象下载成 `data:image/*;base64,...` 后提交，也不得把 Data URL / Blob URL 写入外部生成持久任务 JSON；后端收到引用后统一做 owner 归属校验并签名读取。
 - 快速编辑不保留额外参考图入口；点击修改时只把原图或红框序号标注图作为 `/api/editor/images/edits` 的 `sourceImageSrc` 提交给后端。
 - 素材文件夹可以新建、折叠、重命名和删除；删除普通文件夹后，其素材移动到“项目素材”。普通上传默认落入“上传素材”文件夹；素材库缺少该文件夹时，前端在首次普通上传前创建一次并复用，拖到指定文件夹或点击指定文件夹上传时仍进入目标文件夹。
 - 上传按钮和拖拽上传都支持多文件；底部工具栏的上传入口选择文件后直接进入“上传素材”并在当前画布视口中心创建画布图层，素材栏文件夹内的上传入口只写入对应素材文件夹、不自动入画布；拖到文件夹或该文件夹内素材时进入目标文件夹；拖到画布时进入“上传素材”并在投放点创建画布图层。上传图片必须在创建占位素材、画布图层和账号级素材记录前先读取原图 Resolution，图层宽高、`originalWidth/originalHeight` 和素材库 `width/height` 都使用图片本身尺寸；上传视频同样在创建素材和图层前读取视频 metadata 宽高，保证单层下载或 ZIP 导出的真实视频文件重新导入后仍按文件自身尺寸入画布；仅在无法解析尺寸时才使用对应媒体兜底尺寸。
@@ -42,6 +42,7 @@ cargo run -p pingora-gateway --manifest-path server-rs/Cargo.toml

 ```bash
 npm run check:pingora-gateway-smoke
+npm run check:nginx-spa-routes
 npm run check:pingora-route-parity
 npm run check:nginx-pingora-canary
 npm run check:pingora-canary-docker
@@ -59,9 +60,11 @@ npm run check:pingora-cutover-evidence-audit
 npm run check:pingora-release-readiness
 ```

-`check:pingora-gateway-smoke` 会临时启动 mock `api-server`、mock SpacetimeDB、mock Gitea 和 `pingora-gateway`，覆盖 SPA fallback、后台静态路由、HTML / 普通静态资源 `no-cache`、Vite 指纹静态资源 immutable 缓存、静态 `ETag` / `Last-Modified` 与 `304` 协商缓存、静态 `HEAD` 响应、静态 Range、静态 access log method/path/status 对账、gzip 最小长度、小响应不压缩、图片资源不压缩、大响应压缩、ACME、TLS 直连、HTTP/2 ALPN、HTTP 到 HTTPS 重定向、内部路由拒绝、shadow probe、API 代理头（`Host` / `X-Forwarded-Host` / `X-Forwarded-Proto` / `X-Real-IP` / `X-Forwarded-For`）、Gitea Host 整站转发、请求体上限、429 接流保护、上游断连 / 超时 JSON 错误、维护模式、维护模式不拦截 Gitea Host 和 SpacetimeDB WebSocket Upgrade，并复用 `check-pingora-direct-live.mjs` 对临时 HTTPS / HTTP redirect / WSS subscribe 入口做 live smoke。该本地 fixture 会让首页同时引用普通静态资源和 Vite 指纹静态资源，direct live JSON 必须确认指纹资源 GET / HEAD / `Range: bytes=0-0` 以及 access log method/path/status 证据，避免正式直连前只证明普通静态读取。排查失败时可追加 `-- --verbose` 输出网关 stderr / stdout；已确认二进制无需重编时可追加 `-- --skip-build`。
+`check:pingora-gateway-smoke` 会临时启动 mock `api-server`、mock SpacetimeDB、mock Gitea 和 `pingora-gateway`，覆盖精确主站 SPA fallback、大小写与尾部斜杠兼容、同前缀未知路径真实 404、后台静态路由、HTML / 普通静态资源 `no-cache`、Vite 指纹静态资源 immutable 缓存、静态 `ETag` / `Last-Modified` 与 `304` 协商缓存、静态 `HEAD` 响应、静态 Range、静态 access log method/path/status 对账、gzip 最小长度、小响应不压缩、图片资源不压缩、大响应压缩、ACME、TLS 直连、HTTP/2 ALPN、HTTP 到 HTTPS 重定向、内部路由拒绝、shadow probe、API 代理头（`Host` / `X-Forwarded-Host` / `X-Forwarded-Proto` / `X-Real-IP` / `X-Forwarded-For`）、Gitea Host 整站转发、请求体上限、429 接流保护、上游断连 / 超时 JSON 错误、维护模式、维护模式不拦截 Gitea Host 和 SpacetimeDB WebSocket Upgrade，并复用 `check-pingora-direct-live.mjs` 对临时 HTTPS / HTTP redirect / WSS subscribe 入口做 live smoke。该本地 fixture 会让首页同时引用普通静态资源和 Vite 指纹静态资源，direct live JSON 必须确认指纹资源 GET / HEAD / `Range: bytes=0-0` 以及 access log method/path/status 证据，避免正式直连前只证明普通静态读取。排查失败时可追加 `-- --verbose` 输出网关 stderr / stdout；已确认二进制无需重编时可追加 `-- --skip-build`。

-`check:pingora-route-parity` 读取 `deploy/pingora/nginx-route-parity.matrix.json`，静态确认生产 / 开发 Nginx 模板、Pingora Rust 路由单测和本文档都覆盖同一组核心路由。`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml matches_nginx_route_parity_matrix` 会读取同一份矩阵，逐条断言 `classify_path` 的路由结果、body limit 和接流保护分组。
+`check:nginx-spa-routes` 从 `appPageRoutes.ts` 的 `STAGE_ROUTE_ENTRIES` / `APP_RUNTIME_ROUTES`、`appRoutes.tsx` 的精确路由判断和兼容恢复路径 `/creation/rpg/agent` 提取当前主站 SPA allowlist，确认生产、开发和容器三套 Nginx 模板集合一致，并验证大小写、尾部斜杠和 `/creation/not-exist`、`/runtime/not-exist`、`/puzzle/not-exist` 等未知反例。
+
+`check:pingora-route-parity` 会先执行同一 Nginx SPA 路由门禁，再读取 `deploy/pingora/nginx-route-parity.matrix.json`，静态确认生产 / 开发 Nginx 模板、Pingora Rust 路由 allowlist / 单测和本文档都覆盖同一组核心路由。`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml matches_nginx_route_parity_matrix` 会读取同一份矩阵，逐条断言 `classify_path` 的路由结果、body limit 和接流保护分组。

 `check:nginx-pingora-canary` 会静态校验 `deploy/nginx/snippets/genarrative-pingora-canary.conf` 的本机来源限制、handoff 响应头、probe token 占位、前缀 rewrite、低缓冲和 WebSocket Upgrade 设置，也会校验 `deploy/nginx/snippets/genarrative-pingora-realpath-canary.conf` 只能作为独立 loopback `server` 片段使用、默认监听 `127.0.0.1:18083`、写独立 access log、没有 rewrite、覆盖真实 `/api` / `/v1` / `/assets` 代表路径。本机安装了 Nginx 时脚本会额外把两个 snippet 包进临时 `http {}` 执行 `nginx -t`；需要在 CI / 目标 agent 上强制要求真实 Nginx 语法检查时执行 `node scripts/check-nginx-pingora-canary.mjs --require-nginx`。

@@ -539,9 +542,10 @@ dev 根盘空间在安装后曾接近满盘；2026-06-17 进入 canary 前已清
 | `/v1/database/{db}/subscribe`、`/v1/identity*`                                            | 转发到 SpacetimeDB，保留 WebSocket Upgrade 头。                                        |
 | `/__genarrative_pingora/healthz`                                                          | 仅在携带 `X-Genarrative-Pingora-Probe` 且匹配配置 token 时返回 shadow JSON，否则 404。 |
 | `/v1/*`、`/generated-*`、`/healthz*`、`/readyz*`                                          | 返回 404，保持生产公网不暴露口径。                                                     |
-| 其它路径                                                                                  | 先读取静态文件或目录 index，失败回退 `/index.html`，HTML 默认 `no-cache`，并支持条件请求返回 `304` 与单段 `Range: bytes=` 返回 `206` / 越界返回 `416`。 |
+| 主站 SPA allowlist                                                                        | 只对当前前端完整路由及兼容恢复路径 `/creation/rpg/agent` 失败回退 `/index.html`；匹配大小写不敏感并允许一个尾部斜杠，HTML 默认 `no-cache`。 |
+| 其它 Web 路径                                                                             | 只读取真实静态文件或目录 index，缺失时返回真实 404；`/creation/not-exist`、`/runtime/not-exist`、`/puzzle/not-exist` 不进入 SPA fallback。 |

-维护模式下，API-like 路由返回 JSON `503`，Web 静态路由优先返回 `maintenance.html`，不存在时返回纯文本 `503`。
+维护模式下，公网 API-like 路由返回 JSON `503`，公网 Web 静态路由优先返回 `maintenance.html`，不存在时返回纯文本 `503`。IPv4 loopback / RFC1918 / link-local 和 IPv6 loopback / ULA / link-local 来源绕过整站维护闸，主站页面与静态资源、普通 API、后台页面与后台 API、SpacetimeDB 路由均按非维护状态继续处理；应用层登录、管理员鉴权和其它业务鉴权保持不变。Pingora 直连按 TCP peer 判定来源；仅当 peer 是 loopback 的同机 Nginx 时才接受 Nginx 强制覆盖的 `X-Real-IP`，绝不使用客户端可伪造的 `X-Forwarded-For` 做维护放行。该放行只绕过网关维护响应；若 `pause-after-stdb` 已停止 api-server，内网普通 API 和后台 API 仍不可用。
 代理失败时，API / SpacetimeDB 等代理路由返回统一 JSON 网关错误；本地静态路由仍保持对应 HTTP 错误状态。
 静态 `Range` 只支持单段 bytes range；多段 range 暂按完整文件返回，避免在正式替换前引入 multipart 响应面。`If-None-Match` / `If-Modified-Since` 优先于 `Range` 判定，命中时仍返回 `304`；`If-Range` 日期匹配时继续返回 `206`，日期旧于文件或弱 ETag 校验器时回完整 `200`；`206` / `304` / `416` 不做 gzip 压缩，避免 `Content-Range` 语义被响应体改写破坏。Gateway smoke 会用固定 `X-Request-Id` 对账静态 `304`、`405`、`206`、`416` 的 Pingora access log 行，确认本地响应状态也进入正式切换证据链。
 静态路由只允许 `GET` / `HEAD` 读取；其它方法在确认命中静态候选后返回 `405` 并写入 `Allow: GET, HEAD`，缺失文件仍返回 `404`，避免直连后错误客户端把静态入口当作可写接口。
@@ -16,7 +16,7 @@ server-rs + Axum + SpacetimeDB

 `server-rs/Cargo.toml` 是 workspace 事实源。默认构建成员为 `crates/api-server`；第三方依赖版本和 workspace 内 crate path 统一放在 `[workspace.dependencies]`。

-SpacetimeDB 版本口径：当前 Rust crate `spacetimedb`、`spacetimedb-sdk`、`spacetimedb-lib` 统一锁定 `2.5.0`；本地 `spacetime` CLI / standalone、生成的 `spacetime-client` bindings 和容器压测镜像也必须与 `server-rs/Cargo.toml` 锁定版本对齐，避免 BSATN / procedure result 反序列化错配。遇到版本不匹配时，不继续沿着业务超时排查，先把 CLI / standalone 直接升级到锁定版本并重启后再重试。
+SpacetimeDB 版本口径：当前 Rust crate `spacetimedb`、`spacetimedb-sdk`、`spacetimedb-lib` 统一锁定 `2.6.0`；本地 `spacetime` CLI / standalone、生成的 `spacetime-client` bindings 和容器压测镜像也必须与 `server-rs/Cargo.toml` 锁定版本对齐，避免 BSATN / procedure result 反序列化错配。遇到版本不匹配时，不继续沿着业务超时排查，先把 CLI / standalone 直接升级到锁定版本并重启后再重试。

 当前主要 crate：

@@ -189,18 +189,20 @@ npm run check:server-rs-ddd
 ## 账户充值数据契约

 1. `profile_recharge_product_config` 是泥点和会员商品配置真相源，默认商品只在表为空时由 SpacetimeDB 播种。`module-runtime` 中的默认商品 helper 只作为空库种子和兼容入口，不再作为运行期业务真相。
-2. 后台通过 `/admin/api/profile/recharge-products` 读写充值商品配置；字段覆盖 `productId`、标题、商品类型、金额分、基础泥点、首充赠送泥点、会员天数、徽标、说明、会员层级、会员每周期限时泥点、周期天数、队列上限、折扣率、启用状态和排序。
-3. 充值中心、下单校验和支付确认入账都读取 `profile_recharge_product_config`。历史订单保留下单时写入的商品标题、金额、渠道、状态和 provider transaction id，不随配置改动回写。
-4. 泥点首充资格按 `user_id + product_id` 的历史 `paid` 订单独立判断。某个档位已支付后，只隐藏该档位的首充赠送；其它未购买档位仍展示和结算首充赠送。
-5. `hasPointsRecharged` 只保留为账号是否发生过任一泥点充值的兼容字段，不得驱动所有商品展示隐藏或结算金额计算。前端只渲染后端返回的商品快照。
-6. 默认会员商品为空库播种时使用 `Starter / Basic / Pro / Ultimate` 四档，默认有效期均为 30 天，每周期限时泥点分别为 `200 / 800 / 2500 / 6000`，队列上限分别为 `2 / 2 / 5 / 10`。
-7. 会员有效期和周期重置时间是两条独立时间线。`expires_at` 只决定会员是否生效；`cycle_resets_at` 只决定当前周期限时泥点何时重置。会员升级只更新档位并补齐当前周期限时泥点差额，不延长 `expires_at`，不移动 `cycle_resets_at` 和周期天数。同级会员购买只从当前 `expires_at` 延长有效期，不发放额外当前周期泥点，也不移动重置时间。
-8. 会员周期刷新发生在个人中心、充值中心、任务中心、账单读取和钱包扣费入口：到达 `cycle_resets_at` 时先清除上周期剩余限时泥点，再发放当前会员档位周期额度；会员过期时清除剩余限时泥点并把状态降为普通。周期发放和重置流水分别使用 `membership_period_grant`、`membership_period_reset`。
-9. `paymentChannel` 缺失、未知或冒用小程序支付设备时必须拒绝；真实微信渠道只允许 `wechat_mp`、`wechat_mp_virtual`、`wechat_jsapi`、`wechat_h5`、`wechat_native`，生产配置不得把真实支付静默降级为 `mock`。
-10. access JWT 只携带最小设备快照 `device.client_type`、`device.client_runtime`、`device.client_platform`。充值下单按该快照拦截小程序渠道：小程序只允许 `wechat_mp` / `wechat_mp_virtual`；移动网页和微信内 H5 走 `wechat_h5`；桌面网页和桌面微信走 `wechat_native`；`wechat_jsapi` 仅保留后端能力，未接微信开放平台前不由前端自动选择。历史普通 Web 登录态若缺少设备快照也允许继续进入 JSAPI / H5 / Native 渠道的后续支付配置校验，但不放宽小程序虚拟支付。
-11. 所有微信真实渠道都以微信支付通知或服务端查单确认 `SUCCESS` 为到账事实；小程序、H5 跳转和 Native 二维码返回都不能直接发放泥点或会员。
-12. 微信 JSAPI / H5 / 小程序 / Native 下单统一显式传 5 分钟 `time_expire`，格式为 RFC3339 秒级时间；Native 额外通过 `wechatNativePayment.expiresAt` 下发给前端二维码弹窗展示。
-13. 真实微信渠道的新建 pending 充值订单会写入 SpacetimeDB 原生 scheduled 表 `profile_recharge_order_expiration_timer`。到期 reducer 只做数据库内状态转换：订单仍为 `pending` 时更新为 `expired` 并写 `expired_at`，同时删除 timer。HTTP `api-server` 订阅 `profile_recharge_order` 的 `Pending -> Expired` 更新并执行微信查单补偿：`SUCCESS` 可把 `expired` 补确认成 `paid` 入账；`NOTPAY` 会调用微信关单并把本地订单保持为 `expired`；`CLOSED` / `REVOKED` / `PAYERROR` / `ORDER_NOT_EXIST` 只记录检查结果。`external-generation-worker` / controller 不处理充值过期；`wechat_mp_virtual` 到期只记录虚拟渠道不可查，后续真实支付通知仍允许 `Expired -> Paid`。
+2. 默认泥点商品固定为四档：`points_60 = 60 泥点 / 600 分`、`points_180 = 180 + 90 泥点 / 1800 分`、`points_300 = 300 + 150 泥点 / 3000 分`、`points_680 = 680 + 340 泥点 / 6800 分`。`points_60` 的首充赠送为 `0`；后三档首次购买分别赠送基础泥点的 `50%`。
+3. 后台通过 `/admin/api/profile/recharge-products` 读写充值商品配置；字段覆盖 `productId`、标题、商品类型、金额分、基础泥点、首充赠送泥点、会员天数、徽标、说明、会员层级、会员每周期限时泥点、周期天数、队列上限、折扣率、启用状态和排序。
+4. 充值中心、下单校验和支付确认入账都读取 `profile_recharge_product_config`。充值中心 BFF 还必须在 `mudPointBalance` 下发 `totalPoints`、`permanentPoints`、`limitedPoints`、`limitedExpiresAt`、`dailyFreePoints`、`dailyFreeResetPoints` 和 `dailyFreeResetsAt`；前端以该 read model 为真相源，不得自行用总额相减推算余额桶。当前版本公开 UI 只渲染不限时泥点和每日免费泥点，`limitedPoints` 与 `limitedExpiresAt` 仅保留给存量兼容和后端结算。历史订单保留下单时写入的商品标题、金额、渠道、状态和 provider transaction id，不随配置改动回写。
+5. 泥点首充资格按 `user_id + product_id` 的历史 `paid` 订单独立判断。某个档位已支付后，只隐藏该档位的首充赠送；其它未购买档位仍展示和结算首充赠送。
+6. `hasPointsRecharged` 只保留为账号是否发生过任一泥点充值的兼容字段，不得驱动所有商品展示隐藏或结算金额计算。前端只渲染后端返回的商品快照。
+7. 当前版本公开充值 UI 只展示泥点商品，不渲染会员购买页签、会员商品、购买会员或升级会员入口。充值中心响应中的会员商品兼容字段、默认会员商品、`profile_membership` 和周期刷新逻辑继续保留；存量会员的 `cycle_remaining_points` 仍通过充值中心 read model 下发用于兼容和结算，但不作为限时泥点在当前版本前台展示。
+8. 默认会员商品为空库播种时使用 `Starter / Basic / Pro / Ultimate` 四档，默认有效期均为 30 天，每周期限时泥点分别为 `200 / 800 / 2500 / 6000`，队列上限分别为 `2 / 2 / 5 / 10`。
+9. 会员有效期和周期重置时间是两条独立时间线。`expires_at` 只决定会员是否生效；`cycle_resets_at` 只决定当前周期限时泥点何时重置。会员升级只更新档位并补齐当前周期限时泥点差额，不延长 `expires_at`，不移动 `cycle_resets_at` 和周期天数。同级会员购买只从当前 `expires_at` 延长有效期，不发放额外当前周期泥点，也不移动重置时间。
+10. 会员周期刷新发生在个人中心、充值中心、任务中心、账单读取和钱包扣费入口：到达 `cycle_resets_at` 时先清除上周期剩余限时泥点，再发放当前会员档位周期额度；会员过期时清除剩余限时泥点并把状态降为普通。周期发放和重置流水分别使用 `membership_period_grant`、`membership_period_reset`。
+11. `paymentChannel` 缺失、未知或冒用小程序支付设备时必须拒绝；真实微信渠道只允许 `wechat_mp`、`wechat_mp_virtual`、`wechat_jsapi`、`wechat_h5`、`wechat_native`，生产配置不得把真实支付静默降级为 `mock`。
+12. access JWT 只携带最小设备快照 `device.client_type`、`device.client_runtime`、`device.client_platform`。充值下单按该快照拦截小程序渠道：小程序只允许 `wechat_mp` / `wechat_mp_virtual`；移动网页和微信内 H5 走 `wechat_h5`；桌面网页和桌面微信走 `wechat_native`；`wechat_jsapi` 仅保留后端能力，未接微信开放平台前不由前端自动选择。历史普通 Web 登录态若缺少设备快照也允许继续进入 JSAPI / H5 / Native 渠道的后续支付配置校验，但不放宽小程序虚拟支付。
+13. 所有微信真实渠道都以微信支付通知或服务端查单确认 `SUCCESS` 为到账事实；小程序、H5 跳转和 Native 二维码返回都不能直接发放泥点或会员。
+14. 微信 JSAPI / H5 / 小程序 / Native 下单统一显式传 5 分钟 `time_expire`，格式为 RFC3339 秒级时间；Native 额外通过 `wechatNativePayment.expiresAt` 下发给前端二维码弹窗展示。
+15. 真实微信渠道的新建 pending 充值订单会写入 SpacetimeDB 原生 scheduled 表 `profile_recharge_order_expiration_timer`。到期 reducer 只做数据库内状态转换：订单仍为 `pending` 时更新为 `expired` 并写 `expired_at`，同时删除 timer。HTTP `api-server` 只订阅这张活跃 timer 表的删除事件，收到 `order_id` 后通过 procedure 重新读取订单，只有状态确认为 `expired` 才执行微信查单补偿；支付或主动关闭同样会删除 timer，但会被状态判断忽略。监听断线期间遗漏的删除事件由未检查过期订单 catch-up 补齐，不订阅完整 `profile_recharge_order` 历史表。普通微信支付查单中 `SUCCESS` 可把 `expired` 补确认成 `paid` 入账；`NOTPAY` 会调用微信关单并把本地订单保持为 `expired`；`CLOSED` / `REVOKED` / `PAYERROR` / `ORDER_NOT_EXIST` 只记录检查结果。`wechat_mp_virtual` 使用小程序 `access_token` 和虚拟支付 AppKey 调用官方 `/xpay/query_order`，只在返回单号、支付类型 `order_type=0/7`、金额、合法 `paid_time` 与本地契约一致且状态为 `2/3/4` 时补入账；退款类型 `1/8` 不得触发充值，其余已知状态只记录检查结果。`short_series_goods` 从 `status=2` 恢复时先幂等入账，再调用 `/xpay/notify_provide_goods`，失败后允许基于本地 `paid` 状态只重试发货；`short_series_coin` 不调用现金单发货接口。`external-generation-worker` / controller 不处理充值过期。

 ## 创作入口泥点扣费契约

@@ -215,13 +217,14 @@ npm run check:server-rs-ddd
 ## 用户钱包与编辑器生成扣费契约

 1. 新用户账号完成注册并成功同步正式认证表后，注册赠送金额读取 `profile_wallet_config.initial_mud_points`；后台通过 `/admin/api/profile/wallet-config` 维护“账号初始泥点数”。未写入配置时默认仍为 `100` 泥点。流水原因仍使用 `new_user_registration_reward`，流水 ID 继续保持幂等，重复发放请求不得叠加余额。
-2. 用户钱包余额对外仍暴露为一个总余额，但后端扣费时优先消耗 `profile_membership.cycle_remaining_points` 中的会员周期限时泥点，再消耗普通永久泥点；扣费流水 `metadata_json` 会记录 `membershipPeriodPointsDelta`、`permanentPointsDelta` 和限时泥点所属 `cycleResetsAtMicros`，退款会按原消费流水优先恢复同一周期的限时泥点，前端不得自行决定扣费桶。
-3. 每日免费泥点当前由每日任务体系发放，流水来源为 `daily_task_reward`，任务进度和可领取状态按北京时间每日刷新；它不参与会员 `cycle_resets_at`，也不由前端合并进会员周期泥点。
-4. 编辑器画板所有会调用外部生成 provider 的入口都不从前端请求接收 `priceMudPoints`；同步请求以 SpacetimeDB `editor_generation_pricing_config` 当前全局配置计算，外部生成队列则以 `external_generation_job.price_mud_points` 保存的入队价格为准，worker 的扣费、退款、响应和资产成本不得按执行时配置重算。前端按钮泥点只作为展示。
-5. 编辑器图片生成 / 图片修改 / 图标 spritesheet / UI 设计图提取素材 / 视频 / 角色动作 / 音效 / 背景音乐必须在后端计算模型价格后使用 `execute_billable_asset_operation_with_cost` 预扣泥点；预扣失败必须 fail-closed，不得继续提交 VectorEngine、Ark、Suno 或 Vidu 上游任务。
-6. 队列任务按 `job_id + claim_attempt` 使用独立 consume/refund ledger。新 attempt 结算旧 attempt 时必须先写 `asset_operation_wallet_settlement`：旧 consume 已存在则原子退款，尚不存在则写取消 intent；迟到 consume 在同一 SpacetimeDB 事务内看到 intent 后必须失败关闭。重复 consume/refund 只有用户、金额、来源和配对 ledger 全部一致时才可视为幂等成功。lease 过期时只有 `attempt < max_attempts` 才能递增并重领；最终 attempt 已耗尽时，claim transaction 必须直接把 job 收口为 `failed`、清理 lease、写失败事件并结算当前 attempt，不能再把任务返回 worker 或调用 provider。
-7. 音频生成的编辑器链路虽然任务提交和结果发布分离，仍必须把提交时后端计算出的模型价格写入 `AudioAssetBindingTarget.billing_points_cost`，最终发布落资产时按该价格扣费；创作音频目标未提供该字段时才使用旧的创作音频固定成本。
-8. 编辑器图片生成、图片修改、图标 spritesheet 和 UI 设计图提取素材的参考图可以提交 Data URL 或已登记的 generated objectKey；objectKey 必须归属于当前账号的 `editor_project_resource`、`editor_asset` 或 `asset_object`，后端通过归属校验后才签名读取 OSS。图标素材和 UI 素材提取的额外参考图必须真正传入 provider，不得只写入 `generationInputs` 展示快照；图片快速编辑当前不开放额外参考图，只提交原图或红框序号标注图作为 `sourceImageSrc`。UI 素材提取额外参考图上限为 5 张，普通图片生成上限 5 张，图标素材上限 8 张额外参考图。
+2. 用户钱包余额对外仍暴露为一个总余额，但后端扣费必须按“每日免费泥点 -> 会员周期限时泥点 -> 普通永久泥点”的顺序消耗，前端不得自行决定扣费桶。扣费流水 `metadata_json` 必须记录 `dailyFreePointsDelta`、`dailyFreeDayKey`、`membershipPeriodPointsDelta`、`permanentPointsDelta` 和会员限时泥点所属 `cycleResetsAtMicros`；资产退款中的会员限时泥点只在原周期仍有效时恢复会员额度，其余会员部分进入普通永久泥点。原每日免费消费部分在同一业务日退款时恢复原当日额度；跨北京时间业务日退款时叠加到退款当日每日免费桶，不进入普通永久泥点，当日 `granted_points` 与 `remaining_points` 均可因此超过 `20`。原永久泥点消费部分无论是否跨业务日，均按退款流水中的 `permanentPointsDelta` 退回普通永久泥点。
+3. 每日免费泥点是独立于每日任务和会员周期的正式余额额度，基础发放量固定为 `20`，不得由前端或后台任务配置改写。`profile_daily_free_points` 保存当前北京时间业务日、当日基础发放及跨日退款叠加后的总额度和剩余额度；北京时间每日 `00:00` 作为业务日边界，个人中心、充值中心、账单读取和钱包扣费入口在首次触达新业务日时原子清除昨日剩余及退款叠加量，并把今日 `granted_points`、`remaining_points` 重置为 `20`。首次初始化使用 `daily_free_grant` 流水，跨日重置使用 `daily_free_reset` 流水。惰性落库不能改变“北京时间 00:00 后读取即为新日额度”的对外语义。
+4. 每日任务奖励继续使用 `daily_task_reward` 流水并进入普通永久泥点，但主站隐藏每日任务卡片和任务中心入口，不再把每日登录任务描述为“每日免费泥点”。任务配置、进度、领取记录和后台管理能力暂时保留，除非后续需求明确删除。
+5. 编辑器画板所有会调用外部生成 provider 的入口都不从前端请求接收 `priceMudPoints`；同步请求以 SpacetimeDB `editor_generation_pricing_config` 当前全局配置计算，外部生成队列则以 `external_generation_job.price_mud_points` 保存的入队价格为准，worker 的扣费、退款、响应和资产成本不得按执行时配置重算。前端按钮泥点只作为展示。
+6. 编辑器图片生成 / 图片修改 / 图标 spritesheet / UI 设计图提取素材 / 视频 / 角色动作 / 音效 / 背景音乐必须在后端计算模型价格后使用 `execute_billable_asset_operation_with_cost` 预扣泥点；预扣失败必须 fail-closed，不得继续提交 VectorEngine、Ark、Suno 或 Vidu 上游任务。
+7. 队列任务按 `job_id + claim_attempt` 使用独立 consume/refund ledger。新 attempt 结算旧 attempt 时必须先写 `asset_operation_wallet_settlement`：旧 consume 已存在则原子退款，尚不存在则写取消 intent；迟到 consume 在同一 SpacetimeDB 事务内看到 intent 后必须失败关闭。重复 consume/refund 只有用户、金额、来源和配对 ledger 全部一致时才可视为幂等成功。lease 过期时只有 `attempt < max_attempts` 才能递增并重领；最终 attempt 已耗尽时，claim transaction 必须直接把 job 收口为 `failed`、清理 lease、写失败事件并结算当前 attempt，不能再把任务返回 worker 或调用 provider。
+8. 音频生成的编辑器链路虽然任务提交和结果发布分离，仍必须把提交时后端计算出的模型价格写入 `AudioAssetBindingTarget.billing_points_cost`，最终发布落资产时按该价格扣费；创作音频目标未提供该字段时才使用旧的创作音频固定成本。
+9. 编辑器进入外部生成持久队列的图片生成、图片修改、去背景、图标 spritesheet、UI 设计图提取、角色动作和视频参考图，只允许提交已登记的 generated `objectKey`、`resourceId` 或 `assetId`；任务 `request_payload_json` / `result_payload_json` 任意层级都禁止 `data:` / `blob:`，并受统一字节上限保护。objectKey 必须归属于当前账号的 `editor_project_resource`、`editor_asset` 或 `asset_object`，后端通过归属校验后才签名读取 OSS。本地红框序号标注图必须先上传并确认对象，再把 objectKey 入队；不得把既有 objectKey 下载成 Data URL 后写入任务。图标素材和 UI 素材提取的额外参考图必须真正传入 provider，不得只写入 `generationInputs` 展示快照；图片快速编辑当前不开放额外参考图。UI 素材提取额外参考图上限为 5 张，普通图片生成上限 5 张，图标素材上限 8 张额外参考图。同步且不持久化的历史兼容入口即使仍能解析 Data URL，也不能把该值转存到工程、素材、元数据、审计或任务表。

 ## 外部服务与资产

@@ -266,7 +269,15 @@ npm run check:server-rs-ddd

 - Rust 结构体：`ExternalGenerationJob`
 - 源码：`server-rs/crates/spacetime-module/src/external_generation.rs`
- 用途：外部生成 worker 的持久任务队列和用户可见生成任务列表；`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 时，`api-server` HTTP 角色只入队，`external-generation-worker` 角色通过 claim lease 领取、续租、执行，并用 `lease_token` 栅栏回写完成 / 失败。队列行同时保存 `price_mud_points`、`refund_ledger_id` 和 `notification_acknowledged_at`，BFF 通过 `GET /api/runtime/external-generation/jobs` 返回当前账号的正式生成任务列表、价格、状态和未确认终态数量；前端只能展示该后端事实，完成 / 失败提示展示后后台调用 `POST /api/runtime/external-generation/jobs/acknowledge` 由后端写确认时间，关闭按钮只收起本地弹窗，未确认终态任务会在下次登录后再次集中弹出。拼图 `compile_puzzle_draft` 的前置 `compile_puzzle_agent_draft`、`generate_puzzle_images` 与 `generate_puzzle_ui_background` 的业务写回也在对应 SpacetimeDB transaction 内校验 `job_id + worker_id + lease_token`、job kind、owner 和 source entity，避免过期 worker 写 session / work profile；图片画布编辑器的 `editor_image_generation`、`editor_image_edit`、`editor_background_removal`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation` 和 `editor_background_music_generation` 复用同一队列表，worker 成功后经 `api-server` facade 写入 `editor_project_resource` / `editor_asset` / `editor_canvas.layers_json`，前端只通过 BFF job 状态轮询和项目快照读取恢复完成态。`GENARRATIVE_EXTERNAL_GENERATION_MODE=inline` 时不创建该队列行，三个 external generation guard 字段必须同时为空才允许 api-server 受控同步写回，半空 guard 仍会拒绝。worker 成功写回业务事实后才能 complete job；业务失败态写回成功后才能 fail job，失败态未写回时保留租约等待后续重领。
+- 用途：外部生成 worker 的内部持久任务队列；`GENARRATIVE_EXTERNAL_GENERATION_MODE=queue` 时，`api-server` HTTP 角色只入队，`external-generation-worker` 角色通过 claim lease 领取、续租、执行，并用 `lease_token` 栅栏回写完成 / 失败。队列行继续保存 worker 执行、计费与滚动发布兼容所需字段，但用户可见任务列表、价格、状态、未确认终态数量和通知确认时间的正式读取事实源已经迁到 `external_generation_job_summary`；BFF 不得再为列表 / 详情 / acknowledge 读取该大表。拼图 `compile_puzzle_draft` 的前置 `compile_puzzle_agent_draft`、`generate_puzzle_images` 与 `generate_puzzle_ui_background` 的业务写回也在对应 SpacetimeDB transaction 内校验 `job_id + worker_id + lease_token`、job kind、owner 和 source entity，避免过期 worker 写 session / work profile；图片画布编辑器的 `editor_image_generation`、`editor_image_edit`、`editor_background_removal`、`editor_icon_spritesheet_generation`、`editor_ui_design_asset_extraction`、`editor_character_animation_generation`、`editor_video_generation`、`editor_sound_effect_generation` 和 `editor_background_music_generation` 复用同一队列表，worker 成功后经 `api-server` facade 写入 `editor_project_resource` / `editor_asset` / `editor_canvas.layers_json`，前端只通过 BFF job 状态轮询和项目快照读取恢复完成态。`GENARRATIVE_EXTERNAL_GENERATION_MODE=inline` 时不创建该队列行，三个 external generation guard 字段必须同时为空才允许 api-server 受控同步写回，半空 guard 仍会拒绝。worker 成功写回业务事实后才能 complete job；业务失败态写回成功后才能 fail job，失败态未写回时保留租约等待后续重领。
+- 载荷约束：本次先对 `source_module = editor-canvas` 的 `request_payload_json` / `result_payload_json` 实施有限大小合法 JSON、任意层级禁止 `data:` / `blob:` 的双层门禁，只保存 worker 执行必需的普通参数和已登记媒体引用；其它玩法在完成各自参考图资源化之前不由本次门禁静默改变既有请求契约。该主表只供 worker claim / 执行和受控维护读取；正式用户任务列表、单任务状态、队列概览与 acknowledge 不得再返回或解析这两个 payload。
+
+### `external_generation_job_summary`
+
+- Rust 结构体：`ExternalGenerationJobSummary`
+- 源码：`server-rs/crates/spacetime-module/src/external_generation.rs`
+- 用途：外部生成正式任务列表的轻量投影，按 `job_id` 保存 owner、来源、状态、价格、有界错误摘要、通知确认时间、各阶段时间和入队时提取的 `request_prompt`，不包含 request/result payload、worker lease 或 dedupe 内部字段。错误摘要统一拒绝内联媒体并限制为 2048 字符；列表在单次 owner 扫描中同时计数并只保留请求 limit 的固定大小 top-N，不得先收集全量历史再截断。enqueue、claim、renew、complete、fail 事务同步投影；acknowledge 只更新该轻量表并写审计事件，后续主任务同步必须保留已有确认时间，禁止为了写确认时间加载 / 重写大 payload 行。BFF 的列表、状态和确认只调用 summary procedure。历史终态任务由迁移操作员的游标分批 maintenance procedure 在压缩 payload 时同步回填摘要，正式列表不得为兼容旧数据回扫完整主表。
+- 正式读取 procedure 为 `get_external_generation_job_summary_and_return`、`list_external_generation_job_summaries_and_return` 和 `acknowledge_external_generation_job_summaries_and_return`。历史维护 procedure 为 `compact_external_generation_job_payloads_and_return` 与 `backfill_external_generation_job_summaries_and_return`，仅 migration operator 可调用；运维入口统一使用 `npm run spacetime:external-generation:maintain -- ...`，默认 dry-run、单批最多 25 条。B-tree cursor 选择阶段最多反序列化 `limit + 1` 行，apply 再按主键逐条读取选中行；怀疑存在单行异常巨型 JSON 时必须先使用 `--limit 1`。payload 压缩额外固定使用 `source_module = editor-canvas` 的复合 cursor 索引，不得静默改写其它玩法历史任务。

 ### `external_generation_job_event`

@@ -683,6 +694,12 @@ npm run check:server-rs-ddd
 - Rust 结构体：`ProfileDashboardState`
 - 源码：`server-rs/crates/spacetime-module/src/runtime/profile.rs`

+### `profile_daily_free_points`
+
+- Rust 结构体：`ProfileDailyFreePoints`
+- 源码：`server-rs/crates/spacetime-module/src/runtime/profile.rs`
+- 作用：每日免费泥点事实源。`day_key` 使用北京时间业务日，基础发放量固定为 `20`，`remaining_points` 保存当日剩余额度；跨业务日退款的每日免费消费部分会叠加到退款当日，使 `granted_points` 和 `remaining_points` 可暂时超过 `20`，下一业务日首次触达时旧余额与叠加量一并失效并重置为 `20`。
+
 ### `profile_feedback_submission`

 - Rust 结构体：`ProfileFeedbackSubmission`
@@ -709,7 +726,7 @@ npm run check:server-rs-ddd

 - Rust 结构体：`ProfileRechargeProductConfig`
 - 源码：`server-rs/crates/spacetime-module/src/runtime/profile.rs`
- 作用：泥点和会员充值商品配置真相源，供充值中心展示、下单校验、支付确认和后台“充值商品”页维护。
+- 作用：泥点和会员充值商品配置真相源，供充值中心展示、下单校验、支付确认和后台“充值商品”页维护；当前公开充值中心只展示四档泥点商品，会员商品配置留存但不公开购买或升级入口。
 - 字段补充：会员商品追加 `membership_period_points`、`membership_period_days`、`membership_queue_limit`、`membership_discount_bps`；泥点商品这些字段必须为 `0`。

 ### `profile_played_world`
@@ -774,7 +791,7 @@ npm run check:server-rs-ddd

 - Rust 结构体：`ProfileWalletLedger`
 - 源码：`server-rs/crates/spacetime-module/src/runtime/profile.rs`
- 说明：账号钱包流水表。`metadata_json` 为可选 JSON 对象字符串，旧行缺失时读取层按 `{}` 归一；外部生成扣费 / 退款写入 `externalGenerationJobId`，使退款记录可以追溯到对应 `external_generation_job`。
+- 说明：账号钱包流水表。`created_at` 表示钱包事务实际结算时间，列表先按当前余额反向校验 `balance_after - amount_delta` 的结算链，再以该时间倒序兜底，避免支付回调或退款重放延迟时出现余额顺序倒置；支付平台确认时间继续保存在充值订单 `paid_at`。`metadata_json` 为可选 JSON 对象字符串，旧行缺失时读取层按 `{}` 归一；外部生成扣费 / 退款写入 `externalGenerationJobId`，使退款记录可以追溯到对应 `external_generation_job`。

 ### `asset_operation_wallet_settlement`

@@ -67,13 +67,19 @@ lease 过期后不代表任务一定再次执行：claim transaction 只有在 `

 `我的` 页签或排障面板展示队列等待时，只读取 BFF 队列接口：`GET /api/runtime/external-generation/queue-overview` 查看当前用户可见队列概览，`GET /api/runtime/external-generation/jobs/{jobId}` 查看单 job 状态。生成页 / 进度页不承接队列概览，只展示当前玩法业务进度；队列接口只提供等待 / 运行 / 失败 / 完成状态补充，最终草稿、作品和结果页仍要轮询对应玩法 session/detail 接口收敛到 ready 或 failed；不要直接查询 `external_generation_job` private table，也不要把 worker 内部 payload 暴露到前端。

+外部生成任务摘要投影与历史 payload 维护使用 `npm run spacetime:external-generation:maintain -- ...`，且只能由已授权 migration operator 的 SpacetimeDB CLI 登录态执行。脚本默认 dry-run、每次只处理一批，绝不自动循环全表；`--apply` 才写入。先发布包含 `external_generation_job_summary` 与 cursor 索引的 SpacetimeDB 模块，在维护模式内对事故时间以前的编辑器终态任务执行小批 dry-run，例如 `npm run spacetime:external-generation:maintain -- --database <database> --server-url <url> --limit 5 --completed-before-micros <micros>`；核对 `matched_count`、`before_bytes`、`after_bytes` 和 `inline_media_count` 后，保持本批输入 cursor 不变并追加 `--apply` 重跑同一批，即使最后一批 `has_more = false`，只要 dry-run 仍有 `matched_count` / `selected_count` 也必须 apply；只有 apply 成功后才使用它返回的 `next_cursor_job_id` 继续。B-tree cursor 的选择阶段最多反序列化 `limit + 1` 行，apply 会再按主键逐条读取选中行但不会同时保留整批 payload；如怀疑存在单行异常巨型历史 JSON，先用 `--limit 1`。payload 压缩硬限制 `source_module = editor-canvas`；终态压缩完成后，用 `--backfill-summaries` 先 dry-run、再 `--apply` 分批补齐仍缺失的活动任务或无内联媒体历史任务摘要，直到 `has_more = false`，最后再切换使用 summary procedure 的 api-server。Stdb 构建 artifact 和完整 release 包都必须包含 `scripts/spacetime-maintain-external-generation-jobs.mjs` 与 `scripts/spacetime-migration-common.mjs`。首次上线不得让 Full Build 从 Stdb 自动直落 API：`STDB_API_ROLLOUT_MODE` 默认 fail-closed 为 `pause-after-stdb`，必须填写受限的 `STDB_API_ROLLOUT_APPROVERS`；Stdb Publish 通过 `KEEP_MAINTENANCE_MODE` 保持维护文件并停止旧 API/controller/worker，暂停点最多等待 4 小时，完成上述维护并确认无后续批次后才由指定审批人放行 API。定时构建缺少审批人时必须在发布前失败，不能静默退回 `normal`；也可分开运行 Stdb publish、维护、API deploy 三个受控 Job。任一批次都不得处理 pending / running payload；不要用 runtime writer、bootstrap secret 或匿名 identity 代替 migration operator，也不要在未核对 dry-run 时直接 apply。
+
+自 2026-07-11 起，`Genarrative-Full-Build-And-Deploy` 的每日 04:00 timer 默认以 `DEPLOY_TARGET=development`、`STDB_API_ROLLOUT_MODE=normal` 对仅供开发使用的 dev 服务器执行 Stdb → API → Web 完整发布，不进入人工 rollout gate。三个下游 Build 都由 Full Job 显式传 `PUBLISH_AFTER_BUILD=false`，不得依赖下游 Job 默认值或提前各自发布；统一 Build 完成后仍由 Full Job 按固定顺序发布。人工维护窗口才选择 `pause-after-stdb`，且必须配置 `STDB_API_ROLLOUT_APPROVERS`。上文“定时构建缺少审批人时失败”的旧口径不再作为当前 dev 定时发布行为。
+
+Full Job 通过 `EXIT_MAINTENANCE_MODE_AFTER_COMPLETION` 明确选择完整发布成功后是否退出维护，默认勾选以保持历史行为。Full 对 Stdb Publish 和 API Deploy 两个下游阶段都固定传 `KEEP_MAINTENANCE_MODE=true`，让 maintenance marker 持续覆盖 Stdb → API → Web 整段发布；Web Deploy 成功后才进入独立 `Exit Maintenance` 阶段。取消勾选时跳过最终退出阶段，便于内网验收完成后人工恢复公网。`Genarrative-Api-Deploy` 也单独暴露 `KEEP_MAINTENANCE_MODE` 参数，并转换为随发布包脚本的 `--keep-maintenance-mode`；失败路径仍按既有 current 切换边界保留或退出维护，不受成功态选项覆盖。
+
 需要验证“更新 API 不停 worker”和“worker 是否持续消费队列”时，优先使用隔离容器 smoke：`npm run container:worker-smoke -- smoke`。该脚本生成 gitignored 的 `deploy/container/worker-smoke/api-server.env`，启动独立 compose project 与独立 SpacetimeDB，发布当前 `spacetime-module` 后写入 `worker_smoke_unsupported` 测试 job；预期 worker claim 后执行 unsupported 失败分支，再执行 API-only recreate 并确认 worker 容器 ID 不变，最后再次入队验证 API 更新后队列仍可消费。`external_generation_job` 是 private table，脚本通过 worker 日志确认 job_id 被消费，不用 CLI SQL 查询私表。该 smoke 不读取 `.env.local`，也不依赖真实 VectorEngine / OSS 密钥；真实生图链路联调再在本地私有 env 中补齐 provider 配置。worker-smoke 默认把本机 `spacetime` CLI 打成轻量 SpacetimeDB 镜像，避免本机首次 smoke 依赖官方大镜像下载。若容器内 Cargo 拉取 crates.io 依赖不稳定，可用 `npm run container:worker-smoke -- smoke --local-binary` 让容器内 Cargo 复用本机 Cargo 缓存构建当前二进制，再打入 Debian bookworm smoke runtime 临时镜像；可用 `GENARRATIVE_WORKER_SMOKE_LOCAL_BASE_IMAGE` 覆盖运行时基础镜像；若隔离端口或库数据需要重建，追加 `--force`。完成 queue 链路验证时，还要用队列概览 BFF 和单 job 状态接口确认 job 从 queued/running 收敛，并用对应玩法 session/detail 接口确认业务状态同步完成。

 本地只做账号/UI smoke 且需要短信登录时，`SMS_AUTH_PROVIDER` 应显式设为 `mock`，并把 `SMS_AUTH_MOCK_VERIFY_CODE` 设为固定值（当前常用 `123456`），再重启 `npm run dev` 或 `npm run dev:api-server`。如果 `.env.local` 还保留 `SMS_AUTH_PROVIDER=aliyun`，`POST /api/auth/phone/login` 用 mock 验证码会稳定报“验证码错误”，不是前端表单问题。真实短信联调再切回 `aliyun` 并重启。

 微信小程序虚拟支付使用 `WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_OFFER_ID`、`WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_APP_KEY`、`WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_SANDBOX_APP_KEY` 和 `WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_ENV` 配置。小程序充值统一走 `wechat_mp_virtual` / `wx.requestVirtualPayment`：泥点属于代币（`coin`），`buyQuantity` 按当前充值商品快照里的 `points_amount` 传；会员和后台新增道具类商品走 `short_series_goods`，`productId` 对应微信后台道具 ID。旧登录快照若缺 `session_key`，需要用户在小程序内重新登录后再支付；客户端成功回调不是最终到账，仍以后端通知或查询确认订单为准。详细口径见 `docs/【技术方案】微信虚拟支付接入-2026-05-26.md`。

-普通微信充值订单本地有效期为 5 分钟。SpacetimeDB 原生 `profile_recharge_order_expiration_timer` 到点后只把仍为 `pending` 的订单改为 `expired`；HTTP `api-server` 通过订阅 `profile_recharge_order` 的 `Pending -> Expired` 更新执行微信查单补偿。`external-generation-worker` 和 `external-generation-controller` 不运行充值过期逻辑，也不应因为扩容外部生成 worker 放大微信查单或关单流量。查账时本地未支付终态保持 `expired`，不再改写为 `closed`；`expiration_checked_at`、`expiration_provider_state`、`expiration_last_error` 用于判断 HTTP 监听器是否已经完成补偿。
+普通微信充值订单本地有效期为 5 分钟。SpacetimeDB 原生 `profile_recharge_order_expiration_timer` 到点后只把仍为 `pending` 的订单改为 `expired`；HTTP `api-server` 只订阅活跃 timer 表的删除事件，按事件中的 `order_id` 重新读取订单并仅对 `expired` 执行微信查单补偿，不订阅完整充值订单历史表。支付或主动关闭也会删除 timer，但读取到非 `expired` 后直接忽略；监听断线窗口由未检查过期订单 catch-up 补齐。`external-generation-worker` 和 `external-generation-controller` 不运行充值过期逻辑，也不应因为扩容外部生成 worker 放大微信查单或关单流量。查账时本地未支付终态保持 `expired`，不再改写为 `closed`；`expiration_checked_at`、`expiration_provider_state`、`expiration_last_error` 用于判断 HTTP 监听器是否已经完成补偿。

 微信小程序订阅消息生成结果通知使用 `WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_ENABLED`、`WECHAT_MINIPROGRAM_GENERATION_RESULT_TEMPLATE_ID` 和 `WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_STATE` 配置。当前模板为 `AI创作生成结果通知`；H5 在生成动作发起前先进入生成进度态并立即继续生成动作，同时非阻塞跳转到小程序原生订阅授权页尝试请求授权，用户接受、拒绝或返回都不能阻塞生成，且原生页不改写上一页 `webViewUrl`，避免返回后丢失 H5 当前进度页状态。后端只在玩法草稿生成成功或失败终态后用微信登录保存的 openid 调用 `subscribeMessage.send`，发送失败只打 warning，不影响生成主链路。模板 `thing1` 字段发送玩法模板名，例如 `拼图`、`敲木鱼`、`抓大鹅`；`number6` 字段发送本次生成结算后的实际泥点扣除，失败退款后固定为 `0`。模板 `time4` 字段固定发送北京时间 `YYYY-MM-DD HH:mm`，不要使用内部微秒时间戳、秒级时间戳或带时区后缀的 RFC3339 字符串，否则微信会返回 `argument invalid! data.time4.value invalid`。当前已接入拼图、敲木鱼、抓大鹅、跳一跳、方洞、视觉小说的草稿生成终态；分槽素材生成或发布动作不得直接复用生成结果通知，避免一次作品生成产生多条订阅消息。

@@ -89,7 +95,7 @@ spacetime sql <database> "SELECT * FROM puzzle_gallery_card_view LIMIT 1" --serv

 本地 `npm run dev:spacetime` 发布模块时必须显式忽略仓库根目录的 `spacetime.json`，由脚本固定追加 `--no-config` 并使用命令参数里传入的数据库名和 `--server http://127.0.0.1:3101`。否则 CLI 可能把发布目标改写到配置文件里的其他数据库，导致 `dev:spacetime` 启动后又因发布失败自动退出，浏览器随后会在 `ws://127.0.0.1:3101/v1/database/.../subscribe` 看到连接拒绝。

-本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致；当前统一版本为 `2.5.0`。若版本错配，procedure 返回值可能在宿主侧触发 `Failed to BSATN deserialize procedure return value`，api-server 最终表现为敲木鱼等创作动作的 `SpacetimeDB procedure 调用超时`。排障时先运行 `spacetime --version`，再对照 `server-rs/Cargo.toml` 的 `spacetimedb = "..."`；遇到版本不匹配时不要继续深挖业务超时，直接执行 `spacetime version install <version> && spacetime version use <version>`，或在目标就是最新版本时执行 `spacetime version upgrade`，升级后重启 `npm run dev:spacetime` 再重试。当前 `scripts/dev.mjs` 会在启动和复用本地 SpacetimeDB 前写入并校验 `dev-spacetime-tool-version`，避免把旧 standalone 继续带进新一轮创作。
+本地 `spacetime` CLI / standalone 版本必须和 `server-rs/Cargo.toml` 里锁定的 `spacetimedb` 版本一致；当前统一版本为 `2.6.0`。若版本错配，procedure 返回值可能在宿主侧触发 `Failed to BSATN deserialize procedure return value`，api-server 最终表现为敲木鱼等创作动作的 `SpacetimeDB procedure 调用超时`。排障时先运行 `spacetime --version`，再对照 `server-rs/Cargo.toml` 的 `spacetimedb = "..."`；遇到版本不匹配时不要继续深挖业务超时，直接执行 `spacetime version install <version> && spacetime version use <version>`，或在目标就是最新版本时执行 `spacetime version upgrade`，升级后重启 `npm run dev:spacetime` 再重试。当前 `scripts/dev.mjs` 会在启动和复用本地 SpacetimeDB 前写入并校验 `dev-spacetime-tool-version`，避免把旧 standalone 继续带进新一轮创作。

 本地 `.env`、`.env.local` 或 `.env.secrets.local` 修改后必须重启 `api-server` 才会生效；若已经通过 `npm run dev` 启动完整联调，可在该终端输入 `rs api-server`。排查 RPG / 拼图 / 抓大鹅等 VectorEngine 生图链路时，确认 `VECTOR_ENGINE_BASE_URL`、`VECTOR_ENGINE_API_KEY` 和 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 只在本地或服务器密钥文件中配置，不能写入 Git。VectorEngine `gpt-image-2` 图片协议、URL / base64 响应解析、远端图片下载和 provider 侧结构化日志在 `server-rs/crates/platform-image`；`api-server` 只做配置、玩法编排、OSS / asset 持久化、计费和失败审计落库。开局 CG 故事板、首图、背景和图集都属于长耗时图片请求；后端默认会把 `VECTOR_ENGINE_IMAGE_REQUEST_TIMEOUT_MS` 下限收口到 `1000000`，旧进程仍可能沿用重启前的短超时。若 VectorEngine 在 `send()` 阶段失败且日志显示 `SendRequest`，先看同一 `request_id` 的 provider 日志字段 `source`、`source_chain`、`source_chain_depth`，再查 `external_api_call_failure.metadata_json.errorSource`；当前 multipart `/v1/images/edits` 单独强制 HTTP/1.1。拼图关卡资产按 `level_scene -> ui_spritesheet -> level_background` 顺序生成，日志会带 `slot`、`asset_kind` 和 `elapsed_ms`。

@@ -241,7 +247,7 @@ UI 相关修改要重点验证：
 npm run database:backup:oss -- --data-dir /stdb --stop-service spacetimedb.service --restart-service-after genarrative-api.service --restart-service-after genarrative-external-generation-worker@1.service --restart-service-after genarrative-external-generation-controller.service
 ```

-脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS；因 `genarrative-api.service`、`genarrative-external-generation-worker@*.service` 和 `genarrative-external-generation-controller.service` 都依赖 `spacetimedb.service`，生产定时冷备份还必须传入对应的 `--restart-service-after`，确保备份后 API、保底 worker 和 controller 随数据库一起恢复。`2026-06-10` release 故障就是现场 unit 漏掉 API 重启参数，`03:20` 冷备份停止 SpacetimeDB 后 API 被依赖关系一并停止，备份脚本只恢复了 SpacetimeDB，API 直到人工重启前都不可用；`2026-06-24` release 又出现同类依赖停机后只恢复 API、未恢复外部生成 worker/controller，导致图片画布生成任务长期停留在队列中。后续现场变更、provision 模板和 Jenkins 归档都必须通过 `npm run check:production-ops` 防止回退。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用后台 `node -- ... --upload-archive <tar.gz>` 上传同一份发布前备份，不等待上传完成。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。
+脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS；因 `genarrative-api.service`、`genarrative-external-generation-worker@*.service` 和 `genarrative-external-generation-controller.service` 都依赖 `spacetimedb.service`，生产定时冷备份还必须传入对应的 `--restart-service-after`，确保备份后 API、保底 worker 和 controller 随数据库一起恢复。`2026-06-10` release 故障就是现场 unit 漏掉 API 重启参数，`03:20` 冷备份停止 SpacetimeDB 后 API 被依赖关系一并停止，备份脚本只恢复了 SpacetimeDB，API 直到人工重启前都不可用；`2026-06-24` release 又出现同类依赖停机后只恢复 API、未恢复外部生成 worker/controller，导致图片画布生成任务长期停留在队列中。后续现场变更、provision 模板和 Jenkins 归档都必须通过 `npm run check:production-ops` 防止回退。由于 OSS 上传可能受服务器带宽限制，`Genarrative-Stdb-Module-Publish` 默认使用 `DATABASE_BACKUP_MODE=async`：先在 publish 前用 `--defer-upload` 生成本地冷备份和 `.manifest.json`，随后继续执行 publish；发布脚本退出前会用后台 `node -- ... --upload-archive <tar.gz>` 上传同一份发布前备份，不等待上传完成。`Genarrative-Full-Build-And-Deploy` 必须显式暴露并透传同一个 `DATABASE_BACKUP_MODE`，不得静默使用下游 `async`；release 已有验真冷备且明确禁止再上传时，Full 必须选择 `skip`。发布脚本在校验 wasm 后、执行 `spacetime publish` 前会等待显式 `SPACETIME_SERVER_URL` 的 `/v1/ping` 就绪，默认最多等待 `60` 秒；如生产机器冷备份恢复 `spacetimedb.service` 较慢，可临时设置 `GENARRATIVE_STDB_PUBLISH_READY_TIMEOUT_SECONDS` 调整等待时间。需要强一致发布闸门时改用 `DATABASE_BACKUP_MODE=sync`（等价脚本参数 `--backup-mode sync`），备份会在 publish 前同步打包并上传，失败会阻断 publish；确认已有其他备份窗口时才使用 `DATABASE_BACKUP_MODE=skip`（兼容脚本参数 `--skip-backup`）。若业务不能接受停机窗口，应先规划 SpacetimeDB 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。

 生产环境变量模板在 `deploy/env/api-server.env.example`：

@@ -389,12 +395,24 @@ Pingora current release 自审脚本 `scripts/ops/pingora-current-release-audit.

 `Genarrative-Stdb-Module-Build` 的 Jenkins 归档产物必须包含 `build/<version>/spacetime_module.wasm`、`spacetime_module.wasm.sha256`、`release-manifest.json`、`scripts/deploy/production-stdb-publish.sh`、`scripts/deploy/production-runtime-writer-identity-rotate.mjs`、`scripts/deploy/maintenance-on.sh`、`scripts/deploy/maintenance-off.sh`、`scripts/spacetime-migration-common.mjs` 和 `scripts/database-backup-to-oss.mjs`，不得包含 `migration-bootstrap-secret.txt` 或任何原始 bootstrap secret。`Genarrative-Stdb-Module-Build` 只接受 `MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID` 指向的受保护 Jenkins Secret File：构建 shell 从临时文件读取原始值，强制校验为 64 位十六进制，计算 SHA-256，随后只通过 `GENARRATIVE_SPACETIME_MIGRATION_BOOTSTRAP_SECRET_SHA256` 注入 Rust 编译；WASM 因而只包含摘要，不包含可下载的原文，Stdb `release-manifest.json` 以 `migration_bootstrap_secret_sha256` 记录该非敏感摘要。`Genarrative-Stdb-Module-Publish` 只通过 `copyArtifacts` 复制上述非敏感产物，不在目标机器 checkout Git，并在发布阶段用同一个凭据 ID 再次挂载 Secret File；publish 必须再次校验 64 位十六进制、重算 SHA-256，并与 manifest 的 `migration_bootstrap_secret_sha256` 强制匹配后才可发布。Full Build 必须保证 Stdb Build / Publish 的 `MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID` 完全相同并把同一个 ID 同时透传，不能从构建 artifact 传 secret；ID 不同、manifest 缺摘要或摘要不匹配都必须在发布前失败。

+三个 SCM Jenkinsfile 将 `MIGRATION_BOOTSTRAP_SECRET_CREDENTIAL_ID` 默认固定为 `genarrative-spacetime-bootstrap-secret-dev-file`。Secret File 的原文只存在于 Jenkins Credentials；credential ID、参数默认值和定时 / 发布行为以仓库 Jenkinsfile 为事实源，不能只改 Job UI，因为 Declarative Pipeline 下一次载入会重写参数定义。旧 Secret Text `genarrative-spacetime-bootstrap-secret-dev` 继续保留给 Database Import / Export，不得原地改类型或删除。
+
+生产 Stdb publish 固定传 `--delete-data=never --yes=migrate,break-clients`，普通 Stdb Jenkins Job 不提供 `CLEAR_DATABASE`；任何需要删除数据的迁移都必须失败并重新核对 schema 与 artifact，不能在发布路径内切换清库继续。
+
 生产运行时不把 bootstrap secret 明文写进 `/etc/genarrative/*.env`。`api-server.env` 和 worker env 只登记固定 FILE 路径 `GENARRATIVE_SPACETIME_RUNTIME_SERVICE_BOOTSTRAP_SECRET_FILE=/var/lib/genarrative/spacetime/runtime-service-bootstrap-secret.txt`；若检测到明文 `GENARRATIVE_SPACETIME_RUNTIME_SERVICE_BOOTSTRAP_SECRET` 或其他 FILE 路径，Server-Provision / API deploy 必须失败。Full Build 先执行 Stdb publish、后执行 API deploy，因此两段必须透传同一 `API_ENV_FILE` / `WORKER_ENV_FILE`；Stdb Publish 把 Secret File 路径作为 `--migration-bootstrap-secret-file` 传给随包 `production-stdb-publish.sh`。脚本先进入维护模式、按所选模式完成发布前冷备份、校验 checksum 并发布 module；成功后拒绝符号链接目标，把 secret 安装成 `root:genarrative 0440`、目录收紧为 `root:genarrative 0750`，原子补齐 API / worker env 的固定 FILE 配置，再快照并重启发布前为 active 的 API、controller 和 worker。`systemctl is-active` 只有明确返回合法的非 active 状态时才允许跳过，查询错误或 active worker 的 `list-units` 失败都必须保留维护模式并阻断；所有原 active 服务重启后必须重新确认为 `active`。如果 API 原本 active，还必须在 `maintenance-off` 前通过本机 `http://127.0.0.1:8082/healthz` readiness；可用 `--api-health-url` / `GENARRATIVE_STDB_PUBLISH_API_HEALTH_URL` 调整本机 URL，并用 `--api-readiness-timeout-seconds` / `GENARRATIVE_STDB_PUBLISH_API_READINESS_TIMEOUT_SECONDS` 调整超时。这样旧服务器首次 rollout 也不会等到后续 API deploy 才拿到 FILE；只覆盖 secret 文件或只补 env 而不重启都不生效，因为 `AppConfig` 在进程启动时读取 secret。人工执行 `npm run build:production-release -- --component spacetime-module --name <version>` 且未显式提供 secret / SHA-256 时，原始随机 secret 只写入 gitignored 的 `server-rs/.spacetimedb/build-secrets/<version>.txt`，目录权限 `0700`、文件权限 `0600`，发布包和 `release-manifest.json` 都不收录它；必须把该受保护文件另行交给 publish 阶段。旧 `npm run deploy:rust:remote` Ubuntu 直传入口也使用同一 sidecar 目录，发布包内不含原文；上传模式通过独立 SSH 标准输入把 secret 原子安装到远端发布目录并收紧为 `0600`，`--skip-upload` 时必须单独受保护交付。 本地 dev 的原始值也只能进入 api-server，不得扩散给 Web / Vite，任何控制台、Jenkins 日志、归档或生成 README 都不得输出明文。相关变更至少运行 `bash -n scripts/deploy/production-stdb-publish.sh scripts/deploy/production-api-deploy.sh scripts/deploy-rust-remote.sh scripts/jenkins-server-provision.sh`、`node --check scripts/dev.mjs scripts/check-production-ops-guardrails.mjs`、`npm run check:production-ops`、`npm run check:encoding` 和 `git diff --check`。

-生产 runtime writer 不能通过替换 bootstrap secret 或重启服务隐式轮换。migration operator 与 runtime writer 必须身份互斥：operator 不能成为 writer，当前 writer 不能授权为 operator；已有任一 operator 后，bootstrap secret 不得新增或接管 operator。先准备新 api-server identity，并使用当前已授权 migration operator 的 CLI 登录态执行 `node scripts/deploy/production-runtime-writer-identity-rotate.mjs --database <database> --server-url <url> --operator-identity <operatorIdentity> --operator-user-id <userId> --next-writer-identity <nextIdentity> --confirm-next-writer-identity <nextIdentity> --note <reason>`。CLI 会校验当前登录 identity、双录新 identity 和审计原因；模块 procedure 还会拒绝把 writer 设为任一已登记 migration operator。成功后必须核对 `editor_generation_runtime_identity_rotation` 的旧 writer、新 writer、operator identity、操作人、原因和服务端时间，再切换 API token；轮换只改 writer，不改模型价格。
+生产 runtime writer 不能通过替换 bootstrap secret 或重启服务隐式轮换。migration operator 与 runtime writer 必须身份互斥：operator 不能成为 writer，当前 writer 不能授权为 operator；已有任一 operator 后，bootstrap secret 不得新增或接管 operator。先准备新 api-server identity，并使用当前已授权 migration operator 的 CLI 登录态执行 `node scripts/deploy/production-runtime-writer-identity-rotate.mjs --database <database> --server-url <url> --operator-identity <operatorIdentity> --operator-user-id <userId> --next-writer-identity <nextIdentity> --confirm-next-writer-identity <nextIdentity> --note <reason>`。CLI 会校验当前登录 identity、双录新 identity 和审计原因；模块 procedure 还会拒绝把 writer 设为任一已登记 migration operator。成功后必须核对 `editor_generation_runtime_identity_rotation` 的旧 writer、新 writer、operator identity、操作人、原因和服务端时间，再切换 API token；轮换只改 writer，不改模型价格。`pause-after-stdb` 人工维护不得把 `api-server.env` 的 `GENARRATIVE_SPACETIME_TOKEN` identity 授权为 migration operator；首次初始化前数据库还没有 writer 记录，模块无法提前识别这枚 identity 的未来用途，误授权会让 API 启动持续报“数据库迁移操作员 identity 不能初始化为模型生成运行时服务 identity”。若已误授权，必须在维护完成后由该 identity 自撤 migration operator 权限，再确认 rollout gate。API deploy 的本机 readiness 探测每次请求固定 `--max-time 2`，即使端口已建立但 API 尚未响应也会回到有限重试，不得使用无超时 curl。

 `Genarrative-Web-Build` 打包 `web.tar.gz` 前、`Genarrative-Web-Deploy` 解包后都会把 Web 静态目录规范为目录 `755`、文件 `644`。如果前端页面能打开但 public 图片、字体或音频返回 `403 Forbidden`，优先检查当前 `/srv/genarrative/web` 指向的 release 中对应文件权限是否被异常归档为 `600`，临时恢复可对该 release 的 `web` 目录执行目录 `755`、文件 `644` 的权限修正。

+## 维护模式只拦截公网流量
+
+Nginx 与 Pingora 在维护 marker 存在时对内网来源绕过整站维护闸，主站页面与静态资源、普通 API、后台页面与 `/admin/api/**`、SpacetimeDB 路由均按非维护状态继续处理；公网应用主站、普通 API、后台和 SpacetimeDB 路由继续返回维护响应。内网范围为 IPv4 loopback / RFC1918 / link-local 和 IPv6 loopback / ULA / link-local。Nginx 只按 TCP `$remote_addr` 判定；Pingora 只按 TCP peer 判定，peer 为 loopback 的同机 Nginx 时才读取 Nginx 强制覆盖的 `X-Real-IP`，绝不能把客户端可伪造的 `X-Forwarded-For` 用作维护放行依据。应用本身的登录、管理员鉴权和其它业务鉴权不变。
+
+该规则只绕过网关维护响应，不会自动拉起 api-server、SpacetimeDB 或其它已停止的服务。人工执行 `maintenance-on.sh` 且后端仍运行时，可以从内网继续访问整站和修改后台数据；`pause-after-stdb` 会停止旧 API/controller/worker，在 API 被停期间静态页面可能仍可加载，但普通 API 与 `/admin/api/**` 仍不可用。验证使用 `npm run check:nginx-spa-routes`、`npm run check:pingora-route-parity`、`cargo test -p pingora-gateway --manifest-path server-rs/Cargo.toml`、`npm run check:pingora-gateway-smoke` 和 `npm run check:production-ops`，不要在 live 机器上为测试临时创建维护 marker。
+
+维护页源码固定为 `public/maintenance.html`，正常 Web 构建由 Vite 复制到发布包根目录的 `web/maintenance.html`。计划内停服需要临时更新公告时，先更新该源码，避免后续 Web Deploy 把现场公告覆盖回旧内容；现场紧急替换必须原子写入当前 `/srv/genarrative/web/maintenance.html`，并同时用 `genarrative.world` 与 `www.genarrative.world` 的真实 HTTPS 响应校验 `503` 和公告正文。
+
 生产 Jenkins 的 `Pipeline script from SCM` 由 Jenkins controller 读取 Jenkinsfile。`Genarrative-Server-Provision` 是服务器初始化流水线，Job 配置里的 SCM URL 必须使用 controller 本机可访问的仓库路径或内网 Gitea 地址，不能使用 `https://git.genarrative.world/...`；否则日志一开始的 `Checking out git ... to read jenkins/Jenkinsfile.production-server-provision` 就会先从公网拉 Jenkinsfile。构建类流水线和 `Genarrative-Server-Provision` 的 Jenkinsfile 内部源码准备阶段统一使用 `ssh://git@192.168.35.82:2222/GenarrativeAI/Genarrative.git`，并显式传入 Jenkins SSH 凭据 `genarrative-local-gitea-ssh`；不再配置 `https://git.genarrative.world/...` 公网 fallback，也不再默认使用 `https://git.genarrative.world/git/GenarrativeAI/Genarrative.git`。所有 `GitSCM checkout` 都必须保留单分支 refspec、`shallow=true`、`depth=1`、`noTags=true` 与 `honorRefspec=true`。API / Web / Stdb 发布类流水线不在目标机器 checkout Git，统一执行上游构建归档里的部署脚本，避免产物 commit 与部署脚本 commit 漂移；Server-Provision 也不在目标 dev / release agent checkout Git，而是由 Jenkins 构建节点先准备 provision 脚本与配置并上传给目标 agent。

 当前 Jenkins / 本机内网 Git 入口固定为 `ssh://git@192.168.35.82:2222/GenarrativeAI/Genarrative.git`，用于 controller、构建节点和本机 Agent 直接拉取仓库，避免绕公网 `git.genarrative.world`。验证时在具备对应 SSH key 和 known_hosts 的环境执行 `git ls-remote ssh://git@192.168.35.82:2222/GenarrativeAI/Genarrative.git HEAD`，应能返回 HEAD。若机器仍保留旧的 `https://git.genarrative.world/git/GenarrativeAI/Genarrative.git` 或 `http://10.2.0.10/GenarrativeAI/Genarrative.git` 内网入口，只作为历史兼容和排障参考，新流水线不再默认使用。
@@ -424,7 +442,7 @@ worker 被硬杀或断电后，lease 过期任务只有尚未耗尽 `max_attempt
 - `api-server` 正常运行时 `/healthz` 只返回进程存活状态，`/readyz` 会同时检查进程是否仍接收新流量和 SpacetimeDB 连接租约是否健康；收到 `SIGINT` / `SIGTERM` 后会先把 readiness 标记为不可用，再让 Axum 停止接新连接并等待已有 HTTP 请求排空。systemd 仍以 `KillSignal=SIGINT` 停服务，`TimeoutStopSec=90` 作为长请求排空上限。
 - SpacetimeDB 健康检查默认使用 `GENARRATIVE_SPACETIME_HEALTH_CHECK_TIMEOUT_SECONDS=2` 的短等待窗口，和业务 procedure 的 `GENARRATIVE_SPACETIME_PROCEDURE_TIMEOUT_SECONDS` 分开。`/readyz` 失败时 `details.spacetime.stage` 会标出当前卡住阶段：`pool_acquire`、`connect_build`、`connect_handshake`、`read_model_subscribe`、`procedure_result`、`reducer_result` 或 `read_cache`；`elapsedMs` / `timeoutMs` 用于确认是否命中健康检查窗口。业务请求日志也会写入 `operation_kind`、`operation_name`、`spacetime_stage` 和 `elapsed_ms`，后续 45 秒超时不再只靠 Nginx `request_time=45s` 推断。
 - `genarrative-api.service` 设置 `LimitNOFILE=65535`、`TasksMax=2048`；上线后用 `systemctl show genarrative-api.service -p LimitNOFILE -p TasksMax -p TimeoutStopUSec` 和 `cat /proc/$(pidof api-server)/limits` 核对。
- Server provision 不再通过 Windows helper 下载，也不再通过 Linux build 节点中转 SpacetimeDB / otelcol 工具包；Linux build 节点只负责从内网 Git 源准备 provision 脚本和配置并上传给目标 agent。`Prepare Provision Tools` 在目标 dev / release agent 工作区内先检查 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current`：版本已满足时直接复用目标机现有文件生成 `provision-tools/`，只有缺失或版本不匹配时才使用 `PROVISION_DOWNLOADS_DIR` 里的本地包或从配置的下载源准备 SpacetimeDB `2.5.0` / `otelcol-contrib 0.151.0`；如果目标服务器下载需要代理，在 `PROVISION_DOWNLOAD_PROXY` 配置目标机可访问的 HTTP 代理。
+- Server provision 不再通过 Windows helper 下载，也不再通过 Linux build 节点中转 SpacetimeDB / otelcol 工具包；Linux build 节点只负责从内网 Git 源准备 provision 脚本和配置并上传给目标 agent。`Prepare Provision Tools` 在目标 dev / release agent 工作区内先检查 `/usr/local/bin/otelcol-contrib` 与 `${SPACETIME_ROOT}/bin/current`：版本已满足时直接复用目标机现有文件生成 `provision-tools/`，只有缺失或版本不匹配时才使用 `PROVISION_DOWNLOADS_DIR` 里的本地包或从配置的下载源准备 SpacetimeDB `2.6.0` / `otelcol-contrib 0.151.0`；如果目标服务器下载需要代理，在 `PROVISION_DOWNLOAD_PROXY` 配置目标机可访问的 HTTP 代理。
 - 除 `Genarrative-Server-Provision` 外，`Genarrative-Stdb-Module-Build`、`Genarrative-Web-Build`、`Genarrative-Api-Build`、`Genarrative-*Deploy`、`Genarrative-Database-Import/Export`、`Genarrative-Full-Build-And-Deploy` 和 `Genarrative-Notify-Email` 的生产流水线现都以 Linux agent 为主，仍按各自 Jenkinsfile 的 checkout 口径执行。Server provision 不使用公网备用 Git 源，目标部署 agent 也不再需要访问源码 Git remote。
 - `otelcol-contrib.service` 作为可选系统服务加入 provision，默认监听 `127.0.0.1:4317/4318` 并使用 `deploy/otelcol/genarrative-debug.yaml`。api-server 是否发送 OTLP 仍由 `GENARRATIVE_OTEL_ENABLED` 控制，服务 unit 见 `deploy/systemd/otelcol-contrib.service`。该服务必须存在系统用户 / 组 `otelcol`，并且 `/etc/otelcol/genarrative-debug.yaml` 已安装到目标机；若看到 `status=217/USER` 或 `Failed to determine user credentials`，优先检查 `getent passwd otelcol`，再补齐 `/etc/otelcol` 配置目录并重启服务。
 - Nginx `/api/` 与 `/admin/api/` 通过 `genarrative_api` upstream 代理到 `127.0.0.1:8082`，upstream keepalive 为 64；`limit_conn` 负责连接 / 并发保护，`limit_req` 负责入口 RPS 快拒绝。当前模板把公开 gallery list 单独放到 `genarrative_gallery_rps`，默认 `rate=5000r/s`、`burst=4096`、`limit_conn=320`；公开详情和普通 API 放到 `genarrative_api_rps`，后台 API 放到 `genarrative_admin_rps`。通用 `/api` location 设置 `client_max_body_size 64m` 是反代兜底，防止拼图入口页 / 新增关卡本地参考图 Data URL 或旧兼容请求在到达 `api-server` 前被默认 1 MiB 上限拦截；拼图本地参考图前后端统一限制 6MB，历史图片仍提交 `referenceImageAssetObjectId(s)`。若线上出现 `413 Request Entity Too Large` 且 access log 中 `request_time=0.000`、`upstream_status=-`，说明请求在 Nginx 层被拦截，先用 `nginx -T | grep client_max_body_size` 检查 release 模板是否已渲染并 reload，同时检查前端是否超出 6MB 或错误提交了未压缩大图。`limit_conn_status 429` 和 `limit_req_status 429` 必须在 HTTP 与 HTTPS server 中同时生效；若线上压测看到 `limiting connections by zone "genarrative_api_conn"` 却返回 503，优先检查 `nginx -T` 里 HTTPS server 是否缺少这些状态码，以及 `/api/runtime/puzzle/gallery` 是否误落到通用 `location ~ ^/api` 的 `limit_conn=64`。压测时看 `/var/log/nginx/genarrative.access.log` 中的 `request_time`、`upstream_connect_time`、`upstream_header_time`、`upstream_response_time`、`upstream_status`、`request_id`。
@@ -609,6 +627,8 @@ SELECT * FROM profile_recharge_product_config ORDER BY sort_order ASC;

 后台通用表查询已经处理 SpacetimeDB 无载荷枚举的 SATS 形态。新增后台表展示时，枚举列优先按表名和列名做业务映射，再落回通用解码。

+后台通用表查询的“每页条数”不是筛选前的 SQL 截断量。API Server 通过单次 `SELECT * ... LIMIT 50001` 读取哨兵行，最多保留前 50,000 条候选；关键词 / JSON 过滤、所选列的完整候选集稳定排序和 1-based `page` 分页都基于这一次 SQL 结果，`totalMatched` 不再依赖另一份 `COUNT(*)` 快照。请求页码超过实际总页数时钳制到末页，零结果固定返回第 1 页。存在第 50,001 条哨兵行时响应必须返回 `scanLimitReached=true`，后台固定分页栏上方明确提示匹配总数和分页结果可能不完整，不得把扫描范围外的数据误报为不存在。候选 SQL 响应体仍受 32 MiB 和 20 秒硬限制；宽表即使每页条数很小也可能整次拒绝，不会返回部分结果。实时写入仍可能改变相邻请求的候选快照，精确审计应使用对应业务表的专用查询而不是通用浏览页。
+
 ## Issue 与交接

 - Issue tracker：自托管 Gitea。
@@ -8,7 +8,7 @@
 - 会员商品在微信小程序 WebView 内同样走 `wechat_mp_virtual`，由小程序页调用 `wx.requestVirtualPayment` 的 `short_series_goods` 模式，并在 `signData` 内带 `productId` 与 `goodsPrice`。
 - 微信内浏览器走 `wechat_jsapi`，复用微信支付 V3 JSAPI 下单返回的预支付参数并通过 `WeixinJSBridge.invoke('getBrandWCPayRequest')` 调起支付；普通 Web 统一走 `wechat_native` 二维码支付，不进入虚拟支付链路，也不依赖 H5 产品权限。`wechat_h5` 仅作为未来 H5 产品权限明确开通后的保留渠道。
 - `session_key` 只保存在后端认证仓储内，用于计算虚拟支付用户态签名，不下发给前端。
- 客户端支付成功回调只代表已拉起支付并返回成功；最终到账仍以后端虚拟支付消息推送写入订单为准，普通微信支付订单则继续走微信支付 V3 notify / query。虚拟支付订单的确认接口只读取本地订单真相，不再用普通微信支付 V3 查单。
+- 客户端支付成功回调只代表已拉起支付并返回成功；最终到账以后端虚拟支付消息推送或官方 `/xpay/query_order` 查单结果为准，普通微信支付订单则继续走微信支付 V3 notify / query。虚拟支付不得误用普通微信支付 V3 查单。
 - 小程序 WebView 普通进入不预登录；H5 触发受保护入口或支付前必须保留 `clientRuntime=wechat_mini_program` 等宿主上下文，并用 `MicroMessenger + miniProgram` User-Agent 兜底识别首点 bridge 未就绪场景，再跳转小程序原生授权态，确保后端拿到带 `session_key` 的微信登录态。

 ## 关键文件
@@ -34,6 +34,8 @@ WECHAT_PAY_PROVIDER=real
 WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_OFFER_ID=<微信虚拟支付 offerId>
 WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_APP_KEY=<现网 AppKey>
 WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_SANDBOX_APP_KEY=<沙箱 AppKey，可选>
+WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_QUERY_ORDER_ENDPOINT=https://api.weixin.qq.com/xpay/query_order
+WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_NOTIFY_PROVIDE_GOODS_ENDPOINT=https://api.weixin.qq.com/xpay/notify_provide_goods
 WECHAT_MINIPROGRAM_MESSAGE_TOKEN=<微信消息推送 Token>
 WECHAT_MINIPROGRAM_MESSAGE_ENCODING_AES_KEY=<微信消息推送 EncodingAESKey>
 WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_ENABLED=true
@@ -47,6 +49,11 @@ WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_ENV=0
 - `signData`：传给 `wx.requestVirtualPayment` 的订单数据。
 - `paySig`：`HMAC-SHA256(appKey, "requestVirtualPayment&" + signData)` 的小写 hex。
 - `signature`：`HMAC-SHA256(session_key, signData)` 的小写 hex。
+- 服务端虚拟支付查单使用 `POST https://api.weixin.qq.com/xpay/query_order`：请求体固定携带 `openid`、`env` 和 `order_id`，查询参数携带小程序 `access_token` 与 `pay_sig`。`pay_sig` 按官方算法计算为 `HMAC-SHA256(appKey, "/xpay/query_order&" + 实际发送的 JSON body)` 的小写 hex；参与签名的 body 必须与 HTTP 实际发送字节一致。
+- 查单返回 `status=2/3/4` 分别表示“已支付待发货 / 发货中 / 已发货”，只有这三种状态可以补确认本地订单入账。入账前必须同时校验 `order_id`、支付类型 `order_type=0/7`、`order_fee` 与合法 `paid_time`；不得用本机当前时间伪造结算时间。`status=0/1/5..10` 只记录供应方状态，不直接发放泥点或会员权益。
+- `short_series_goods` 查单恢复到 `status=2` 时，必须先完成本地幂等入账，再调用官方 `/xpay/notify_provide_goods` 补发货确认；`status=3/4` 不重复通知。发货确认失败时，本地订单已是 `paid`，后续用户确认、到期补偿重试或历史脚本必须允许只重试发货，不得再次发放权益。`short_series_coin` 不调用该现金单发货接口。
+- `order_type` 的官方枚举是 `0=普通虚拟支付`、`1=普通退款`、`7=iOS 支付`、`8=iOS 退款`，不区分 `short_series_coin` 与 `short_series_goods`。普通和 iOS 的支付单分别使用 `0` 和 `7`；退款类型 `1/8` 绝不可触发充值入账。官方查单响应本身不提供可反查 coin / goods 的字段，不得自行发明数值映射；商品契约继续以本地订单快照和 `order_fee` 一致性作防线。
+- `WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_QUERY_ORDER_ENDPOINT` 与 `WECHAT_MINI_PROGRAM_VIRTUAL_PAYMENT_NOTIFY_PROVIDE_GOODS_ENDPOINT` 默认使用微信官方地址，仅用于测试注入 mock endpoint，生产不应覆盖。`WechatConfig` 支持注入 stable token、query order 与 notify provide goods endpoint；缓存 token 遇到 `40001/40014/42001` 时只清除本次失败 token，强制刷新并最多重放一次。
 - 泥点属于微信虚拟支付代币（coin），`short_series_coin` 的 `buyQuantity` 必须使用当前泥点商品的 `points_amount`；例如 60 泥点商品应传 `buyQuantity: 60`。
 - 会员直购 `signData` 额外包含 `productId` 和 `goodsPrice`；`goodsPrice` 使用后端商品配置价，和微信后台道具价格校验保持一致。
 - 微信小程序“开发者服务器接收消息推送”必须配置为安全模式，数据格式选 JSON，URL 统一指向 `/api/profile/recharge/wechat/virtual-notify`。
@@ -63,6 +70,36 @@ npm run typecheck
 npm run check:encoding
 ```

+## 历史订单逐单核对
+
+升级前已存在的 `wechat_mp_virtual` pending 订单没有 expiration timer，不会被到期 catch-up 自动遍历。这类订单使用受控脚本逐单处理，不得批量改状态：
+
+```bash
+# openid 只放入当次临时文件，不作为 CLI 参数或仓库文件。
+install -m 0600 /dev/null /run/genarrative-virtual-payment-openid
+
+# 第一次固定 dry-run；人工核对订单、金额、微信状态和 applyFingerprint。
+npm run spacetime:wechat-virtual-payment:reconcile -- \
+  --database genarrative-prod \
+  --server-url http://127.0.0.1:3101 \
+  --order-id <orderId> \
+  --openid-file /run/genarrative-virtual-payment-openid \
+  --env-file /etc/genarrative/api-server.env
+
+# 只有 dry-run 显示 eligibleForCredit=true 时，使用同一订单追加 --apply 和当次指纹。
+# dry-run 结束会删除 openid 临时文件；apply 前需按同样的 0600 要求重新准备该文件。
+npm run spacetime:wechat-virtual-payment:reconcile -- \
+  --database genarrative-prod \
+  --server-url http://127.0.0.1:3101 \
+  --order-id <orderId> \
+  --openid-file /run/genarrative-virtual-payment-openid \
+  --env-file /etc/genarrative/api-server.env \
+  --apply \
+  --confirm <applyFingerprint>
+```
+
+脚本每次重新读取本地订单并重新向微信查单；`--apply` 要求事实指纹与前一次 dry-run 完全一致，只对 `status=2/3/4` 且单号、金额、支付类型 `order_type=0/7` 和 `paid_time` 一致的订单调用既有 `mark_profile_recharge_order_paid_and_return`。本地已 `paid` 的 `short_series_goods` 订单仍允许重跑同一 dry-run/apply 门禁，以便对微信 `status=2` 只补发货确认。脚本使用 `/etc/genarrative/api-server.env` 内的 `GENARRATIVE_SPACETIME_TOKEN` 通过显式 `--server-url` 调用 procedure，不复用 migration operator 身份；不输出 openid、AppSecret、AppKey、access token 或 SpacetimeDB token，且 apply 默认拒绝非微信官方 endpoint。读取成功后的临时 openid 文件无论处理成功失败都会删除。
+
 ## 注意事项

 - 旧微信登录快照可能没有 `session_key`；普通进入小程序 WebView 仍允许匿名打开，虚拟支付会由后端拦截并提示用户在小程序内重新登录。H5 内部导航不得清理 `clientType`、`clientRuntime`、`miniProgramEnv`，且首点登录要用小程序 User-Agent 兜底识别，否则登录和支付会误判为普通网页环境。
@@ -74,6 +111,6 @@ npm run check:encoding
 - 微信虚拟支付消息推送使用独立后端入口 `/api/profile/recharge/wechat/virtual-notify`，按 `xpay_goods_deliver_notify` 和 `xpay_coin_pay_notify` 推进充值订单入账；回包需按入站格式返回 `ErrCode=0` / `ErrMsg=success`（JSON 入站回 JSON，XML 入站回 XML），错误时带具体 `ErrMsg` 便于微信侧重试与排障。
 - 沙箱或基础库失败会把微信返回的 `errCode` / `errMsg` 透传到前端失败弹窗，便于区分微信后台道具、沙箱 AppKey、签名和基础库能力问题。
 - Web 侧在拉起虚拟支付后会短时轮询 `wx_pay_result`，即使小程序 `web-view` 回写 hash 没触发浏览器 `hashchange`，也必须展示回写的微信错误内容。
- WebView 返回但没有拿到 `wx_pay_result` 时，前端必须主动调用订单确认接口，并接入 `/api/profile/recharge/orders/{orderId}/wechat/events` 的 SSE 事件流作为服务端推送兜底；后端收到虚拟支付消息推送并入账后会发布订单更新，SSE 先推当前订单快照，再在订单结束时推 `done`。
+- WebView 返回但没有拿到 `wx_pay_result` 时，前端必须主动调用订单确认接口，并接入 `/api/profile/recharge/orders/{orderId}/wechat/events` 的 SSE 事件流作为服务端推送兜底；虚拟支付确认接口会使用当前用户后端保存的小程序 `openid` 调用官方 `/xpay/query_order`，查到已支付且契约校验通过后写入订单。后端通过消息推送或查单入账后都会发布订单更新，SSE 先推当前订单快照，再在订单结束时推 `done`。
 - 小程序订阅消息用于 AI 创作生成结果通知：H5 在生成动作发起前先把页面切到生成进度态并立即调用生成 action，同时非阻塞跳转到小程序原生订阅授权页尝试请求授权；授权接受、拒绝或页面返回都不得阻塞或取消生成。原生页不得改写上一页 `webViewUrl`，避免返回后丢失 H5 当前进度页状态。通知发送只允许发生在玩法草稿生成成功或失败终态之后，api-server 使用当前用户微信登录保存的 openid 调用微信 `subscribeMessage.send`。发送失败只记录 warning，不阻断作品生成。模板 `thing1` 发送玩法模板名，`number6` 发送本次生成结算后的实际泥点扣除，失败退款后固定为 `0`；模板 `time4` 字段必须是北京时间 `YYYY-MM-DD HH:mm`。`WECHAT_MINIPROGRAM_SUBSCRIBE_MESSAGE_STATE` 支持 `formal` / `trial` / `developer`，应与当前发布环境一致。
 - WebView 返回后，在订单状态拉取或 SSE 等待期间展示不可关闭遮罩“正在确认支付”，阻止用户离开或继续操作；只有确认到最终订单状态后才展示一次最终结果弹窗，不能先弹“正在支付/支付已提交”再二次弹成功。
@@ -22,10 +22,12 @@

 ### 顶部品牌区

- 标题：`陶泥儿 - 开启全民精品游戏创作`
+- 小眉题：`陶泥儿 Genarrative｜游戏美术 AI 创作工具`，保持普通小字，不使用 heading 标签。
+- 唯一 H1：`陶泥儿 · 开启全民精品游戏创作`。
+- 产品说明：`面向个人创作者的游戏美术 AI 工作台。用美术 Agent 与无限画布，快速制作角色、场景、UI 与宣发素材。`，作为 H1 下方真实可见的普通正文分两行展示。
 - 主按钮：`开始创作`
 - 社群入口：原地弹出“玩家社区”二维码弹窗，复用现有社区弹层能力，不跳转或切换到“我的 / 用户中心”。
- 营销点：`登录即送100泥点，可以免费制作50个素材`
+- 营销点：`登录即送 100 泥点，可以免费制作 50 个素材`，作为产品说明下方的小字权益提示。

 `开始创作` 与“新建项目”使用同一项目创建链路。用户已登录时调用现有 `createEditorProject`，成功后进入 `/editor/canvas?projectid=xxx&guide=toolbar`，画布只消费一次 `guide=toolbar` 并清理 query，用于显示新画布工具栏引导；未登录或登录过期时打开登录弹窗，并在登录后重试创建。

@@ -33,7 +35,7 @@

 ### 九大创作工具能力

-创作主页展示九项能力，用于说明陶泥儿创作工具覆盖范围：
+分区标题使用 H2 `游戏美术 AI 创作工具`。创作主页展示九项能力，用于说明陶泥儿创作工具覆盖范围，卡片标题继续使用 H3：

 1. 游戏视觉规范：轻松约束多类素材视觉一致性。
 2. 游戏角色：整套高完成度 2D / 3D 角色素材及动画。
@@ -12,7 +12,7 @@

 旧库或旧迁移包没有 `event_banners_json` 时，后端读取层必须把 `eventBanners` 归一到 `module-runtime` 默认公告数组，不能把旧结构化 `eventBanner` 当成前端优先数组下发。默认公告引用的背景图必须指向 `public/` 下真实存在的站内静态资源，当前默认使用 `/creation-type-references/puzzle.webp`，避免创作入口顶部 banner 出现失效图片。

-创作页和草稿页顶栏右上角的泥点余额胶囊是补足泥点入口：如果当前运行环境开启充值入口，点击后直接打开账户充值弹窗；否则直接打开运营兑换码弹窗。该入口不再跳到账户面板或泥点账单，头像 / 设置等账号入口继续保留各自语义。
+创作页和草稿页顶栏右上角统一复用公共泥点资产入口，不再把余额区本身作为直接充值按钮。余额区展开后只展示不限时泥点、每日免费泥点及重置口径；会员周期限时泥点仅由后端保留用于存量兼容和结算，当前版本不在前台展示。独立“充值”按钮进入“购买更多泥点”弹窗，“使用详情”进入泥点账单。主站各位置必须保持同一组件、数据口径和交互语义，头像 / 设置等账号入口继续保留各自语义。

 创作恢复参数只保留 `sessionId`、`profileId`、`draftId`、`workId` 这四个私有 query。它们只允许在同一条创作链路的结果页、生成页、工作台之间保留；切到首页、公开作品详情、runtime 或另一条玩法链路时必须清掉。平台入口刷新直达时，路径到玩法恢复目标、四个 query 归一化、生成页标记、大鱼吃小鱼 workId 兜底、作品 / 草稿身份匹配和跳一跳 / 敲木鱼恢复阶段落点统一由 `platformCreationUrlStateModel.ts` 解析，壳层只执行读取作品、恢复草稿和切换阶段等副作用。生成页等待时间统一以生成状态里的 `startedAtMs` 为准；创建该状态时优先使用后端 session 下发的时间戳，作品摘要里的 `updatedAt` 仍只用于排序与摘要展示，不作为前端自行推导业务状态的真相。

@@ -56,14 +56,15 @@ Genarrative / 陶泥儿是一个 AI 原生互动内容与小游戏平台。当

 ## 账户与充值

-1. “我的”页账户充值弹窗包含 `泥点充值` 与 `会员卡充值` 两个页签，入口必须打开独立弹窗，不在当前面板下方展开。
-2. 泥点默认档位为 `60 / 180 / 300 / 680 / 1280 / 3280`，会员默认档位为月卡、季卡、年卡；实际展示、下单校验和支付确认都以后端返回的充值商品配置为准。
-3. 首充双倍按泥点商品档位独立计算。用户买过 `points_60` 后，只影响 `points_60` 的首充展示和结算，其它未购买档位仍保留各自首充权益。
-4. 前端不得用 `hasPointsRecharged` 统一隐藏所有泥点档位首充权益；该字段只表示账号是否发生过任一泥点充值。
-5. 充值支付渠道只允许由设备平台隔离层解析为 `wechat_mp`、`wechat_mp_virtual`、`wechat_jsapi`、`wechat_h5` 或 `wechat_native`；生产真实支付不得默认落到 `mock`，缺失或未知 `paymentChannel` 必须拒绝。
-6. 小程序 WebView 充值使用 `wechat_mp_virtual` 调起小程序虚拟支付；微信内浏览器使用 `wechat_jsapi` 调起微信支付 JSAPI；普通 Web 使用 `wechat_native` 二维码支付，避免因移动 UA、触控能力或窄屏误入 `wechat_h5`。只有微信通知或查单确认 `SUCCESS` 后才刷新余额或会员状态。
-7. 后端必须按 access JWT 中的最小设备快照拦截真实微信充值路径，不能只依赖前端隐藏入口或请求体传入的 `paymentChannel`。
-8. 后台“充值商品”页维护泥点和会员商品配置，保存后影响新的充值中心快照、下单和支付确认；历史订单保留下单时快照。
+1. 主站和图片画板统一使用公共泥点资产入口。收起态展示“泥点图标 + 泥点总额 | 充值”；桌面端通过 hover / focus 展开，移动端通过点击展开。展开态只展示不限时泥点、每日免费泥点及“每天重置为 20 泥点”，并提供“使用详情”入口；余额都以后端充值中心 read model 为准，前端不得自行相减推算。
+2. 账户充值弹窗标题统一为“购买更多泥点”，当前版本只展示泥点商品，不展示会员页签、会员商品、购买会员或升级会员入口。底层会员数据与周期刷新能力继续保留用于存量兼容和结算，会员周期限时泥点不在当前版本前台展示。
+3. 泥点默认商品固定为四档：`60 泥点 / ¥6`、`180 + 90 泥点 / ¥18`、`300 + 150 泥点 / ¥30`、`680 + 340 泥点 / ¥68`。`60` 档不加赠，后三档首次购买各加赠基础泥点的 `50%`；实际展示、下单校验和支付确认仍以后端返回的充值商品配置为准。
+4. 首充加赠资格按泥点商品档位独立计算。用户买过 `points_180` 后，只影响 `points_180` 的首充展示和结算，其它未购买档位仍保留各自首充加赠资格。
+5. 前端不得用 `hasPointsRecharged` 统一隐藏所有泥点档位首充权益；该字段只表示账号是否发生过任一泥点充值。
+6. 充值支付渠道只允许由设备平台隔离层解析为 `wechat_mp`、`wechat_mp_virtual`、`wechat_jsapi`、`wechat_h5` 或 `wechat_native`；生产真实支付不得默认落到 `mock`，缺失或未知 `paymentChannel` 必须拒绝。
+7. 小程序 WebView 充值使用 `wechat_mp_virtual` 调起小程序虚拟支付；微信内浏览器使用 `wechat_jsapi` 调起微信支付 JSAPI；普通 Web 使用 `wechat_native` 二维码支付，避免因移动 UA、触控能力或窄屏误入 `wechat_h5`。只有微信通知或查单确认 `SUCCESS` 后才刷新余额或会员状态。
+8. 后端必须按 access JWT 中的最小设备快照拦截真实微信充值路径，不能只依赖前端隐藏入口或请求体传入的 `paymentChannel`。
+9. 后台“充值商品”页继续维护泥点和会员商品配置，保存后影响新的充值中心快照、下单和支付确认；历史订单保留下单时快照。会员商品配置保留不表示当前版本开放公开购买或升级入口。

 ## 唯一后端路线

@@ -102,10 +103,10 @@ server-rs + Axum + SpacetimeDB
 7. 主站入口已锁定移动端页面级缩放；单个游戏页面不要再重复实现整页缩放锁定。
 8. 图像输入通用 UI 统一走 `src/components/common/CreativeImageInputPanel.tsx`。外层页面持有业务状态，组件只承担上传卡、预览、参考图缩略图、AI 重绘开关、错误展示和提交按钮。
 9. 发现页 `分类` 子频道的筛选必须打开独立 dialog / drawer / modal，至少支持玩法类型过滤与排序切换；筛选结果为空时显示空状态，不把筛选内容展开在当前列表下方。
-10. 移动端“我的”页顶部品牌行承载扫码和设置入口，正文按参考图顺序组织为头像 / 昵称 / 陶泥号、会员横幅、三张统计卡、每日任务、五项常用功能宫格、通用设置入口和法律信息；`media/profile/` 中的陶泥素材作为该页图形资产。常用功能宫格固定承载泥点充值、邀请好友、兑换码、玩家社区、反馈与建议；当前只展示四项常驻入口时必须按四列铺满整行，不保留五列网格导致左对齐空位。页面不再提供独立存档按钮入口，也不在底部保留旧的填邀请码次级入口；主题设置、账号与安全只作为通用设置弹窗下一级入口，不在“我的”页外层单独占行。填邀请码只由邀请链接 query 或其它明确引导打开独立弹窗，不作为“我的”页常驻按钮。
-11. “我的”页每日任务卡必须展示后端 `/api/profile/tasks` 返回的当前任务摘要，包括奖励泥点数和进度；外层任务卡不展示“去完成”等左右侧行动按钮，领取 / 去完成 / 已完成状态只在任务中心弹窗内表达。任务领取成功后，卡片摘要必须跟随返回的任务中心数据同步刷新，不能继续硬编码 `0 / 1` 或只更新弹窗内任务列表。用户停留在“我的”页跨过北京时间 0 点时，前端必须非阻断刷新登录态以补齐 `daily_login` 埋点，再重拉任务中心，避免继续展示上一自然日已领取状态。
-12. “我的”页泥点余额、累计游玩、已玩游戏三张统计卡只展示各自标签和值，三个统计 icon 使用小尺寸普通 UI 档位，内容不换行，不在统计区底部展示“更新于”时间；移动端昵称、会员卡、每日任务、常用功能和法律信息也应保持 `10px` 到 `14px` 的普通 UI 字号区间，避免展示级字号挤压内容。
-13. 移动端“我的”页需要兼容窄屏：头像 / 昵称 / 陶泥号、三张统计卡、每日任务、五项常用功能和法律信息都必须能在底部固定 TabBar 上方完整滚动露出，不得与底部 dock、刘海 safe-area 或相邻 UI 元素遮挡重叠。
+10. 移动端“我的”页顶部品牌行承载扫码和设置入口，正文按参考图顺序组织为头像 / 昵称 / 陶泥号、三张统计卡、五项常用功能宫格、通用设置入口和法律信息；`media/profile/` 中的陶泥素材作为该页图形资产。常用功能宫格固定承载泥点充值、邀请好友、兑换码、玩家社区、反馈与建议；当前只展示四项常驻入口时必须按四列铺满整行，不保留五列网格导致左对齐空位。页面不再提供会员购买 / 升级横幅、每日任务卡片或任务中心入口，也不提供独立存档按钮入口，不在底部保留旧的填邀请码次级入口；主题设置、账号与安全只作为通用设置弹窗下一级入口，不在“我的”页外层单独占行。填邀请码只由邀请链接 query 或其它明确引导打开独立弹窗，不作为“我的”页常驻按钮。
+11. 每日免费泥点由后端独立余额桶承载，基础额度固定为 `20`，按北京时间每日 `00:00` 重置。跨业务日退款时，原消费中的每日免费泥点部分叠加到退款当日每日免费桶，当日余额允许超过 `20`；到下一业务日仍统一失效并重置为 `20`。主站不得把已隐藏的每日任务入口或 `daily_task_reward` 文案继续当作每日免费泥点入口。
+12. “我的”页泥点余额、累计游玩、已玩游戏三张统计卡只展示各自标签和值，三个统计 icon 使用小尺寸普通 UI 档位，内容不换行，不在统计区底部展示“更新于”时间；移动端昵称、常用功能和法律信息也应保持 `10px` 到 `14px` 的普通 UI 字号区间，避免展示级字号挤压内容。
+13. 移动端“我的”页需要兼容窄屏：头像 / 昵称 / 陶泥号、三张统计卡、五项常用功能和法律信息都必须能在底部固定 TabBar 上方完整滚动露出，不得与底部 dock、刘海 safe-area 或相邻 UI 元素遮挡重叠。
 14. RPG 等运行态的战斗飘字、血量变化和即时反馈必须在暗色、噪声高的场景背景上保持可读：使用高亮文字、深色描边、强阴影或小面积半透明底，不只依赖红/绿文字本身表达伤害或治疗。
 15. 平台亮色 UI 配色以陶泥儿主视觉为准：暖白 / 米杏底、陶土橙主按钮、深棕正文与浅杏边框；新增界面优先复用 `src/index.css` 的 `--platform-*` 主题变量和 `apps/admin-web/src/styles/admin.css` 的同系色值，不再引入粉红、蓝绿等独立主色方案。