feat: add phone frequency controls and modularize codebase

2026-07-31 22:25:23 +08:00
parent 0af671b4ed
commit ca4f591a13
216 changed files with 41579 additions and 23694 deletions
@@ -0,0 +1,100 @@
+# 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，应拆成独立业务版本，不与文件移动同批发布。