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

作品可见性后台管理 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。