merge: admin work visibility controls

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,7 @@
 - 旧 view 保留，不删除。
 - 旧 view 退到底层 source / 兼容职责。
 - 新 `public_work_*` view 是 `api-server` 公开列表 / 详情的统一主读模型。
+- 各玩法 source view 只暴露 `visible=true` 的已发布作品；旧数据迁移默认补 `visible=true`，避免历史作品被误隐藏。
 - 旧 `/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/*`。
@@ -257,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`
 
@@ -293,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`
 
@@ -356,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`
 
@@ -415,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`
 
@@ -450,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`
 
@@ -477,6 +483,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`
 
@@ -663,6 +670,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`
 
@@ -715,6 +723,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`
 
@@ -790,3 +799,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` 补默认值。