XLSX 多来源 ETL 导入与数仓交付

目标与适用范围

把多个工作簿和 CSV 来源整理成可追溯、带 schema 依据的 SQL、Parquet 与对象存储批处理输入。
本指南将当前任务范围转化为可复核的交付结果。请保留源文件、中间产物和关键判断，让后续协作者能够理解检查了什么以及为什么这样处理。

准备证据并作出选择

• 为每个文件、API 响应或对象存储前缀准备稳定的来源 ID、批次 ID、采集时间，以及预期工作表或区域。

• 准备一份正常批次和若干坏样例，包括表头变化、混合类型、重复键、错误编码和空工作表。

• 先定义规范字段名、业务键或增量游标、空值策略、目标 SQL 方言，以及最终要交付 Parquet、NDJSON 还是 CSV 包。

• 确定拒绝行和中间产物的保存位置，确保修复后可以重跑且不会覆盖原始输入。

• 决策点: 来源是文件批次、API 落地，还是对象存储前缀？. 分页 JSON 需要先进入工作表时选择 API To Sheet；处理获准的存储前缀时选择 S3 Batch Processor；分隔符或编码不稳定的 CSV 则先用检测/规范化和批量转换工具。每个落地产物都要写回来源分支。

• 决策点: 应该拆表、重塑，还是直接合并？. 工作表各自代表独立数据集时先拆分或抽取命名区域；合并前先映射字段；月份或类别横向展开时用 unpivot 变成长表；只有目标契约确实需要嵌套结构时才使用 JSON 转换。

• 决策点: 下游契约和交付格式是什么？. 把 JSON Schema 推断结果当作待审查提案，用迁移规划器设计表和字段，再在确认类型、键、转义规则和方言后生成 INSERT。分析管道可选择 Parquet 或 NDJSON，需要逐表检查时则选择带 manifest 的 CSV 包。

按步骤完成工作流

1. 落地来源并建立接收记录

需要时把分页 API 记录写入工作表，处理获准的对象存储批次，并在批量转换 CSV 前识别分隔符和编码。先分配来源与批次标识，保留原始输入到落地文件的关系，再改变字段值。 使用 xlsx-api-to-sheet, xlsx-s3-batch-processor, xlsx-csv-detect-normalize, xlsx-csv-batch-converter.

2. 选择数据表并形成规范行结构

拆开多工作表工作簿或只抽取批准的区域，然后统一字段名、顺序和保留列。目标是按行存储时，把月份等宽列转换成长表；只有下游契约明确需要时，才压平或恢复嵌套 JSON。 使用 xlsx-multi-sheet-splitter, xlsx-range-extractor, xlsx-column-mapper, xlsx-unpivot-normalizer, xlsx-json-transformer.

3. 合并批次并执行增量规则

只合并工作表和字段契约兼容的工作簿。周期性导入使用经过审查的时间列或主键游标追加新行；同时比较来源、保留、重复和拒绝计数，并将游标与批次血缘一起保存，保证重跑可解释。 使用 xlsx-workbook-merger, xlsx-append-incremental.

4. 审查 schema 并准备数据库交付

从代表性行推断候选 JSON Schema，把确认后的字段转换成数据库迁移计划，再按选定方言生成 SQL INSERT。执行外部写入前检查日期、数字、空值、标识符、转义和目标列顺序。 使用 xlsx-sheet-to-json-schema, csv-to-database-migration-planner, xlsx-sql-insert-generator.

5. 导出可审阅的下游产物

把确认后的表结构导出为分析管道可消费的 Parquet 或 NDJSON，或者把每个工作表打成带 manifest 的 CSV 包以便检查和传输。交付时附上行数、字段和血缘信息；上传、权限和最终提交仍由接收系统负责。 使用 xlsx-parquet-exporter, xlsx-sheet-to-csv-pack.

交付前验收结果

• 每个输出都能追溯到来源 ID、输入文件或 API 页、工作簿/工作表/区域、批次或游标、转换分支和目标产物；没有可用血缘的结果不予接收。
• 每个批次都能对上输入、合并、追加、导出和拒绝行数，重复或跳过的行必须有解释，不能静默丢失。
• 在交付 SQL、Parquet、NDJSON 或 CSV 前，必须核对规范字段集合、必要时的字段顺序、类型、可空性和键唯一性。
• 坏编码或分隔符、缺少表头、区域无效、类型混杂、重复键、schema 漂移和 SQL 目标不匹配必须停止或隔离受影响分支；失败分支不能被标成完整数据集。

常见问题

• 这条工作流会自动把数据写进数仓吗？ 不会。它准备并检查 SQL、Parquet、NDJSON 或 CSV 包等产物。数据库执行、存储桶上传、凭据、事务和生产调度仍由接收管道负责。
• 怎样证明增量运行没有漏行？ 把游标或水位和批次 ID 一起保存，比较来源、接受、重复、拒绝和导出计数；如果源数据可能回改，再重跑一个小的重叠窗口。任何无法解释的差异都应阻止游标前进。
• 生成的 JSON Schema 是否等于数据质量保证？ 不是。它只是根据所选表头和样例推断的候选契约，仍需对照业务类型、空值规则和键审查。样例不具代表性时，schema 也可能准确描述错误或不完整的数据。
• 多来源批次中有一个工作表失败怎么办？ 保留原始来源和血缘记录，按项目策略隔离或拒绝该工作表或行；在数量和字段差异解决前，不要把合并结果标记为完整。