多表对账与差异报告
把「对不上」定位到具体哪个主键的哪一列，而不是只告诉你总数不一致。
触发规则
| 用户意图 | 处理 |
|---|---|
| 这两张表对得上吗 / 核对一下差异 | 执行完整对账，先报总数再报明细 |
| 哪些记录对方没有 / 我们漏了 | 重点输出「仅 A 有」「仅 B 有」 |
| 金额/状态哪里不一致 | 用 --compare 指定列，重点输出字段差异 |
| 帮我把差异导出来 | 加 --out 输出四类差异 CSV |
| 只是问本技能能干嘛 | 仅介绍，不执行任何操作 |
依赖
| 依赖 | 用途 |
|---|---|
| Python 3.8+ | 仅标准库（csv / io / pathlib / collections） |
无需联网、无需第三方包。
快速开始
# 基础对账
python3 scripts/reconcile.py 本系统.csv 对方.csv --key 订单号
# 只比金额和状态，金额容差 0.01
python3 scripts/reconcile.py a.csv b.csv --key 订单号 --compare 金额,状态 --tolerance 0.01
# 导出四类差异
python3 scripts/reconcile.py a.csv b.csv --key 订单号 --out ./差异
# 两张表主键列名不同（按位置一一对应）
python3 scripts/reconcile.py a.csv b.csv --key 订单号 --key-b order_no
# 复合主键 + 忽略大小写
python3 scripts/reconcile.py a.csv b.csv --key 门店编码,日期 --ignore-case
参数
| 参数 | 说明 | 默认 |
|---|---|---|
--key 列名[,列名…] |
A 表主键（复合主键用逗号分隔） | 必填 |
--key-b 列名[,列名…] |
B 表主键列名（与 --key 按位置对应） |
同 --key |
--compare 列名[,列名…] |
只比较这些列 | 所有同名列（排除主键） |
--tolerance 数值 |
数值比较容差 | 0.01 |
--ignore-case |
文本比较忽略大小写 | 关 |
--no-trim |
关闭首尾空白裁剪 | 关（默认裁剪） |
--out DIR |
导出四类差异 CSV | 不导出 |
--show N |
终端预览每类前 N 行 | 10 |
--delimiter |
强制分隔符 | 自动嗅探 |
输出文件
| 文件 | 内容 |
|---|---|
only_in_a.csv |
仅 A 有的主键 |
only_in_b.csv |
仅 B 有的主键 |
value_diff.csv |
主键 + __列 + __A值 + __B值，逐单元格定位 |
duplicate_keys.csv |
重复主键 + __出现在（A/B） |
退出码约定
| 码 | 含义 | 用途 |
|---|---|---|
0 |
完全一致 | 可接入自动化流水线做门禁 |
1 |
存在差异 | 需要人工核查 |
2 |
用法或数据错误 | 主键列不存在、表为空等 |
Agent 执行要求
- 先报主键重复：主键重复会让"对账"结论失真，报告中必须最先把重复情况摊开，
并提示用户先处理重复再做正式对账。 - 不臆断哪边是对的：本工具只指出不一致，不判定 A 对还是 B 对，交由用户裁决。
- 数值容差要说明：报告差异时必须一并说明采用的容差，否则用户可能误判精度问题。
- 列名不同要核实：用
--key-b时确认两边列含义确实一一对应，不可凭猜测映射。 - 不修改源表：本工具只读源表，只写用户指定的输出目录。
- 不给结论性话术：不要输出"数据质量很好"之类主观判断，只陈述差异统计。
输出模板
## 对账结果
A 表：本系统.csv 12840 行 9 列
B 表：对方.csv 12800 行 8 列
主键：订单号
⚠ A 表主键重复 3 个，示例：A002/订单号、D118/订单号
建议先处理重复主键，否则对账结论会失真。
匹配主键：12600 个
① 仅 A 有（对方缺）：210 条
② 仅 B 有（我方漏）：170 条
③ 字段不一致：86 处，涉及 74 个主键
差异分布：金额（52）、状态（34）
--- 字段不一致（前 10 / 86）---
A002 金额：A='200.50' ↔ B='200.60'
A005 状态：A='已付' ↔ B='已取消'
差异主键合计：454 个
注意事项
- 禁止修改、删除、重命名源表。
- 数值容差默认 0.01，若数据涉及汇率或高精度金额，请显式指定更小容差并在报告中说明。
- 空主键行会被跳过（不计入任何差异类别）。
- 只处理 CSV/TSV；Excel 请先另存为 CSV 或配合 xlsx 处理工具转换。
- 不做多表链路对账（A→B→C 的传递差异），本工具一次只比两张表。
