进销存配平质检

用途

对采集的进销存数据做配平质检，验证"期初库存 + 期间流入 - 期间流出 = 期末库存"的勾稽关系是否成立。

支持两种业务场景：

连锁企业：总部采购 + 总部配送 + 门店销售 + 总部库存 + 门店库存 → 分别配平总部和门店
商业企业：总部采购 + 总部销售 + 总部库存 → 按客户配平

触发条件

当用户提出以下任一类请求时调用此技能：

"做进销存配平" / "配平质检" / "数据配平计算"
"连锁企业进销存配平" / "商业企业进销存配平"
"检查进销存数据" / "质检配平"
"分析库存数据的勾稽关系"
涉及 "期初"、"期末"、"采购"、"销售"、"配送"、"库存" 等关键词的配平计算请求

工作流程

Step 1: 获取用户参数

通过提问明确以下参数：

| 参数 | 说明 | 选项 / 示例 | |------|------|-------------| | business_type | 业务类型 | 连锁 或 商业 | | identifier_type | 标识方式（仅连锁） | 编码 或 名称 | | start_date | 期初日期 | 如 2026-04-01（可选，不填则自动取库存表最早日期+5天） | | end_date | 期末日期 | 如 2026-04-20（可选，不填则自动取库存表最晚日期-5天） | | hq_identifier | 总部标识（仅连锁） | 字符串=单总部（如 WMS_HQ_001）；列表=显式多总部（如 ["FB8","FD8"]）；留空 + auto_hq:true（默认）=从采购表机构列自动识别全部总部 | | company_name | 连锁/商业名称（可选） | 如 示例医药连锁有限公司 | | data_dir | 数据文件所在目录 | 默认 ./data（用户可自行指定数据目录） | | output_dir | 结果输出目录 | 默认 ./output（用户可自行指定输出目录） |

输出文件命名规则：

连锁：{公司名}-连锁进销存配平结果{开始日期}-{结束日期}.xlsx
商业：{公司名}-商业进销存配平结果{开始日期}-{结束日期}.xlsx
如不提供公司名，则省略前缀

提问示例（连锁 - 编码）：

"我们来设定配平参数。请告诉我：

期初日期和期末日期分别是？

总部的编码是什么？（例如 WMS_HQ_001）

数据文件存放在哪个目录？"

Step 2.5: 采购编码确认（仅连锁-按编码模式）

在调用脚本前，必须检查采购数据中的 大仓编码 列：

读入采购文件的前几行，检查 大仓编码 列的值：
- 全部为空（NaN）：说明采购数据缺少编码 → 暂停执行，告知用户："采购数据的大仓编码为空，总部销量无法关联到采购，结果可能不准。请补充编码后再跑"
- 有值但不同（如采购编码是 WMS_HQ_001，但总部是 000）：→ 暂停执行，先向用户确认："采购数据的编码是xxx，与你说的总部编码xxx不同，是否继续执行？"
- 全部匹配或部分匹配（如采购编码=总部编码）： ✅ 可以执行
如果用户确认继续执行，直接进入 Step 3。

Step 2: 确认数据文件存在

检查用户指定的 data_dir 下是否有 *.xlsx 或 *.csv 文件，文件名应包含以下关键词：

连锁企业：需要包含"库存"、"采购"、"配送"、"销售"的文件（至少要有库存表）
商业企业：需要包含"库存"、"采购"、"销售"的文件（至少要有库存表）

如果文件不存在，提示用户检查路径。

Step 3: 调用统一脚本执行配平计算

使用 --file 参数传入 JSON 参数文件（推荐，避免命令行引号转义问题）：

python scripts/reconciliation.py --file params.json

或通过 stdin 管道传入：

echo '{"business_type":"连锁",...}' | python scripts/reconciliation.py

或直接命令行传入 JSON 字符串（仅限 Linux/macOS）：

python scripts/reconciliation.py '{"business_type":"连锁",...}'

参数 JSON 结构：

连锁 - 按编码：

{
  "business_type": "连锁",
  "identifier_type": "编码",
  "start_date": "2026-04-01",
  "end_date": "2026-04-20",
  "hq_identifier": "WMS_HQ_001",
  "data_dir": "../data/连锁数据/",
  "output_dir": "../output/"
}

连锁 - 按名称：

{
  "business_type": "连锁",
  "identifier_type": "名称",
  "start_date": "2026-04-10",
  "end_date": "2026-04-30",
  "hq_identifier": "配送中心",
  "data_dir": "../data/连锁数据/",
  "output_dir": "../output/"
}

商业：

{
  "business_type": "商业",
  "start_date": "2026-04-03",
  "end_date": "2026-04-20",
  "data_dir": "../data/商业数据/",
  "output_dir": "../output/"
}

Step 4: 解读输出结果

脚本会输出三部分内容：

1. 控制台日志：

重复记录检查结果
数据处理进度
配平统计（总记录数、不平记录数）

2. 结果Excel文件：

位于 output_dir 下
文件名：连锁-进销存配平结果.xlsx 或 商业-进销存配平结果.xlsx
包含所有配平明细和配平状态标记
不平记录自动附带诊断列（追加到结果表右侧）

3. 统计摘要JSON： _summary.json

total_records：总记录数
unbalanced_count：不平记录数
unbalanced_pct：不平比例
diagnosis：诊断摘要（可解释数量、需人工核实数量）

4. 精准诊断（自动执行）：

当存在不平记录时，脚本自动执行期末日活动排查。

原理： 脚本每天凌晨1点采集库存 → T日快照 = T-1日营业结束后的实际库存。因此期间流入/流出应为 [start_date, end_date)（含期初日，不含期末日），而配平公式用的是全闭区间 [start_date, end_date]，差异 = 期末日当天的流入/流出。

| 排查逻辑 | 适用 | 说明 | 排查结论 | |----------|------|------|----------| | 剔除期末日活动 | 连锁+商业 | 连锁：剔除期末日配送(流出)+纯销(流出)；商业：剔除期末日销售(流出)+采购(流入) | 期末日活动 | | 无法解释 | 连锁+商业 | 剔除后仍不平 | 需人工核实 |

注意：不再需要"T-1纯销补回"逻辑。凌晨1点采集意味着 T-1 的纯销已经包含在期初快照中，不需要额外补回。

诊断输出3列：排查活动、可配平、排查结论

排查结论可能值：期末日活动 / 需人工核实

Step 5: 向用户汇报结果

向用户汇报时应包含：

✅ 配平计算是否完成
📊 总记录数和不平记录数
⚠️ 不平比例（若>0需重点标注）
📄 结果文件路径
如果存在不平记录，进一步建议：
- 检查期初数据是否遗漏
- 检查采购/配送/销售数据的时间范围
- 检查产品代码/机构编码是否有误
- 商业场景下销售数据可后补，尝试剔除结尾日数据重新计算

Step 6: 交付文件

调用 deliver_attachments 交付计算结果文件给用户。

常见问题

Q: 数据文件应该放在哪里？

A: 默认放在 ./data，结果输出到 ./output。也可以指定任意路径。

Q: 我的默认路径是什么？

A: 从上一次使用后已记录：

数据路径：./data
输出路径：./output
默认标识方式：编码

Q: 文件名有什么要求？

A: 文件名必须包含关键词以便自动识别：

库存表 → 文件名含"库存"
采购表 → 文件名含"采购"
配送表（连锁） → 文件名含"配送"
销售表（连锁） → 文件名含"销售"

Q: 支持哪些文件格式？

A: 支持 .xlsx 和 .csv（UTF-8编码）。所有列会按字符串读取以保留前导零。

Q: 表格列名必须完全一致吗？

A: 必须匹配 schema.md 中定义的列名（如 "大仓编码"、"产品代码"、"数量" 等）。如果用户数据列名不同，可以先确认后重命名。

Q: 什么是"不平（期初为0）"？

A: 当理论期末≠实际期末，且期初库存为0时，标记为此状态。这通常意味着期初数据可能缺失，需要人工核实。

Q: 配送数据中的逆向退货和跨店调拨如何处理？

A: 配送表如有 原库房编码/原库房名称 列，脚本会自动区分三种配送方向：

正向配送（总/虚拟库房→门店）：计入总部出库 + 门店配送入
逆向退货（门店→总/虚拟库房）：计入源门店退货
跨店调拨（门店→门店）：计入目标门店配送入 + 源门店退货，不影响总部

此外，原库房名称为"从XX调入"格式的记录，无论目标是谁，都会汇总到总部结果的**"总部退货"**列（仅展示，不影响配平公式）。

总部配平公式：理论期末 = 期初 + 采购 - 总部销售/配送（不含总部退货）

Q: 总部的配平结果有几种可能的输出列？

A: 连锁企业总部输出列包括：机构类型、机构标识（编码/名称）、产品代码、总部退货（如有）、总部期初、总部采购、总部销售/配送、总部期末、理论期末、配平状态。门店输出还包括：门店期初、配送到门店、门店退货、门店纯销、门店期末。