ListCompare_std
两份清单数据的自动比对工具。输入两份文件（.xlsx / .xls / .csv），按主键列匹配，找出三类差异，生成格式化的 Excel 差异报告，并自动打包成交付文件夹 + ZIP。
功能
- 读表：读取两份清单，自动识别两边的共用字段
- 比对：按主键列匹配，找出三类差异——只在 A 出现、只在 B 出现、两边都有但数值不同（金额容差默认 0.01）
- 报告：生成带汇总页 + 明细页的 Excel 差异报告（列宽自适应）
- 打包：报告 + 原始文件复制进日期命名的交付文件夹，并生成 ZIP
模块结构
ListCompare_std/
├── run_pipeline.py # 总入口：一条命令跑完全流程
├── 01_reader/lc_reader.py # read_two_lists(file_a, file_b, encoding) -> dict
├── 02_compare/lc_compare.py # compare_two_lists(df_a, df_b, common_cols, key_col, value_col, tolerance) -> dict
├── 03_reporter/lc_reporter.py # generate_report(compare_result, output_path, file_prefix, title) -> str
├── 04_output/lc_output.py # pack_output(report_path, output_dir, file_prefix, source_files, zip_output) -> str
├── make_test_data.py # 重新生成示例数据
└── test_data/ # 示例数据：test_a.xlsx / test_b.xlsx（订单表，含三类差异）
调用方式
方式一：命令行（推荐）
python run_pipeline.py --file-a test_data/test_a.xlsx --file-b test_data/test_b.xlsx
可选参数：
| 参数 | 必填 | 说明 | 默认值 |
|---|---|---|---|
--file-a |
是 | 第一份清单路径 | - |
--file-b |
是 | 第二份清单路径 | - |
--key-col |
否 | 主键列名（如"订单号"） | 第一个共用列 |
--value-col |
否 | 要比对的数值列名（如"金额"） | 自动检测 |
--encoding |
否 | CSV 编码 | utf-8 |
--tolerance |
否 | 金额容差 | 0.01 |
--output-dir |
否 | 输出目录 | ListCompare_std\output |
退出码：0 成功；1 文件不存在；2 参数/数据问题；3 文件读写失败；99 未预料异常。所有错误提示均为中文。
方式二：作为 Python 模块调用
from run_pipeline import run_pipeline
result = run_pipeline(
file_a="test_data/test_a.xlsx",
file_b="test_data/test_b.xlsx",
key_col="订单号", # 可省略，自动选择
value_col="金额", # 可省略，自动检测
)
# result["report_path"] -> 差异报告路径
# result["deliver_dir"] -> 交付文件夹路径
# result["elapsed"] -> 总耗时（秒）
各模块接口（供单独调用）
01_reader
from lc_reader import read_two_lists
read_result = read_two_lists("a.xlsx", "b.xlsx")
# -> {df_a, df_b, common_cols, only_in_a, only_in_b}
# 异常：FileNotFoundError / ValueError（中文提示）
02_compare
from lc_compare import compare_two_lists
compare_result = compare_two_lists(
read_result["df_a"], read_result["df_b"], read_result["common_cols"],
key_col="订单号", value_col="金额", tolerance=0.01,
)
# -> {only_in_a, only_in_b, value_diff}，均为 DataFrame
03_reporter
from lc_reporter import generate_report
report_path = generate_report(compare_result, "output/差异报告.xlsx")
# -> 实际写入的报告绝对路径
04_output
from lc_output import pack_output
deliver_dir = pack_output(report_path, output_dir="output", source_files=["a.xlsx", "b.xlsx"])
# -> 交付文件夹完整路径（YYYYMMDD_交付包，含 ZIP）
支持的文件格式
- 支持：
.xlsx、.xls、.csv - 不支持：
.txt、.json、.docx、.pdf、图片 OCR（如需 OCR 请用 ListCompare_max 项目）
依赖
- Python 3.10+
- pandas、openpyxl（读 Excel 必需）
示例数据
test_data/test_a.xlsx 与 test_b.xlsx：5 条订单的小数据集，故意包含三类差异各 1 条（DD-2026-0004 只在 A、DD-2026-0006 只在 B、DD-2026-0002 金额 899 vs 889）。找不到该文件夹可运行 make_test_data.py 重新生成，或手动新建。
