CASE STUDY / 项目复盘
生态店铺 GMV 清洗迁移
从历史 Kettle 任务、数仓文档、源表与字段血缘中还原旧口径，再迁移为九个平台服务、统一规则治理与可预览、可补跑的 Java 总控链路。
EVIDENCE TRAIL
先把历史线索串成证据链，再开始迁移。
从历史任务和数仓文档建立规则地图
以 KJB/KTR 链路报告、GMV 清洗总纲、字段映射图和唯一键对照表定位源表、目标表、字段口径、日期逻辑及下游同步。
逐平台还原取数、退款和品类规则
按平台记录销售来源、退款算法、品类匹配顺序、事业部归属和特殊日期逻辑，并对得物、唯品、快手等特殊分支单独核验。
迁移为九个平台服务与统一总控
平台 Service/Mapper 保留差异，总控负责平台选择、日期范围、预览/写入、失败策略、平台结果和汇总刷新。
把规则排查继续收敛为治理能力
围绕统一规则表、未匹配池、单条命中解释、规则影响预览和回刷任务继续建设可解释、可复核的规则治理闭环。
RULE RECONSTRUCTION
难点不是重写 SQL，而是把历史链路还原成可验证的业务口径。
旧逻辑分散在 Kettle 作业、历史文档、多个数据源和数据库调用中；天猫、得物、京东、抖音、快手、拼多多、微信视频号、社交与唯品在销售、退款、日期、品类和事业部口径上各不相同。迁移难点不是重写 SQL，而是证明新链路没有丢掉旧口径。
MIGRATION DESIGN
先建立规则地图，再决定哪些统一、哪些隔离。
- 先把 Kettle 链路、源表、目标表、唯一键和字段映射整理成可追踪的规则地图，再决定 Java 迁移边界。
- 采用“平台差异隔离、公共流程统一”：九个平台分别保留取数与退款规则，总控统一日期解析、选择执行、失败策略、结果汇总和通知。
- 把预览与写入明确分开：save=false 只计算，save=true 才删除指定范围旧数据并写入；目标表受配置白名单约束。
- 只有平台生成全部成功才刷新 GMV 汇总；平台失败时保留平台结果并跳过汇总，避免把部分结果包装成完整结果。
- 将品类与事业部规则从平台实现中抽离，补充未匹配池、规则追踪和影响预览，逐步把临时排查变成治理能力。
CHAIN ACCEPTANCE
迁移是否完成，要看结果能否校验、定位和补跑。
- 当前代码已形成抖音、京东、快手、拼多多、唯品、微信视频号、天猫、得物和社交九个平台执行器及独立 Service/Mapper 边界。
- 统一入口支持全量或指定平台、手工日期或平台日期字典、预览或写入、失败继续或立即停止，并返回未知平台与失败平台清单。
- 运行结果记录生成/落库行数、平台日期范围、GMV/GSV、耗时、错误与警告；全平台成功后刷新汇总，并可发送执行通知。
- 已补充目标表白名单、天猫生成测试、规则管理测试和配置测试；新旧同范围金额对账与长期生产成功率仍需持续采集。
SYSTEM INVARIANTS
先定义系统必须始终成立的性质。
任何迁移实现都必须能回指历史来源、字段、公式和生效范围，不能以代码跑通代替业务正确。
平台特殊取数、退款与品类逻辑留在平台边界内，总控不复制平台规则。
写入前可以只计算并检查平台范围、日期、行数与金额，预览不删除也不插入数据。
平台和日期范围可以明确选择，失败平台能够定位，不要求每次全量重做。
只有平台生成全部成功才刷新汇总，部分失败不能覆盖成完整统计结果。
ARCHITECTURE DECISIONS
三个决定系统能否恢复的结构选择。
历史证据层
保留 Kettle 链路报告、数仓清洗总纲、字段映射与唯一键说明，作为迁移规则的事实来源，而不是只读最终 Java 代码反推业务。
平台策略层
九个平台分别拥有 Controller、Service、Mapper 与模型，封装各自取数、退款、品类和日期差异，并共享统一品类事业部规则能力。
编排与治理层
总控统一平台筛选、日期解析、预览/保存、失败策略、运行结果、汇总刷新和通知；规则治理负责未匹配、解释、补规则与回刷。
FAILURE INJECTION
主动制造失败，验证系统语义。
RETROSPECTIVE
如果重新开始，会提前做什么？
- 迁移第一步应该是建立可查询的数据血缘和规则目录，而不是先把旧 SQL 翻译成 Java。
- 规则需要能解释为什么命中或未命中；否则规则表只是把硬编码从代码搬到了数据库。
- 旧 Kettle 与新 Java 链路在切换前需要同范围双跑和金额对账，代码结构完成不等于迁移验收完成。
EVIDENCE BOUNDARY
迁移结构已经落地，同范围对账和生产运行仍需继续验证。
历史链路文档、九个平台实现、总控代码和现有测试能够证明迁移结构与运行控制已形成；新旧链路同范围对账、性能变化、生产成功率和下游完整同步仍需运行记录补齐。