gyxx-flow/docs/migration-runbook.md

迁移手册

当前边界

• 四个旧项目的源码、数据和现有计划任务保持原状。
• 工作流及其业务脚本已复制到 src/gyxx_flow/modules/*/runtime，运行时不引用旧项目。
• 21 个定时工作流可生成候选系统任务；默认不应用。
• 所有发现到的本地可执行脚本可通过 gyxx scripts 手工 dry-run 或执行。
• 历史数据副本按模块落入新数据根，并保留数量、字节和 SHA-256 对账证据。

工程验收

1. 四份 config/source-manifests/*.json 的目标文件和 SHA-256 全部通过。
2. 扫描源码、配置和启动器，确认无四个旧项目根目录或 GYXX_LEGACY_*_ROOT。
3. 在不设置旧项目环境变量的进程中导入目录、列出脚本并 dry-run 21 个工作流。
4. 执行 uv run pytest、uv run gyxx doctor --json 和 wheel 构建检查。
5. 只生成调度计划，不注册、不禁用任何系统任务。

逐任务生产切换

1. 轮换历史明文凭据，并将新凭据放入外部密钥系统或环境变量。
2. 对目标 workflow 做 dry-run 和 shadow 对账。
3. 审核 run journal、artifact manifest、effect ledger 和 outbox。
4. 取得负责人明确授权，只安装一个新任务并禁用对应旧任务；旧任务不删除。
5. 日任务连续观察 7 天，周任务观察 2 个周期，月任务完成指定历史月回放。
6. 数据库、飞书、文件产物和通知对账通过后，才迁移下一任务。

推荐顺序：shop_intelligence → supply_chain → content_marketing → product_commerce。