WPS 表格批量处理助手
面向业务台账的批处理工具链：把几十上百份格式不一的表格，收敛成一张干净、可追溯、能出报表的数据底表。核心命令为 scripts/wps_batch.py（依赖 openpyxl，其余为 Python 标准库）。
何时使用
- 多份同构表格需要合并（月度分表、多门店导出、多系统台账）
- 表格来自系统导出，存在空格、货币符号、千分位、多种日期写法、空值占位符
- 需要按地区/月份/部门拆分成独立文件，或把一堆文件按规则归到子目录
- 需要按维度出汇总报表，带合计、占比与图表
- 上述步骤要固化成可重复执行的流水线
不适用：单表简单增删改（走本地 office 编辑能力）、需要 .pptx 输出、纯数据分析建模。
核心原则
- 先勘察，后动手：任何批处理都先跑
scan，确认表头、行数、空表与格式兼容性。 - 不改源文件：默认拒绝覆盖源文件；清洗只写新文件；归档默认复制而非移动。
- 不静默丢数据：解析失败的值保留原文，空值单列「未分类」，异常值只标记不删除。
- 口径先确认：金额单位、含税与否、去重依据、日期格式有歧义时，先问用户，不猜。
- 全程可追溯：每步输出伴随 JSON 日志（
*.merge.json、*.clean.json），交付时一并给出。
工作流
第 0 步：勘察
python <技能目录>/scripts/wps_batch.py scan --src "<目录>" --out "清单.json"
读取：文件数、每表行数、表头在第几行、表头并集与差异、格式不兼容项。
输出解读要点：
- 「表头不一致」提示 → 确认是同一业务字段的不同叫法（别名会归一），还是真的不同表
.et/.xls报错 → 必须请用户另存为.xlsx，说明是格式限制而非权限问题- 出现 0 行的表 → 合并时会跳过，需告知用户
第 1 步：合并
python <技能目录>/scripts/wps_batch.py merge --src "<目录>" --out "合并.xlsx" --dedupe
- 按表头并集合并，缺列留空；自动附加
来源文件 / 来源工作表 / 来源行号三列，便于回溯到原始单元格 - 表头自动识别，兼容「标题行 + 空行 + 表头」的排版；识别不准时用
--header-row N指定（1 起） - 默认只读每个文件的首个工作表，多表全并加
--all-sheets --dedupe整行去重，自动忽略来源列
第 2 步：清洗
python <技能目录>/scripts/wps_batch.py clean --src "合并.xlsx" --out "清洗.xlsx" \
--dedupe --fill-down "地区,部门" --mask "手机号" --flag-outliers
- 按列自动判定 text / number / date / percent 角色，ID 类列强制保留文本（防止前导零丢失）
- 详细处置规则见
references/cleaning-playbook.md - 合并单元格造成的空值用
--fill-down向下填充 - 需要强制列类型或改列名时用
--rules rules.json
清洗后必须核对：行数守恒、金额合计与源表一致、抽 3–5 行看日期与编号。
第 3 步：归档
按列拆分一张表（一份表 → 多个分组文件）：
python <技能目录>/scripts/wps_batch.py archive --src "清洗.xlsx" --out "归档" --by "地区,日期@month"
按规则把一堆文件分到子目录（多文件 → 目录树），先预演再执行：
python <技能目录>/scripts/wps_batch.py archive --src "<目录>" --out "归档" --by-col "地区" --dry-run
两种模式都会生成 归档索引.xlsx（分组、文件名、行数），交付时说明分组数与未分类数量。
第 4 步：报表
python <技能目录>/scripts/wps_batch.py report --src "清洗.xlsx" --out "月报.xlsx" \
--group "地区,日期@month" --metrics "金额:sum,订单编号:count_distinct" \
--filter "状态!=已取消" --with-detail --title "2024 销售月报"
产出 汇总（含合计行、占比、柱状图）、明细、处理说明 三张表。指标口径与常用配方见 references/report-patterns.md。
第 5 步：固化为流水线
python <技能目录>/scripts/wps_batch.py run --config pipeline.json --log pipeline_log.json
配置里的相对路径以配置文件所在目录为基准。模板见 assets/pipeline-template.json。适合每月重复执行的固定流程。
决策规则
| 用户情况 | 处理方式 |
|---|---|
| 只有一个文件 | 跳过 merge，直接 clean |
| 多文件、表头一致 | merge → clean |
| 多文件、表头差异大（字段名不同） | 先 scan 看并集；差异超出业务合理范围时，先与用户确认字段映射，再决定是否合并 |
| 用户只要"汇总一下" | merge → report（清洗参数从简，但必须去重并检查金额列角色） |
| 目录里混有 .et / .xls | 停下，请用户另存为 .xlsx 后再继续 |
| 金额量级异常（差 10^4） | 停下确认单位（元/万元），不做隐式换算 |
| 需要按人员/部门分发 | clean --mask 脱敏后 archive 拆分 |
表头归一
内置常见业务表头别名（订单号/订单编码/单号 → 订单编号；销售额/总额/金额 → 金额；区域/省份/大区 → 地区 等），比对前统一做全角转半角、去空格与标点。
自定义行业别名，写 JSON 后用 --alias 传入：
{"合同额": ["签约金额", "合同总价", "contract_amount"]}
扩展方式与完整别名表见 scripts/wps_lib.py 的 CANON_ALIASES。
清洗规则文件
{
"types": {"批次号": "text", "折扣": "percent"},
"drop": ["备注", "内部编号"],
"rename": {"客户名称": "客户"},
"dedupe": true,
"keep": "last",
"fill_down": "地区,部门"
}
命令行参数优先级高于规则文件；两者可叠加使用。
交付与核对
每次交付向用户说明：
- 数据流：几个文件、几张表、多少行进 → 多少行出，去重删除多少
- 清洗动作摘要：数值转换、日期归一、空值清理、脱敏、向下填充各多少条
- 列类型判定结果（尤其金额、日期、编号三类）
- 产出清单：主文件 + 索引/报表 + JSON 日志
- 需人工确认的遗留项：未分类分组数、解析失败值、被跳过的表
核对红线：行数不守恒、金额合计对不上、日期出现 未分类 之外的空值，必须回到上一步查原因，不得直接交付。
参考文件
references/cleaning-playbook.md— 脏数据类型处置、列角色判定、去重与脱敏口径references/report-patterns.md— 报表结构、时间维度表达式、指标口径、常用配方references/wps-pitfalls.md— 格式兼容、合并单元格、公式空值、编码、规模与安全守则
