# M0：仓库边界决议

日期：`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)
- [00_MASTER_TASKLIST.md](./00_MASTER_TASKLIST.md)
- [01_M0_M2_FOUNDATION_AND_AUTH.md](./01_M0_M2_FOUNDATION_AND_AUTH.md)

## 1. 文档目的

这份文档用于持续冻结 `M0` 中与仓库边界直接相关的决策，避免进入 `M1` 后再反复改目录、改职责口径。

当前已确认的事项只包含第一条；后续几条会继续在这份文档上追加。

## 2. 边界决议状态

| 事项 | 当前状态 | 当前结论 |
| --- | --- | --- |
| Rust 后端新目录名与根目录落位方案 | 已确认 | 新 Rust 后端固定为仓库根目录下的 `server-rs/`，与 `server-node/` 同级。 |
| 旧 `server-node/` 在迁移期继续保留，不提前删除 | 已确认 | `server-node/` 在 `M0 ~ M6` 期间持续保留，直到 `M7` 切流与回退验证完成后再评估清理。 |
| 前端第一阶段仍然只访问 Axum，不直连 SpacetimeDB | 待确认 | 后续补充。 |
| 外部副作用统一收口在 Axum，不放进 SpacetimeDB 模块 | 待确认 | 后续补充。 |

## 3. 已确认决议一：`server-rs/` 固定落在仓库根目录

### 3.1 决议内容

本次重写固定采用以下仓库落位：

1. 新后端目录名固定为 `server-rs/`
2. 目录位置固定在仓库根目录
3. 与以下目录保持同级：
   - `server-node/`
   - `src/`
   - `docs/`
   - `packages/`

目标形态：

```text
Genarrative/
├─ server-node/
├─ server-rs/
├─ src/
├─ packages/
├─ docs/
└─ backend-rewrite-tasklist/
```

### 3.2 不采用的落位方案

以下方案当前明确不采用：

1. 不放进 `server-node/` 子目录中做“Node + Rust 混编后端”。
2. 不放进 `packages/`，避免被前端 package/workspace 语义误导。
3. 不使用过于泛化的根目录名如 `server/`、`backend/`，避免和当前 `server-node/` 职责混淆。

### 3.3 这样落位的原因

1. 与当前重写设计文档、任务清单、后续 `M1` crate 规划保持一致。
2. 允许 `server-node/` 与 `server-rs/` 在迁移期并行存在，便于逐阶段切流。
3. 让 Rust 工作区边界清晰，不污染现有前端 `src/`、`packages/`、Vite 工具链。
4. 后续新增 `server-rs/scripts/*`、`Cargo.toml`、`crates/*` 时路径最直接，不需要额外中间层。

### 3.4 对后续任务的直接约束

从这一条决议开始，后续任务必须统一按以下路径落位：

1. `M1` 的工作区初始化在 `server-rs/`
2. Axum 入口在 `server-rs/crates/api-server`
3. SpacetimeDB 模块在 `server-rs/crates/spacetime-module`
4. 相关脚本在 `server-rs/scripts/`

## 4. 本条任务完成定义

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

1. 新 Rust 后端目录名已经书面固定为 `server-rs/`
2. 目录位置已经书面固定为仓库根目录
3. 后续 `M1` 的工作区初始化不会再出现 `server-rs/`、`backend-rs/`、`server/` 等多套候选名并存

## 5. 已确认决议二：迁移期保留 `server-node/`

### 5.1 决议内容

在本次重写迁移期内，旧 `server-node/` 固定继续保留，不提前删除、不整体挪位、不提前做破坏性收缩。

保留周期固定为：

1. `M0` 到 `M6` 全阶段
2. 至少持续到 `M7` 的以下条件全部满足之后，才允许评估清理：
   - 新后端已切流
   - 旧接口 contract 回归通过
   - 关键主链 smoke 通过
   - 已具备明确回退方案

### 5.2 保留它的原因

1. 旧 `server-node/` 是当前 `96` 条路由、`6` 个挂载面、`12` 个模块的真实对照实现。
2. 前面已经冻结的路由矩阵、模块迁移清单、SSE 协议、静态资源前缀，都需要它作为回归对照源。
3. 如果在 `M1 ~ M6` 提前删除旧实现，就会失去最可靠的回退锚点与 diff 基准。

### 5.3 迁移期允许做什么

迁移期内允许：

1. 在 `server-rs/` 中逐步补等价实现。
2. 在文档和 manifest 中继续引用 `server-node/` 作为当前系统基线。
3. 在必要时从 `server-node/` 补测试样例、补协议对照、补回归夹具。

迁移期内不允许：

1. 提前整体删除 `server-node/`
2. 把 `server-node/` 改成只剩空壳目录
3. 在还没切流前，把旧服务关键实现批量迁走导致无法对照

### 5.4 对后续任务的直接约束

从这一条决议开始，后续任务必须遵守：

1. `M1` 搭建 `server-rs/` 时，不改动 `server-node/` 的存在性。
2. `M2 ~ M6` 迁移功能时，旧 `server-node/` 继续作为验收基线与回退锚点。
3. 真正评估清理旧 Node 后端的动作，只能放到 `M7` 切流完成之后。