2.4 KiB
2.4 KiB
2026-07-20 回执身份与报表口径迁移说明
升级
- 发布前按生产流程备份 PostgreSQL、运行源码和环境配置并校验归档。
- 依次应用
20260720110000_add_receipt_identity、20260720113000_add_report_business_metrics与20260720114500_add_receipt_phone_number。三者为历史回执生成不冲突的receiptKey，增加回执文本、目的号码和匹配索引，并增加报表失败数及利润退款金额列。历史目的号码先从原关联主记录回填；对已知错绑记录仍须依据生产提交记录、通道和原始 Gateway 日志专项复核，不能仅靠该回填自动改绑。 - 先重启 Gateway，再重启 API；检查 Redis Stream、活动通道、TPS key、API/Gateway health 和近期错误日志。
- 对 T-4 至 T-1 及需修复的历史日期重复执行报表重算，核对查询与 CSV 的发送、成功、失败、收入、退款、成本、利润和到达时长。
- 追加应用
20260721150000_backfill_misattributed_delivery_receipts。该迁移只处理“回执已关联主记录，且主记录 + 上游 Msg_Id + 目的号码只能命中一条提交记录”的成功回执：先把历史错误通道改为真实提交通道，再将成功状态聚合到主记录。零匹配或多匹配记录保持不变。迁移可重复执行且不会创建回执、计费或客户下游投递。 - 新迁移完成并启动 API 后，确认启动时 T-4 至 T-1 重算覆盖受影响日期；若发布日期已使目标历史日超出滚动窗口，必须在受控维护命令中显式重算对应日期，不能只修改报表表格或手工填写成功数。
回滚
应用代码可回滚到上一版本，但新增列和索引默认保留，避免丢失已接收的回执身份、错误文本和重算结果。若确认不存在新版本写入且必须做结构回滚，应先备份，再依次删除两个报表新增列、回执新增列及索引；删除 receiptKey 唯一约束前必须确认旧代码不会再次以模糊条件消费回执。生产禁止未经审批直接执行破坏性回滚。
20260721150000_backfill_misattributed_delivery_receipts 是数据纠正迁移，没有安全的自动逆向迁移。回滚应用代码时保留已纠正的回执和主记录；若业务要求恢复迁移前值，只能从发布前 PostgreSQL 备份按明确记录 ID 定向恢复，禁止用账号或日期范围批量反向覆盖。