junhong_cmp_fiber/docs/tech-public-foundation/迁移发布与数据安全回滚.md

公共基础迁移发布与数据安全回滚

执行顺序

1. 使用 ./scripts/test-tech-public-foundation.sh 完成真实依赖公共接缝验收，再使用 go run ./cmd/foundation-check --phase pre 执行只读前置检查。
2. 依次执行 000165_create_public_outbox、000166_create_system_config 正向迁移。
3. 使用 go run ./cmd/foundation-check --phase post 验证字段、约束、索引、异常计数和事务内读写冒烟。
4. 部署兼容 API 和 Outbox Relay/Worker，确认监控就绪后再部署依赖消费者，最后允许前端或生产者放量。

门禁报告只输出稳定错误码、数据库对象安全标识和计数。依赖迁移版本不足或脏状态、对象定义冲突、重复身份、空值、非法枚举、未完成任务、未投递事件和过期租约均以非零状态阻断。

数据迁移与隔离

165/166 只创建新的公共表和索引，不回填历史业务数据，因此没有批次回填步骤。后续确需回填时必须按稳定主键分批记录进度，允许中断重跑并验证行数守恒；不得借本次迁移扫描或改写下游业务表。

自动化验收在独立 PostgreSQL schema 和测试事务内执行，只删除本次创建的 schema 或依赖事务回滚，不执行全库清理。Redis/Asynq 测试使用唯一事件 ID 和配置 Key，并只删除本次任务与缓存键。

回滚边界

新增表为空时，down 迁移允许删除结构。任一公共表已经保存事件或配置事实时，down 迁移主动失败；发布负责人必须停止新生产者、停止 Relay 领取、保留已有事实，回滚无数据风险的应用版本，并修复后向前恢复。禁止通过删表、清空 Outbox 或删除配置事实完成降级。

停止条件包括：迁移门禁异常、Outbox 持续积压或过期租约大量增加、配置读写不一致、Access Log 脱敏回归失败和关键任务无法恢复。