进销存配平质检

用途

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

支持两种业务场景：
1. 连锁企业：总部采购 + 总部配送 + 门店销售 + 总部库存 + 门店库存 → 分别配平总部和门店
2. 商业企业：总部采购 + 总部销售 + 总部库存 → 按客户配平

触发条件

当用户提出以下任一类请求时调用此技能：
- "做进销存配平" / "配平质检" / "数据配平计算"
- "连锁企业进销存配平" / "商业企业进销存配平"
- "检查进销存数据" / "质检配平"
- "分析库存数据的勾稽关系"
- 涉及 "期初"、"期末"、"采购"、"销售"、"配送"、"库存" 等关键词的配平计算请求

工作流程

Step 1: 获取用户参数

通过提问明确以下参数：

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

提问示例（连锁 - 编码）：
> "我们来设定配平参数。请告诉我：
> 1. 期初日期和期末日期分别是？
> 2. 总部的编码是什么？（例如 WMS_HQ_001）
> 3. 数据文件存放在哪个目录？"

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

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

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

2. 如果用户确认继续执行，直接进入 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: 配送表如有 原库房编码/原库房名称 列，脚本会自动区分三种配送方向：
1. 正向配送（总/虚拟库房→门店）：计入总部出库 + 门店配送入
2. 逆向退货（门店→总/虚拟库房）：计入源门店退货
3. 跨店调拨（门店→门店）：计入目标门店配送入 + 源门店退货，不影响总部

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

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

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

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