# M0：后端挂载面冻结基线

日期：`2026-04-20`

依据来源：

- [../docs/technical/NODE_BACKEND_MODULE_AND_API_INDEX.md](../docs/technical/NODE_BACKEND_MODULE_AND_API_INDEX.md)
- [../server-node/manifests/backend-capability-index.json](../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 分层