GenarrativeAI/Genarrative
11
0
Fork 0
Code Issues 39 Pull Requests 9 Actions Packages Projects 1 Releases Wiki Activity
Files
0d0166c2d9bdf10735a3ef12b8ac38b6123ff513
Genarrative/server-rs/crates/api-server
T
History
suzmii 0d0166c2d9
Project CI / AI game creator shell Rust lane 1/2 (pull_request) Has been cancelled
Details
Project CI / AI game creator shell Rust lane 2/2 (pull_request) Has been cancelled
Details
Project CI / Native shell tests (pull_request) Has been cancelled
Details
Project CI / Frontend tests (pull_request) Has been cancelled
Details
Project CI / Repository checks (pull_request) Has been cancelled
Details
Project CI / AI game creator shell Rust crates (pull_request) Has been cancelled
Details
Project CI / Backend tests (pull_request) Has been cancelled
Details
Project CI / AI game creator shell web tests (pull_request) Has been cancelled
Details
feat(游戏共创): 后台读取主题成员名单（含草稿/归档主题与不可见成员 + 可见性列） 
缺口：后台原先只能借**公开投影** `GET /api/game-distribution/themes/{themeId}` 列成员，而公开投影只服务
`published` 主题 ⇒ **草稿 / 已归档主题在后台看不到成员名单**，运营没法在发布前核对。

新增 `GET /admin/api/game-distribution/themes/{theme_id}/members?limit=&cursor=`：

- **鉴权照既有两层**：路由挂既有 admin 支的 `route_layer(require_admin_auth)`，handler 取
  `Extension<AuthenticatedAdmin>`（未登录/失效 → 401 `UNAUTHORIZED`、非 admin → 403，同组同码同形）；
  模块侧 procedure 先跑 `require_editor_generation_runtime_service_identity`（照 `033e3aa79` 五条写接口）。
- **返回全部成员行，不套公开可见性过滤**，且**不要求主题已发布**（`draft` / `archived` 照常可读；
  只有主题真的不存在才 404 `THEME_NOT_FOUND`）。响应：
  `{ themeId, totalMembers, members: [{ rootGameId, title, sortOrder, createdAt, visible, visibility }], nextCursor }`。
- **两个可见性字段刻意独立**：
  · `visible` = 「公开侧此刻会不会出现」，**复用** `game_distribution_theme_member_visible`（未删 + 已公开
    + 有当前公开版本），不另写第二套判定；
  · `visibility` = 更细状态（新纯函数）：游戏行不存在 → `missing`（优先于 `deleted`），软删除行 → `deleted`，
    否则原样透传游戏行 `visibility`（`published` / `unpublished` / `suspended`）。
    因此 `visibility == "published"` 但无当前公开版本时 `visible = false` ——运营能看出「公开了但没公开版本」；
    三处钉住这个组合（纯函数单测、api-server payload 单测、事务结构断言）。
- **排序与分页照既有口径**：复用 `sort_theme_members`（`sort_order` 升序 + 成员 id 兜底）+ 新增
  `page_admin_theme_members`；`limit` 缺省 20 / 上限 50 / `0` 取默认 / 超界截断（同一归一化）；
  游标 `"{sortOrder}:{memberId}"`，解析**只委托** `parse_game_distribution_theme_cursor` ⇒ 非法游标仍是
  上一轮刚修好的**可达** `THEME_INVALID_CURSOR`（不另造一个不可达码）；`totalMembers` 是成员**行**总数，
  切页前算，不受分页影响。
- **契约与登记**：`packages/shared/src/contracts/gameDistribution.ts` 新增
  `GameDistributionAdminThemeMemberRow` / `…ListResponse` / `…MemberVisibility`；parity 登记
  `TS_ONLY_TYPES` +3、`RESPONSE_BUILDERS` +2（列表响应与单条成员各一条，条目形状有独立证据）；api-server
  用命名构建器（不内联 `json!`）。
- **测试**：module-game-distribution +5 条纯函数（`missing` 优先于 `deleted`、三类不可见各一条并断言
  `visible`/`visibility` 组合、`published` 无公开版本 ⇒ `visible=false`、游标委托共享实现、翻页不重不漏、
  末页 null、复用共享比较器与同一归一化）；spacetime-module +1 并扩 2（结构断言：走主题索引、不套公开可见性
  过滤、不复用「只取可见成员」的助手、不自写排序、不删行、`totalMembers` 在切页前取）；spacetime-client +1
  mapper（行总数与游标透传、两个可见性字段不互相推导、空名单是正常结果）；api-server 例（401/403、草稿主题
  可读、含不可见成员仍返回、`totalMembers` 不受分页影响、limit 缺省与截断、非法游标 → 400 `THEME_INVALID_CURSOR`、
  主题不存在 → 404）。
- **文档**：技术方案 `§3.10.8`（新行 + `visible`/`visibility` 语义 + 「草稿也能读」的理由）与 `§3.4` 后台接口表；
  里程碑（后台路由清单、实施清单、验收与测试清单，原「只能借公开投影」的留白项标记为已落地）。
- **生成绑定**：新增 4 个 `admin_theme_member_list*` / `list_admin_…_procedure` 生成文件 + `module_bindings.rs`
  入口；wire format 有新增（新 procedure/结果类型）⇒ 部署需重新 publish 模块。

门禁：wasm build 0；`cargo check --all-targets` 0；`cargo test -p api-server game_distribution` **89 passed**；
`cargo test -p module-game-distribution` **106 passed**；`cargo test -p spacetime-module` **287 passed** / 1 ignored；
`cargo test -p spacetime-client` 39 passed；DTO parity 0（58 组 / **17** 构建器 / **15** 手拼类型）；
`check:spacetime-schema` 0（96 tables）；`check:encoding` 0（5424 files）；`cargo fmt --all -- --check` 0；
`git diff --check` 0。

不在本提交内（属另一个 session 的文件，工作区里由我的子代理顺带做了**纯新增性**改动，未提交）：
`apps/admin-web/src/api/adminGameThemeTypes.ts` 增加了三个指向共享契约新类型的别名 + 一段注释 —— 与该 session
「登记好之后改回引用共享契约」的计划一致，交由其 review / 提交（或直接删掉其本地重复定义）。
2026-10-06 04:28:39 +08:00
..
config
完成 SFX V2 T5 正式生成链路
2026-08-07 06:13:34 +00:00
prompts/external_mcp
升级mcp，增加按语义分类的工具。旧工具不变 (#493)
2026-09-24 17:19:45 +08:00
src
feat(游戏共创): 后台读取主题成员名单（含草稿/归档主题与不可见成员 + 可见性列）
2026-10-06 04:28:39 +08:00
Cargo.toml
补充创作者主页与关注粉丝工程文档 (#638)
2026-10-05 22:05:11 +08:00
README.md
清理旧创作模板退役过程记录与死代码 (#489)
2026-09-23 11:46:39 +08:00

README.md

api-server 主工程 crate 占位说明

日期：2026-04-20

1. crate 职责

api-server 是新后端的 Axum 主工程 crate，后续负责：

  1. main.rs 启动入口
  2. Router 装配
  3. with_state 共享状态注入
  4. 中间件挂载
  5. /healthz、/api/*、SSE 与静态资源兼容层装配
  6. 由 ../../scripts/dev.ps1 与 ../../scripts/dev.sh 驱动的本地开发启动链路
  7. 由 ../../scripts/test.ps1 与 ../../scripts/test.sh 驱动的本地测试链路
  8. 由 ../../scripts/check.ps1 与 ../../scripts/check.sh 驱动的本地统一检查链路
  9. 由 ../../scripts/smoke.ps1 与 ../../scripts/smoke.sh 驱动的本地启动与协议冒烟链路

2. 当前阶段说明

当前目录已经完成以下基础骨架：

  1. 目录占位
  2. Cargo.toml
  3. src/main.rs
  4. src/app.rs
  5. src/state.rs
  6. src/config.rs
  7. 基础 TraceLayer 挂载
  8. 接入 shared-logging 完成 tracing subscriber 初始化
  9. 接入 POST /api/auth/entry 首版密码登录链路
  10. 接入 POST /api/auth/password/change 登录后修改密码链路
  11. 接入 POST /api/auth/password/reset 手机验证码重置密码链路
  12. 接入 POST /api/assets/direct-upload-tickets 直传票据接口
  13. 接入 GET /api/auth/me 当前用户查询链路
  14. 接入 POST /api/auth/refresh refresh token 轮换链路
  15. 接入 POST /api/auth/logout 当前设备退出链路
  16. 接入 POST /api/assets/objects/confirm 上传完成确认链路
  17. 接入 GET /api/auth/login-options 登录方式探测链路
  18. 接入 POST /api/auth/phone/send-code 手机验证码发送链路
  19. 接入 POST /api/auth/phone/login 手机验证码登录链路
  20. 接入 GET /api/auth/wechat/start 微信授权起跳链路
  21. 接入 GET /api/auth/wechat/callback 微信回调换取系统登录态链路
  22. 接入 POST /api/auth/wechat/bind-phone 微信待绑定账号补绑手机号链路
  23. 接入 POST /api/assets/objects/bind 已确认对象绑定业务实体槽位链路
  24. 接入 POST /api/assets/sts-upload-credentials 禁用式 STS 写权限 contract
  25. 接入 POST /api/assets/character-visual/generate
  26. 接入 GET /api/assets/character-visual/jobs/{task_id}
  27. 接入 POST /api/assets/character-visual/publish
  28. 接入 GET /api/assets/character-animation/templates
  29. 接入 POST /api/assets/character-animation/import-video
  30. 接入 GET /api/assets/character-workflow-cache/{character_id}
  31. 接入 POST /api/assets/character-workflow-cache
  32. 接入 POST /api/assets/character-animation/generate
  33. 接入 GET /api/assets/character-animation/jobs/{task_id}
  34. 接入 POST /api/assets/character-animation/publish
  35. 生成资产读取统一走 /api/assets/read-url 或 asset object projection

后续与本 crate 直接相关的任务包括：

  1. 接入统一日志与 tracing
  2. 接入 request_id
  3. 接入统一错误处理中间件
  4. 接入 response envelope
  5. 接入 /healthz
  6. 接入 /api/auth/entry
  7. 接入 /api/assets/direct-upload-tickets
  8. 接入 /api/auth/me
  9. 接入 /api/auth/refresh
  10. 接入 /api/auth/logout
  11. 接入 /api/assets/objects/confirm
  12. 接入 /api/auth/login-options
  13. 接入 /api/auth/phone/send-code
  14. 接入 /api/auth/phone/login
  15. 接入 /api/auth/wechat/start
  16. 接入 /api/auth/wechat/callback
  17. 接入 /api/auth/wechat/bind-phone
  18. 接入 /api/assets/objects/bind
  19. 接入 /api/assets/sts-upload-credentials
  20. 接入 character-visual generate / jobs / publish 第一批 OSS 主链
  21. 接入 character-animation templates / import-video 第一批 OSS 草稿链路
  22. 接入 character-workflow-cache get / save 第一批 OSS JSON 草稿链路
  23. 接入 character-animation generate / jobs / publish 第一批 OSS 主链
  24. 生成资产读取统一走 /api/assets/read-url 或 asset object projection

当前 tracing 约定：

  1. 进程启动时通过 shared-logging 统一初始化 tracing subscriber。
  2. 默认日志过滤器来自 GENARRATIVE_API_LOG，未提供时回落到 info,tower_http=info。
  3. HTTP 访问日志统一通过 Axum 路由层的 TraceLayer 输出，后续 request_id、响应头与错误中间件继续在同一层扩展。
  4. 本地启动器 npm run dev:api-server 和完整联调入口 npm run dev 会在保留终端实时输出的同时，把同一份 cargo / api-server 输出持久化到 logs/api-server/。如需固定文件或目录，可设置 GENARRATIVE_API_SERVER_LOG_FILE 或 GENARRATIVE_API_SERVER_LOG_DIR。

当前 request context 约定：

  1. 中间件优先读取来访 x-request-id，未提供时生成新的 UUID。
  2. request_id 会统一写入请求 extensions 与请求头，供 tracing、错误处理中间件和响应头层复用。
  3. 最终响应会回写同一个 x-request-id，保证调用方、日志链路和后续 envelope meta.requestId 可对齐。

当前错误处理中间件约定：

  1. 对 Axum 默认产生的空 4xx / 5xx 响应，统一归一化为 legacy 兼容 JSON 错误体：{ error: { code, message, details? } }。
  2. 已经带 content-type 的业务错误响应不会被覆盖，避免抢走后续 response envelope 的职责。
  3. 统一错误日志会复用当前请求的 request_id，便于后续和响应头、envelope 元信息串联。

当前 response envelope 约定：

  1. RequestContext 已记录 request_id、请求开始时间、默认 operation 与 envelope 协商结果。
  2. json_success_body(...) / json_error_body(...) 会根据 x-genarrative-response-envelope 自动在“裸数据 / 标准 envelope / legacy error + meta”之间切换。
  3. meta.apiVersion、meta.requestId、meta.routeVersion、meta.operation、meta.latencyMs、meta.timestamp 已按当前前端契约生成，响应头回写仍留给后续独立任务。

当前基础响应头约定：

  1. 所有响应都会回写 x-request-id。
  2. 所有响应都会回写固定的 x-api-version，值来自 shared_contracts::api::API_VERSION，当前为 2026-06-16，并与 body meta.apiVersion 保持一致。
  3. 所有响应都会回写 x-route-version，当前阶段默认与 x-api-version 保持一致，后续再按路由粒度细分。
  4. 所有响应都会回写 x-response-time-ms，值来源于 RequestContext 内记录的请求开始时间。

当前 /healthz 约定：

  1. 路径固定为 /healthz。
  2. 裸响应继续返回 { ok: true, service: "genarrative-node-server" }，保持与当前 Node 工程兼容。
  3. 当请求携带 x-genarrative-response-envelope 时，/healthz 会返回标准 success envelope。
  4. x-request-id、x-api-version、x-route-version、x-response-time-ms 会在 /healthz 响应中一并回写。

当前本地检查链路约定：

  1. ../../scripts/check.ps1 与 ../../scripts/check.sh 统一串联 cargo fmt --all --check、cargo clippy、cargo check、cargo test。
  2. 默认检查整个 server-rs workspace，确保后续多 crate 扩容时仍然保持统一口径。
  3. 当只需聚焦单个 crate 时，可通过 -Package 或 SERVER_RS_CHECK_PACKAGE 收窄 clippy / check / test 目标。
  4. cargo fmt --all --check 仍固定覆盖整个 workspace，避免多 crate 下格式基线漂移。

当前本地 smoke 链路约定：

  1. ../../scripts/smoke.ps1 与 ../../scripts/smoke.sh 会先构建 api-server，再拉起临时本地进程完成冒烟验证。
  2. smoke 当前固定校验 /healthz 的 raw 响应、envelope 响应以及 x-request-id、x-api-version、x-route-version、x-response-time-ms 头。
  3. smoke 通过后，可作为“Axum 服务可独立启动且基础 contract 可联通”的本地自动化证据。

3. 边界约束

  1. api-server 负责 HTTP、SSE、Cookie、Header、路由与协议装配。
  2. 业务逻辑优先通过独立模块 crate 暴露能力，再由主工程组合。
  3. 外部副作用通过 platform-auth、platform-oss、platform-llm 与各模块 crate 的应用层完成。
  4. 不把领域规则直接堆在 handler 中。
  5. 当前密码登录由 module-auth 负责用例编排，api-server 只负责请求解析、JWT 签发与 refresh cookie 写回。
  6. 当前 /api/auth/me 复用现有 Bearer JWT 中间件与 module-auth 用户快照查询，不直接绕过模块边界读取内部状态。
  7. 当前 /api/auth/refresh 复用 module-auth 的 refresh session 轮换能力，api-server 负责 refresh cookie 读取、失败清理与 access token 重签。
  8. 当前 /api/auth/logout 复用 module-auth 的当前会话吊销与用户版本递增能力，api-server 负责 Bearer JWT、refresh cookie 读取与清理 cookie 回写。
  9. 当前 /api/assets/objects/confirm 先由 platform-oss 完成私有 HEAD Object 校验，再通过 spacetime-client 调用 spacetime-module 的对象确认持久化入口。
  10. 当前 /api/assets/objects/bind 只绑定已确认对象到业务实体槽位，不访问 OSS，不创建悬空 asset_object_id。
  11. 当前手机号登录与微信登录都复用 module-auth 的进程内认证仓储，api-server 负责请求解析、场景判定、系统 JWT 签发与 refresh cookie 写回。
  12. 当前微信回调不会把第三方 token 直接透传给前端或 SpacetimeDB，而是统一换成系统签发的 JWT。
  13. 当前 /api/assets/sts-upload-credentials 按“服务器上传、Web 只下载”口径固定返回 403，不向浏览器下发 OSS 写权限。
  14. 当前 /api/assets/character-visual/* 第一批只保证现役接口 contract、OSS 草稿/正式对象、asset_object 与 asset_entity_binding 主链可用；真实图片模型、workflow cache 与本地角色覆盖写回仍在后续阶段。
  15. 当前 /api/assets/character-animation/import-video 第一批只接受 data:video/*;base64,... 并写入 OSS 草稿区，不读取旧本地 public/ 路径，也不创建正式 asset_object。
  16. 当前 /api/assets/character-workflow-cache/* 第一批只把工作流 JSON 草稿写入 OSS，不迁移历史本地缓存，也不创建正式 asset_object。
  17. 当前 /api/assets/character-animation/generate 第一批只用 Rust 占位产物打通 AiTaskService + OSS 草稿链；image-sequence 写 SVG 帧，视频类策略优先复用参考视频或仓库内可播放占位视频，不代表真实上游视频模型已完成迁移。
  18. 当前 /api/assets/character-animation/publish 会把前端提交帧、动作级 manifest 与总 manifest 写入 OSS，并只把总 manifest 确认为 asset_object 后绑定到 character / animation_set。
  19. /generated-* 只作为 legacyPublicPath / OSS object key 标识，读取必须通过 /api/assets/read-url 或业务投影中的签名读 URL。
Reference in New Issue View Git Blame Copy Permalink