M0：阶段验收矩阵

日期：2026-04-20

依据来源：

1. 文档目的

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

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

2. 阶段推进总规则

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

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

5. 跨阶段回归维度

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

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

6. 阶段证据留存要求

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

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

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

8.9 KiB Raw Blame History Unescape Escape