Genarrative/backend-rewrite-tasklist/M0_CAPABILITY_SURFACE_BASELINE_2026-04-20.md

M0：后端挂载面冻结基线

日期：2026-04-20

依据来源：

• ../docs/technical/NODE_BACKEND_MODULE_AND_API_INDEX.md
• ../server-node/manifests/backend-capability-index.json

1. 文档目的

这份文档用于完成 M0 的第一条任务：

• 整理当前后端 6 个挂载面并锁定为重写验收基线

这里的“冻结”不是要求新后端永远维持原实现，而是要求：

1. 当前 Node 后端历史基线仍固定为这 6 个挂载面。
2. 本轮 Rust 后端的 active rewrite target 固定覆盖其中 5 个挂载面：assets、auth、health、runtime-main、runtime-story-action。
3. editor 作为历史遗留挂载面继续保留对照记录，但自 2026-04-21 起不纳入 server-rs 本轮重写验收。
4. 允许内部实现从 Express + PostgreSQL + 本地 public/generated-* 重写为 Axum + SpacetimeDB + 阿里云 OSS，但不允许把挂载面职责打散到无法对照验收。

2. 冻结结论

当前 Node 后端的正式挂载面固定为以下 6 个：

挂载面 ID	中文名称	当前路由数	当前入口	必须保留的顶层路径
assets	资产生成工具面	14	server-node/src/app.ts -> /api/assets	/api/assets/*
auth	鉴权与会话面	17	server-node/src/app.ts -> /api/auth	/api/auth/*
editor	编辑器工具面	3	server-node/src/app.ts -> /api/editor	/api/editor/*
health	基础健康检查	1	server-node/src/app.ts -> /healthz	/healthz
runtime-main	运行时主能力面	59	server-node/src/app.ts -> /api	/api/runtime/*、/api/profile/*、/api/custom-world/*、/api/llm/*、/api/ws/*
runtime-story-action	运行时 Story Action 面	2	server-node/src/app.ts -> /api/runtime/story	/api/runtime/story/*

冻结总数：

1. 历史对外挂载面：6
2. 本轮 active rewrite target：5
3. 已登记路由：96
4. 公开接口：10
5. JWT 接口：69
6. 开关控制接口：17
7. 流式接口：6

3. 各挂载面冻结要求

3.1 assets

当前定位：

1. 角色主形象生成
2. 角色动作生成
3. Qwen 精灵表生成与保存
4. 工作流缓存
5. 产物发布到 public/generated-*

重写后的冻结要求：

1. 仍保留独立的 /api/assets/* 命名空间。
2. 仍保留“生成任务、任务状态查询、发布/保存”三类操作语义。
3. 当前基于本地 public/generated-* 的产物落地，可改为 OSS + 元数据表，但前端一阶段必须继续通过原有路径习惯访问资源。
4. 当前 ASSETS_API_ENABLED 门禁能力必须保留。

3.2 auth

当前定位：

1. 本地账号登录
2. 手机验证码登录
3. 微信登录
4. refresh session
5. 会话吊销
6. 审计与风控

重写后的冻结要求：

1. 仍保留独立的 /api/auth/* 命名空间。
2. 仍保留当前 JWT + refresh cookie 双令牌模型。
3. 仍保留 password / phone / wechat 三类登录能力面。
4. 仍保留审计日志、风控封禁、会话列表与会话吊销能力。

3.3 editor

当前定位：

1. 编辑器 JSON 读取
2. 编辑器 JSON 回写
3. 图标目录枚举

重写后的冻结要求：

1. server-node/src/app.ts -> /api/editor/* 的历史存在事实继续保留在基线文档中。
2. 自 2026-04-21 起，该挂载面不纳入 server-rs 本轮重写范围，不再作为 M1 ~ M6 主线交付目标。
3. 若未来仍需清理或替代 editor，需要在遗留链路依赖核对完成后单独立项。

3.4 health

当前定位：

1. 提供后端进程健康探针
2. 为代理层与 smoke 提供最小可用确认

重写后的冻结要求：

1. 仍保留 /healthz。
2. 仍返回简单、无鉴权、无数据库强耦合的健康状态。
3. 仍可作为 smoke 与部署探针的第一检查点。

3.5 runtime-main

当前定位：

1. 运行时存档、设置、个人档案
2. 聊天、剧情、任务、运行时物品意图
3. custom world library / gallery / sessions
4. custom world agent 会话、消息、操作

重写后的冻结要求：

1. 仍保留运行时主入口作为最大能力面，不把这些能力拆散到前端无法感知的新命名空间。
2. 仍兼容当前：
   • /api/runtime/*
   • /api/profile/*
   • /api/custom-world/*
   • /api/llm/*
   • /api/ws/*
3. 除公开画廊与少量公开接口外，仍以登录态为默认访问前提。
4. 当前大量业务逻辑虽然会迁到 SpacetimeDB reducer/view + Axum facade，但对前端看起来仍应是一个统一运行时能力面。

3.6 runtime-story-action

当前定位：

1. story choice 动作解析
2. story session 状态恢复

重写后的冻结要求：

1. 仍保留 /api/runtime/story/* 作为独立挂载面。
2. 仍保持“前端动作输入 -> 后端统一结算 -> 返回新状态”的接口职责。
3. 当前 storyActionService 里跨 quest / inventory / runtime-item / npc / progression / combat / runtime 的协作，迁移后必须继续存在，只是实现位置改到 SpacetimeDB + Axum。

4. 挂载面与新架构映射

当前挂载面	新架构主归属	说明
assets	Axum + OSS + SpacetimeDB asset metadata	外部副作用在 Axum，二进制在 OSS，任务与引用状态在 SpacetimeDB。
auth	Axum auth-service + SpacetimeDB auth tables	登录副作用与 cookie/JWT 在 Axum，身份与会话状态在 SpacetimeDB。
editor	遗留保留于 server-node	历史挂载面对照，当前不进入 Rust 重写主链。
health	Axum health route	维持最小化健康检查面。
runtime-main	Axum runtime facade + SpacetimeDB runtime/custom-world tables	Axum 维持兼容 REST/SSE，SpacetimeDB 负责状态真相。
runtime-story-action	Axum story facade + SpacetimeDB gameplay reducers/views	Story Action 入口继续独立存在，但结算内核迁到新状态层。

5. 本轮冻结后的硬约束

后续迁移中，不允许出现以下情况：

1. 把历史 6 个挂载面减少成更少但无法一一对照的“超级入口”。
2. 为了迎合本轮重写范围而把历史存在的 /api/editor/* 从基线文档中抹掉。
3. 把当前 /api/auth/*、/api/assets/*、/api/runtime/story/* 顶层命名空间直接改掉。
4. 在未完成路径兼容前，直接移除 /healthz 或 /generated-* 的既有访问习惯。
5. 在未完成契约回归前，把 runtime-main 和 runtime-story-action 的职责重新混成一个难以验收的大入口。

6. 本任务完成定义

当以下条件成立时，这条任务视为完成：

1. 当前历史 6 个挂载面已经有正式书面冻结清单。
2. 每个挂载面都有：
   • 当前入口
   • 当前路由数
   • 顶层路径空间
   • 重写后必须保留的职责边界
3. 本轮 active rewrite target 为 5 个，且 editor 的遗留/不迁移口径已经冻结。
4. 后续任务可以直接以这份文档作为验收引用，不再靠聊天记录记忆。

7. 后续直接依赖这份基线的任务

1. 整理当前后端 96 条路由并生成“旧接口 -> 新实现”映射表
2. 整理当前 12 个内部模块并锁定迁移归属
3. 设计 Axum 路由树
4. 设计 SpacetimeDB 表 / reducer / view 分层