20 KiB
20 KiB
M0：旧接口到新实现路由迁移矩阵
日期：2026-04-20
依据来源：
- ../docs/technical/NODE_BACKEND_MODULE_AND_API_INDEX.md
- ../server-node/manifests/backend-capability-index.json
- M0_CAPABILITY_SURFACE_BASELINE_2026-04-20.md
1. 文档目的
这份文档用于完成 M0 的第二条任务：
- 整理当前后端
96条路由并生成一份“旧接口 -> 新实现”映射表
这里的“新实现”不是指最终文件路径，而是指第一阶段重写时每条旧接口在新架构中的落点：
- 哪条 Axum 路由负责对外兼容
- 哪层 application service 负责编排
- 哪些状态进入 SpacetimeDB
- 哪些二进制对象进入 OSS
2. 映射代码说明
为避免 96 条路由的映射表过长，本表使用以下“新实现归属代码”：
| 代码 | 新实现归属 |
|---|---|
A-HEALTH |
Axum health route |
A-AUTH |
Axum auth routes + auth-service + SpacetimeDB auth tables |
A-EDITOR |
历史 Node editor 路由（遗留保留，不迁移到 server-rs） |
A-OSS |
Axum assets routes + application::assets + oss-service + SpacetimeDB asset metadata |
A-LLM |
Axum llm proxy/service |
A-RUNTIME |
Axum runtime facade + SpacetimeDB runtime reducers/views |
A-STORY |
Axum story facade + SpacetimeDB gameplay reducers/views |
A-CHAT |
Axum SSE facade + llm-service + SpacetimeDB story/npc state |
A-CW |
Axum custom-world facade + llm-service + SpacetimeDB custom_world reducers/views |
A-AGENT |
Axum custom-world-agent facade + llm-service + oss-service + SpacetimeDB agent tables |
补充说明：
- 第一阶段默认保留旧路径，不主动改前端请求地址。
- 兼容路径与主路径在新后端中应尽量共用同一 handler。
- 所有
stream接口第一阶段继续用 Axum SSE，不强推改成 WebSocket。 - 自
2026-04-21起，editor路由仅保留历史对照，不纳入本轮 Rust 重写范围。
3. 总量校验
| 项目 | 数量 |
|---|---|
| 挂载面 | 6 |
| 总路由数 | 96 |
assets |
14 |
auth |
17 |
editor |
3 |
runtime-main |
59 |
runtime-story-action |
2 |
health |
1 |
补充说明：
- 上表总量仍然是当前 Node 后端历史基线。
- 其中
editor的3条路由继续计入历史对照，但不计入本轮server-rsactive rewrite target。
4. assets 路由映射（14 条）
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
assets.characterAnimationGenerate |
POST /api/assets/character-animation/generate |
A-OSS |
保留原路径；Axum 创建 asset_job，外部生成结果写 OSS，任务状态进 SpacetimeDB。 |
assets.characterAnimationImportVideo |
POST /api/assets/character-animation/import-video |
A-OSS |
保留原路径；视频参考素材由 Axum 上传 OSS，并写任务/对象元数据。 |
assets.characterAnimationJobGet |
GET /api/assets/character-animation/jobs/:taskId |
A-OSS |
保留原路径；查询改读 SpacetimeDB asset_job view。 |
assets.characterAnimationPublish |
POST /api/assets/character-animation/publish |
A-OSS |
保留原路径；发布动作改为“绑定 OSS 对象到业务实体 + 回写元数据”。 |
assets.characterAnimationTemplatesList |
GET /api/assets/character-animation/templates |
A-OSS |
保留原路径；模板清单先由 Axum 提供，后续再视情况对象化。 |
assets.characterVisualGenerate |
POST /api/assets/character-visual/generate |
A-OSS |
保留原路径；角色主形象候选生成改为 Axum 编排 + OSS 入库。 |
assets.characterVisualJobGet |
GET /api/assets/character-visual/jobs/:taskId |
A-OSS |
保留原路径；任务状态改读 SpacetimeDB。 |
assets.characterVisualPublish |
POST /api/assets/character-visual/publish |
A-OSS |
保留原路径；发布改为对象绑定，不再依赖本地 public/generated-* 真相。 |
assets.characterWorkflowCacheSave |
POST /api/assets/character-workflow-cache |
A-OSS |
保留原路径；工作流缓存改写 OSS/对象存储，索引进 SpacetimeDB。 |
assets.characterWorkflowCacheGet |
GET /api/assets/character-workflow-cache/:characterId |
A-OSS |
保留原路径；按角色查缓存索引，再返回对象内容或签名 URL。 |
assets.qwenSpriteFrameRepairGenerate |
POST /api/assets/qwen-sprite/frame-repair |
A-OSS |
保留原路径；Qwen 修帧结果统一入 OSS，状态进 SpacetimeDB。 |
assets.qwenSpriteMasterGenerate |
POST /api/assets/qwen-sprite/master |
A-OSS |
保留原路径；主图生成改为 Axum 编排。 |
assets.qwenSpriteAssetSave |
POST /api/assets/qwen-sprite/save |
A-OSS |
保留原路径；保存动作改为持久化对象元数据与引用关系。 |
assets.qwenSpriteSheetGenerate |
POST /api/assets/qwen-sprite/sheet |
A-OSS |
保留原路径；整表生成链路保留，底层切换为 OSS + SpacetimeDB。 |
5. auth 路由映射（17 条）
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
auth.auditLogs |
GET /api/auth/audit-logs |
A-AUTH |
保留原路径；从 SpacetimeDB auth_audit_log view 返回。 |
auth.entry |
POST /api/auth/entry |
A-AUTH |
保留原路径；密码登录与自动注册由 Axum 完成，再写 auth 表。 |
auth.loginOptions |
GET /api/auth/login-options |
A-AUTH |
保留原路径；由 Axum 直接返回登录方式配置。 |
auth.logout |
POST /api/auth/logout |
A-AUTH |
保留原路径；Axum 吊销 refresh session 并清理 cookie。 |
auth.logoutAll |
POST /api/auth/logout-all |
A-AUTH |
保留原路径；批量吊销用户全部 session。 |
auth.me |
GET /api/auth/me |
A-AUTH |
保留原路径；由 Axum 校验 JWT 后查询用户读模型。 |
auth.phoneChange |
POST /api/auth/phone/change |
A-AUTH |
保留原路径；短信校验在 Axum，绑定结果写 SpacetimeDB。 |
auth.phoneLogin |
POST /api/auth/phone/login |
A-AUTH |
保留原路径；验证码校验成功后创建/恢复账号与 session。 |
auth.phoneSendCode |
POST /api/auth/phone/send-code |
A-AUTH |
保留原路径；阿里云短信发送适配收口到 Axum。 |
auth.refresh |
POST /api/auth/refresh |
A-AUTH |
保留原路径；沿用 refresh cookie -> access token 刷新模型。 |
auth.riskBlocks |
GET /api/auth/risk-blocks |
A-AUTH |
保留原路径；改读风控封禁表/视图。 |
auth.riskBlocksLift |
POST /api/auth/risk-blocks/:scopeType/lift |
A-AUTH |
保留原路径；解除请求由 Axum 执行校验并写状态。 |
auth.sessions |
GET /api/auth/sessions |
A-AUTH |
保留原路径；会话列表改读 SpacetimeDB refresh_session view。 |
auth.sessionRevoke |
POST /api/auth/sessions/:sessionId/revoke |
A-AUTH |
保留原路径；会话吊销改写 refresh_session 状态。 |
auth.wechatBindPhone |
POST /api/auth/wechat/bind-phone |
A-AUTH |
保留原路径；微信身份补绑手机号逻辑迁到 Axum。 |
auth.wechatCallback |
GET /api/auth/wechat/callback |
A-AUTH |
保留原路径与 redirect 语义；微信 code 交换由 Axum 处理。 |
auth.wechatStart |
GET /api/auth/wechat/start |
A-AUTH |
保留原路径；授权 URL 由 Axum 按设备场景生成。 |
6. editor 路由映射（3 条，历史遗留）
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
editor.catalogItems |
GET /api/editor/catalog/items |
A-EDITOR |
保留在 server-node/ 遗留链路，仅作为历史对照；不迁移到 server-rs。 |
editor.resourceRead |
GET /api/editor/json/:resourceId |
A-EDITOR |
保留在 server-node/ 遗留链路，仅作为历史对照；不迁移到 server-rs。 |
editor.resourceWrite |
POST /api/editor/json/:resourceId |
A-EDITOR |
保留在 server-node/ 遗留链路，仅作为历史对照；不迁移到 server-rs。 |
7. runtime-main 路由映射（59 条）
7.1 custom world 资源与实体生成
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
runtime.customWorldCoverImage |
POST /api/custom-world/cover-image |
A-CW |
保留原路径；封面图生成由 Axum 编排，产物进 OSS，绑定关系进 SpacetimeDB。 |
runtime.customWorldCoverUpload |
POST /api/custom-world/cover-upload |
A-CW |
保留原路径；上传改为 OSS 直传或 Axum 中转上传。 |
runtime.customWorldEntity.primary |
POST /api/custom-world/entity |
A-CW |
保留原路径；实体生成由 Axum 调 LLM，再写 custom world 表。 |
runtime.customWorldSceneImage |
POST /api/custom-world/scene-image |
A-CW |
保留原路径；场景图生成由 Axum + OSS 完成。 |
runtime.customWorldSceneNpc.primary |
POST /api/custom-world/scene-npc |
A-CW |
保留原路径；场景 NPC 生成结果写 custom world / npc 相关表。 |
7.2 LLM 透传
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
runtime.llmChatCompletionsProxy |
POST /api/llm/chat/completions |
A-LLM |
保留原路径；继续由 Axum 承接代理，不进入 SpacetimeDB。 |
7.3 profile 主路径
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
runtime.profileBrowseHistoryDelete.primary |
DELETE /api/profile/browse-history |
A-RUNTIME |
保留原路径；清理动作改为 reducer 写 user_browse_history。 |
runtime.profileBrowseHistoryGet.primary |
GET /api/profile/browse-history |
A-RUNTIME |
保留原路径；历史记录改读 browse history view。 |
runtime.profileBrowseHistoryPost.primary |
POST /api/profile/browse-history |
A-RUNTIME |
保留原路径；批量写入改为 Axum -> reducer。 |
runtime.profileDashboard.primary |
GET /api/profile/dashboard |
A-RUNTIME |
保留原路径；个人主页汇总改读 dashboard view。 |
runtime.profilePlayStats.primary |
GET /api/profile/play-stats |
A-RUNTIME |
保留原路径；统计数据改读 projection。 |
runtime.profileSaveArchivesList.primary |
GET /api/profile/save-archives |
A-RUNTIME |
保留原路径；存档摘要改读 save archive view。 |
runtime.profileSaveArchivesResume.primary |
POST /api/profile/save-archives/:worldKey |
A-RUNTIME |
保留原路径；恢复动作改读 profile_save_archive 后重建兼容快照。 |
runtime.profileWalletLedger.primary |
GET /api/profile/wallet-ledger |
A-RUNTIME |
保留原路径；资产流水改读 ledger view。 |
7.4 runtime 聊天与流式对话
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
runtime.characterReplyStream |
POST /api/runtime/chat/character/reply/stream |
A-CHAT |
保留 SSE contract；Axum 流式产出，状态写 story/session 表。 |
runtime.characterSuggestions |
POST /api/runtime/chat/character/suggestions |
A-CHAT |
保留原路径；由 Axum 生成建议语并按需写会话状态。 |
runtime.characterSummary |
POST /api/runtime/chat/character/summary |
A-CHAT |
保留原路径；摘要生成留在 Axum，摘要索引可回写 SpacetimeDB。 |
runtime.npcDialogueStream |
POST /api/runtime/chat/npc/dialogue/stream |
A-CHAT |
保留 SSE contract；NPC 对话状态迁到 SpacetimeDB。 |
runtime.npcRecruitStream |
POST /api/runtime/chat/npc/recruit/stream |
A-CHAT |
保留 SSE contract；招募对话与状态变化统一进入新状态层。 |
runtime.npcTurnStream |
POST /api/runtime/chat/npc/turn/stream |
A-CHAT |
保留 SSE contract；单回合发言的判定与状态回写统一收口。 |
7.5 custom world gallery / library / sessions / works
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
runtime.customWorldGalleryList |
GET /api/runtime/custom-world-gallery |
A-CW |
保留原路径；公开画廊改读 custom_world_gallery view。 |
runtime.customWorldGalleryDetail |
GET /api/runtime/custom-world-gallery/:ownerUserId/:profileId |
A-CW |
保留原路径；详情改读 gallery detail view。 |
runtime.customWorldLibraryList |
GET /api/runtime/custom-world-library |
A-CW |
保留原路径；资料库改读用户 custom world view。 |
runtime.customWorldLibraryDelete |
DELETE /api/runtime/custom-world-library/:profileId |
A-CW |
保留原路径；删除改为 reducer 或软删除标记。 |
runtime.customWorldLibraryUpsert |
PUT /api/runtime/custom-world-library/:profileId |
A-CW |
保留原路径；写入改为 Axum facade + SpacetimeDB profile tables。 |
runtime.customWorldLibraryPublish |
POST /api/runtime/custom-world-library/:profileId/publish |
A-CW |
保留原路径；发布改为状态切换与画廊投影刷新。 |
runtime.customWorldLibraryUnpublish |
POST /api/runtime/custom-world-library/:profileId/unpublish |
A-CW |
保留原路径；撤回发布改为状态切换。 |
runtime.customWorldSessionCreate |
POST /api/runtime/custom-world/sessions |
A-CW |
保留原路径；传统问答会话状态迁到 SpacetimeDB。 |
runtime.customWorldSessionGet |
GET /api/runtime/custom-world/sessions/:sessionId |
A-CW |
保留原路径；读取传统问答会话改读 view。 |
runtime.customWorldSessionAnswer |
POST /api/runtime/custom-world/sessions/:sessionId/answers |
A-CW |
保留原路径；回答动作改为 reducer 写会话状态。 |
runtime.customWorldSessionGenerateStream |
GET /api/runtime/custom-world/sessions/:sessionId/generate/stream |
A-CW |
保留 SSE contract；编译过程由 Axum 流式回推并回写状态。 |
runtime.customWorldWorksList |
GET /api/runtime/custom-world/works |
A-CW |
保留原路径；作品汇总改读 custom world work summary view。 |
7.6 custom world agent
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
runtime.customWorldAgentCreateSession |
POST /api/runtime/custom-world/agent/sessions |
A-AGENT |
保留原路径；Agent 会话创建改写 custom_world_agent_session。 |
runtime.customWorldAgentGetSession |
GET /api/runtime/custom-world/agent/sessions/:sessionId |
A-AGENT |
保留原路径；会话快照改读 Agent session view。 |
runtime.customWorldAgentExecuteAction |
POST /api/runtime/custom-world/agent/sessions/:sessionId/actions |
A-AGENT |
保留原路径；动作编排由 Axum 执行，状态与操作记录进 SpacetimeDB。 |
runtime.customWorldAgentGetCardDetail |
GET /api/runtime/custom-world/agent/sessions/:sessionId/cards/:cardId |
A-AGENT |
保留原路径；卡片详情改读 custom_world_draft_card。 |
runtime.customWorldAgentSendMessage |
POST /api/runtime/custom-world/agent/sessions/:sessionId/messages |
A-AGENT |
保留原路径；消息提交后由 Axum 触发编排，消息与操作状态入库。 |
runtime.customWorldAgentStreamMessage |
POST /api/runtime/custom-world/agent/sessions/:sessionId/messages/stream |
A-AGENT |
保留 SSE contract；流式消息由 Axum 输出，Agent 状态表持续更新。 |
runtime.customWorldAgentGetOperation |
GET /api/runtime/custom-world/agent/sessions/:sessionId/operations/:operationId |
A-AGENT |
保留原路径；操作状态改读 custom_world_agent_operation view。 |
7.7 compat 路径
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
runtime.customWorldEntity.compat |
POST /api/runtime/custom-world/entity |
A-CW |
保留兼容路径；与主路径共用同一 handler。 |
runtime.customWorldSceneNpc.compat |
POST /api/runtime/custom-world/scene-npc |
A-CW |
保留兼容路径；与主路径共用同一 handler。 |
runtime.profileBrowseHistoryDelete.compat |
DELETE /api/runtime/profile/browse-history |
A-RUNTIME |
保留兼容路径；与 /api/profile/browse-history 共用实现。 |
runtime.profileBrowseHistoryGet.compat |
GET /api/runtime/profile/browse-history |
A-RUNTIME |
保留兼容路径；共用 browse history facade。 |
runtime.profileBrowseHistoryPost.compat |
POST /api/runtime/profile/browse-history |
A-RUNTIME |
保留兼容路径；共用写入逻辑。 |
runtime.profileDashboard.compat |
GET /api/runtime/profile/dashboard |
A-RUNTIME |
保留兼容路径；共用 dashboard facade。 |
runtime.profilePlayStats.compat |
GET /api/runtime/profile/play-stats |
A-RUNTIME |
保留兼容路径；共用 play stats facade。 |
runtime.profileSaveArchivesList.compat |
GET /api/runtime/profile/save-archives |
A-RUNTIME |
保留兼容路径；共用 save archives list facade。 |
runtime.profileSaveArchivesResume.compat |
POST /api/runtime/profile/save-archives/:worldKey |
A-RUNTIME |
保留兼容路径；共用 resume facade。 |
runtime.profileWalletLedger.compat |
GET /api/runtime/profile/wallet-ledger |
A-RUNTIME |
保留兼容路径；共用 wallet ledger facade。 |
7.8 runtime 其他核心接口
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
runtime.itemsIntent |
POST /api/runtime/items/runtime-intent |
A-CW |
保留原路径；Axum 调 LLM 生成意图，物品领域状态与引用写 SpacetimeDB。 |
runtime.questsGenerate |
POST /api/runtime/quests/generate |
A-CW |
保留原路径；任务候选生成由 Axum 编排，结果写 quest 相关表。 |
runtime.snapshotDelete |
DELETE /api/runtime/save/snapshot |
A-RUNTIME |
保留原路径；删除动作改为更新 runtime_snapshot / archive。 |
runtime.snapshotGet |
GET /api/runtime/save/snapshot |
A-RUNTIME |
保留原路径；读取兼容聚合快照，由 view/projection 输出。 |
runtime.snapshotPut |
PUT /api/runtime/save/snapshot |
A-RUNTIME |
保留原路径；写入由 Axum facade + reducer 完成。 |
runtime.settingsGet |
GET /api/runtime/settings |
A-RUNTIME |
保留原路径；设置改读 runtime_setting view。 |
runtime.settingsPut |
PUT /api/runtime/settings |
A-RUNTIME |
保留原路径；设置更新改为 reducer。 |
runtime.storyContinue |
POST /api/runtime/story/continue |
A-STORY |
保留原路径；故事推进由 Axum 调新 story/application 层。 |
runtime.storyInitial |
POST /api/runtime/story/initial |
A-STORY |
保留原路径；首段故事生成保持 REST 兼容。 |
runtime.wsHealth |
GET /api/ws/health |
A-RUNTIME |
保留原路径；继续作为实时链路占位健康检查。 |
8. runtime-story-action 路由映射（2 条）
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
storyAction.resolve |
POST /api/runtime/story/actions/resolve |
A-STORY |
保留原路径；Axum 接收动作请求，SpacetimeDB reducer 执行跨模块结算。 |
storyAction.stateGet |
GET /api/runtime/story/state/:sessionId |
A-STORY |
保留原路径；读取 story session 兼容状态 view。 |
9. health 路由映射（1 条）
| 旧路由 ID | 方法/路径 | 新实现归属 | 第一阶段迁移策略 |
|---|---|---|---|
health.check |
GET /healthz |
A-HEALTH |
保留原路径与最小返回结构。 |
10. 迁移落地规则
后续做路由树时，必须遵守：
- 旧路径优先保留，新实现从内部切换，不先要求前端改地址。
- 主路径与兼容路径必须共用同一 application service，避免再次出现双份逻辑。
stream接口第一阶段默认沿用 SSE。assets与custom-world里的生成类接口，外部副作用统一在 Axum，状态与任务统一进 SpacetimeDB。storyAction.resolve、runtime.snapshotPut、auth.refresh属于最优先回归接口，后续开发必须优先补完整测试。editor相关旧路径只保留历史基线记录，不纳入server-rs路由树实施范围。
11. 本任务完成定义
当以下条件成立时，这条任务视为完成：
96条旧路由都已经有新实现落点。- 每条路由至少明确：
- 旧方法/路径
- 新实现归属
- 第一阶段迁移策略
- 后续搭建 Axum 路由树与 application service 时，可以直接按这份矩阵逐项落位。