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

更新时间：`2026-05-01`

> 2026-04-29 补充：本文件保留为迁移期路由快照。DDD G1 后续并行工作的契约冻结口径以 [`SERVER_RS_DDD_G1_CONTRACT_AND_ROUTE_MATRIX_2026-04-29.md`](./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 接口：`12` 条。
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/refresh`
7. `POST /api/auth/phone/send-code`
8. `POST /api/auth/phone/login`
9. `GET /api/auth/wechat/start`
10. `GET /api/auth/wechat/callback`
11. `POST /api/auth/wechat/bind-phone`
12. `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 清单，避免只完成编译而遗漏外部可访问路径。