数据流水线设计

解决什么问题

数据处理代码最常见的衰变路径是：一个脚本变成五个脚本，再变成一个谁都敢改的千行文件。列名写死、路径散落在各处、计算逻辑和导出格式混在一起，改一次提成规则就要通读全文；换个 Excel 目录就要改十处路径。当需求来自频繁变动的业务规则（提成、定价、评分）或多个来源的合并计算时，这种结构会迅速失控。

它如何工作

这个技能给出的是一套经过生产验证的设计模式，而不是现成代码库。它用自然语言即可驱动——描述你的数据、业务规则和输出格式，它会先问澄清问题，再逐步给出架构。

核心结构是一条 5 阶段管道，配合多个设计原则：

• 配置驱动：列名、路径、规则集中在配置文件，代码里不出现字面量
• 策略模式 + 注册表：多来源接入时按处理逻辑分组，registry 负责映射来源名到对应的 enricher
• 职责分离：steps/ 只做计算，output/ 只做展示，校验逻辑独立成 quality 模块，产出结构化结果
• 统一合并入口：所有 join 走 merge_lookup() 而非裸 pd.merge()，自动处理类型转换、去重与键清洗

调试单个阶段时，注释掉 STAGES 中其他阶段，加载上一阶段的缓存产物单独跑。

适用边界与注意点

适合规则驱动的计算、多来源 ETL、周期性报表与数据质量校验场景。但不要用于一次性脚本、需要毫秒级响应的实时处理、或少于 3 个变体的组件——后者用配置化是过度设计。

生产环境部署前用 ENVIRONMENT = "prod" 本地验证；Excel 输出注意列名特殊字符、sheet 名超 31 字符和混合类型导致的损坏问题。