# 基于 SpacetimeDB + Axum + 阿里云 OSS 的后端重写设计文档

日期：`2026-04-20`

## 1. 文档定位

这份文档不是继续扩写当前 `server-node/` 的实现细节，而是基于**当前仓库已经落地的后端能力**，为下一版 Rust 后端提供一份可以直接落地编码的重写设计。

目标很明确：

1. 保留当前项目已经具备的后端能力面，不做需求缩水。
2. 把后端实现从 `Express + PostgreSQL + 本地 public/generated-* 文件` 重写为：
   - `Axum`：唯一 HTTP 边界层与流式接口层
   - `SpacetimeDB`：唯一运行时状态与实时订阅真相源
   - `阿里云 OSS`：唯一大文件与二进制资产存储
3. 让前端在第一阶段尽量少改，优先兼容当前 `/api/*`、`/healthz`、SSE 与资源路径习惯。

## 2. 当前工程必须继承的能力基线

以下能力清单来自 `2026-04-20` 迁移设计时对旧 Node 后端的快照整理，只作为迁移参考，不再作为新功能扩展依据。后续实现方向以 `docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md` 为准。

- 对外挂载面：`6` 个
- 已登记路由：`96` 条
- 内部模块目录：`12` 个
- 公开接口：`10` 条
- JWT 接口：`69` 条
- 环境开关接口：`17` 条
- 流式接口：`6` 条

当前 Node 后端的历史基线仍然是这 `6` 个挂载面，但自 `2026-04-21` 起，本轮 Rust 后端重写的 active rewrite target 固定为其中 `5` 个：

1. `health`
2. `auth`
3. `assets`
4. `runtime-main`
5. `runtime-story-action`

补充说明：

1. `editor` 挂载面在历史系统中真实存在，但已被确认为遗留无用能力。
2. `editor` 仅保留为历史基线对照，不纳入本轮 `server-rs` 重写验收。
3. 当前执行顺序允许在 `M3 / M4 / M5` 前，先前置 `assets / OSS` 的基础设施接入，以便后续 runtime、custom world、agent 统一复用同一资产入口。

当前后端内部模块也不能“凭感觉重设计”，而要按现有职责做映射：

1. `ai`
2. `assets`
3. `combat`
4. `custom-world`
5. `editor`
6. `inventory`
7. `npc`
8. `progression`
9. `quest`
10. `runtime`
11. `runtime-item`
12. `story`

其中：

1. 上述 `12` 个模块是历史基线总量。
2. 本轮 active rewrite modules 固定为 `11` 个。
3. `editor` 仅保留历史事实，不进入 `server-rs` 主线 crate 与阶段验收。

## 3. 技术选型后的硬边界

### 3.1 SpacetimeDB 的平台约束与本项目边界

根据 SpacetimeDB 官方 Rust crate 文档，`reducer` 不能直接使用 `std::net` 或 `std::fs` 进行外部 IO；而 2.0 官方文档又提供了 `procedure + ctx.http` 的受控 HTTP 能力。  
也就是说，**平台层面并不是完全不能做外部调用**，但对于本项目这次重写，我们仍然主动把下面这些副作用统一放到 Axum，而不是塞进 SpacetimeDB：

1. 阿里云 OSS 上传、下载、签名
2. DashScope / Ark / 其他 LLM 请求
3. 微信 OAuth
4. 短信验证码
5. 本地文件系统读写

这样设计不是因为“SpacetimeDB 绝对做不到”，而是因为这类能力都要求：

1. 更强的重试、超时、日志和熔断能力
2. 更自由的 SDK / multipart / 签名上传实现
3. 与 HTTP 头、cookie、回调、对象存储策略深度耦合
4. 与游戏状态 schema 解耦，避免把第三方供应商能力直接绑进数据库模块发布周期

结论：

- `SpacetimeDB` 负责状态、规则、订阅、命令执行与读模型。
- `Axum` 负责所有外部副作用与 HTTP 协议。
- 在本次重写中，不为 SpacetimeDB module 增加任何外部副作用例外通道。

### 3.2 Axum 的边界

根据 Axum 官方文档，`Router<S>` 通过 `.with_state(...)` 注入共享状态后才成为可真正 `serve()` 的路由树；因此 Axum 适合作为：

1. 统一 HTTP 入口
2. Bearer / Cookie 鉴权入口
3. SSE 输出入口
4. OSS 上传凭证签发入口
5. 与 SpacetimeDB 的应用层编排入口

结论：

- Axum 是唯一 BFF / API Gateway。
- 前端第一阶段仍然只认识 Axum，不直接依赖 SpacetimeDB 原生接口。
- 在 `M0 ~ M6` 迁移期内，不新增前端直连 SpacetimeDB 的主链方案。

### 3.3 OSS 的边界

根据阿里云 OSS 官方文档：

1. `PostObject` 适合浏览器表单直传，服务端可以下发 `policy`、`signature` 与上传条件。
2. `STS` 临时访问凭证适合把上传权限以有限时、有限范围的方式下发给客户端。
3. `PutObject` / `PostObject` 都支持 `x-oss-meta-*` 元数据与标签。

结论：

- 所有图片、动画、精灵表、场景图、封面图、视频参考素材都存 OSS。
- SpacetimeDB 只存 `bucket`、对象键、版本、尺寸、状态、逻辑元数据，不存二进制。
- Axum 负责下发直传凭证、校验上传结果、补写元数据。

## 4. 目标总体架构

```text
Web / Mobile Frontend
├─ 继续访问 /api/*、/healthz、/generated-*
└─ 第一阶段不直接依赖 SpacetimeDB 原生协议

Axum API Server
├─ auth：登录、refresh cookie、JWT/OIDC 签发
├─ runtime facade：兼容当前 REST / SSE contract
├─ asset gateway：OSS 直传签名、对象确认、媒体任务编排
├─ ai gateway：DashScope / Ark / 其他模型调用
├─ background workers：异步作业执行与回写
└─ SpacetimeDB client：调用 reducer、查询 view / public table、订阅任务状态

SpacetimeDB Module
├─ auth tables：用户、身份、session、风控、审计
├─ runtime tables：存档、设置、浏览历史、个人面板
├─ gameplay tables：story / npc / quest / inventory / combat / progression
├─ custom-world tables：问答会话、agent 会话、草稿卡、操作记录
├─ asset metadata tables：生成任务、对象清单、引用关系
├─ reducers：唯一状态写入口
└─ views / public tables：唯一读模型与订阅面

Aliyun OSS
├─ generated-character-drafts
├─ generated-characters
├─ generated-animations
├─ generated-custom-world-scenes
├─ generated-custom-world-covers
├─ generated-qwen-sprites
└─ temp-uploads / workflow-cache
```

## 5. 重写后的核心原则

### 5.1 先兼容当前 API 面，再逐步让前端吃到实时能力

第一阶段不要强推前端直接改成 SpacetimeDB 客户端模式，而是：

1. Axum 保持当前 `/api/*` 路由空间。
2. Axum 保持当前 `x-request-id / x-api-version / x-route-version` 头和响应 envelope。
3. Axum 保持当前 story / custom-world-agent 的 SSE 体验。
4. SpacetimeDB 先做后端内部真相源。

补充执行口径：

1. 虽然总体里程碑仍保留 `M6` 编号，但 `OSS` 的平台适配、浏览器直传票据与旧 `/generated-*` 路径兼容能力允许提前于 `M3 / M4 / M5` 落地。
2. 提前落地的目标是先收口统一资产入口，不是提前把全部资产业务状态迁完。

第二阶段再按模块把只读页改成直接订阅 SpacetimeDB。

### 5.2 命令与读模型分离

SpacetimeDB 官方文档明确说明：

1. reducer 是唯一可修改表的入口。
2. reducer 不直接返回业务数据给客户端。
3. view 可被查询与订阅，并会随底层表变化自动更新。

因此本项目必须采用：

- `Reducer = 命令入口`
- `View / Public Table = 读模型入口`
- `Axum = HTTP 兼容层与聚合层`

### 5.3 大对象不进数据库

当前 Node 后端把生成结果落在 `public/generated-*`。重写后统一改成：

- `OSS` 存二进制
- `SpacetimeDB` 存引用和状态
- `Axum` 输出 URL、签名 URL 或 CDN URL

### 5.4 Schema 必须按 SpacetimeDB 的迁移约束设计

SpacetimeDB 官方文档对自动迁移的限制很强：

1. 删表、改列类型、改列名、调整列顺序都不是安全日常操作。
2. 新列只能追加到表末尾，且要提供默认值。
3. reducer 改名或删除会直接影响客户端调用。

因此本项目的数据模型必须尽量满足：

1. 主表稳定、字段追加式演进
2. 高频变化数据优先事件表化
3. 聚合结果优先投影表 / view，而不是频繁重塑旧表结构

### 5.5 主工程必须按多 crate 方式组织模块

从当前版本开始，Rust 后端固定采用“主工程 crate + 独立模块 crate”的方式组织。

这里再明确一层：

1. `crates/` 只是工作区下统一承载 Rust crate 的目录名。
2. 目录里的每个独立单元在 Rust 语义上都按 workspace crate 对待。

组织规则固定为：

1. `crates/api-server` 作为 Axum 主工程 crate，只负责协议装配与模块组合。
2. `crates/spacetime-module` 作为 SpacetimeDB 主工程 crate，只负责聚合各模块 crate 的表、reducer、view。
3. 每个独立业务模块必须优先拥有自己的 workspace crate，再由主工程 crate 引用。
4. 只有共享 contract、共享领域内核、平台适配、SpacetimeDB client 这类跨模块能力，才允许使用共享 crate。

这样做的目的，是避免把当前 `12` 个既有模块边界重新压缩回单个“大 application crate”或“大 domain crate”中，确保后续重写能继续按模块独立演进。

### 5.6 SpacetimeDB 相关修改的执行约束

从当前版本开始，凡是涉及 `SpacetimeDB` 的设计、实现、脚本、调试与前端接入，统一要求显式使用以下 skill 作为执行依据：

1. [$spacetimedb-cli](../../.codex/skills/spacetimedb-cli/SKILL.md)
2. [$spacetimedb-rust](../../.codex/skills/spacetimedb-rust/SKILL.md)
3. [$spacetimedb-concepts](../../.codex/skills/spacetimedb-concepts/SKILL.md)
4. [$spacetimedb-typescript](../../.codex/skills/spacetimedb-typescript/SKILL.md)

执行要求：

1. 涉及 `spacetime` CLI、发布、绑定生成、本地联调时，优先按 `spacetimedb-cli` 约束执行。
2. 涉及 `crates/spacetime-module` 的表、reducer、view、Rust API 使用时，优先按 `spacetimedb-rust` 与 `spacetimedb-concepts` 约束执行。
3. 涉及前端或 Node 侧的 SpacetimeDB 绑定、订阅、TypeScript SDK 接入时，优先按 `spacetimedb-typescript` 与 `spacetimedb-concepts` 约束执行。
4. 若 skill 约束与仓库内已有旧实现存在冲突，必须先以 skill 约束校正设计文档与实现方案，再继续编码，避免沿用已过时或幻觉式 API。

## 6. 推荐工程结构

本次重写固定在仓库根目录新增 Rust 工作区 `server-rs/`，并与 `server-node/` 同级：

```text
server-rs/
├─ Cargo.toml
├─ crates/
│  ├─ api-server/                # Axum 主工程 crate，负责装配路由、中间件、SSE 与模块引用
│  ├─ spacetime-module/          # SpacetimeDB 主工程 crate，负责聚合表、reducer、view 并发布 wasm
│  ├─ module-auth/               # 鉴权与会话模块 crate
│  ├─ module-runtime/            # runtime snapshot / settings / profile 模块 crate
│  ├─ module-story/              # story 主循环模块 crate
│  ├─ module-combat/             # 战斗规则模块 crate
│  ├─ module-inventory/          # 背包与奖励模块 crate
│  ├─ module-npc/                # NPC 状态与对话模块 crate
│  ├─ module-progression/        # 成长与章节推进模块 crate
│  ├─ module-quest/              # 任务运行时模块 crate
│  ├─ module-runtime-item/       # 运行时物品模块 crate
│  ├─ module-custom-world/       # 自定义世界与 agent 模块 crate
│  ├─ module-assets/             # 资产任务与对象绑定模块 crate
│  ├─ module-ai/                 # AI 编排模块 crate
│  ├─ shared-contracts/          # HTTP DTO / SSE event / 前后端兼容 contract
│  ├─ shared-kernel/             # 跨模块共享领域类型、ID、枚举、值对象
│  ├─ shared-logging/            # 工作区统一日志初始化与 tracing subscriber 基础设施
│  ├─ platform-auth/             # JWT、cookie、provider adapter
│  ├─ platform-oss/              # OSS 直传、签名、对象管理
│  ├─ platform-llm/              # DashScope / Ark / 其他模型适配
│  ├─ spacetime-client/          # 生成 bindings 后的 DB client adapter
│  └─ tests-support/             # 集成测试、contract 测试、smoke 支撑
└─ scripts/
   ├─ dev.sh / dev.ps1
   ├─ check.sh / check.ps1
   ├─ spacetime-dev.sh / spacetime-dev.ps1
   └─ smoke.sh / smoke.ps1
```

目录职责约束：

1. `crates/api-server/` 只做协议装配、鉴权、中间件、handler 与模块组合，不把业务模块重新堆回单包。
2. `crates/spacetime-module/` 只负责聚合各模块 crate 的状态模型，不直接承接外部副作用。
3. `crates/module-*` 保持与当前业务模块边界一一对应，已明确退出本轮的 `editor` 遗留模块除外；必要时可在 crate 内部再拆 `application`、`domain`、`spacetime` 子层次。
4. `crates/shared-contracts/` 负责与当前前端兼容的 JSON / SSE 协议。
5. `crates/shared-kernel/` 只放跨模块复用的数据结构和规则，不碰框架。
6. `crates/shared-logging/` 负责统一日志初始化、过滤器解析与 subscriber 基础设施，不承接 HTTP 业务语义。
7. `crates/platform-*` 统一承接三方供应商与平台适配。

命名补充说明：

1. 本文后续若出现 `auth-service`、`oss-service`、`llm-service`、`application::...` 等历史逻辑名，统一视为职责标签，而不是强制要求继续存在同名顶层目录。
2. 在新的多 crate 版本中，这些职责会落到 `crates/module-*` 内部子层次，或落到 `crates/platform-*`、`crates/shared-*` 等共享 crate 中。

## 7. 目标模块映射

| 当前模块 | 重写后主归属 | 次归属 | 说明 |
| --- | --- | --- | --- |
| `auth` | Axum `auth-service` + SpacetimeDB private tables | 无 | 登录入口、refresh cookie、JWT/OIDC、审计与风控拆为“Axum 处理副作用 + SpacetimeDB 落状态”。 |
| `runtime` | SpacetimeDB module | Axum facade | 存档、设置、浏览历史、profile dashboard 统一进入 SpacetimeDB。 |
| `story` | SpacetimeDB module | Axum SSE facade | story action、状态推进、可选项构造、恢复态读取以后端 reducer/view 为准。 |
| `combat` | SpacetimeDB module | 无 | 纯规则计算，天然适合 reducer。 |
| `inventory` | SpacetimeDB module | 无 | 背包、赠礼、交易、物品副作用全部 reducer 化。 |
| `npc` | SpacetimeDB module | Axum for LLM dialogue | 关系、招募、状态机在 SpacetimeDB；LLM 台词生成留在 Axum。 |
| `progression` | SpacetimeDB module | 无 | 关卡、等级、敌对 scaling、章节推进都做领域表和 reducer。 |
| `quest` | SpacetimeDB module | Axum for AI quest drafting | 任务主状态在 SpacetimeDB；生成型内容由 Axum 生产后回写。 |
| `runtime-item` | SpacetimeDB module | Axum for AI intent | 物品奖励和解析归 reducer；AI 意图生成由 Axum 负责。 |
| `custom-world` | SpacetimeDB module + Axum orchestration | OSS | 会话、草稿、agent 状态放 SpacetimeDB；世界编译、资产生成、发布编排在 Axum。 |
| `ai` | Axum `llm-service` | SpacetimeDB task tables | 外部模型调用全部放 Axum。 |
| `assets` | Axum `oss-service` | SpacetimeDB asset metadata | 二进制进 OSS，元数据进 SpacetimeDB。 |

补充说明：

1. 历史 `editor` 模块不纳入 `server-rs` 本轮重写。
2. 相关 `/api/editor/*` 与 `server-node/src/modules/editor` 仅保留为旧系统对照事实，后续若要清理再单独立项。

## 8. 数据建模方案

## 8.1 表的分层

建议在 SpacetimeDB 中至少拆成 5 组表：

### A. 身份与会话表

- `user_account`
- `auth_identity`
- `refresh_session`
- `auth_audit_log`
- `auth_risk_block`
- `sms_auth_event`
- `wechat_auth_state`

说明：

1. 这些表默认都应为 private。
2. 密码哈希、短信验证码校验、微信 code 换 token 的动作在 Axum 完成。
3. Axum 再调用 reducer 写入最终结果。

`user_account` 的详细字段、状态迁移与旧 `users` 映射规则，见：

- [SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_USER_ACCOUNT_TABLE_DESIGN_2026-04-21.md)

`auth_identity` 的 provider 约束、唯一键与手机号/微信身份写入规则，见：

- [SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_IDENTITY_TABLE_DESIGN_2026-04-21.md)

`refresh_session` 的 cookie/hash 边界、轮换与吊销语义，见：

- [SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_REFRESH_SESSION_TABLE_DESIGN_2026-04-21.md)

`auth_audit_log` 的事件范围、追加写规则与 DTO 派生约束，见：

- [SPACETIMEDB_AUTH_AUDIT_LOG_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_AUDIT_LOG_TABLE_DESIGN_2026-04-21.md)

`auth_risk_block` 的作用域、活跃态与解除规则，见：

- [SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_AUTH_RISK_BLOCK_TABLE_DESIGN_2026-04-21.md)

`sms_auth_event` 的事件范围、发送/校验写入规则、统计口径与和风控/审计表的边界，见：

- [SPACETIMEDB_SMS_AUTH_EVENT_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_SMS_AUTH_EVENT_TABLE_DESIGN_2026-04-21.md)

`wechat_auth_state` 的字段、过期时间、授权场景、callback 单次消费与清理策略，见：

- [SPACETIMEDB_WECHAT_AUTH_STATE_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_WECHAT_AUTH_STATE_TABLE_DESIGN_2026-04-21.md)

### B. 运行时主状态表

- `runtime_snapshot`
- `runtime_setting`
- `profile_dashboard_state`
- `profile_wallet_ledger`
- `profile_played_world`
- `profile_save_archive`
- `user_browse_history`

说明：

1. `runtime_snapshot` 继续作为“恢复游戏”的主聚合表。
2. `profile_*` 作为只读页投影表，避免每次从大快照现算。
3. `browse_history`、`save_archive` 单独建表，不要藏进 snapshot blob。

### C. Gameplay 领域表

- `story_session`
- `story_event`
- `npc_state`
- `quest_record`
- `inventory_slot`
- `treasure_record`
- `battle_state`
- `player_progression`
- `chapter_progression`

说明：

1. `story_action` 不直接改大 JSON，而是 reducer 驱动多个领域表。
2. 是否继续保留兼容快照，可由投影 reducer 汇总生成。
3. 旧前端仍需要 `gameState + currentStory` 时，由 Axum 聚合成兼容 DTO。

### D. Custom World 表

- `custom_world_profile`
- `custom_world_session`
- `custom_world_agent_session`
- `custom_world_agent_message`
- `custom_world_agent_operation`
- `custom_world_draft_card`
- `custom_world_asset_link`
- `custom_world_gallery_entry`

说明：

1. 传统问答流与 Agent 流不再混一个 payload。
2. 卡片、操作、消息必须拆表，不能再都塞进一个大 JSON 会话体。
3. 公开画廊作为独立投影，避免从 profile 运行时拼装。

### E. 资产与对象元数据表

- `asset_job`
- `asset_object`
- `asset_manifest`
- `character_visual_asset`
- `character_animation_asset`
- `scene_image_asset`
- `sprite_sheet_asset`

说明：

1. 任务状态在 SpacetimeDB。
2. 二进制对象在 OSS。
3. `asset_object` 的正式真相字段固定为 `bucket + object_key`。
4. 所有 URL 都只作为派生读模型，不作为对象主键存储。
5. `asset_object` 的首版字段、访问级别与索引设计见：
   - [SPACETIMEDB_ASSET_OBJECT_TABLE_DESIGN_2026-04-21.md](./SPACETIMEDB_ASSET_OBJECT_TABLE_DESIGN_2026-04-21.md)

## 8.2 public / private 原则

依据 SpacetimeDB 官方访问权限文档：

1. private table 默认只给 reducer / view / owner 看。
2. public table 才适合直接查询和订阅。

本项目建议：

- `auth_*`、`refresh_session`、风控、验证码全部 private
- `runtime_snapshot` private
- `story_session` private
- `custom_world_agent_*` 绝大多数 private
- `gallery`、公共角色卡、公共作品索引可 public
- 如需“用户自己的读模型”，优先用 `ViewContext` view 暴露

## 8.3 view 设计原则

依据 SpacetimeDB 官方 view 文档：

1. view 可以被查询和订阅，底层表变化时会自动更新。
2. `AnonymousViewContext` 可被所有用户共享物化结果，性能明显优于按用户单独计算。
3. view 不适合全表 `.iter()` 扫描，应该通过索引查找或返回可分析的 query。

所以本项目的 view 设计规则必须是：

1. 画廊、排行榜、商店、公共世界列表，优先匿名 view。
2. “我的背包 / 我的档案 / 我的当前会话”这类按用户隔离的读模型，才用带身份上下文的 view。
3. 首页、资料库、历史记录、存档列表都必须先有索引，再写 view。

## 9. 鉴权设计

## 9.1 总体方案

建议保留当前“密码 / 手机验证码 / 微信”三类登录能力，但把实现改成：

1. Axum 负责登录副作用：
   - 密码校验
   - 短信发送与校验
   - 微信 OAuth code 交换
   - refresh cookie 签发与轮换
2. Axum 负责签发**OIDC 兼容 JWT**
3. 同一张 JWT 同时用于：
   - Axum 自身 Bearer 鉴权
   - SpacetimeDB reducer / view 的身份透传

这是可行的，因为 SpacetimeDB 官方文档说明其可以从 OIDC 兼容 JWT 中提取身份声明，并在模块上下文中使用这些 claims。

## 9.2 Token 设计

建议：

- `iss`：固定为 Axum 网关身份发行者，例如 `https://api.genarrative.example/auth`
- `sub`：稳定用户 ID
- 扩展 claims：
  - `sid`：session id
  - `provider`：password / phone / wechat
  - `roles`
  - `phone_verified`
  - `display_name`

`iss/sub/sid/provider/roles/ver/phone_verified/binding_status` 的字段定义、哪些字段禁止进入 JWT、以及 Axum 与 `SpacetimeDB` 的使用边界，见：

- [OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md](./OIDC_JWT_CLAIMS_DESIGN_2026-04-21.md)

## 9.3 Refresh Session

建议保留当前模式：

1. 浏览器短期 Bearer access token
2. HttpOnly refresh cookie
3. refresh session 服务端可吊销

但新的会话 ledger 写入 SpacetimeDB private 表即可。

## 10. Axum 侧设计

## 10.1 进程职责

Axum 进程建议拆成以下子系统：

1. `http::middleware`
   - request id
   - tracing
   - envelope / 错误标准化
   - auth extractor
2. `http::routes`
   - `/healthz`
   - `/api/auth/*`
   - `/api/runtime/*`
   - `/api/runtime/story/*`
   - `/api/assets/*`
3. `application::services`
   - story facade
   - runtime snapshot facade
   - custom world facade
   - asset facade
4. `infra`
   - SpacetimeDB client
   - OSS adapter
   - DashScope / Ark adapter
   - SMS / WeChat adapter

## 10.2 流式接口

当前项目已经有 6 条流式接口，重写时不建议一上来全部改成 WebSocket。

第一阶段建议：

1. 继续使用 Axum SSE 输出流式文本与阶段事件。
2. Axum 在处理流式过程中，持续把阶段状态写回 SpacetimeDB。
3. 前端仍按当前 SSE 协议消费。

适合继续保留为 Axum SSE 的场景：

1. `story/initial`
2. `story/continue`
3. `chat/character/*`
4. `chat/npc/*`
5. `custom-world/generate/stream`
6. `custom-world/agent/messages/stream`

## 10.3 兼容 contract

Axum 第一阶段需要兼容当前项目的这些约定：

1. 路径空间不变
2. `x-request-id`
3. `x-api-version`
4. `x-route-version`
5. `x-response-time-ms`
6. 可选 envelope：`x-genarrative-response-envelope`

这样前端可以在不大改 `src/services/*` 的前提下切换后端实现。

## 11. OSS 设计

## 11.1 对象键规划

建议统一对象键前缀，保持与当前前端路径习惯接近：

```text
generated-character-drafts/{character_id}/{job_id}/{file}
generated-characters/{character_id}/visual/{asset_id}/{file}
generated-animations/{character_id}/{animation_set_id}/{action}/{file}
generated-custom-world-scenes/{profile_id}/{landmark_id}/{asset_id}/{file}
generated-qwen-sprites/{role_id}/{sheet_id}/{file}
generated-custom-world-covers/{profile_id}/{asset_id}/{file}
workflow-cache/{workflow_type}/{workflow_id}.json
```

## 11.2 上传模式

建议：

1. 前端直传图片、封面、小文件：`PostObject`
2. 大文件或需要细粒度控制时：`STS + PutObject / Multipart`
3. 生成型资产：Axum worker 直接上传 OSS

其中：

- `PostObject` 用于浏览器上传时，Axum 负责生成 policy 与 signature。
- policy 中必须明确：
  - key 前缀
  - content-type 白名单
  - content-length-range
  - success_action_status

当前已落地的最小实现补充：

1. `server-rs/crates/platform-oss` 已提供 `PostObject` 直传签名能力。
2. `server-rs/crates/api-server` 已暴露 `POST /api/assets/direct-upload-tickets`。
3. `server-rs/crates/platform-oss` 已提供私有对象 `GET` 短期签名 URL 能力。
4. `server-rs/crates/api-server` 已暴露 `GET /api/assets/read-url`。
5. 上传接口当前输出：
   - `bucket`
   - `objectKey`
   - `legacyPublicPath`
   - `formFields`
   - `expiresAt`
6. 读取接口当前支持：
   - `objectKey`
   - `legacyPublicPath`
   - `expireSeconds`
7. 当前 bucket 已明确为私有读写，因此 `publicUrl` 不再作为正式对象真相输出。
8. 当前签名链路优先兼容旧公开前缀：
   - `/generated-character-drafts/*`
   - `/generated-characters/*`
   - `/generated-animations/*`
   - `/generated-custom-world-scenes/*`
   - `/generated-custom-world-covers/*`
   - `/generated-qwen-sprites/*`
9. 当前 `POST /api/assets/sts-upload-credentials` 已按“服务器上传、Web 只下载”的需求固定为禁用式 contract，不向浏览器下发 OSS 写权限。
10. 当前 `platform-oss` 已提供服务端 `PutObject` 上传 helper，供后续 AI worker 上传生成资源后继续走对象确认链路。

## 11.3 元数据与标签

建议所有业务对象写入统一元数据：

- `x-oss-meta-owner-user-id`
- `x-oss-meta-profile-id`
- `x-oss-meta-entity-id`
- `x-oss-meta-asset-kind`
- `x-oss-meta-source-job-id`
- `x-oss-meta-content-hash`
- `x-oss-meta-origin`

注意：

1. OSS 官方文档要求自定义元数据使用 `x-oss-meta-*` 前缀。
2. 所有元数据总大小不能超过 `8 KB`。

## 11.4 URL 策略

建议：

1. 业务表里统一存 `bucket + object_key`
2. 对外输出 `cdn_url` 或签名 URL
3. 私有对象默认输出短期签名 URL，而不是假设匿名公开读

为了兼容当前前端相对路径使用习惯，第一阶段可以让 Axum 或 CDN 兼容以下历史前缀：

1. `/generated-character-drafts/*`
2. `/generated-characters/*`
3. `/generated-animations/*`
4. `/generated-custom-world-scenes/*`
5. `/generated-custom-world-covers/*`
6. `/generated-qwen-sprites/*`

补充约束：

1. 当前 `xushi-dev` bucket 已明确为私有读写，因此这些旧前缀在第一阶段只代表兼容路径习惯，不代表对象可匿名读取。
2. Web 端若拿到的是历史 `/generated-*` 路径，必须先调用 `GET /api/assets/read-url` 换取 `signedUrl`，不能直接把该路径当成正式可读 URL。
3. 前端工程内凡是图片、背景图、封面图、角色图、场景图等展示入口，只要可能接收到 `/generated-*`，都必须统一走资源解析层：
   - 列表/卡片/普通 `<img>` 优先复用 `src/services/assetReadUrlService.ts`
   - 组件内优先复用 `src/hooks/useResolvedAssetReadUrl.ts`
   - 通用图片标签优先复用 `src/components/ResolvedAssetImage.tsx`
   - 当前已完成的高优先级入口包括：`CharacterAnimator`、`CharacterPanel`、`CompanionCampModal`、`CharacterSelectionFlow`、`MapModal`、`GameCanvasSceneLayer`、`GameCanvasShared`、`GameCanvasEntityLayer`、`CustomWorldResultView`、`CustomWorldEntityEditorModal`、`CustomWorldRoleAssetStudioModal`、`CustomWorldAgentDraftDetailPanel`、`PlatformHomeView`、`PlatformWorldDetailView`、`QwenSpriteSheetTool`
4. 对私有 OSS 资源，前端在签名地址返回前不能先回退渲染原始 `/generated-*` 路径，否则浏览器会先发起一次无签名请求并触发 `403`。
2. 具体对象引用设计见：
   - [SPACETIMEDB_ASSET_OBJECT_STORAGE_DESIGN_2026-04-21.md](./SPACETIMEDB_ASSET_OBJECT_STORAGE_DESIGN_2026-04-21.md)

## 12. 关键业务流设计

## 12.1 Story Action

目标：

1. `storyActionService` 当前承担的跨模块结算必须迁到 SpacetimeDB reducer。
2. Axum 只做 request parse、auth、调用 reducer、读取 view、拼回当前前端响应。

推荐流程：

1. 前端 `POST /api/runtime/story/actions/resolve`
2. Axum 校验请求并附带 JWT
3. Axum 调用 SpacetimeDB `resolve_story_action` reducer
4. reducer 内部联动：
   - `story`
   - `combat`
   - `inventory`
   - `npc`
   - `quest`
   - `runtime-item`
   - `progression`
5. reducer 写回领域表
6. Axum 再读取 `current_story_view`、`runtime_snapshot_view`
7. Axum 返回兼容当前前端的 `RuntimeStoryActionResponse`

## 12.2 存档与恢复

目标：

1. 仍保留当前“完整恢复游戏”的能力。
2. 但底层不再由 PostgreSQL 单大 JSON 承担全部职责。

建议：

1. `runtime_snapshot` 继续保留兼容聚合快照，满足现有恢复链路。
2. gameplay 真相由领域表维护。
3. 每次重要 reducer 提交后，异步或同步刷新 snapshot projection。

这样可以兼顾：

1. 旧前端兼容
2. 新后端可审计
3. SpacetimeDB 实时订阅能力

## 12.3 Custom World Agent

当前 Node 后端中，`customWorldAgentOrchestrator + SessionStore + Operation` 已经是一条清晰主链。  
重写后建议进一步正规化：

1. SpacetimeDB：
   - 存会话
   - 存消息
   - 存卡片
   - 存操作状态
   - 存草稿 profile
2. Axum：
   - 调 LLM
   - 调图片生成
   - 调 OSS
   - 发 SSE
   - 把阶段结果回写 reducer

不再允许“一整个 agent 会话对象 JSON 一把写回”作为长期形态。

## 12.4 资产生成

资产链路拆成四步：

1. Axum 创建 `asset_job`
2. Axum worker 调外部模型
3. 产物上传 OSS，写 `asset_object`
4. Axum 调 reducer 将对象绑定到：
   - 角色
   - 地点
   - 世界草稿
   - Qwen sprite sheet

所有“对象是否已经被业务引用”的事实，以 SpacetimeDB 绑定表为准，而不是以 OSS 是否存在某个 key 为准。

## 13. 迁移阶段建议

迁移期仓库边界补充约束：

1. 旧 `server-node/` 在 `M0 ~ M6` 期间继续保留，作为协议对照、回归基线与回退锚点。
2. 只有在 `M7` 切流、回归、回退方案都稳定后，才评估是否清理旧 Node 后端。

## Phase 0：冻结能力清单

交付：

1. 固定当前 `96` 条接口为重写验收基线
2. 固定当前 `12` 个模块为迁移映射基线
3. 固定当前前端 contract 与 SSE 协议

## Phase 1：先搭 Axum 外壳与鉴权

交付：

1. `/healthz`
2. `/api/auth/*`
3. response envelope
4. request id / tracing
5. Axum -> SpacetimeDB 基础 client
6. OIDC-compatible JWT 签发

阶段执行补充：

1. 微信登录链路在当前阶段暂缓，不进入连续执行顺序。
2. 当前优先顺序固定为：JWT / refresh cookie / 密码登录 / 手机验证码登录。

## Phase 2：迁移 runtime snapshot / settings / profile

交付：

1. 存档
2. 设置
3. 浏览历史
4. profile dashboard
5. save archives

这是最容易先跑通的闭环。

## Phase 3：迁移 story action 主循环

交付：

1. story reducer
2. combat / inventory / npc / quest / runtime-item / progression 联动
3. `/api/runtime/story/*`

这一阶段完成后，运行时真相就真正从 Node 版切出去了。

## Phase 4：迁移 custom world 与 agent

交付：

1. legacy custom world session
2. custom world library / gallery
3. custom world agent 会话、卡片、操作
4. scene npc / entity generation

## Phase 5：迁移 assets / OSS

交付：

1. OSS 直传
2. 生成任务
3. 对象元数据
4. 旧 `/generated-*` 路径兼容

补充说明：

1. `editor` 已于 `2026-04-21` 被确认为遗留无用模块，退出本轮 Rust 后端重写范围。
2. Phase 5 只覆盖资产与 OSS 主链，不再包含 editor 迁移。

## Phase 6：联调、回归、部署与切流收口

交付：

1. 联调与回归测试体系
2. 灰度环境、切流开关、回退方案
3. tracing / request id / 关键链路观测
4. 拆分 `server-rs/crates/spacetime-module/src/lib.rs`，按业务模块与 SpacetimeDB 的 `table / reducer / procedure / view` 结构重组为 `runtime`、`gameplay::{story/combat/inventory/npc/quest/runtime_item/progression}`、`custom_world`、`asset_metadata`、`ai` 等聚合子模块，主工程 crate 根入口只保留模块声明、统一导出与最小发布入口

阶段执行补充：

1. 这是切流前的工程结构收口，不是新功能扩张；拆分过程中不得改变既有 table schema、reducer / procedure 名称、对外 contract 与 publish 行为。
2. 拆分后的目录与模块边界必须对齐 `M0` 已冻结的模块迁移归属，避免 `spacetime-module` 回退成“单大文件 + 单大包”结构。
3. 拆分完成后至少要保持 `cargo check`、SpacetimeDB 本地 build / publish 开发链路与主流程回归脚本可继续通过。

## 14. 验收标准

重写完成至少要满足：

1. 当前 `96` 条已登记路由全部有对应实现或明确兼容替代。
2. 当前历史 `6` 个挂载面的迁移去向全部明确，且本轮 active rewrite target 的 `5` 个挂载面全部落地。
3. 浏览器无需直接知道 SpacetimeDB 原生接口即可跑通主流程。
4. story action、存档、custom world、agent、assets 都以后端为唯一真相。
5. 所有生成图片、动画、精灵表都不再依赖本地 `public/generated-*` 持久化。
6. Axum 和 SpacetimeDB 的职责边界稳定，不把外部网络 IO 偷放进 module。

## 15. 关键风险

### 15.1 不能把 SpacetimeDB 当 PostgreSQL 替身直接套

SpacetimeDB 更像“带强实时订阅能力的状态机数据库”，不是传统 SQL 仓储替身。  
如果仍沿用“单大 JSON + 巨型路由文件 + 过程式 handler”思路，重写后仍然会很快回到旧热点。

### 15.2 schema 演进成本高于 PostgreSQL

SpacetimeDB 自动迁移更适合“增量追加”，不适合高频改列结构。  
所以必须提前定好：

1. 稳定主键
2. 稳定 reducer 命名
3. 事件表 / 投影表边界

### 15.3 view 滥用会造成性能问题

如果把资料库、画廊、排行榜写成按用户逐个计算、又缺索引的 view，性能会很差。  
因此 read model 必须先建索引，再决定用匿名 view 还是按用户 view。

### 15.4 资产路径兼容是迁移成败关键

当前前端大量相对路径、角色图、场景图、动画图都是围绕 `/generated-*` 组织的。  
如果不先做路径兼容层，存档恢复和世界资料库会大面积失效。

## 16. 内部实现依据

这份设计稿对当前工程的判断，主要依据以下仓库现状：

1. `server-node/src/server.ts`
2. `server-node/src/app.ts`
3. `server-node/src/routes/authRoutes.ts`
4. `server-node/src/routes/runtimeRoutes.ts`
5. `server-node/src/modules/story/storyActionRoutes.ts`
6. `server-node/src/repositories/runtimeRepository.ts`
7. `server-node/src/services/customWorldAgentOrchestrator.ts`
8. 本文第 2 节保留的旧 Node 能力快照
9. `docs/technical/CURRENT_BACKEND_IMPLEMENTATION_BASELINE_2026-04-25.md`

## 17. 外部技术依据

以下外部依据用于确定本次新架构的技术边界，均来自官方文档或官方 crate 文档：

1. [SpacetimeDB Tables](https://spacetimedb.com/docs/tables/)
2. [SpacetimeDB Table Access Permissions](https://spacetimedb.com/docs/tables/access-permissions/)
3. [SpacetimeDB Reducers Overview](https://spacetimedb.com/docs/functions/reducers/)
4. [SpacetimeDB Views](https://spacetimedb.com/docs/functions/views/)
5. [SpacetimeDB Authorization](https://spacetimedb.com/docs/http/authorization/)
6. [SpacetimeDB Authentication](https://spacetimedb.com/docs/core-concepts/authentication/)
7. [SpacetimeDB Using Auth Claims](https://spacetimedb.com/docs/core-concepts/authentication/usage/)
8. [SpacetimeDB Rust crate docs](https://docs.rs/spacetimedb/latest/spacetimedb/)
9. [SpacetimeDB Rust Client SDK](https://spacetimedb.com/docs/sdks/rust/)
10. [Axum crate docs](https://docs.rs/axum/latest/axum/)
11. [Axum SSE](https://docs.rs/axum/latest/axum/response/sse/)
12. [阿里云 OSS 服务端签名表单上传](https://help.aliyun.com/zh/oss/user-guide/form-upload)
13. [阿里云 OSS STS 临时授权访问](https://help.aliyun.com/zh/oss/developer-reference/authorized-access-1)
14. [阿里云 OSS PutObject](https://help.aliyun.com/zh/oss/developer-reference/putobject)
15. [阿里云 OSS PostObject](https://help.aliyun.com/zh/oss/developer-reference/postobject)

## 18. 一句话结论

这次重写最正确的落点不是“把 Express 改成 Axum”，而是：

**让 Axum 成为唯一外部副作用和 HTTP 边界，让 SpacetimeDB 成为唯一状态机真相源，让 OSS 成为唯一资产对象仓，从而在不丢当前 96 条能力面的前提下，把项目升级成真正可持续扩展的 Rust 后端。**