Genarrative/docs/technical/RUST_API_SERVER_ROUTE_INDEX_2026-04-22.md

Rust API Server 路由索引（2026-04-23）

更新时间：2026-05-13

2026-04-29 补充：本文件保留为迁移期路由快照。DDD G1 后续并行工作的契约冻结口径以 SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md 为准，尤其是新增的 Big Fish、Puzzle、profile、runtime chat、story facade 和兼容路由删除计划。

2026-04-29 WP-RS 进度：旧 /api/runtime/story/* HTTP compat 路由已从 api-server/src/app.rs 取消挂载，并删除 api-server/src/runtime_story* 兼容实现。当前 Rust api-server 对外 story 主链只保留 /api/story/*、/api/runtime/sessions/{runtime_session_id}/inventory 与 runtime chat 相关路由。

1. 文档目标

本文件记录当前 server-rs/crates/api-server/src/app.rs 中已挂载的 Rust Axum 路由面，用于对照 Node 后端 96 条路由能力基线。

本文件只做路由索引，不替代单个阶段的设计文档；接口字段、权限、错误模型仍以各阶段技术方案和 shared-contracts 为准。

2. 当前统计

当前 Rust api-server 从 app.rs 可抽取到 116 条路由：

1. 管理后台 API：6 条。
2. 内部鉴权调试接口：2 条。
3. AI task 接口：9 条。
4. assets / OSS 接口：15 条。
5. auth 接口：13 条。
6. custom world / agent 接口：23 条。
7. match3d creation / runtime 接口：14 条。
8. llm proxy 接口：1 条。
9. profile / runtime profile 接口：12 条。
10. runtime story / story gameplay 接口：15 条。
11. legacy generated 静态标识：6 类历史路径字符串，直读代理已下线。
12. health check：1 条。

3. 路由清单

3.1 管理后台 API

1. POST /admin/api/login
2. GET /admin/api/me
3. GET /admin/api/overview
4. POST /admin/api/debug/http
5. POST /admin/api/profile/redeem-codes
6. POST /admin/api/profile/redeem-codes/disable

GET /admin 同源内嵌页面入口已取消挂载，后台 UI 后续由独立前端工程承接。

3.2 内部鉴权调试

1. GET /_internal/auth/claims
2. GET /_internal/auth/refresh-cookie

3.3 AI Task

1. POST /api/ai/tasks
2. POST /api/ai/tasks/{task_id}/start
3. POST /api/ai/tasks/{task_id}/cancel
4. POST /api/ai/tasks/{task_id}/complete
5. POST /api/ai/tasks/{task_id}/fail
6. POST /api/ai/tasks/{task_id}/chunks
7. POST /api/ai/tasks/{task_id}/references
8. POST /api/ai/tasks/{task_id}/stages/{stage_kind}/start
9. POST /api/ai/tasks/{task_id}/stages/{stage_kind}/complete

3.4 Assets / OSS

1. POST /api/assets/direct-upload-tickets
2. POST /api/assets/sts-upload-credentials
3. POST /api/assets/objects/confirm
4. POST /api/assets/objects/bind
5. GET /api/assets/read-url
6. POST /api/assets/character-visual/generate
7. GET /api/assets/character-visual/jobs/{task_id}
8. POST /api/assets/character-visual/publish
9. POST /api/assets/character-animation/generate
10. GET /api/assets/character-animation/jobs/{task_id}
11. POST /api/assets/character-animation/publish
12. POST /api/assets/character-animation/import-video
13. GET /api/assets/character-animation/templates
14. GET /api/assets/character-workflow-cache/{character_id}
15. GET / POST /api/assets/character-workflow-cache

3.5 Auth

1. GET /api/auth/login-options
2. GET /api/auth/me
3. POST /api/auth/logout
4. POST /api/auth/logout-all
5. GET /api/auth/sessions
6. POST /api/auth/sessions/{session_id}/revoke
7. POST /api/auth/refresh
8. POST /api/auth/phone/send-code
9. POST /api/auth/phone/login
10. GET /api/auth/wechat/start
11. GET /api/auth/wechat/callback
12. POST /api/auth/wechat/bind-phone
13. POST /api/auth/entry

3.6 Custom World / Agent

1. GET /api/runtime/custom-world-library
2. GET /api/runtime/custom-world-library/{profile_id}
3. POST /api/runtime/custom-world-library/{profile_id}/publish
4. POST /api/runtime/custom-world-library/{profile_id}/unpublish
5. GET /api/runtime/custom-world-gallery
6. GET /api/runtime/custom-world-gallery/{owner_user_id}/{profile_id}
7. GET /api/runtime/custom-world/works
8. POST /api/runtime/custom-world/agent/sessions
9. GET /api/runtime/custom-world/agent/sessions/{session_id}
10. POST /api/runtime/custom-world/agent/sessions/{session_id}/messages
11. GET /api/runtime/custom-world/agent/sessions/{session_id}/messages/stream
12. GET /api/runtime/custom-world/agent/sessions/{session_id}/operations/{operation_id}
13. GET /api/runtime/custom-world/agent/sessions/{session_id}/cards/{card_id}
14. POST /api/runtime/custom-world/agent/sessions/{session_id}/actions
15. POST /api/custom-world/entity
16. POST /api/runtime/custom-world/entity
17. POST /api/custom-world/scene-npc
18. POST /api/runtime/custom-world/scene-npc
19. POST /api/custom-world/scene-image
20. POST /api/custom-world/cover-image
21. POST /api/custom-world/cover-upload
22. POST /api/runtime/custom-world/cover-image
23. POST /api/runtime/custom-world/cover-upload

3.7 LLM Proxy

1. POST /api/llm/chat/completions

3.8 Match3D Creation / Runtime

1. POST /api/creation/match3d/sessions
2. GET /api/creation/match3d/sessions/{session_id}
3. POST /api/creation/match3d/sessions/{session_id}/messages
4. POST /api/creation/match3d/sessions/{session_id}/messages/stream
5. POST /api/creation/match3d/sessions/{session_id}/actions
6. POST /api/creation/match3d/sessions/{session_id}/compile
7. GET /api/creation/match3d/works
8. GET / PATCH / PUT / DELETE /api/creation/match3d/works/{profile_id}
9. POST /api/creation/match3d/works/{profile_id}/publish
10. GET /api/runtime/match3d/gallery
11. POST /api/runtime/match3d/works/{profile_id}/runs
12. GET /api/runtime/match3d/runs/{run_id}
13. POST /api/runtime/match3d/runs/{run_id}/click
14. POST /api/runtime/match3d/runs/{run_id}/stop / restart / time-up

3.9 Profile / Runtime Profile

1. GET /api/profile/dashboard
2. GET /api/runtime/profile/dashboard
3. GET /api/profile/play-stats
4. GET /api/runtime/profile/play-stats
5. GET /api/profile/wallet-ledger
6. GET /api/runtime/profile/wallet-ledger
7. GET /api/profile/browse-history
8. GET /api/runtime/profile/browse-history
9. GET /api/profile/save-archives
10. GET /api/runtime/profile/save-archives
11. POST /api/profile/save-archives/{world_key}
12. POST /api/runtime/profile/save-archives/{world_key}

3.10 Runtime Story / Gameplay

1. POST /api/runtime/save/snapshot
2. GET /api/runtime/settings
3. POST /api/story/sessions
4. POST /api/story/sessions/continue
5. GET /api/story/sessions/{story_session_id}/state
6. POST /api/story/battles
7. POST /api/story/battles/resolve
8. GET /api/story/battles/{battle_state_id}
9. POST /api/story/npc/battle
10. GET /api/runtime/sessions/{runtime_session_id}/inventory

3.11 Legacy Generated 路径

旧 /generated-* 直读代理已下线。生成资产读取统一走 GET /api/assets/read-url 或 asset object projection；/generated-* 字符串仅作为 legacyPublicPath / OSS object key 兼容标识保留。

3.12 Health

1. GET /healthz

4. 维护规则

1. 新增、删除或改名 Rust 路由时，必须同步更新本索引。
2. 如果 Rust 后端公开能力面发生变化，必须同时更新本索引、当前后端实现基线与对应阶段任务清单。
3. 任何 breaking route change 都必须先更新阶段设计文档，再改代码。
4. 真实切流前，必须用本索引对照代理层、前端调用面和 smoke 清单，避免只完成编译而遗漏外部可访问路径。