# SpacetimeDB + Axum + 阿里云 OSS 后端重写任务总纲

日期：`2026-04-20`

关联设计文档：

- [../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)
- [../docs/technical/NODE_BACKEND_MODULE_AND_API_INDEX.md](../docs/technical/NODE_BACKEND_MODULE_AND_API_INDEX.md)
- [../docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../docs/technical/RPG_ENTRY_RUNTIME_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)
- [../docs/technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md](../docs/technical/CREATION_FLOW_CHAIN_REFACTOR_EXECUTION_PLAN_2026-04-21.md)

关联拆分任务：

- [01_M0_M2_FOUNDATION_AND_AUTH.md](./01_M0_M2_FOUNDATION_AND_AUTH.md)
- [02_M3_RUNTIME_PROFILE.md](./02_M3_RUNTIME_PROFILE.md)
- [03_M4_STORY_AND_GAMEPLAY.md](./03_M4_STORY_AND_GAMEPLAY.md)
- [04_M5_CUSTOM_WORLD_AND_AGENT.md](./04_M5_CUSTOM_WORLD_AND_AGENT.md)
- [05_M6_ASSETS_OSS_EDITOR.md](./05_M6_ASSETS_OSS_EDITOR.md)
- [06_M7_TEST_DEPLOY_CUTOVER.md](./06_M7_TEST_DEPLOY_CUTOVER.md)
- [07_CROSS_CUTTING_AND_ACCEPTANCE.md](./07_CROSS_CUTTING_AND_ACCEPTANCE.md)

## 0. 使用说明

这份总纲用于把控整体重写节奏，拆分文件用于落地执行。

执行原则：

1. 第一阶段优先兼容当前 `/api/*`、`/healthz`、`/generated-*` 访问习惯。
2. 不允许先删旧能力再补新能力，必须按能力面平移。
3. 以当前 Node 后端 `96` 条路由、`6` 个挂载面、`12` 个模块为最低覆盖基线。
4. 每个阶段完成后，都要形成可运行、可回归、可继续迭代的中间态。

## 1. 总体里程碑

- [x] `M0`：冻结当前后端能力清单与迁移边界
- [ ] `M1`：搭建 Rust 工作区、Axum 主入口与基础中间件
- [ ] `M2`：完成鉴权、会话、JWT、refresh cookie 主链迁移
- [ ] `M3`：完成 runtime snapshot / settings / profile 迁移
- [ ] `M4`：完成 story action 主循环与核心 gameplay reducer 迁移
- [ ] `M5`：完成 custom world / agent 主链迁移
- [ ] `M6`：完成 assets / OSS 主链迁移
- [ ] `M7`：完成联调、回归、部署与切流准备

## 2. 阶段导航

### `M0 ~ M2`

重点：

1. 冻结能力清单
2. 搭建 Rust workspace
3. 搭建 Axum 基础设施
4. 迁移鉴权、会话、JWT、refresh cookie

详见：

- [01_M0_M2_FOUNDATION_AND_AUTH.md](./01_M0_M2_FOUNDATION_AND_AUTH.md)

### `M3`

重点：

1. 迁移 runtime snapshot
2. 迁移 settings
3. 迁移 profile dashboard / browse history / save archive

详见：

- [02_M3_RUNTIME_PROFILE.md](./02_M3_RUNTIME_PROFILE.md)

### `M4`

重点：

1. 迁移 RPG runtime story 主循环
2. 迁移 RPG 入口 / session / runtime 对应的后端边界与编译职责
3. 兼容当前 story view model 与 state 恢复接口，并与 `rpgEntry / rpgSession / rpgRuntime / rpgRuntimeStory` 口径对齐

详见：

- [03_M4_STORY_AND_GAMEPLAY.md](./03_M4_STORY_AND_GAMEPLAY.md)

### `M5`

重点：

1. 迁移 RPG 创作主链：Agent session、result preview、published profile
2. 迁移 works / library / gallery / publish / enter-world 配套链路
3. 旧 `custom-world/sessions` 传统问答流只按历史兼容台账处理，不再作为当前主链扩展目标

详见：

- [04_M5_CUSTOM_WORLD_AND_AGENT.md](./04_M5_CUSTOM_WORLD_AND_AGENT.md)

### `M6`

重点：

1. 迁移 assets
2. 接入阿里云 OSS
3. 做旧静态资源路径兼容

详见：

- [05_M6_ASSETS_OSS_EDITOR.md](./05_M6_ASSETS_OSS_EDITOR.md)

### `M7`

重点：

1. 联调
2. 回归
3. 部署
4. 观测
5. 灰度切流
6. 收口 `spacetime-module` 主工程结构，拆分过大的 `src/lib.rs`

详见：

- [06_M7_TEST_DEPLOY_CUTOVER.md](./06_M7_TEST_DEPLOY_CUTOVER.md)

## 3. 横向专项

以下专项贯穿整个迁移期：

1. contract 与前端兼容
2. SpacetimeDB schema 演进治理
3. 大对象与缓存治理
4. 文档持续维护

详见：

- [07_CROSS_CUTTING_AND_ACCEPTANCE.md](./07_CROSS_CUTTING_AND_ACCEPTANCE.md)

## 4. 第一优先级建议执行顺序

1. 先做 `M0`，冻结基线，避免迁移过程中口径漂移。
2. 再做 `M1 + M2`，先把 Axum 壳与鉴权打稳。
3. 当前执行顺序允许前置 `M6` 的 OSS 基础设施与直传票据能力，为后续各阶段复用统一资产入口。
4. 再做 `M3`，优先跑通快照、设置、profile。
5. 再做 `M4`，把 story action 主循环真正迁走。
6. 然后做 `M5`，迁 custom world 与 agent。
7. 最后收口 `M6` 余下资产绑定、`M7` 部署与切流。

## 5. 最终验收清单

- [ ] 当前 `96` 条后端接口已全部迁移或有兼容替代
- [ ] 当前 `6` 个挂载面已全部迁移
- [ ] 当前 `12` 个内部模块已完成新架构落位
- [ ] Axum 已成为唯一 HTTP / SSE / 副作用边界
- [ ] SpacetimeDB 已成为唯一运行时状态真相源
- [ ] 阿里云 OSS 已成为唯一资产对象仓
- [ ] 前端主流程在不大改 UI 的前提下可跑通
- [ ] 能完成灰度切流，并保留可回退能力