.env.example

@@ -46,8 +46,6 @@ AUTH_REFRESH_SESSION_TTL_DAYS="30"
 AUTH_REFRESH_COOKIE_PATH="/api/auth"
 AUTH_REFRESH_COOKIE_SAME_SITE="Lax"
 AUTH_REFRESH_COOKIE_SECURE="false"
-# Rust 鉴权快照路径；包含 password_hash 与 refresh token hash，只能放服务端私有目录。
-GENARRATIVE_AUTH_STORE_PATH="server-rs/.data/auth-store.json"
 # 开发期便捷开关：true 时允许 /api/auth/entry 对未知手机号用本次密码直接创建账号；生产必须保持 false。
 GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED="false"
 
@@ -145,6 +143,17 @@ ALIYUN_OSS_POST_EXPIRE_SECONDS="600"
 ALIYUN_OSS_POST_MAX_SIZE_BYTES="20971520"
 ALIYUN_OSS_SUCCESS_ACTION_STATUS="200"
 
+# SpacetimeDB 数据目录备份到 OSS。备份 bucket 可与资源 bucket 分离；未设置时脚本回退使用 ALIYUN_OSS_BUCKET。
+GENARRATIVE_DATABASE_BACKUP_DATA_DIR=""
+GENARRATIVE_DATABASE_BACKUP_WORK_DIR=""
+GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET=""
+GENARRATIVE_DATABASE_BACKUP_OSS_ENDPOINT=""
+GENARRATIVE_DATABASE_BACKUP_OSS_PREFIX="database-backups"
+GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL="false"
+GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID=""
+GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET=""
+GENARRATIVE_DATABASE_BACKUP_STOP_SERVICE=""
+
 # Optional model name for custom-world scene image generation.
 DASHSCOPE_IMAGE_MODEL="wan2.7-image"
 

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

@@ -16,6 +16,14 @@
 
 ---
 
+## 2026-05-27 生成页总进度圆弧锁定固定画布
+
+- 背景：多轮圆环角度微调后，`GenerationProgressHero` 的 SVG 圆弧仍会出现底部开口偏斜的问题，且圆环还会随着容器宽度伸缩，导致 UI 看起来时大时小、位置漂移。
+- 决策：共用 `GenerationProgressHero` 的 SVG 圆弧起始角固定为 `135deg`，轨道和橘黄色填充都从同一个对称起点 `rotate(135 200 200)` 出发；`270deg` 扫描角配合正下方 `90deg` 留空，圆环本体改为固定 `400x400` 画布，不再跟随页面宽度缩放，外层布局只负责定位，不负责改动圆环样式。
+- 影响范围：`src/components/GenerationProgressHero.tsx`、共用 `CustomWorldGenerationView`、汪汪声浪 `BarkBattleGeneratingView` 以及生成页圆环布局文档。
+- 验证方式：`CustomWorldGenerationView` 和 `BarkBattleGeneratingView` 测试断言 `data-ring-start-degrees=135`、`data-ring-fill-start-degrees=135`，且圆环容器固定为 `h-[400px] w-[400px]`，track / fill transform 都是 `rotate(135 200 200)`。
+- 关联文档：`docs/【玩法创作】生成页圆环布局口径-2026-05-23.md`。
+
 ## 2026-05-26 平台跨流程错误统一用可复制来源弹窗展示
 
 - 背景：拼图等生成链路可能同时存在多个草稿或游玩实例，页面内裸错误 banner 容易让用户误以为当前正在看的拼图失败，也不方便复制完整错误给开发排查。
@@ -201,6 +209,14 @@
 - 验证方式：背景 prompt 单测应包含中央禁区硬约束，试玩图中央不再出现苹果或其它主题主体。
 - 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
+## 2026-05-27 敲木鱼背景 prompt 不再写中央木鱼预设
+
+- 背景：背景 prompt 曾写入“木鱼预设在屏幕中央位置”，与“背景图中不包含新木鱼物品”“中央 40% 禁止出现主题主体”直接冲突，导致 image2 偶发把静态木鱼画回背景中心。
+- 决策：背景 prompt 只能写“中央主体预留区”“运行态叠放敲击物的留白区域”“只生成背景环境图”，不得再出现“木鱼预设在屏幕中央位置”或任何等价的中心主体正向描述。
+- 影响范围：`server-rs/crates/api-server/src/wooden_fish.rs`、敲木鱼 PRD、平台链路文档、背景 prompt 单测。
+- 验证方式：`wooden_fish_background_prompt_uses_hidden_image2_flow` 必须断言旧冲突句子不存在，并断言新的中央留白表述存在。
+- 关联文档：`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 2026-05-21 外部 API 失败必须 OTLP 上报并落库
 
 - 背景：图片生成等外部供应商调用失败时，仅返回 502/504 或普通日志无法支持后续按 provider、阶段和重试属性聚合排障。
@@ -507,6 +523,13 @@
 - 验证方式：执行 `npm run spacetime:generate -- --rust-only`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、认证相关定向测试和 `npm run check:encoding`。
 - 关联文档：`docs/technical/AUTH_SPACETIMEDB_FORMAL_TABLE_RECOVERY_STAGE3_2026-04-24.md`、`docs/technical/SPACETIMEDB_TABLE_CATALOG.md`。
 
+## 2026-05-27 auth_store_snapshot 改为行级记录，不再保留 default 聚合单行
+
+- 背景：`auth_store_snapshot/default` 聚合 JSON 行会把整份认证快照收敛到单键，过期快照一旦被导入就可能覆盖 `user_account` / `auth_identity` / `refresh_session` 的整表状态。
+- 决策：`auth_store_snapshot` 只保留行级记录，按 `meta/next_user_id`、`user/<user_id>`、`phone/<phone+user>`、`session/<session_id>`、`session_hash/<hash+session>`、`wechat/<provider_uid+user>`、`union/<union+user>` 拆分存储；`api-server` 启动恢复只认正式认证表，`auth_store_snapshot` 仅作为行级备查，不再作为文件快照替代源。
+- 影响范围：`spacetime-module` auth procedures、`spacetime-client` auth facade、`api-server` 启动恢复、后端架构文档、开发运维文档、认证排障记忆。
+- 验证方式：`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server spacetime_unavailable_router_returns_service_unavailable_for_requests --manifest-path server-rs/Cargo.toml -- --nocapture`、`npm run check:encoding`。
+
 ## 2026-05-13 微信小程序支付以后端通知为唯一入账事实
 
 - 背景：“我的”账户充值需要接入微信小程序支付，同时保留本地 / H5 mock 支付联调能力。
@@ -1064,10 +1087,26 @@
 - 影响范围：拼图图片模型选择器、拼图结果页关卡重生成面板、拼图生成进度文案、宝贝识物结果页占位提示和相关错误提示。
 - 验证方式：前端可见文本中不再出现 `gpt-image-2` / `gemini-3.1-flash-image-preview` / `image-2 资源`；相关交互测试改为断言产品化模式名，但提交 payload 仍保持原有模型 ID。
 - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 2026-05-27 微信新用户用户名与孤儿作品作者回退收口
+
+- 背景：用户数据清空后，旧作品的 `owner_user_id` 可能落到空洞或顺序号账号上，新注册用户会错误顶替历史作品；同时微信新用户默认用户名过于固定，不便于区分 openid。
+- 决策：微信新用户的用户名统一改为 `名字_openid`，内部 `user_id` 改为不可复用的 `user_` 前缀 UUID 风格；作品作者找不到真实账号时统一回退到占位作者 `wx-openid-placeholder`，显示名固定为 `失效作者`，公开陶泥号固定为 `SY-00000000`。
+- 影响范围：`module-auth`、`api-server` 作品作者解析、`AppState` 启动初始化、历史孤儿作品离线回填脚本与相关文档。
+- 验证方式：`cargo test -p module-auth --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml work_author`、`npm run test -- scripts/rebind-orphan-work-owners.test.ts`。
+- 关联文档：`server-rs/crates/module-auth/src/domain.rs`、`server-rs/crates/module-auth/src/lib.rs`、`server-rs/crates/api-server/src/work_author.rs`、`scripts/rebind-orphan-work-owners.mjs`。
 ## 2026-05-26 敲木鱼发布后作品架与推荐流刷新口径
 
 - 背景：敲木鱼已具备公开广场投影，但草稿 Tab 的作品架没有当前用户作品列表接口，导致已发布作品在发布后不能立即出现在“已发布”筛选和推荐流里。
 - 决策：新增 `GET /api/creation/wooden-fish/works` 作为当前用户木鱼作品架事实源，返回 `WoodenFishWorksResponse.items` 摘要；平台壳在发布成功后必须同时刷新作品架和公开广场列表。
 - 影响范围：`server-rs/crates/api-server/src/wooden_fish.rs`、`server-rs/crates/api-server/src/modules/wooden_fish.rs`、`src/services/wooden-fish/woodenFishClient.ts`、`src/components/custom-world-home/creationWorkShelf.ts`、`src/components/platform-entry/PlatformEntryFlowShellImpl.tsx`。
 - 验证方式：发布一个木鱼作品后，草稿 Tab 的已发布筛选应立刻出现 `WF-*` 作品卡，推荐 / 最新流也应立即刷新出公开卡片。
-- 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`。
+ - 关联文档：`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`。
+
+## 2026-05-27 认证快照完全去文件化并仅保留行级备查
+
+- 背景：`api-server` 依赖本地 `auth-store.json` 或 `GENARRATIVE_AUTH_STORE_PATH` 恢复认证真相会在 SpacetimeDB 不可用时把旧快照回灌到 `auth_identity` / `user_account`，导致用户数据被清空或覆盖。
+- 决策：`api-server` 启动时只允许从 SpacetimeDB 正式认证表恢复；`module-auth` 不再维护本地持久化文件，只保留内存工作集和 JSON 导入 / 导出；`spacetime-module` 的认证快照只保留行级 `auth_store_snapshot` 备查，不再提供旧 `get_auth_store_snapshot` / `upsert_auth_store_snapshot` / `import_auth_store_snapshot` 兼容入口。
+- 影响范围：`server-rs/crates/api-server/src/state.rs`、`server-rs/crates/module-auth/src/lib.rs`、`server-rs/crates/spacetime-module/src/auth/procedures.rs`、`server-rs/crates/spacetime-client/src/auth.rs`、对应生成 bindings。
+- 验证方式：`cargo check -p module-auth --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`cargo test -p module-auth password --manifest-path server-rs/Cargo.toml -- --nocapture`、`npm run check:spacetime-schema`、`npm run check:encoding`、`cargo test -p api-server spacetime_unavailable_router_returns_service_unavailable_for_requests --manifest-path server-rs/Cargo.toml -- --nocapture`。
+- 关联文档：`docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。

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

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

.hermes/shared-memory/pitfalls.md

@@ -134,6 +134,15 @@
 - 验证：浏览器里这三页的根区应仍保留 `platform-remap-surface`，但不再出现 `platform-page-stage`；草稿页顶部筛选样式应和发现页频道标签一致。
 - 关联：`src/components/custom-world-home/CustomWorldCreationHub.tsx`、`src/components/custom-world-home/CustomWorldWorkTabs.tsx`、`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/index.css`。
 
+
+## Jenkinsfile 开头不能带 UTF-8 BOM
+
+- 现象：`Genarrative-Stdb-Module-Publish` 在 `Pipeline script from SCM` 读取 `jenkins/Jenkinsfile.production-stdb-module-publish` 后，流水线还未进入任何 stage 就失败，报 `java.lang.NoSuchMethodError: No such DSL method 'pipeline'`，堆栈位置是 `WorkflowScript.run(WorkflowScript:1)`。
+- 原因：该 Jenkinsfile 文件前三字节是 UTF-8 BOM `EF BB BF`，Jenkins/Groovy 把它拼进首个标识符，导致实际调用的是 `\ufeffpipeline` 而不是 Declarative Pipeline 的 `pipeline` 全局。
+- 处理：仓库内 `jenkins/Jenkinsfile.production-*` 保存为 UTF-8 without BOM；不要为了解决 Windows PowerShell 5.1 `.ps1` 中文解析问题而给 Jenkinsfile 本身加 BOM。只有 Jenkins helper 临时写出的 `.ps1` 才按需要转成 UTF-8 with BOM。
+- 验证：检查 `jenkins/Jenkinsfile.production-stdb-module-publish` 文件开头字节不再是 `EF BB BF`，并用 Jenkins `validateDeclarativePipeline` 或重放 `Genarrative-Stdb-Module-Publish`，不应再停在 `No such DSL method 'pipeline'`。
+- 关联：`jenkins/Jenkinsfile.production-stdb-module-publish`、`docs/【开发运维】本地开发验证与生产运维-2026-05-15.md`。
+
 ## SpacetimeDB 入口迁移 helper 合并时不要只保留调用
 
 - 现象：`cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 或 Jenkins `Genarrative-Stdb-Module-Build` 报 `E0425 cannot find function migrate_rpg_entry_from_old_hidden_default in this scope`，位置在 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs` 的默认入口配置播种流程。
@@ -170,7 +179,7 @@
 
 - 现象：苹果等主题试玩时，中央敲击物图带明显黑底；背景图中央还可能出现苹果主体，或背景环境图偶发变成纯绿色底，和“中央只叠加 hitObjectAsset”的运行态设定冲突。
 - 原因：gpt-image-2 对“透明底”和“背景只做外围氛围”的遵循不稳定。若 hit object 直接入库，黑底会被当成真实像素展示；若背景 prompt 只有软描述，模型会把主题主体画进中央。第一步为了去背刻意要求绿幕图时，如果第二步参考图或 prompt 没有切断绿幕语义，背景图也可能继承纯绿色画布。
-- 处理：敲木鱼 hit object prompt 固定要求先输出 `1:1` 绿色背景主体图（纯绿色绿幕、单一 `#00FF00` 背景），再由 `api-server` 只对绿幕背景做去绿透明化；不要回到黑底 / 白底 / 透明底 prompt 后再做泛抠图。背景生成必须使用第一步抠图完成后的透明图作为参考图，并在 prompt 中显式禁止继承绿色底色、绿幕底色或纯绿色画布；背景 prompt 还要固定要求中央 40% 主体预留区干净，禁止主题主体、局部特写、轮廓影子、重复元素和主题碎片，只允许外围氛围。
+- 处理：敲木鱼 hit object prompt 固定要求先输出 `1:1` 绿色背景主体图（纯绿色绿幕、单一 `#00FF00` 背景），再由 `api-server` 只对绿幕背景做去绿透明化；不要回到黑底 / 白底 / 透明底 prompt 后再做泛抠图。背景生成必须使用第一步抠图完成后的透明图作为参考图，并在 prompt 中显式禁止继承绿色底色、绿幕底色或纯绿色画布；背景 prompt 还要固定要求中央 40% 主体预留区干净，禁止主题主体、局部特写、轮廓影子、重复元素和主题碎片，只允许外围氛围。不要在背景 prompt 写“木鱼预设在屏幕中央位置”或类似中心主体正向描述，运行态敲击物只能由前端叠放。
 - 验证：`cargo test -p api-server wooden_fish --manifest-path server-rs\Cargo.toml`，并用花朵 / 苹果 / 玉米主题跑试玩图确认绿幕被去除、主体未被抠除、背景中央不出现主题主体，背景环境图不再出现纯绿色底。
 - 关联：`server-rs/crates/api-server/src/wooden_fish.rs`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
 
@@ -182,6 +191,14 @@
 - 验证：`cargo test -p api-server wooden_fish --manifest-path server-rs\Cargo.toml`，并重新试玩确认返回按钮只剩圆形底色和中央左箭头。
 - 关联：`server-rs/crates/api-server/src/wooden_fish.rs`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`.
 
+## 敲木鱼历史已发布作品缺返回按钮要补齐，不要靠推荐过滤
+
+- 现象：推荐页或公开列表中的历史敲木鱼作品点击运行态时报 `敲木鱼运行态需要完整作品配置`，但这类作品的敲击物、背景、音效和飘字都已完整，只是 `backButtonAsset` 为空。
+- 原因：早期已发布作品缺少统一的默认返回按钮快照；运行态启动时如果仍直接按完整配置校验，就会把可玩的历史作品拒掉。这个问题不应通过推荐流或公开列表过滤解决。
+- 处理：`spacetime-module` 在 `start_wooden_fish_run_tx` 和 work snapshot 构建时，若作品已发布且 `generationStatus=ready`，但仅缺 `backButtonAsset`，就补写内置默认返回按钮 `/UI/11_left_arrow.png`，再继续进入运行态。默认返回按钮以 `bundled-default` 资产快照写回 work profile，字段保持 `assetId=wooden-fish-default-back-button`、`imageObjectKey=public/UI/11_left_arrow.png`。
+- 验证：历史木鱼作品点击运行态不再报完整作品配置缺失；第一次进入后，work profile 里应补出 `backButtonAsset`。
+- 关联：`server-rs/crates/spacetime-module/src/wooden_fish.rs`、`docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
 ## 敲木鱼创作生成不要沿用 15 秒会话超时
 
 - 现象：敲木鱼工作台点击“生成”后，前端直接提示 `请求超时：15000ms`，但后端和 VectorEngine 未必已经失败。
@@ -512,10 +529,17 @@
 
 - 现象：用户通过“忘记密码”重设密码后，接口返回成功或页面进入登录态，但再次使用新密码登录仍提示“手机号或密码错误”；重启后还可能出现 `Bearer JWT 版本已失效`，日志里的 token version 与本地快照不一致。
 - 原因：重置/修改密码会更新 `password_hash`、`password_login_enabled` 和 `token_version`，如果 API 层只更新本地 `InMemoryAuthStore`，没有调用 `sync_auth_store_snapshot_to_spacetime()`，`api-server` 重启时可能从旧的 SpacetimeDB 表或旧快照恢复账号状态。
-- 处理：`POST /api/auth/password/change` 与 `POST /api/auth/password/reset` 成功后必须同步认证快照；启动恢复时从 SpacetimeDB 表、SpacetimeDB 快照记录和本地 `GENARRATIVE_AUTH_STORE_PATH` 文件中选择可判断的最新快照，本地文件更新时尝试回写 SpacetimeDB。
+- 处理：`POST /api/auth/password/change` 与 `POST /api/auth/password/reset` 成功后必须同步认证快照。2026-05-27 起，启动恢复只允许从 SpacetimeDB 正式认证表恢复；`auth_store_snapshot` 只保留行级记录，不再写 `default` 聚合单行，也不再把本地文件 `auth-store.json` / `GENARRATIVE_AUTH_STORE_PATH` 当作恢复源。若启动时连不上 SpacetimeDB，`api-server` 等待启动恢复超时后进入依赖不可用模式，所有请求返回 `503 SERVICE_UNAVAILABLE`，`details.reason = "spacetime_startup_unavailable"`。
 - 验证：执行 `cargo test -p module-auth password --manifest-path server-rs/Cargo.toml` 与 `cargo test -p api-server password --manifest-path server-rs/Cargo.toml`；手测时重设密码后旧密码应失败，新密码应成功，重启后仍应保持。
 - 关联：`server-rs/crates/api-server/src/password_management.rs`、`server-rs/crates/api-server/src/state.rs`、`docs/technical/PASSWORD_LOGIN_CHANGE_RESET_DESIGN_2026-04-24.md`。
 
+## 认证本地文件快照已废弃，旧 procedure 也已删
+
+- 现象：有些旧代码和生成 bindings 里还会残留 `get_auth_store_snapshot`、`upsert_auth_store_snapshot`、`import_auth_store_snapshot`，或者把 `auth-store.json` 误当成认证恢复源。
+- 原因：认证恢复已经彻底收口到 SpacetimeDB 正式表和 `module-auth` 的 JSON 导入 / 导出路径；本地文件持久化会和正式表投影打架，SpacetimeDB 不可用时还可能把旧快照回灌到用户表。
+- 处理：先用 `npm run spacetime:generate -- --rust-only` 刷新 bindings，确认 `server-rs/crates/spacetime-client/src/module_bindings.rs` 里已没有旧 procedure 导出；`module-auth` 只保留内存态，不再写本地快照文件。
+- 验证：`cargo check -p module-auth --manifest-path server-rs/Cargo.toml`、`cargo check -p api-server --manifest-path server-rs/Cargo.toml`、`npm run check:spacetime-schema`、`npm run check:encoding`。
+
 ## 抓大鹅生成页只显示服务暂不可用先查 reason 和外部服务配置
 
 - 现象：点击生成抓大鹅草稿后，页面只提示“服务暂不可用”，或者本地 `npm run dev:api-server` 看似启动但生成接口不可用。
@@ -1560,6 +1584,8 @@
 
 2026-05-24 补充：生成页“预计等待 / 已耗时”卡片本身已经有标签，传给 `GenerationProgressHero` 的值只能是纯时间，例如 `4 分钟`、`1 分 15 秒`，不要再拼接“预计还需”或“已耗时”；两张时间卡也要和当前步骤卡一样保持半透明。拼图总进度初始帧必须允许显示 `0%`，不要再用 `Math.max(1, nextProgress)` 之类的保护把启动态抬到 `1%`。
 
+2026-05-27 补充：`generation-hero-progress-ring-fill` 里那个橘黄色小点不是背景噪点，而是 `strokeLinecap="round"` 在短弧段上的端点；当前圆环口径要求底部 `90deg` 开口居中对称，因此轨道和填充都应使用 `135deg` 起点。圆环本体现在固定为 `400x400`，排查时先看 `data-ring-start-degrees`、`data-ring-fill-start-degrees` 和容器尺寸，不要把尺寸伸缩误认成素材渲染问题。
+
 ## `dev:spacetime` 启动后 3101 又断开先查 publish 是否被 spacetime.json 干扰
 
 - 现象：浏览器报 `Failed to initiate WebSocket connection`，目标为 `ws://127.0.0.1:3101/v1/database/<db>/subscribe`，端口检查发现 `3101` 没有长期监听；手动运行 `npm run dev:spacetime` 可看到 standalone 短暂启动后退出，发布阶段报 `No database target matches '<db>'`。
@@ -1607,3 +1633,19 @@
 - 处理：后续如果需要重新暴露存档入口，优先评估是否应回到“玩过”或别的独立弹窗流程，不要默认把存档再塞回常用功能宫格或设置列表。
 - 验证：`npm test -- src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx -t "mobile profile page matches the reference layout sections|profile scan action opens camera scanner instead of recharge panel"`。
 - 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`docs/【项目基线】当前产品与工程约束-2026-05-15.md`、`docs/【玩法创作】平台入口与玩法链路-2026-05-15.md`。
+
+## 微信历史孤儿作品不要让新注册账号顶替
+
+- 现象：清空用户数据或迁移历史数据后，旧作品的 `owner_user_id` 为空或失效，新注册用户会因为顺序号复用或旧 ID 残留顶替作品归属，导致刚注册就看到别人的草稿或已发布作品。
+- 原因：作品作者解析曾经把缺失作者简单回退到普通登录用户，且微信新用户用户名 / 内部 ID 都太容易被误认或复用。
+- 处理：作品作者找不到真实账号时统一回退到占位作者 `wx-openid-placeholder`，展示名固定为 `失效作者`；微信新用户用户名改为 `名字_openid`，内部 `user_id` 改成不可复用的 UUID 风格；离线回填时先识别真实有效用户，再把孤儿作品表写回占位账号。
+- 验证：`cargo test -p module-auth --manifest-path server-rs/Cargo.toml`、`cargo test -p api-server --manifest-path server-rs/Cargo.toml work_author`、`npm run test -- scripts/rebind-orphan-work-owners.test.ts`。
+- 关联：`server-rs/crates/api-server/src/work_author.rs`、`server-rs/crates/module-auth/src/domain.rs`、`scripts/rebind-orphan-work-owners.mjs`。
+
+## 访客推荐页上下滑不要绑定登录态
+
+- 现象：访客模式进入移动端推荐页后，推荐内容可展示和点击底部“下一个”，但在作品信息区域上下滑不会切换推荐作品，表现为推荐页不能上下滑动。
+- 原因：推荐页滑动切换逻辑 `beginRecommendDrag(...)` 误把 `isAuthenticated` 作为启用条件；访客态虽然允许浏览和通过底部按钮切换，却无法触发同一套拖拽切换。
+- 处理：推荐页拖拽只校验当前是否有作品、多作品可切换以及是否正在提交动画，不再要求登录；登录态相关操作仍由点赞、改造等按钮自身权限控制。
+- 验证：`npx vitest run src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx` 覆盖访客态纵向滑动不弹登录且触发下一条推荐。
+- 关联：`src/components/rpg-entry/RpgEntryHomeView.tsx`、`src/components/rpg-entry/RpgEntryHomeView.recharge.test.tsx`。

apps/admin-web/src/api/adminApiClient.ts

@@ -13,10 +13,13 @@ import type {
   AdminOverviewResponse,
   AdminTrackingEventListQuery,
   AdminTrackingEventListResponse,
+  AdminUpdateWorkVisibilityRequest,
+  AdminUpdateWorkVisibilityResponse,
   AdminUpsertProfileInviteCodeRequest,
   AdminUpsertProfileRechargeProductRequest,
   AdminUpsertProfileRedeemCodeRequest,
   AdminUpsertProfileTaskConfigRequest,
+  AdminWorkVisibilityListResponse,
   ApiErrorEnvelope,
   ApiMeta,
   ApiSuccessEnvelope,
@@ -194,6 +197,27 @@ export function upsertAdminCreationEntryConfig(
   );
 }
 
+export function listAdminWorkVisibility(token: string) {
+  return request<AdminWorkVisibilityListResponse>(
+    '/admin/api/works/visibility',
+    {token},
+  );
+}
+
+export function updateAdminWorkVisibility(
+  token: string,
+  payload: AdminUpdateWorkVisibilityRequest,
+) {
+  return request<AdminUpdateWorkVisibilityResponse>(
+    '/admin/api/works/visibility',
+    {
+      method: 'POST',
+      token,
+      body: payload,
+    },
+  );
+}
+
 export function listProfileRedeemCodes(token: string) {
   return request<ProfileRedeemCodeAdminListResponse>(
     '/admin/api/profile/redeem-codes',

apps/admin-web/src/api/adminApiTypes.ts

@@ -177,6 +177,36 @@ export interface AdminUpsertCreationEntryTypeConfigRequest {
   categorySortOrder: number;
 }
 
+export interface AdminWorkVisibilityEntryPayload {
+  sourceType: string;
+  workId: string;
+  profileId: string;
+  sourceSessionId?: string | null;
+  publicWorkCode: string;
+  ownerUserId: string;
+  authorDisplayName: string;
+  title: string;
+  subtitle: string;
+  coverImageSrc?: string | null;
+  visible: boolean;
+  publishedAtMicros?: number | null;
+  updatedAtMicros: number;
+}
+
+export interface AdminWorkVisibilityListResponse {
+  entries: AdminWorkVisibilityEntryPayload[];
+}
+
+export interface AdminUpdateWorkVisibilityRequest {
+  sourceType: string;
+  profileId: string;
+  visible: boolean;
+}
+
+export interface AdminUpdateWorkVisibilityResponse {
+  entry: AdminWorkVisibilityEntryPayload;
+}
+
 export interface AdminUpsertProfileRedeemCodeRequest {
   code: string;
   mode: ProfileRedeemCodeMode;

apps/admin-web/src/app/AdminApp.tsx

@@ -28,6 +28,7 @@ import {AdminRechargeProductPage} from '../pages/AdminRechargeProductPage';
 import {AdminRedeemCodePage} from '../pages/AdminRedeemCodePage';
 import {AdminTaskConfigPage} from '../pages/AdminTaskConfigPage';
 import {AdminTrackingEventsPage} from '../pages/AdminTrackingEventsPage';
+import {AdminWorkVisibilityPage} from '../pages/AdminWorkVisibilityPage';
 import {AdminShell} from './AdminShell';
 import type {AdminRouteId} from './adminRoutes';
 import {resolveAdminRoute, routeHash} from './adminRoutes';
@@ -205,6 +206,12 @@ export function AdminApp() {
           onUnauthorized={handleUnauthorized}
         />
       ) : null}
+      {routeId === 'work-visibility' ? (
+        <AdminWorkVisibilityPage
+          token={token}
+          onUnauthorized={handleUnauthorized}
+        />
+      ) : null}
       {routeId === 'tasks' ? (
         <AdminTaskConfigPage
           result={taskConfigResult}

apps/admin-web/src/app/AdminShell.tsx

@@ -3,6 +3,7 @@ import {
   BadgeDollarSign,
   LayoutDashboard,
   LogOut,
+  Eye,
   ShieldCheck,
   ListChecks,
   SlidersHorizontal,
@@ -35,6 +36,7 @@ const routeIcons = {
   tasks: ListChecks,
   'recharge-products': BadgeDollarSign,
   'creation-entry': SlidersHorizontal,
+  'work-visibility': Eye,
 } satisfies Record<AdminRouteId, typeof LayoutDashboard>;
 
 export function AdminShell({

apps/admin-web/src/app/adminRoutes.ts

@@ -7,7 +7,8 @@ export type AdminRouteId =
   | 'invite'
   | 'tasks'
   | 'recharge-products'
-  | 'creation-entry';
+  | 'creation-entry'
+  | 'work-visibility';
 
 export interface AdminRouteDefinition {
   id: AdminRouteId;
@@ -25,6 +26,7 @@ export const adminRoutes: AdminRouteDefinition[] = [
   {id: 'tasks', label: '任务配置', hash: '#tasks'},
   {id: 'recharge-products', label: '充值商品', hash: '#recharge-products'},
   {id: 'creation-entry', label: '入口开关', hash: '#creation-entry'},
+  {id: 'work-visibility', label: '作品可见性', hash: '#work-visibility'},
 ];
 
 export function resolveAdminRoute(hash: string): AdminRouteId {

apps/admin-web/src/pages/AdminWorkVisibilityPage.tsx

@@ -0,0 +1,269 @@
+import {Eye, EyeOff, RefreshCcw} from 'lucide-react';
+import {useEffect, useMemo, useState} from 'react';
+
+import {
+  listAdminWorkVisibility,
+  updateAdminWorkVisibility,
+} from '../api/adminApiClient';
+import type {AdminWorkVisibilityEntryPayload} from '../api/adminApiTypes';
+import {useAdminWriteConfirm} from '../components/useAdminWriteConfirm';
+import {handlePageError} from './pageUtils';
+
+interface AdminWorkVisibilityPageProps {
+  token: string;
+  onUnauthorized: (message?: string) => void;
+}
+
+const sourceLabels: Record<string, string> = {
+  puzzle: '拼图',
+  'custom-world': '自定义世界',
+  'jump-hop': '跳一跳',
+  'wooden-fish': '敲木鱼',
+  match3d: '抓大鹅',
+  'square-hole': '方洞挑战',
+  'visual-novel': '视觉小说',
+  'big-fish': '大鱼吃小鱼',
+  'bark-battle': '汪汪声浪',
+};
+
+export function AdminWorkVisibilityPage({
+  token,
+  onUnauthorized,
+}: AdminWorkVisibilityPageProps) {
+  const [entries, setEntries] = useState<AdminWorkVisibilityEntryPayload[]>([]);
+  const [keyword, setKeyword] = useState('');
+  const [isLoading, setIsLoading] = useState(false);
+  const [savingKey, setSavingKey] = useState('');
+  const [errorMessage, setErrorMessage] = useState('');
+  const {confirmWrite, confirmDialog} = useAdminWriteConfirm();
+
+  useEffect(() => {
+    void refreshEntries();
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [token]);
+
+  const filteredEntries = useMemo(() => {
+    const normalizedKeyword = keyword.trim().toLowerCase();
+    if (!normalizedKeyword) {
+      return entries;
+    }
+    return entries.filter((entry) =>
+      [
+        entry.sourceType,
+        sourceLabels[entry.sourceType] ?? '',
+        entry.title,
+        entry.subtitle,
+        entry.authorDisplayName,
+        entry.publicWorkCode,
+        entry.profileId,
+        entry.workId,
+      ]
+        .join(' ')
+        .toLowerCase()
+        .includes(normalizedKeyword),
+    );
+  }, [entries, keyword]);
+
+  async function refreshEntries() {
+    setIsLoading(true);
+    setErrorMessage('');
+    try {
+      const response = await listAdminWorkVisibility(token);
+      setEntries(sortEntries(response.entries));
+    } catch (error: unknown) {
+      handlePageError(error, onUnauthorized, setErrorMessage);
+    } finally {
+      setIsLoading(false);
+    }
+  }
+
+  async function handleToggle(entry: AdminWorkVisibilityEntryPayload) {
+    const nextVisible = !entry.visible;
+    const target = entry.title.trim() || entry.publicWorkCode || entry.profileId;
+    const confirmed = await confirmWrite({
+      action: nextVisible ? '显示作品' : '隐藏作品',
+      target,
+    });
+    if (!confirmed) {
+      return;
+    }
+
+    const rowKey = buildEntryKey(entry);
+    setSavingKey(rowKey);
+    setErrorMessage('');
+    try {
+      const response = await updateAdminWorkVisibility(token, {
+        sourceType: entry.sourceType,
+        profileId: entry.profileId,
+        visible: nextVisible,
+      });
+      upsertEntry(response.entry);
+    } catch (error: unknown) {
+      handlePageError(error, onUnauthorized, setErrorMessage);
+    } finally {
+      setSavingKey('');
+    }
+  }
+
+  function upsertEntry(next: AdminWorkVisibilityEntryPayload) {
+    setEntries((current) =>
+      sortEntries([
+        ...current.filter((entry) => buildEntryKey(entry) !== buildEntryKey(next)),
+        next,
+      ]),
+    );
+  }
+
+  return (
+    <section className="admin-page admin-page-wide">
+      <div className="admin-page-heading">
+        <div>
+          <h2>作品可见性</h2>
+        </div>
+        <button
+          className="admin-secondary-button"
+          disabled={isLoading}
+          type="button"
+          onClick={refreshEntries}
+        >
+          <RefreshCcw size={17} aria-hidden="true" />
+          <span>{isLoading ? '刷新中' : '刷新'}</span>
+        </button>
+      </div>
+
+      <section className="admin-panel">
+        <label className="admin-field">
+          <span>搜索</span>
+          <input
+            placeholder="标题 / 作者 / 公开码 / profileId"
+            value={keyword}
+            onChange={(event) => setKeyword(event.target.value)}
+          />
+        </label>
+
+        {errorMessage ? (
+          <div className="admin-alert" role="status">
+            {errorMessage}
+          </div>
+        ) : null}
+
+        <div className="admin-table-wrap">
+          <table className="admin-table admin-table-wide">
+            <thead>
+              <tr>
+                <th>玩法</th>
+                <th>作品</th>
+                <th>作者</th>
+                <th>公开码</th>
+                <th>更新时间</th>
+                <th>状态</th>
+                <th>操作</th>
+              </tr>
+            </thead>
+            <tbody>
+              {filteredEntries.map((entry) => {
+                const rowKey = buildEntryKey(entry);
+                const isSaving = savingKey === rowKey;
+                return (
+                  <tr key={rowKey}>
+                    <td>
+                      <span className="admin-tag">
+                        {sourceLabels[entry.sourceType] ?? entry.sourceType}
+                      </span>
+                    </td>
+                    <td>
+                      <strong>{entry.title || entry.profileId}</strong>
+                      <small>{entry.subtitle || entry.profileId}</small>
+                    </td>
+                    <td>
+                      {entry.authorDisplayName || '玩家'}
+                      <small>{entry.ownerUserId}</small>
+                    </td>
+                    <td>
+                      <span className="admin-table-cell-ellipsis">
+                        {entry.publicWorkCode}
+                      </span>
+                      <small>{entry.profileId}</small>
+                    </td>
+                    <td>{formatMicros(entry.updatedAtMicros)}</td>
+                    <td>
+                      <span
+                        className={
+                          entry.visible
+                            ? 'admin-status admin-status-ok'
+                            : 'admin-status admin-status-error'
+                        }
+                      >
+                        {entry.visible ? '显示' : '隐藏'}
+                      </span>
+                    </td>
+                    <td>
+                      <button
+                        className={
+                          entry.visible
+                            ? 'admin-danger-button'
+                            : 'admin-secondary-button'
+                        }
+                        disabled={isSaving}
+                        type="button"
+                        onClick={() => handleToggle(entry)}
+                      >
+                        {entry.visible ? (
+                          <EyeOff size={16} aria-hidden="true" />
+                        ) : (
+                          <Eye size={16} aria-hidden="true" />
+                        )}
+                        <span>
+                          {isSaving
+                            ? '处理中'
+                            : entry.visible
+                              ? '隐藏'
+                              : '显示'}
+                        </span>
+                      </button>
+                    </td>
+                  </tr>
+                );
+              })}
+            </tbody>
+          </table>
+        </div>
+
+        {!isLoading && filteredEntries.length === 0 ? (
+          <div className="admin-empty-state">暂无作品</div>
+        ) : null}
+      </section>
+
+      {confirmDialog}
+    </section>
+  );
+}
+
+function sortEntries(entries: AdminWorkVisibilityEntryPayload[]) {
+  return [...entries].sort((left, right) => {
+    const timeCompare = right.updatedAtMicros - left.updatedAtMicros;
+    if (timeCompare !== 0) {
+      return timeCompare;
+    }
+    const sourceCompare = left.sourceType.localeCompare(right.sourceType);
+    if (sourceCompare !== 0) {
+      return sourceCompare;
+    }
+    return left.profileId.localeCompare(right.profileId);
+  });
+}
+
+function buildEntryKey(entry: AdminWorkVisibilityEntryPayload) {
+  return `${entry.sourceType}:${entry.profileId}`;
+}
+
+function formatMicros(value: number) {
+  if (!Number.isFinite(value)) {
+    return '-';
+  }
+  const date = new Date(Math.floor(value / 1000));
+  if (!Number.isFinite(date.getTime())) {
+    return '-';
+  }
+  return date.toLocaleString('zh-CN', {hour12: false});
+}

deploy/container/api-server.Dockerfile

@@ -24,7 +24,6 @@ EXPOSE 8082
 ENV GENARRATIVE_ENV=container \
     GENARRATIVE_API_HOST=0.0.0.0 \
     GENARRATIVE_API_PORT=8082 \
-    GENARRATIVE_AUTH_STORE_PATH=/var/lib/genarrative/auth/auth-store.json \
     GENARRATIVE_TRACKING_OUTBOX_DIR=/var/lib/genarrative/tracking-outbox
 
 CMD ["api-server"]

deploy/container/api-server.env.example

@@ -27,7 +27,6 @@ GENARRATIVE_INTERNAL_API_SECRET=CHANGE_ME_FOR_CONTAINER
 GENARRATIVE_JWT_ISSUER=genarrative-container
 GENARRATIVE_JWT_SECRET=CHANGE_ME_FOR_CONTAINER
 AUTH_REFRESH_COOKIE_SECURE=false
-GENARRATIVE_AUTH_STORE_PATH=/var/lib/genarrative/auth/auth-store.json
 
 # 默认连接 compose 内部 SpacetimeDB；宿主机发布模块使用 127.0.0.1:13101。
 GENARRATIVE_SPACETIME_SERVER_URL=http://spacetimedb:3101

deploy/container/docker-compose.loadtest.yml

@@ -52,7 +52,6 @@ services:
     extra_hosts:
       - "host.docker.internal:host-gateway"
     volumes:
-      - api-auth-store:/var/lib/genarrative/auth
       - api-tracking-outbox:/var/lib/genarrative/tracking-outbox
     ulimits:
       nofile:
@@ -142,6 +141,5 @@ services:
 
 volumes:
   spacetime-data:
-  api-auth-store:
   api-tracking-outbox:
   nginx-logs:

deploy/env/api-server.env.example

@@ -34,7 +34,6 @@ AUTH_REFRESH_SESSION_TTL_DAYS=30
 AUTH_REFRESH_COOKIE_PATH=/api/auth
 AUTH_REFRESH_COOKIE_SAME_SITE=Lax
 AUTH_REFRESH_COOKIE_SECURE=true
-GENARRATIVE_AUTH_STORE_PATH=/var/lib/genarrative/auth/auth-store.json
 GENARRATIVE_DEV_PASSWORD_ENTRY_AUTO_REGISTER_ENABLED=false
 
 GENARRATIVE_SPACETIME_SERVER_URL=http://127.0.0.1:3101
@@ -119,3 +118,15 @@ ALIYUN_OSS_READ_EXPIRE_SECONDS=600
 ALIYUN_OSS_POST_EXPIRE_SECONDS=600
 ALIYUN_OSS_POST_MAX_SIZE_BYTES=20971520
 ALIYUN_OSS_SUCCESS_ACTION_STATUS=200
+
+# SpacetimeDB 数据目录 OSS 冷备份配置。可由 cron / Jenkins 调用发布包内 scripts/database-backup-to-oss.mjs。
+GENARRATIVE_DATABASE_BACKUP_DATA_DIR=/stdb
+GENARRATIVE_DATABASE_BACKUP_WORK_DIR=/var/lib/genarrative/database-backups
+GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET=
+GENARRATIVE_DATABASE_BACKUP_OSS_ENDPOINT=oss-cn-shanghai.aliyuncs.com
+GENARRATIVE_DATABASE_BACKUP_OSS_PREFIX=database-backups
+GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL=false
+# 可选：定时 / publish 前备份使用独立最小权限 AccessKey；为空时回退 ALIYUN_OSS_ACCESS_KEY_*。
+GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID=
+GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET=
+GENARRATIVE_DATABASE_BACKUP_STOP_SERVICE=spacetimedb.service

deploy/systemd/genarrative-database-backup.service

@@ -0,0 +1,18 @@
+[Unit]
+Description=Genarrative SpacetimeDB OSS Backup
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=oneshot
+User=root
+Group=root
+WorkingDirectory=/opt/genarrative/current
+EnvironmentFile=/etc/genarrative/api-server.env
+ExecStart=/usr/bin/node /opt/genarrative/current/scripts/database-backup-to-oss.mjs --env-file /etc/genarrative/api-server.env --stop-service spacetimedb.service
+
+# 备份需要停止 / 启动 spacetimedb.service，并读取 /stdb、写入 /var/lib/genarrative/database-backups。
+PrivateTmp=true
+ProtectSystem=full
+ReadWritePaths=/stdb /var/lib/genarrative
+

deploy/systemd/genarrative-database-backup.timer

@@ -0,0 +1,12 @@
+[Unit]
+Description=Run Genarrative SpacetimeDB OSS Backup Daily
+
+[Timer]
+OnCalendar=*-*-* 03:20:00
+Persistent=true
+RandomizedDelaySec=600
+Unit=genarrative-database-backup.service
+
+[Install]
+WantedBy=timers.target
+

docs/prd/【玩法创作】敲木鱼玩法模板PRD-2026-05-20.md

@@ -166,11 +166,11 @@ WF-*
 1. 调用 VectorEngine `/v1/images/edits`，模型固定为 `gpt-image-2`；
 2. multipart 参考图固定为第一步敲击物图案抠图完成后的透明图；默认未生成新敲击物时使用内置默认敲击物图案的透明兜底图；
 3. 尺寸固定竖屏 `9:16`；
-4. 背景环境图只适配新敲击物主题和画风，背景中不得包含新敲击物本体，也不得增加木槌互动物品；中央主体预留区必须保持干净，画面中央 40% 区域禁止出现主题主体、主体局部特写、主体轮廓影子、重复元素或主题主体的局部碎片；
+4. 背景环境图只适配新敲击物主题和画风，背景中不得包含新敲击物本体，也不得增加木槌互动物品；中央主体预留区必须保持干净，画面中央 40% 区域禁止出现主题主体、主体局部特写、主体轮廓影子、重复元素或主题主体的局部碎片；运行态的敲击物只在前端叠放，不允许出现在背景图提示词里。
 5. 提示词严格使用：
 
 ```text
-生成敲木鱼背景，要求主题，画风与参考图保持高度一致，背景元素和颜色搭配与主题对应，木鱼预设在屏幕中央位置，木鱼主体周围元素保持干净，背景氛围围绕外围设计，背景环境图中不包含新木鱼物品，背景氛围中不增加木槌互动物品。尺寸竖屏9:16。参考图必须是第一步敲击物抠图完成后的透明图，不继承任何绿色底色、绿幕底色或纯绿色画布，并要求最终输出完整不透明的背景环境图。中央主体预留区必须保持干净，画面中央 40% 区域禁止出现主题主体、主体局部特写、主体轮廓影子、重复元素或主题主体的局部碎片；主题元素只允许出现在外围氛围，不得把主题物品画在画面中央，也不要把主题物品作为背景中心装饰。
+生成敲木鱼背景，要求主题、画风与参考图保持高度一致，背景元素和颜色搭配与主题对应，只生成竖屏背景环境图，不生成、不描绘、不暗示新木鱼物品本体，也不要出现木槌互动物品。尺寸竖屏9:16。参考图必须是第一步敲击物抠图完成后的透明图，不继承任何绿色底色、绿幕底色或纯绿色画布，并要求最终输出完整不透明的背景环境图。中央主体预留区必须保持干净，中央区域是运行态叠放敲击物的留白区域，画面中央 40% 区域禁止出现主题主体、主体局部特写、主体轮廓影子、重复元素或主题主体的局部碎片；主题元素只允许出现在外围氛围，不得把主题物品画在画面中央，也不要把主题物品作为背景中心装饰。
 主题为：（用户提供参考图或用户输入关键词）
 ```
 
@@ -384,6 +384,8 @@ finish
 
 公开列表优先消费 `wooden_fish_gallery_card_view` 订阅缓存。公开详情如果卡片摘要不足以进入运行态，必须补读完整 work profile。
 
+历史已发布且 `generationStatus=ready` 的木鱼作品如果仅缺 `backButtonAsset`，运行态启动前必须补齐内置默认返回按钮 `/UI/11_left_arrow.png`，并持久写回 work profile；这类历史作品不应通过推荐流过滤隐藏。
+
 ## 13. 验收
 
 1. 创作入口能看到 `敲木鱼` 模板；

docs/superpowers/plans/2026-05-27-admin-work-visibility.md

@@ -0,0 +1,83 @@
+# 作品可见性后台管理 Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** 在后台增加统一作品可见性列表与修改能力，让管理员可以把已发布作品从公开 read model 中隐藏或恢复显示。
+
+**Architecture:** 可见性仍以各玩法源表 `visible` 字段为真相源；新增 SpacetimeDB admin procedure 统一列出和更新各玩法作品可见性，`api-server` 只做鉴权、DTO 校验和 BFF 转发，后台前端新增简洁管理页。统一公开 read model 继续只消费 `visible=true` 的 source view，不向公开契约暴露后台字段。
+
+**Tech Stack:** Rust server-rs + SpacetimeDB module/procedure + spacetime-client bindings/facade + shared-contracts DTO + React admin-web TypeScript。
+
+---
+
+### Task 1: 文档契约补齐
+
+**Files:**
+- Modify: `docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md`
+- Modify: `docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md`
+
+- [ ] 在 API 路由分组中补充 `/admin/api/works/visibility`。
+- [ ] 在统一公开作品 ReadModel 文档中写清后台只能修改源表 `visible`，隐藏后不进入 `public_work_gallery_entry` / `public_work_detail_entry`。
+
+### Task 2: DTO 与后端路由
+
+**Files:**
+- Modify: `server-rs/crates/shared-contracts/src/admin.rs`
+- Modify: `server-rs/crates/api-server/src/admin.rs`
+- Modify: `server-rs/crates/api-server/src/app.rs` 或现有 admin module router 文件
+
+- [ ] 增加 `AdminWorkVisibilityEntryPayload`、`AdminWorkVisibilityListResponse`、`AdminUpdateWorkVisibilityRequest`、`AdminUpdateWorkVisibilityResponse`。
+- [ ] 新增 `GET /admin/api/works/visibility` handler，必须走 `require_admin_auth`。
+- [ ] 新增 `POST /admin/api/works/visibility` handler，校验 `sourceType`、`profileId` 非空并转发到 SpacetimeDB facade。
+
+### Task 3: SpacetimeDB runtime/procedure 与 facade
+
+**Files:**
+- Modify: `server-rs/crates/module-runtime/src/domain.rs`
+- Create: `server-rs/crates/spacetime-module/src/runtime/admin_work_visibility.rs`
+- Modify: `server-rs/crates/spacetime-module/src/runtime.rs`
+- Modify: `server-rs/crates/spacetime-module/src/lib.rs`
+- Modify: `server-rs/crates/spacetime-client/src/runtime.rs`
+- Modify: `server-rs/crates/spacetime-client/src/mapper/runtime.rs`
+
+- [ ] 增加 module-runtime typed input/output 类型。
+- [ ] SpacetimeDB procedure 统一读取各玩法已发布源表/view，并返回可见性列表。
+- [ ] SpacetimeDB procedure 根据 `sourceType + profileId` 修改对应源表 `visible`；`custom-world` 同步 `custom_world_gallery_entry.visible`；`big-fish` 使用 `session_id`，`bark-battle` 使用 `work_id`。
+- [ ] spacetime-client 增加 list/update facade 和 mapper。
+
+### Task 4: 后台前端页面
+
+**Files:**
+- Modify: `apps/admin-web/src/api/adminApiTypes.ts`
+- Modify: `apps/admin-web/src/api/adminApiClient.ts`
+- Create: `apps/admin-web/src/pages/AdminWorkVisibilityPage.tsx`
+- Modify: `apps/admin-web/src/app/adminRoutes.ts`
+- Modify: `apps/admin-web/src/app/AdminShell.tsx`
+- Modify: `apps/admin-web/src/app/AdminApp.tsx`
+
+- [ ] 增加 API 类型和 client 方法。
+- [ ] 新增简洁表格页，显示玩法、标题、作者、公开码、更新时间、可见状态。
+- [ ] 修改可见性时使用 `useAdminWriteConfirm` 确认。
+- [ ] 接入后台导航和 route switch。
+
+### Task 5: 生成绑定与验证
+
+**Files:**
+- Generated: `server-rs/crates/spacetime-client/src/module_bindings*`
+- Generated: front-end shared bindings if generator updates them
+
+- [ ] Run: `npm run spacetime:generate`。
+- [ ] Run: `npm run check:spacetime-schema`。
+- [ ] Run: `cargo check -p spacetime-client --manifest-path server-rs/Cargo.toml`。
+- [ ] Run: `cargo check -p api-server --manifest-path server-rs/Cargo.toml`。
+- [ ] Run: `npm run admin-web:typecheck`。
+- [ ] Run: `npm run check:encoding`。
+
+### Task 6: 提交并推送
+
+**Files:**
+- All changed files
+
+- [ ] Inspect `git diff` and `git status --short --branch`。
+- [ ] Commit with message `feat: add admin work visibility controls`。
+- [ ] Push current branch `codex/visible-work-field`。

docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md

@@ -39,8 +39,21 @@
 - `sort_time_micros`
 - `detail_payload_json`
 
+作品源表新增 `visible` 可见性字段，默认 `true`。`visible` 属于源表 / source view 过滤条件，不作为统一公开契约默认返回字段；当 `visible=false` 时，对应作品不得进入 `public_work_gallery_entry` 和 `public_work_detail_entry`。
+
 其中 `detail_payload_json` 只承载平台详情页展示扩展，不承载正式 runtime 配置、玩法规则或草稿真相。
 
+## 后台可见性管理
+
+后台通过独立接口管理已发布作品的源表可见性：
+
+- `GET /admin/api/works/visibility`
+- `POST /admin/api/works/visibility`
+
+后台操作 key 使用统一的 `sourceType + profileId` 组合。`profileId` 在大多数玩法中对应作品 profile；特殊玩法维持既有源表身份：`big-fish` 对应 `session_id`，`bark-battle` 对应 `work_id`。`custom-world` 更新源表时必须同步 `custom_world_gallery_entry.visible`，避免兼容 gallery 缓存与统一公开 read model 出现可见性漂移。
+
+该后台能力只修改源表 / source view 过滤事实，不把 `visible` 暴露到公开列表或公开详情契约。隐藏作品后，统一 `public_work_gallery_entry` 与 `public_work_detail_entry` 不再返回该作品；恢复显示后重新进入公开 read model。
+
 ## 来源与兼容
 
 统一 public view 由现有玩法 source view 组装：
@@ -63,6 +76,8 @@
 - 旧 view 保留，不删除。
 - 旧 view 退到底层 source / 兼容职责。
 - 新 `public_work_*` view 是 `api-server` 公开列表 / 详情的统一主读模型。
+- 各玩法 source view 只暴露 `visible=true` 的已发布作品；旧数据迁移默认补 `visible=true`，避免历史作品被误隐藏。
+- 临时运行约束：SpacetimeDB 2.2 下抓大鹅 `match_3_d_gallery_view` 的 `publication_status` 索引过滤在源表更新触发统一 view 刷新时可能初始化 panic；为避免后台隐藏作品打爆 module instance，统一 `public_work_*` view 暂不级联抓大鹅 source view，抓大鹅公开入口先保留玩法专用路径。后续应以 source projection 表替代索引 view 后再重新并入统一 read model。
 - 旧 `/api/runtime/<play>/gallery` 响应 shape 保持兼容，由 BFF mapper 把统一 cache 再映射回当前 DTO。
 - 旧详情 / runtime / 点赞 / 游玩 / Remix 仍走玩法专用路径。
 

docs/【后端架构】server-rs与SpacetimeDB数据契约-2026-05-15.md

@@ -51,7 +51,7 @@ npm run check:server-rs-ddd
 路由树由 `server-rs/crates/api-server/src/app.rs` 统一构造。当前主要分组：
 
 - 健康检查：`GET /healthz`。
-- 后台管理：`/admin/api/*`，包括登录、概览、HTTP debug、埋点、表查询、创作入口开关、兑换码、邀请码、任务配置和充值商品配置。
+- 后台管理：`/admin/api/*`，包括登录、概览、HTTP debug、埋点、表查询、创作入口开关、作品可见性、兑换码、邀请码、任务配置和充值商品配置。
 - 认证与账号：`/api/auth/*`、`/api/profile/me`，包括短信、密码、微信、refresh session、多端会话和登出。
 - 个人中心：`/api/profile/*`，包括钱包流水、任务、领奖、充值、反馈、邀请、兑换、存档、历史浏览和游玩统计。
 - LLM 与语音：`/api/llm/*`、`/api/speech/volcengine/*`。
@@ -159,7 +159,7 @@ npm run check:server-rs-ddd
 ## 外部服务与资产
 
 - LLM：`GENARRATIVE_LLM_*`，创意 Agent 另用 `APIMART_BASE_URL` / `APIMART_API_KEY`。
-- 图片生成：VectorEngine `gpt-image-2` 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。APIMart 只保留给创意 Agent `gpt-5` Responses 文本 / 多模态链路；DashScope 只按仍在使用的历史能力单独处理，不作为 GPT-image-2 兜底。
+- 图片生成：VectorEngine `gpt-image-2` 图片 provider 归属 `platform-image`，密钥只在后端环境变量中；`api-server` 内的 `openai_image_generation.rs` 只是兼容调用面和外部失败审计桥接，不再承载 provider 协议实现。实际外部生成运行记录统一落 `tracking_event`，`event_key = external_generation_run`，metadata 记录开始 / 结束时间、耗时、状态、成功标记、失败原因、provider task id 和结果摘要，不再写回过时的 `ai_task`。APIMart 只保留给创意 Agent `gpt-5` Responses 文本 / 多模态链路；DashScope 只按仍在使用的历史能力单独处理，不作为 GPT-image-2 兜底。
 - Match3D 物品 sheet：关卡整图完成后走 VectorEngine `/v1/images/edits` multipart `image`，模型为 `gpt-image-2`，`2K 1:1` 输出 `10*10` spritesheet；物品 sheet prompt 固定要求纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG，并把透明整图写入 `itemSpritesheetImageSrc/itemSpritesheetImageObjectKey`。后端优先按透明 alpha 连通域从该 sheet 识别真实素材矩形并持久化 20 个物品、每个 5 个形态；识别数量不足时才回退 `10*10` 固定网格。通用系列素材图集的行列索引按每行 2 个物品计算，必须落在 `1..=10`，难度只决定运行态加载 3 / 9 / 15 / 20 种。
 - Match3D UI spritesheet 和背景派生图：关卡整图作为参考图并发生成 `1K 1:1` UI spritesheet 与 `1K 9:16` 背景图，模型均为 `gpt-image-2`。UI spritesheet prompt 固定要求纯绿色绿幕背景，后端上传 OSS 前必须把绿幕扣成透明 PNG；背景图必须合成为全画幅不透明 PNG。
 - Match3D 1:1 容器 UI：VectorEngine `/v1/images/edits` multipart 参考图。该容器参考图是后端生图协议输入，必须通过 `include_bytes!` 随 `api-server` 编译进二进制，避免 API 单独发布或运行目录缺少 `public/` 时生成失败。
@@ -168,6 +168,7 @@ npm run check:server-rs-ddd
 - 音频：视觉小说专用音频路由保留；VectorEngine Suno/Vidu provider 协议、任务提交/查询、音频 URL 提取、下载、MIME/extension 归一和 OSS put 请求准备归属 `platform-audio`。`api-server/src/vector_engine_audio_generation.rs` 只做路由、配置、计费、asset object confirm、entity binding 和错误 envelope 映射；拼图、抓大鹅和敲木鱼提示词生成音效入口暂时关闭，通用 `/api/creation/audio/*` 对这些目标返回 `410 Gone`。敲木鱼创作只接收上传 / 录音音频资产；未提供时由 `api-server` 写回内置默认木鱼音 `/wooden-fish/default-hit-sound.mp3`。
 - OSS：私有 generated legacy path 进入浏览器前必须通过 `/api/assets/read-url` 换签；不要裸请求 `/generated-*`。
 - 外部 API 失败审计：外部供应商调用未成功时，`api-server` 必须发送 OTLP 失败事件并写入 `tracking_event`。VectorEngine 图片 provider 在 `platform-image` 内输出结构化日志和 `PlatformImageFailureAudit`，覆盖 `request_send`、`response_body`、`upstream_status`、`response_parse`、`missing_image` 和 `image_download` 阶段；`api-server` 只把该 audit 映射成 `external_api_call_failure`，`scope_kind = module`、`scope_id = provider`、`module_key = external-api`。metadata 固定包含 provider、endpoint、operation、failureStage、statusCode、statusClass、timeout、retryable、errorMessage、latencyMs、promptChars、referenceImageCount、imageModel 和 rawExcerpt。入库优先复用 tracking outbox，outbox 不可写或保护阈值拒绝时回退同步写 SpacetimeDB；不得新增前端兜底或在 SpacetimeDB reducer 内做外部 I/O。
+- 外部生成运行记录：所有外部生成编排的完成态统一写入 `tracking_event`，`event_key = external_generation_run`，`scope_kind = module`，`scope_id = provider`，`module_key = external-generation`。metadata 固定包含 `runId`、`provider`、`operation`、`requestLabel`、`requestPayload`、`status`、`success`、`failureReason`、`providerRequestId`、`resultPayload`、`startedAtMicros`、`completedAtMicros` 和 `durationMs`。这类记录只用于运行审计和排障，不再走 `ai_task` 旧表。
 
 ## SpacetimeDB 表目录
 
@@ -233,6 +234,10 @@ npm run check:server-rs-ddd
 - Rust 结构体：`AuthStoreSnapshot`
 - 源码：`server-rs/crates/spacetime-module/src/auth/tables.rs`
 
+认证恢复策略：`api-server` 启动时只从 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）投影恢复进程内认证工作集；`auth_store_snapshot` 只保留行级快照备查，不再作为启动兜底来源。`module-auth` 只保留内存工作集和 JSON 导入 / 导出能力，不再写本地持久化文件；`auth-store.json` / `GENARRATIVE_AUTH_STORE_PATH` 不再是兼容恢复源，也不得在启动时回写覆盖 `auth_identity` / `user_account`。若启动恢复阶段 SpacetimeDB 不可连接或超时，`api-server` 进入依赖不可用模式并对请求返回 `503 SERVICE_UNAVAILABLE`，直到运维恢复 SpacetimeDB 并重启服务。
+
+`auth_store_snapshot` 禁止再写单行 `snapshot_id = "default"` 聚合 JSON。认证同步入口收到 `module-auth` 整份快照后必须拆成行级记录写入同一张表，当前行键前缀包括：`meta/next_user_id`、`user/<user_id>`、`phone/<phone+user>`、`session/<session_id>`、`session_hash/<hash+session>`、`wechat/<provider_uid+user>`、`union/<union+user>`。SpacetimeDB 模块只保留 `import_auth_store_snapshot_json` 与 `export_auth_store_snapshot_from_tables` 两个认证快照过程；旧 `get_auth_store_snapshot`、`upsert_auth_store_snapshot`、`import_auth_store_snapshot` 兼容入口已删除。导入正式表时只按主键 upsert 本次快照包含的用户、身份和会话，避免过期快照把其他用户整表删除。
+
 ### `bark_battle_draft_config`
 
 - Rust 结构体：`BarkBattleDraftConfigRow`
@@ -252,6 +257,7 @@ npm run check:server-rs-ddd
 
 - Rust 结构体：`BarkBattlePublishedConfigRow`
 - 源码：`server-rs/crates/spacetime-module/src/bark_battle/tables.rs`
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
 
 ### `bark_battle_runtime_run`
 
@@ -288,6 +294,7 @@ npm run check:server-rs-ddd
 - Rust 结构体：`BigFishCreationSession`
 - 源码：`server-rs/crates/spacetime-module/src/big_fish/tables.rs`
 - 索引：`by_big_fish_session_owner_user_id`、`by_big_fish_session_stage`。公开广场 view 使用 `by_big_fish_session_stage` 读取已发布会话，避免扫整表。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
 
 ### `big_fish_event`
 
@@ -351,11 +358,13 @@ npm run check:server-rs-ddd
 - Rust 结构体：`CustomWorldGalleryEntry`
 - 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
 - 作用：自定义世界公开 source 读模型。统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该投影并映射成跨玩法契约；`/api/runtime/custom-world-gallery` 保留旧 HTTP shape，并从统一 public cache 映射回旧 DTO。旧 procedure 只用于兼容旧库缺少 gallery 读模型行时的一次性同步兜底。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
 
 ### `custom_world_profile`
 
 - Rust 结构体：`CustomWorldProfile`
 - 源码：`server-rs/crates/spacetime-module/src/custom_world.rs`
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
 
 ### `custom_world_session`
 
@@ -410,6 +419,7 @@ npm run check:server-rs-ddd
 - 返回类型：`Vec<JumpHopGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/jump_hop.rs`
 - 说明：跳一跳公开详情兼容投影，包含作品、路径和素材字段；统一公开详情主路径通过 `public_work_detail_entry` 消费该 view，只保留平台详情页展示摘要。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
 
 ### `wooden_fish_agent_session`
 
@@ -445,6 +455,7 @@ npm run check:server-rs-ddd
 - 返回类型：`Vec<WoodenFishGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/wooden_fish.rs`
 - 说明：敲木鱼公开详情兼容投影，包含敲击物图案、背景环境图、主题返回按钮图、敲击音效和飘字配置；统一公开详情主路径通过 `public_work_detail_entry` 消费该 view，只保留平台详情页展示摘要。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
 
 ### `match3d_agent_message`
 
@@ -461,10 +472,12 @@ npm run check:server-rs-ddd
 - Rust 结构体：`Match3DRuntimeRunRow`
 - 源码：`server-rs/crates/spacetime-module/src/match3d/tables.rs`
 
-### `match3d_work_profile`
+### `match_3_d_work_profile`
 
 - Rust 结构体：`Match3DWorkProfileRow`
+- Rust accessor：`match_3_d_work_profile`
 - 源码：`server-rs/crates/spacetime-module/src/match3d/tables.rs`
+- 兼容说明：dev 现有 SpacetimeDB 元数据中的真实表名 / 索引名为 `match_3_d_work_profile` 与 `match_3_d_work_profile_*_idx_btree`。module 内部 accessor 必须与该 canonical name 对齐，避免 Rust SDK 在 `index_id_from_name` 初始化二级索引时查找 `match3d_work_profile_*` 并触发 `No such index` panic。`migration.rs` 仍兼容旧迁移包中的 `match3d_work_profile` 表名补默认字段。
 
 ### SpacetimeDB view：`match_3_d_gallery_view`
 
@@ -472,6 +485,7 @@ npm run check:server-rs-ddd
 - 返回类型：`Vec<Match3DGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/match3d.rs`
 - 说明：抓大鹅公开 source 投影，只暴露 `publication_status = published` 的作品卡片字段；统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该 view 并映射成跨玩法契约。个人作品列表、详情、发布、点赞、游玩记录和 Remix 仍按原有 procedure / reducer 路径处理。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
 
 ### `npc_state`
 
@@ -658,6 +672,7 @@ RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；
 结构化创作和 RPG 的 LLM JSON 链路默认不启用 Responses `web_search`；只有在明确需要联网增强时，才通过 `GENARRATIVE_RPG_LLM_WEB_SEARCH_ENABLED` 或 `GENARRATIVE_CREATION_AGENT_LLM_WEB_SEARCH_ENABLED` 显式打开。否则未开通工具的上游会先吐自然语言再返回 `ToolNotOpen`，这类失败要按上游工具不可用处理，不要误判成模型返回结果解析失败。
 
 统一公开作品 BFF 路由是 `GET /api/public-works` 与 `GET /api/public-works/{publicWorkCode}`，响应契约由 `shared-contracts::public_work` 和 `packages/shared/src/contracts/publicWork.ts` 共同维护。前端首期仍走 BFF HTTP，不直接订阅 SpacetimeDB；后续若允许浏览器直连订阅，也只能订阅 `public_work_gallery_entry` / `public_work_detail_entry` 这类稳定公开 read model，不能订阅 `puzzle_work_profile`、`custom_world_profile` 等源表后自行拼装列表。设计细节见 `docs/technical/【后端架构】统一公开作品ReadModel设计-2026-05-26.md`。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
 
 ### `quest_log`
 
@@ -710,6 +725,7 @@ RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；
 - 返回类型：`Vec<SquareHoleGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/square_hole.rs`
 - 说明：方洞挑战公开 source 投影，只暴露 `publication_status = published` 的作品卡片字段；统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该 view 并映射成跨玩法契约。个人作品列表、详情、发布、点赞、游玩记录和 Remix 仍按原有 procedure / reducer 路径处理。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。
 
 ### `story_event`
 
@@ -785,3 +801,4 @@ RPG 创作入口的配置 ID 是 `rpg`，当前 `visible=true`、`open=true`；
 - 返回类型：`Vec<VisualNovelGalleryViewRow>`
 - 源码：`server-rs/crates/spacetime-module/src/visual_novel.rs`
 - 说明：视觉小说公开 source 投影，只暴露 `publication_status = published` 的作品卡片字段，不把完整 `draft` 暴露给公开列表订阅；统一公开列表 / 详情主路径通过 `public_work_gallery_entry` / `public_work_detail_entry` 消费该 view 并映射成跨玩法契约。个人历史、详情、运行态和发布仍按原有 procedure / reducer 路径处理。
+- 字段变更：`visible` 控制是否进入公开列表 / 详情，默认 `true`；旧迁移数据由 `migration.rs` 补默认值。

docs/【开发运维】本地开发验证与生产运维-2026-05-15.md

@@ -193,6 +193,31 @@ UI 相关修改要重点验证：
 6. Jenkins 数据库导入 / 导出流水线会先加载 `scripts/jenkins-prepare-toolchain-env.sh`，显式补齐 Jenkins 用户的 Node、Cargo、SpacetimeDB 工具链目录；如果目标机器安装路径不同，用 `GENARRATIVE_JENKINS_TOOL_PATHS` 传入额外 `bin` 目录。
 7. 本地 `npm run dev` / `npm run dev:api-server` 若没有显式 `GENARRATIVE_SPACETIME_TOKEN`，会在 SpacetimeDB 就绪后调用 `/v1/identity` 创建当前进程专用 Web API identity token，并只注入本次 `api-server` 环境，不写回 `.env.local`。启动日志只打印 identity 前缀，禁止打印 token 明文；若仍出现 `subscribe ... 401 Unauthorized`，先确认是否绕过了项目 dev 脚本或是否连接到非本次启动的 SpacetimeDB server。
 
+### SpacetimeDB 数据目录 OSS 备份
+
+数据库备份不放进 `spacetime-module` reducer / procedure：备份属于文件系统与 OSS 外部副作用，必须由运维脚本在 SpacetimeDB 宿主外执行。当前统一脚本为；生产 provision 还会安装 `genarrative-database-backup.timer`，每天 `03:20` 左右自动执行一次 OSS 冷备份：
+
+```bash
+npm run database:backup:oss -- --data-dir /stdb --stop-service spacetimedb.service
+```
+
+脚本会将数据目录打包成 `tar.gz`，上传到 `oss://<bucket>/<prefix>/<database>/<database>-<UTC时间>.tar.gz`。生产建议做冷备份：传入 `--stop-service spacetimedb.service`，脚本会在打包前停止服务、打包后恢复服务，再上传 OSS。由于 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 原生快照或主备策略，不要直接在写入中的数据目录上做热拷贝并当作强一致备份。
+
+生产环境变量模板在 `deploy/env/api-server.env.example`：
+
+```env
+GENARRATIVE_DATABASE_BACKUP_DATA_DIR=/stdb
+GENARRATIVE_DATABASE_BACKUP_WORK_DIR=/var/lib/genarrative/database-backups
+GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET=
+GENARRATIVE_DATABASE_BACKUP_OSS_ENDPOINT=oss-cn-shanghai.aliyuncs.com
+GENARRATIVE_DATABASE_BACKUP_OSS_PREFIX=database-backups
+GENARRATIVE_DATABASE_BACKUP_KEEP_LOCAL=false
+GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID=
+GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET=
+```
+
+`GENARRATIVE_DATABASE_BACKUP_OSS_BUCKET` 为空时会回退 `ALIYUN_OSS_BUCKET`；AccessKey 默认复用 `ALIYUN_OSS_ACCESS_KEY_ID` / `ALIYUN_OSS_ACCESS_KEY_SECRET`，也可用 `GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_ID` / `GENARRATIVE_DATABASE_BACKUP_OSS_ACCESS_KEY_SECRET` 为备份 bucket 单独配置最小权限账号。`Genarrative-Server-Provision` 会创建 `/var/lib/genarrative/database-backups` 并归属 `genarrative:genarrative`，同时安装并启用 `genarrative-database-backup.timer`。手动检查定时器：`systemctl list-timers genarrative-database-backup.timer`；手动触发一次：`systemctl start genarrative-database-backup.service`。
+
 ## 生产运维
 
 生产部署当前口径：
@@ -207,6 +232,9 @@ Jenkins 按 web / api / Spacetime module / build / deploy / publish 拆分
 
 生产 Jenkins 的 `Pipeline script from SCM` 由 Windows controller 读取 Jenkinsfile，SCM URL 继续使用 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`。运行在 `linux && genarrative-build` 构建机上的 `Genarrative-Full-Build-And-Deploy` 源码解析阶段和 `Genarrative-Web-Build` checkout 阶段，优先使用 `http://127.0.0.1:3000/GenarrativeAI/Genarrative.git`，失败后回退到 `https://git.genarrative.world/GenarrativeAI/Genarrative.git`；两层 checkout 都必须保留单分支 refspec、`shallow=true`、`depth=1`、`noTags=true` 与 `honorRefspec=true`，后续二次源码确认继续走 `scripts/jenkins-checkout-source.sh`。
 
+
+`Genarrative-Stdb-Module-Publish` 在 `Pipeline script from SCM` 阶段如果一开始就报 `No such DSL method 'pipeline'`，优先检查 `jenkins/Jenkinsfile.production-stdb-module-publish` 是否带 UTF-8 BOM。Jenkins Declarative Pipeline 的首个 token 必须是纯 `pipeline`；仓库中的 Jenkinsfile 应保存为 UTF-8 without BOM，只有临时写给 Windows PowerShell 5.1 `-File` 执行的 `.ps1` 才需要按对应 helper 转成带 BOM。验证时可检查文件前三字节不再是 `EF BB BF`，并运行 `validateDeclarativePipeline` 或重放该流水线。
+
 `Genarrative-Stdb-Module-Build` 或 SpacetimeDB module 构建失败若出现 Rust `E0425 cannot find function migrate_*`，优先排查 `server-rs/crates/spacetime-module/src/runtime/creation_entry_config.rs` 等同文件内默认种子迁移 helper 是否在分支合并时只保留了调用、漏掉了函数定义。修复时不要直接删除迁移调用；应恢复只纠偏历史默认种子且不覆盖后台手动配置的 helper，并用 `cargo check -p spacetime-module --manifest-path server-rs/Cargo.toml` 复现 Jenkins module 编译路径。
 
 Windows Stdb module 构建流水线运行在 Jenkins `windows` 节点上。该流水线需要执行 PowerShell 逻辑时，统一通过 `bat` 显式调用 `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe`，不要直接使用 Jenkins `powershell` step；本地 Jenkins durable-task 曾在 `Genarrative-Stdb-Module-Build` workspace 中启动裸 `powershell` 时触发 `CreateProcess error=5, 拒绝访问`。临时 `.ps1` 由 Jenkins `writeFile` 写出后要先转成 UTF-8 with BOM 再交给 Windows PowerShell 5.1 `-File` 解析，避免中文错误消息在无 BOM UTF-8 下被当成本地 ANSI 误解码。Checkout 阶段要优先复用 Jenkins GitSCM 已经完成的结果：`COMMIT_HASH` 为空或与当前 `HEAD` 一致时，不要再额外 `git clean` / `git checkout`，只在确实需要切到别的指定 commit 时才补 fetch、校验和切换。排查时先看对应 build log、`@tmp/durable-*` 下的 `powershellWrapper.ps1`，以及日志中的 `[jenkins-powershell] user/exe`。
@@ -264,6 +292,7 @@ OpenTelemetry 现阶段默认开启 OTLP traces / metrics / logs，但本地日
 - `GENARRATIVE_SPACETIME_SERVER_URL`
 - `GENARRATIVE_SPACETIME_DATABASE`
 - `GENARRATIVE_SPACETIME_TOKEN`
+- `GENARRATIVE_DATABASE_BACKUP_*`
 - `GENARRATIVE_LLM_*`
 - `APIMART_*`
 - `VECTOR_ENGINE_*`
@@ -342,7 +371,7 @@ systemctl restart genarrative-api.service
 journalctl -u genarrative-api.service --since '30 seconds ago' --no-pager | grep -E 'tracking outbox|Permission denied|os error 13'
 ```
 
-`Genarrative-Server-Provision` 和 `Genarrative-Api-Deploy` 会在保留旧 `/etc/genarrative/api-server.env` 的前提下补齐缺失的 tracking outbox 与 auth-store 运行态路径，并确保 `/var/lib/genarrative/tracking-outbox`、`/var/lib/genarrative/auth` 归属 `genarrative:genarrative`。
+`Genarrative-Server-Provision` 和 `Genarrative-Api-Deploy` 会在保留旧 `/etc/genarrative/api-server.env` 的前提下补齐缺失的 tracking outbox 运行态路径，并确保 `/var/lib/genarrative/tracking-outbox` 归属 `genarrative:genarrative`。用户认证真相源只允许在 SpacetimeDB 正式认证表（`user_account` / `auth_identity` / `refresh_session`）恢复；不要再配置或依赖 `GENARRATIVE_AUTH_STORE_PATH` / `auth-store.json`，`module-auth` 也不再维护本地文件持久化；`auth_store_snapshot` 只保留行级记录，不再保存为单行 `default` 聚合快照，且旧 `get_auth_store_snapshot` / `upsert_auth_store_snapshot` / `import_auth_store_snapshot` 入口已经删除。如果 `api-server` 启动时连不上 SpacetimeDB，会等待启动恢复，超时后继续监听但进入依赖不可用模式，所有请求统一返回 `503 SERVICE_UNAVAILABLE`，错误详情包含 `reason=spacetime_startup_unavailable`，以避免用空本地状态或旧快照覆盖认证表。
 
 常用检查思路：
 
@@ -386,3 +415,24 @@ SELECT * FROM profile_recharge_product_config ORDER BY sort_order ASC;
 ## 文档维护
 
 当前 `docs/` 只保留少量融合文档。新增稳定知识时优先更新现有文档；只有现有文档无法容纳时才新增带 `【标签名】` 的 Markdown。阶段性流水账、一次性修复记录和已关闭实验不要再新增成长期文档。
+
+## 微信登录与孤儿作品归属处理
+
+- 微信新用户的 `username` 统一拼为 `名字_openid`；若昵称或 openid 为空，则分别回退到 `微信旅人` 和 `openid`。
+- 微信新用户的内部 `user_id` 改为不可复用的 `user_` 前缀 UUID 风格，避免清库后旧作品被后来的顺序号账号顶替。
+- 当作品作者的 `owner_user_id` 找不到真实账号时，作品统一显示为占位作者：`失效作者`，公开陶泥号固定为 `SY-00000000`，占位账号 ID 为 `wx-openid-placeholder`。
+- 该占位账号只用于作品作者域，不扩展到全站其它身份域。
+- 如需把历史孤儿作品批量回填到占位作者，使用 `scripts/rebind-orphan-work-owners.mjs` 先基于当前 auth 快照识别有效用户，再把缺失作者对应的作品表写回为占位 ID；脚本输入输出都基于 SpacetimeDB 迁移 JSON。
+
+### 回填脚本用法
+
+```bash
+node scripts/rebind-orphan-work-owners.mjs --in <exported-migration.json> --out <rebound-migration.json>
+node scripts/rebind-orphan-work-owners.mjs --in <exported-migration.json> --dry-run
+node scripts/rebind-orphan-work-owners.mjs --in <exported-migration.json> --out <rebound-migration.json> --placeholder-user-id wx-openid-placeholder
+```
+
+- `--in`：SpacetimeDB 导出的迁移 JSON。
+- `--out`：写回后的迁移 JSON 输出路径。
+- `--dry-run`：只统计回填行数，不写文件。
+- `--placeholder-user-id`：需要时可覆盖默认占位账号 ID。

docs/【玩法创作】平台入口与玩法链路-2026-05-15.md

@@ -42,7 +42,7 @@
 
 1. 草稿页作品卡对齐发现页列表卡风格：左侧信息，右侧封面图，移动端单列，桌面两到三列。
 2. 草稿页顶部 `全部 / 草稿 / 已发布` 筛选与发现页 `推荐 / 今日 / 分类 / 排行` 频道标签复用同一选中 / 未选中视觉，即 `platform-mobile-home-channel` 与 `platform-mobile-home-channel--active`，不再使用旧 `platform-tab` 胶囊样式。
-3. 草稿页与底部导航的未读提示点统一使用平台暖棕色点和暖棕光晕，不再使用红点或红色 glow；草稿 Tab 作品架卡片无论草稿 / 已发布都不外露作者信息；已发布作品卡右上角直接显示无边框分享 icon。删除等破坏性动作继续收口到左滑或长按操作层。
+3. 草稿页与底部导航的未读提示点统一使用平台暖棕色点和暖棕光晕，不再使用红点或红色 glow；草稿 Tab 作品架卡片无论草稿 / 已发布都不外露作者信息；已发布作品卡右上角直接显示无边框分享 icon。删除等破坏性动作在作品卡上也要直接开放独立删除入口，左滑或长按仅作为辅助操作层。
 4. 生成中作品在整卡上加等待遮罩，但不移除作品基础信息。
 5. 生成中状态不能只存在前端内存 notice。后端作品摘要必须下发可恢复的 `generationStatus`；前端刷新或退出产品后，作品架优先用摘要状态恢复等待遮罩，本轮内存 notice 只作为即时反馈。
 6. 点击 `generationStatus=generating` 的草稿卡必须恢复对应玩法的生成进度页，不能进入空白结果页或普通工作区；恢复生成页的 `startedAtMs` 使用进入生成页的当前时间，作品摘要 `updatedAt` 只用于排序和摘要展示，不参与假进度起算。
@@ -276,7 +276,7 @@ RPG / 拼图等运行态存档仍以 `/api/profile/save-archives` 的后端列
 - 创作 Tab 表单：填写作品标题、简介、主题 / 竞技背景描述、玩家形象描述、对手形象描述、拟声词和难度。拟声词支持换行、逗号、顿号、斜杠或竖线分隔；未手动编辑时随主题 / 形象描述自动重算，手动编辑后保持创作者自定义。
 - 草稿编译：`POST /api/creation/bark-battle/drafts` 写入配置 JSON，返回包含 `draftId`、稳定 `workId`、`configVersion` 和 `rulesetVersion` 的草稿结果。
 - 生成页：`bark-battle-generating` 自动并行产出玩家形象、对手形象和竞技背景三图；前端生成页 UI 和其它玩法保持同一圆环主视觉，`media/create_bg_video.mp4` 作为固定全屏页面背景层循环静音播放，主进度圆环居中展示总进度，只保留当前步骤名称和当前步骤进度，不再渲染三行槽位列表。视频层需要显式触发播放。三图都走 Bark Battle 专用后端生图接口 `POST /api/creation/bark-battle/images/generate`，由后端按 `player-character`、`opponent-character`、`ui-background` 分别拼装正式提示词、写入 `generated-bark-battle-assets` 私有资产前缀并返回实际 prompt。玩家 / 对手形象提示词必须保持用户形象描述，不强行注入狗相关主体，并要求正面、单个完整形象和透明背景。部分失败也继续进入结果页。
-- 结果页：围绕三图槽位展示错误态与已生成结果，只保留单槽重试、重新生成和上传，不再提供一次生成按钮、音频配置入口或排名配置。
+- 结果页：围绕三图槽位展示错误态与已生成结果，只保留单槽重试、重新生成和上传，不再提供一次生成按钮、音频配置入口或排名配置；生成回写 `partial_failed` 时作品架不再显示整卡“生成中”遮罩，由结果页槽位错误承接失败。
 - 手动上传：结果页通过平台资产直传 `/api/assets/direct-upload-tickets` 与 `/api/assets/objects/confirm` 写入私有资产，再把返回的历史 generated 路径写回草稿配置。
 - 发布：结果页确认后必须携带草稿返回的同一个 `workId` 和结果页最终 `publishedSnapshot` 调用 `POST /api/creation/bark-battle/works/publish`；SpacetimeDB 发布态的 `config_json` 必须使用该最终快照，works summary 若拿到 `publishedSnapshotJson` 也优先使用最终快照映射封面三图。发布成功后先进入统一作品详情页，再由详情页进入正式 runtime；缺少 `workId` 的旧草稿状态需要重新生成草稿。
 - 作品架：Bark Battle 草稿 / 已发布列表优先读取后端 `/works`，但创建、生成完成、保存或发布后的本地摘要必须在后端 read model 尚未回读到同 `workId` 前继续保留；创作中心作品架同时接入 pending shelf 兜底，避免 ready 且三图齐全的草稿在刷新窗口期从“我的草稿 / 已发布”中消失。

docs/【玩法创作】生成页圆环布局口径-2026-05-23.md

@@ -12,8 +12,8 @@
 - 生成页背景视频必须留在生成页容器内部，直接作为 `fixed inset-0` 的底层背景，不要再通过 portal 挂到 `document.body`；页面根容器使用 `z-[1]`、背景容器使用 `z-0`，确保顶部导航、圆环和当前步骤卡都稳定覆盖在视频之上。
 - 预计等待 / 已耗时信息卡要压缩为更轻的半透明窄卡，标签使用 `9px-10px`，数值使用 `12px-13px`，字号对齐其他生成页 UI 的小字号，不再使用偏大的提示文本；卡片标题和时间值都居中显示，两个数值只展示时间本身，调用侧不要再拼接“预计还需”或“已耗时”前缀。圆环中心不再保留独立白底块，空心圆环只保留条状进度，圆弧半径继续加大，进度数字与“总进度”标题整体上移，靠近圆环上半区。
 - 顶部导航区采用“返回创作中心 / 状态胶囊”结构，返回按钮使用左箭头图标，字号使用 `text-xs-sm`，状态胶囊使用 `11px-12px`，展示 `素材生成中`、`草稿生成中` 等调用侧传入文案。
-- 圆弧区域不再包独立大卡片，左右悬浮信息卡只展示“预计等待”和“已耗时”；总进度数值放在圆弧内侧偏上的位置并保持更小字号。当前圆环外径以 `w-[min(35rem,94vw)] sm:w-[52rem]` 为基准，圆弧使用 `r=166`、`strokeWidth=18` 的 SVG 描边，不再使用 `conic-gradient + mask`，避免进度条边缘模糊。
-- 圆弧描边以圆心为中心整体按 `155deg` 起始；在当前 SVG 坐标系下，这相对 `160deg` 会向左逆时针回调 `5deg`。track 和 fill 都必须共用同一个 `rotate(155 200 200)` 变换，避免只改视觉起点却让填充和轨道错位。
+- 圆弧区域不再包独立大卡片，左右悬浮信息卡只展示“预计等待”和“已耗时”；总进度数值放在圆弧内侧偏上的位置并保持更小字号。圆环本体固定在 `400x400` 的 SVG 画布上，圆弧使用 `r=166`、`strokeWidth=18` 的 SVG 描边，不再跟随页面宽度缩放，也不再使用 `conic-gradient + mask`，避免进度条边缘模糊。
+- 圆弧描边以圆心为中心整体按 `135deg` 起始；`270deg` 扫描角配合 `90deg` 正下方缺口时，轨道和填充都从同一个对称起点出发，轨道保持 `rotate(135 200 200)`，填充端点也使用 `rotate(135 200 200)`。圆环本体尺寸固定，不允许再随容器边长伸缩，只能由外层布局决定放置位置。
 - 总进度标题和百分比数字必须显式高于 SVG 圆环层级渲染，避免被圆环边缘压住；圆环本身只做背景层，不抢文字层。
 - 总进度标题和百分比数字要比圆环再上移一点，当前内容区上边距以 `pt-[2%]` 为准，桌面端可进一步微调到 `sm:pt-[1.5%]`，确保数字不与进度条弧线重合。
 - 从作品架或刷新后的持久化生成中草稿进入生成页时，前端必须重置“展示态 startedAtMs”为进入生成页的当前时间；后端 `progressPercent` 只用于后续真实步骤推进，不得参与首帧总进度展示，避免恢复生成页首帧直接显示 `80%+`。
@@ -27,5 +27,5 @@
 - `src/components/CustomWorldGenerationView.test.tsx` 覆盖圆环主视觉和单步卡片。
 - `src/components/bark-battle-creation/BarkBattleGeneratingView.test.tsx` 覆盖汪汪声浪生成页对齐后的圆环布局。
 - 两个生成页都应在测试里断言页面根容器层级高于背景视频容器，且背景视频确实是页面子节点，避免 portal 背景把业务 UI 压住。
-- 还应断言圆弧正下方留空、圆环中心没有独立底色块，时间卡和总进度字号缩小后仍能在桌面与移动端正常排版；同时断言时间卡 `text-center`、标题行 `justify-center`、总进度内容区上移到 `pt-[4%]`，圆弧 DOM 为 SVG，包含清晰的 track/fill circle 描边。
+- 还应断言圆弧正下方留空、圆环中心没有独立底色块，时间卡和总进度字号缩小后仍能在桌面与移动端正常排版；同时断言时间卡 `text-center`、标题行 `justify-center`、总进度内容区上移到 `pt-[2%]`，桌面端保持 `sm:pt-[1.5%]`，圆弧 DOM 为 SVG，包含清晰的 track/fill circle 描边。
 - 页面在桌面和移动端都不应再出现生成步骤列表块，圆环和当前步骤卡不能被外层卡片嵌套出双层面板感。

jenkins/Jenkinsfile.production-stdb-module-publish

@@ -27,6 +27,7 @@ pipeline {
     string(name: 'SPACETIME_ROOT_DIR', defaultValue: '/stdb', description: 'spacetime CLI root-dir；需与自托管 spacetimedb.service 一致')
     string(name: 'SPACETIME_RUN_AS_USER', defaultValue: 'spacetimedb', description: '执行 spacetime publish 的本机用户，默认使用自托管服务用户')
     booleanParam(name: 'CLEAR_DATABASE', defaultValue: false, description: '是否清空数据库后发布')
+    choice(name: 'DATABASE_BACKUP_MODE', choices: ['async', 'sync', 'skip'], description: '数据库备份策略：async 在 publish 前生成本地冷备份、后台上传 OSS；sync 在 publish 前等待上传完成且失败阻断；skip 跳过')
   }
 
   stages {
@@ -138,6 +139,22 @@ pipeline {
       steps {
         script {
           def clearArg = params.CLEAR_DATABASE ? '--clear-database' : ''
+          def backupMode = params.DATABASE_BACKUP_MODE?.trim() ? params.DATABASE_BACKUP_MODE.trim() : 'async'
+          if (!(backupMode in ['async', 'sync', 'skip'])) {
+            error("DATABASE_BACKUP_MODE 只能是 async、sync 或 skip: ${backupMode}")
+          }
+          def publishScriptPath = 'scripts/deploy/production-stdb-publish.sh'
+          def publishScriptText = readFile(file: publishScriptPath, encoding: 'UTF-8')
+          def publishScriptSupportsBackupMode = publishScriptText.contains('--backup-mode')
+          def backupArg = ''
+          if (publishScriptSupportsBackupMode) {
+            backupArg = "--backup-mode \"${backupMode}\""
+          } else if (backupMode == 'sync') {
+            error('当前工作区的 scripts/deploy/production-stdb-publish.sh 还不支持 --backup-mode，无法保证 sync 语义。请先更新工作区脚本后再运行。')
+          } else {
+            echo "[Jenkins] 当前工作区脚本还不支持 --backup-mode，async/skip 自动降级为 --skip-backup，避免参数不兼容导致发布失败。"
+            backupArg = '--skip-backup'
+          }
           def rootArg = "--root-dir \"${params.SPACETIME_ROOT_DIR?.trim() ? params.SPACETIME_ROOT_DIR.trim() : '/stdb'}\""
           def runAsArg = params.SPACETIME_RUN_AS_USER?.trim()
             ? "--run-as-user \"${params.SPACETIME_RUN_AS_USER.trim()}\""
@@ -155,7 +172,8 @@ pipeline {
                 ${rootArg} \\
                 ${runAsArg} \\
                 ${serverArg} \\
-                ${clearArg}
+                ${clearArg} \\
+                ${backupArg}
             '
           """
         }

package.json

@@ -61,7 +61,8 @@
     "codegraph:init": "codegraph init -i .",
     "codegraph:index": "codegraph index .",
     "codegraph:sync": "codegraph sync .",
-    "codegraph:status": "codegraph status ."
+    "codegraph:status": "codegraph status .",
+    "database:backup:oss": "node scripts/database-backup-to-oss.mjs"
   },
   "dependencies": {
     "@tailwindcss/vite": "^4.1.14",