# R0 渐进式拆分发布与回滚门禁

更新日期：2026-07-30

## 1. 单版本所有权

- 一个拆分版本只能指定一个“结构修改会话”。
- 其他会话可以查阅、测试和报告问题，但不得同时移动同一职责域的文件。
- 开始前记录：负责人、目标域、基线提交、允许修改的文件、明确不修改的文件。
- 发现重叠未提交修改时立即停止移动，先由修改所有者确认边界。

## 2. 开始前检查

- [ ] `git status --short --branch`
- [ ] `git diff`
- [ ] `git fetch`
- [ ] 分别核对 `HEAD` 和 `origin/main`
- [ ] 完整阅读 `docs/testing-progress.md` 最新记录
- [ ] 标记其他会话修改、未跟踪文件和构建产物
- [ ] 选择一个业务域，列出稳定门面、调用者、表、队列和副作用
- [ ] 运行目标域定向特征测试并保存基线结果
- [ ] 确认该版本不混入业务规则修改
- [ ] 确认回滚只需回到本版本前精确提交，不依赖手工修库

## 3. 实施中检查

- [ ] 原公开类、方法、导出名和控制器调用保持兼容
- [ ] 纯移动不同时重命名、格式化或改写逻辑
- [ ] 原事务仍由同一顶层用例持有
- [ ] 子服务接收同一 `Prisma.TransactionClient`
- [ ] 数据库锁顺序、唯一约束、幂等键未改变
- [ ] Redis Stream 名称、消费者组和 JSON 字段未改变
- [ ] CMPP Sequence_Id、Msg_Id、版本和分片规则未改变
- [ ] 错误码、中文提示、金额精度和上海时区口径未改变
- [ ] 新模块依赖单向，不新增 `forwardRef` 循环
- [ ] 每完成一个委托点即运行对应定向测试

## 4. 提交前检查

- [ ] `node tools/quality/verify-refactor-r0.mjs`
- [ ] `node tools/spike/validate-gateway-queue-contract.mjs`
- [ ] 目标域定向测试
- [ ] API 全量测试
- [ ] Prisma format、validate、generate 和 migrate status
- [ ] API TypeScript 正式构建
- [ ] 前端 TypeScript 与 Vite 生产构建
- [ ] Gateway `go test ./...` 和 `go vet ./...`
- [ ] 依赖安全门禁
- [ ] `git diff --check`
- [ ] 逐文件人工核对 diff，确认只有目标域
- [ ] 更新需求、测试用例和 `docs/testing-progress.md`

构建缓存、`outputs/` 和临时文件不能因为“提交全部代码”而混入提交。

## 5. 发布与观察

- [ ] 只使用精确 Git 提交制作发布包
- [ ] 部署前备份 PostgreSQL、运行源码和环境文件
- [ ] 校验本地和服务器发布包 SHA-256
- [ ] 只使用 `tools/deploy/production-deploy.sh`
- [ ] Gateway 先于 API 重启
- [ ] 检查 migration、服务、端口、health、Redis、Stream pending/lag
- [ ] 检查供应商通道和下游客户连接，不修改真实凭据或状态
- [ ] 检查 API/Gateway error 日志
- [ ] 不为重构验收发送、重投或补发真实短信
- [ ] 观察至少一个完整发布周期后再开始同一门面的下一阶段

## 6. 立即停止条件

出现任一情况，停止继续拆分并回到诊断：

- 测试数量减少但没有明确删除用例的依据；
- 同一输入的 API/队列/CMPP 契约发生变化；
- 事务被拆成多个独立提交；
- 账务重复、漏记或余额出现非预期变化；
- 并发测试出现重复提交、重复补发、重复 Deliver 或重复退款；
- Gateway 重连、ACK、分片或 Msg_Id 映射行为变化；
- 页面需要靠 mock、静态数据或 localStorage 才能展示；
- diff 同时跨越两个业务域且无法逐段人工复核。

## 7. 回滚记录模板

```text
版本：
目标域：
结构修改提交：
发布前提交：
数据库 migration：无 / 列表
发布前备份目录：
触发回滚的证据：
是否涉及业务数据修复：
回滚命令/发布包：
回滚后服务与端口：
回滚后 Redis Stream pending/lag：
回滚后通道连接：
回滚后错误日志：
验证人和时间：
```

纯结构拆分原则上不新增 migration。若必须改 schema，应拆成独立业务版本，不与文件移动同批发布。