lislgosms/docs/refactoring/r0-release-gate.md

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. 回滚记录模板

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

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