# M0：阶段验收矩阵

日期：`2026-04-20`

依据来源：

- [00_MASTER_TASKLIST.md](./00_MASTER_TASKLIST.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)
- [../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md](../docs/technical/SPACETIMEDB_AXUM_OSS_BACKEND_REWRITE_DESIGN_2026-04-20.md)

## 1. 文档目的

这份文档用于把 `M0 ~ M7` 各阶段的入口条件、核心交付、退出条件与回归焦点固定下来，避免后续出现“任务勾完了，但阶段是否真的可进入下一步没有统一标准”的问题。

从本文件开始，后续每一阶段都需要按“入口满足 -> 交付完成 -> 验收通过 -> 留存证据”的顺序推进。

## 2. 阶段推进总规则

1. 未满足上一阶段退出条件前，不进入下一阶段主线编码。
2. 每一阶段至少保留一份可复查的证据，证据可以是文档、脚本、测试结果或回归记录。
3. 所有阶段都必须持续对齐当前冻结基线：
   - 历史基线 `6` 个挂载面
   - 本轮 active rewrite target `5` 个挂载面
   - `96` 条路由
   - `12` 个模块
   - `6` 条 SSE 接口
   - `6` 个 `/generated-*` 静态资源前缀
   - 前端直接依赖的响应头、envelope 与鉴权错误格式
4. 任一阶段若引入新的协议差异，必须先补 contract 文档或迁移说明，再允许继续编码。

## 3. 分阶段验收矩阵

| 阶段 | 入口条件 | 核心交付 | 退出条件 | 回归焦点 |
| --- | --- | --- | --- | --- |
| `M0` 冻结能力与边界 | 已完成当前 Node 后端摸底；已明确目标架构为 `SpacetimeDB + Axum + 阿里云 OSS` | 冻结能力基线、路由矩阵、模块归属、SSE、静态资源前缀、前端响应契约、仓库边界决议、阶段验收矩阵 | `6` 个挂载面、`96` 条路由、`12` 个模块、`6` 条 SSE、`6` 个静态资源前缀全部形成书面基线；`server-rs/`、`server-node/`、Axum 边界、副作用收口原则全部冻结 | 文档口径一致性；前端 contract 依赖项是否被遗漏；迁移阶段是否还存在多套边界说法 |
| `M1` Rust 工作区与 Axum 基础设施 | `M0` 全部退出条件满足 | `server-rs/` workspace、`crates/api-server`、`crates/spacetime-module`、独立模块 crates、统一配置、日志、request id、中间件、response envelope、`/healthz`、开发脚本 | Axum 可独立启动；`/healthz` 与当前工程兼容；`x-request-id`、`x-api-version`、`x-route-version`、`x-response-time-ms` 行为稳定；workspace 完整编译通过；主工程与模块 crate 引用边界稳定 | 基础头部兼容；健康检查兼容；目录结构与 crate 归属是否偏离 `M0` 决议 |
| `M2` 鉴权、会话、JWT 与 refresh cookie | `M1` 已可稳定启动；Axum 中间件与配置链可用 | 身份表、会话表、JWT claims、refresh cookie、密码登录、手机验证码登录、微信登录、OIDC 透传、旧鉴权接口兼容 | 密码登录、refresh cookie、手机验证码、微信登录主链可用；旧鉴权接口 contract 回归通过；SpacetimeDB 可识别 Axum 签发身份 | Cookie 与 JWT 兼容；`CAPTCHA_REQUIRED` 与 `details.captchaChallenge` 是否保持；登录态吊销与刷新是否稳定 |
| `M3` runtime snapshot / settings / profile | `M2` 鉴权稳定；用户身份可透传到 SpacetimeDB | `runtime_snapshot`、`runtime_setting`、profile 相关主表与 facade；存档、设置、浏览历史、save archive 兼容接口 | 登录用户可正常保存、读取、删除存档；profile dashboard / browse history / save archive 行为一致；前端恢复流程可直接跑通 | 快照恢复准确性；兼容路径与主路径是否返回一致；历史记录排序与去重逻辑 |
| `M4` story action 与 gameplay reducer | `M3` 快照与用户状态主链稳定 | story / combat / inventory / npc / quest / progression / runtime-item 表与 reducer；story 兼容接口与 view model | 前端 story 主循环可用；`story state` 恢复链可用；NPC / quest / treasure / combat 主循环行为不回退；旧 Node story route 回归平移完成 | `RuntimeStoryActionResponse` 结构；战斗与奖励联动；状态投影是否与旧前端恢复逻辑一致 |
| `M5` custom world / gallery / agent | `M4` story 与 runtime 真相源已稳定；SSE facade 可持续输出 | custom world 主表、agent 会话拆表、传统问答流、library / gallery、agent 消息与操作、LLM/图片生成编排 | 传统 custom world 主链可用；library / gallery 主链可用；agent 主链可用；会话不再依赖单大 JSON 体 | SSE 事件格式；卡片、消息、操作状态一致性；世界草稿编译与发布链是否可回放 |
| `M6` assets / OSS | `M5` 世界与角色主链稳定；Axum 应用层可承接外部副作用 | OSS 对象键规范、上传签名、对象确认、资产任务表、角色/场景/Qwen 资产迁移、旧静态路径兼容 | 所有新生成资产写入 OSS；前端仍能通过旧路径习惯访问资源；资产任务状态可查询 | `/generated-*` 路径兼容；OSS 元数据与对象绑定关系；资产任务链状态一致性 |
| `M7` 联调、回归、部署与切流 | `M6` 已具备主链闭环；双栈对照条件具备 | 测试体系、部署方案、观测能力、灰度切流方案、回退方案、对比脚本与 smoke 清单 | 全链路 smoke 通过；主流程回归通过；关键 SSE 联调通过；可在灰度环境切流并可回退 | 双跑窗口稳定性；API 对比结果；切流开关、回退开关、观测告警是否齐备 |

## 4. M0 冻结项专用验收清单

只有以下项目全部满足，`M0` 才算真正完成：

1. 已产出以下冻结文档：
   - [M0_CAPABILITY_SURFACE_BASELINE_2026-04-20.md](./M0_CAPABILITY_SURFACE_BASELINE_2026-04-20.md)
   - [M0_ROUTE_MIGRATION_MATRIX_2026-04-20.md](./M0_ROUTE_MIGRATION_MATRIX_2026-04-20.md)
   - [M0_MODULE_MIGRATION_BASELINE_2026-04-20.md](./M0_MODULE_MIGRATION_BASELINE_2026-04-20.md)
   - [M0_SSE_INTERFACE_BASELINE_2026-04-20.md](./M0_SSE_INTERFACE_BASELINE_2026-04-20.md)
   - [M0_GENERATED_STATIC_PREFIX_BASELINE_2026-04-20.md](./M0_GENERATED_STATIC_PREFIX_BASELINE_2026-04-20.md)
   - [M0_FRONTEND_RESPONSE_CONTRACT_BASELINE_2026-04-20.md](./M0_FRONTEND_RESPONSE_CONTRACT_BASELINE_2026-04-20.md)
   - [M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md](./M0_REPOSITORY_BOUNDARY_DECISIONS_2026-04-20.md)
   - [M0_PHASE_ACCEPTANCE_MATRIX_2026-04-20.md](./M0_PHASE_ACCEPTANCE_MATRIX_2026-04-20.md)
2. 已书面冻结以下核心数字：
   - 挂载面：`6`
   - 路由：`96`
   - 模块：`12`
   - SSE：`6`
   - 静态资源前缀：`6`
3. 已书面冻结以下边界决议：
   - 新 Rust 后端固定为仓库根目录 `server-rs/`
   - 迁移期保留 `server-node/`
   - 前端 `M0 ~ M6` 期间只访问 Axum
   - 外部副作用统一收口在 Axum
   - `server-rs/` 内部采用 `crates/*` 多 crate 组织
   - `editor` 已于 `2026-04-21` 退出本轮 Rust 重写范围
4. `M1` 以后任何任务引用路由、模块、SSE、静态资源与响应契约时，都必须能追溯到本阶段产出的冻结文档。

## 5. 跨阶段回归维度

无论执行到哪个阶段，都要持续检查以下维度：

| 维度 | 必查内容 | 最晚必须固化的证据 |
| --- | --- | --- |
| 路由兼容 | 旧路由是否已有新实现或明确替代路径 | 路由迁移矩阵、API 对比脚本、contract 回归记录 |
| SSE 兼容 | 事件名、事件顺序、结束事件、错误事件是否保持兼容 | SSE 基线文档、联调记录、smoke 结果 |
| 静态资源兼容 | `/generated-*` 是否可继续访问，是否正确指向 OSS/CDN | 静态资源前缀基线、路径兼容测试记录 |
| 鉴权兼容 | JWT、refresh cookie、验证码、微信登录、风控错误是否保持兼容 | 鉴权接口回归记录、claims 设计文档、集成测试 |
| 前端 contract | 响应头、envelope、错误结构是否稳定 | response contract 基线、接口测试、前端联调记录 |
| 切流回退 | 双栈是否可对照，是否具备回退能力 | `M7` 对比脚本、灰度清单、回退方案 |

## 6. 阶段证据留存要求

每个阶段完成时，至少要补齐以下其中两类证据：

1. 文档：
   - 更新任务清单勾选状态
   - 更新设计文档或阶段落地记录
2. 测试或脚本：
   - 新增或更新 smoke / contract / integration 测试
   - 新增对比脚本、发布脚本或回归脚本
3. 结果记录：
   - 编码检查结果
   - 关键命令执行结果
   - 联调、回归、灰度演练结果

如果阶段只完成了编码、但没有文档和证据留存，则该阶段不能视为完成。