数据工程工作流

适用边界

用于将业务、日志、文件或 API 数据可靠地接入、处理和交付。先遵循用户已确定的技术栈、数据平台和组织规范；本 skill 提供决策框架与交付标准，不强制使用任何特定引擎、数据库或调度工具。

先建立任务画像

在开始实现前，明确或列出待确认项：

• 数据源和目标、数据所有者、数据敏感等级；
• 表、文件或接口范围，主键/业务唯一键及数据粒度；
• 数据规模、更新频率、延迟目标和可接受成本；
• 全量、增量或变更捕获依据；
• 字段口径、下游消费者、保留期限及现有调度约束。

关键事实未知时，说明假设及其风险，不擅自编造业务规则、密钥或生产环境配置。

选择处理路径

• **数据库/文件接入：**设计抽取、传输、落地和可恢复的批次策略；高频变更才考虑 CDC 或流式方案。
• **API 接入：**处理鉴权、分页、限流、幂等、重试边界、响应解析与可重跑的游标/时间窗口。
• **批处理：**适合定期汇总、大规模历史处理和明确的批次验收。
• **流处理：**仅在低延迟、持续到达或事件时序确有要求时采用；明确乱序、迟到、重复和状态管理策略。
• **数据迁移：**先做源目标映射与兼容性评估，灰度验证后再扩大切换范围。

分层与转换

根据目标平台的既有分层建模；若没有规范，可区分原始层、明细标准层和面向分析/应用的汇总层。原始层优先保存来源语义和追溯字段，转换层负责标准化，业务层明确指标口径。

处理规则必须清楚表达：

• 去重键、排序依据与保留策略；
• 类型、时区、单位、编码和枚举映射；
• 空值、非法值、缺失字段与异常记录的去向；
• 关联条件、聚合口径和字段血缘。

默认不静默删除异常数据。除非用户明确要求，应将异常记录隔离、标记或写入异常表，并保留可追溯原因。

字段映射（重点）

字段映射是源数据语义到目标数据语义的可审计约定，不能只列出同名字段。涉及新接入、ETL、接口解析、表结构调整或迁移时，先产出字段映射，再编写转换逻辑。

映射前核对

逐项确认源字段的实际含义、粒度、取值样例、空值语义、主键/唯一性、更新时间、类型精度与单位；并确认目标字段的业务定义、是否必填、存储约束、下游用途和目标层级。名称相同不代表含义相同，例如“金额”可能含税或未含税、以元或分存储。

映射表要求

每一行对应一个目标字段，至少记录源字段或 JSON 路径、源/目标类型、转换规则、空值策略、默认值、唯一性/关联关系、敏感级别和业务说明。一个目标字段可由多个源字段组合；无法映射或待确认的字段必须显式标记，不得静默忽略。

转换规则应可实现、可验证

• **直接映射：**只在语义、单位与类型兼容时采用；仍需处理长度和精度。
• **类型与格式：**明确字符串转数值/日期的解析格式、失败行为、时区、编码和舍入规则。
• **标准化：**写清大小写、空白、枚举字典、代码转换、地址或名称规范化规则及版本。
• **派生与合并：**记录公式、多个源字段的优先级、关联条件和缺失输入的处理。
• **拆分与展开：**说明分隔符、JSON 路径、数组多行展开时的粒度变化和主键策略。
• **脱敏：**明确定义掩码、哈希或权限控制方式；保留原始值必须取得授权。

映射变更与验收

映射应有版本、生效范围和变更原因。修改字段类型、口径、默认值或来源前，识别下游影响。实现后以映射表为验收依据，验证必填率、类型解析失败数、枚举覆盖率、主键唯一性和关键派生字段的抽样结果。

字段映射模板、示例与验收清单见 references/quality-and-operations.md。

增量、幂等与恢复

选择可靠的水位字段、递增键、日志位置或变更版本；定义窗口边界、时区和迟到数据策略。首次全量、日常增量、失败重跑和历史补数必须能避免重复与遗漏。将批次标识、处理时间、来源和版本等审计字段纳入适当层级。

数据治理与质量

维护可理解的数据定义：表/字段说明、数据类型、口径、责任人、敏感级别、更新频率和上下游关系。结构或口径变更前评估对下游的影响。

质量校验按风险选择：总量、唯一键数、空值率、值域/枚举、时间新鲜度、源目标汇总、抽样明细和异常记录。为关键校验提供可执行 SQL、测试或明确计算方法。

编排与运维

为任务明确依赖、运行周期、参数、资源需求、日志、告警、有限重试和补数入口。生产写入、删除、覆盖、重置水位或切换任务前，先呈现影响范围并取得授权。

交付

按请求交付：方案、字段映射、实现代码/配置、数据字典、调度说明、质量校验、运行手册或迁移清单。所有方案至少说明成功判据、失败处置和待确认风险。