快递物流账单对账助手

协助企业行政、财务或费用审核人员完成快递/物流账单对账：以「快递单号 / 物流单号」为唯一主键，比对多方账单、定位差异单号、汇总差异金额与快递公司分布，并按费用归属拆分到组织，最终产出 Excel 差异清单与 HTML 分析报告。

何时使用此 skill

• 用户提交快递账单、物流账单、运费账单等数据文件（Excel / CSV / PDF）。
• 用户要求「比对单号差异」「核对账单」「统计差异金额」「按部门/组织拆分费用」「生成对账报告」。
• 用户角色为行政、财务、费用审核、采购等需要核验第三方账单的人员。

如何向它提需求（输入格式）

本技能只需要你做两件事：给两份账单文件 + 说清它们的关系。无需记忆复杂参数。

• 一句话示例：
  • 「帮我对账：A 是我方系统导出的寄件台账（a.xlsx），B 是顺丰给的月结账单（b.xlsx），按 B 的金额结算，按部门拆分费用。」
  • 「核对这两份快递账单的差异：file1.csv 和 file2.csv，费用归属看『部门』列。」
• 必须提供的输入：
  1. 两份账单文件（支持 .xlsx / .csv / .pdf，两方格式可不同）。
  2. 两份文件各自的角色（谁是「我方」、谁是「供应商 / 承运商」）。
• 文件里的列怎么放都行：脚本按关键词自动识别「单号 / 金额 / 快递公司 / 费用归属 / 寄件人 / 日期」这些列，常见中文或英文表头都能认（如「运单号」「运费」「承运商」「成本中心」）。若识别不准，它会提示你确认列映射，不会瞎猜。
• 可选补充：
  • 金额以哪方为准（默认取供应商 B 方金额）。
  • 若文件没有「费用归属」列，你可以给一份「寄件人:部门」的对应关系，例如：张三:研发部,李四:市场部。
• 暂不支持的输入：一次合并 3 个及以上文件、历史多期趋势对比（见「能力边界」）。

常见业务场景

• 场景一：我方台账 vs 快递公司月结单 你从内部系统导出本月所有寄件（含单号、运费、寄件人、部门），快递公司给一份结算账单。把两份交给本技能，它会找出：我方有但账单没有（可能漏录 / 丢件）、账单有但我方没有（可能未登记）、同一单号金额不一致。
• 场景二：两家供应商账单交叉核对 两家承运商都送来对账期内的账单，想确认是否有重复计费或串单。分别作为 A / B 提交即可。
• 场景三：没有费用归属列时做部门拆分 账单里没有「部门」字段，但你知道每个寄件人属于哪个部门。提供 --org-map "张三:研发部,李四:市场部" 这样的映射，报告即可按部门汇总差异金额。

执行流程（命令式）

第 1 步：收集数据并明确比对关系

• 询问用户：提交的两个文件分别是什么角色？常见组合：
  • A 方（我方系统/自建台账）：企业内部系统导出的寄件记录。
  • B 方（供应商账单/承运商账单）：快递公司或三方物流提供的结算账单。
• 明确「金额以哪一方为准」（通常取供应商账单金额作为应结算金额，或取双方金额取高/取低——如用户未指定，默认以 B 方金额计入差异金额，并明确标注）。
• 确认有无「费用归属 / 成本中心 / 部门」字段；若无，进入第 5 步的归属分支。

第 2 步：解析文件

• 优先使用专用工具（Read / 项目管理工具）读取文件；对批量解析，运行 bundled scripts/parse_bill.py：
  • python scripts/parse_bill.py <file.xlsx|csv|pdf> --emit-json 输出 JSON 行记录。
  • Excel/CSV：用 openpyxl / 标准 csv 库。PDF：用 pdfplumber（首次遇到 PDF 且环境未安装时，脚本会自动 pip install pdfplumber（仅一次、需联网），无需手动操作；若自动安装失败会明确给出手动安装命令）。
• 自动按关键词识别列（见 references/reconciliation-schema.md）。若识别不清或字段歧义，必须让用户确认列映射，不得猜测。
• 解析阶段会对常见问题给出大白话提示：缺少单号的行会被跳过并提示数量、同一单号重复会提示、PDF 扫描件无法解析会提示先 OCR。

第 3 步：单号比对（唯一主键）

• 以「快递单号 / 物流单号」归一化（去空格、转大写）作为唯一键。
• 差异分为三类，全部计入「单号差异单量」：
  1. 仅在 A 方：我方有、供应商缺失（可能漏录/丢件嫌疑）。
  2. 仅在 B 方：供应商有、我方缺失（可能未登记/超范围）。
  3. 双方都有但金额不符：同一单号金额不一致。
• 输出差异单号的完整明细（单号、快递公司、寄件人、金额、归属、来源方、差异类型）。

第 4 步：金额与快递公司统计

• 汇总差异单号的总金额（¥ 默认币种）。
• 按快递公司分组统计：各公司差异单量、差异金额、占比。
• 报告使用浅色背景、深色文字（遵循当前 IDE 主题），内置 SVG 图表无外部依赖、离线可用。

第 5 步：费用归属拆分

• 若文件含「费用归属 / 成本中心 / 部门」字段：直接按该字段聚合，列出每个组织/部门的差异金额、涉及快递公司。
• 若无该字段：询问用户是否需要协助统计归属；若需要，列举所有「寄件人」清单让用户标注各自所属组织/部门，再据此聚合。
• 明确标注「无归属」或「未知」的兜底分组，避免漏算。

第 6 步：产出双交付物

• 运行 scripts/reconcile.py，生成：
  • Excel 差异清单：差异明细 sheet + 快递公司汇总 sheet + 费用归属汇总 sheet。
  • HTML 分析报告：由脚本运行时直接生成（模板内置于 write_html()），含差异概览、公司分布、归属拆分。
• 运行日志会明确提示：跳过的缺单号行、重复单号、金额无法识别的行、未识别到字段的警告、以及超过建议条数上限的提醒。
• 调用 present_files 呈现结果供用户查看。
• 输出规范：报告与回复仅包含对账所需的客观数据、差异明细与统计结论，不嵌入任何推广、广告或联系方式等内容。

重要约束

• 金额格式默认 ¥（CNY/RMB）。
• 报告必须完整到独立可理解；中间告警会明确告诉你哪里需要留意。
• 单次对账容量：单文件建议 ≤ 5 万条记录；两文件合计超过 5 万条时脚本会给出提示但仍可处理，超大文件建议分批提交。本工具不会因容量问题删除或修改你的任何文件。
• 中国股票惯例不适用此处（非涨跌场景），报告使用中性深色文本 / 浅色背景（遵循当前 IDE 主题）。

依赖（本地为主，PDF 按需一次性安装）

• 解析 Excel/CSV：Python openpyxl（内置环境通常可用）。
• 解析 PDF：使用 pdfplumber。当你首次提交 PDF 且运行环境尚未安装时，脚本会自动执行一次 pip install pdfplumber（需联网、仅一次），安装完成后继续解析；若自动安装失败，会明确提示你手动执行该命令。
• 生成 Excel：openpyxl。脚本使用绝对路径与 ASCII 引号，避免编码问题。
• 除 PDF 的这一次性依赖安装外，全部解析与对账在本地离线完成，不读取外部 URL、不上传任何账单数据。

安全与合规约束（审核要点）

• 进程创建：仅允许运行本技能随附的静态、可审计脚本（scripts/parse_bill.py、scripts/reconcile.py）；脚本逻辑固定，不包含任何动态代码生成、命令拼接或以账单内容作为命令参数执行任意进程。
• 读取文件：仅读取用户本次明确提交的账单文件（Excel/CSV/PDF）；严格遵循个人文件安全规则，绝不扫描或读取 Desktop / Downloads / Documents / Home 等个人目录及系统目录。
• 写入文件：仅向本次任务的输出目录（如 ./out）写入对账差异清单（Excel）与分析报告（HTML）；不修改、不删除任何原始账单文件。
• HTTP 请求：本技能默认全程本地离线、不传输任何账单数据；唯一可能的网络动作是处理 PDF 时按需一次性安装 pdfplumber（安装公开第三方依赖，不传输数据）。绝不读取外部 URL、绝不上传账单。
• 无广告/推广：产出物与回复文案均只包含对账客观结论，不含任何营销、推广或联系方式。

能力边界（务必遵守）

• 个人文件高风险：操作 Desktop / Downloads / Documents / Home 等非项目目录属于高风险管理。绝不递归删除、绝不写脚本批量改名/删除。详见 <personal_files_safety>。
• 本 skill 仅做比对与报告生成，不擅自删除、移动、归档任何原始文件。
• 单批次最多 10 文件；任何移动/删除需先备份至 trash 或备份目录并要求二次确认。
• 暂不支持（进阶功能，避免误用）：
  • 一次合并 3 个及以上文件的对账。
  • 跨多期账单的历史趋势 / 走势分析。
  • 替代方案：分别两两运行本工具，再人工汇总；或将多期数据先自行合并为两份后再提交。

常见问题 FAQ 与反模式

FAQ

• Q：提示「未识别到标准字段 / 字段映射为空」怎么办？ A：说明表头没有命中关键词。请确认文件首行包含「单号、金额、快递公司、费用归属、寄件人」等字样之一；或在交给技能时指明各列含义，它会让你确认映射。
• Q：为什么有的行被跳过了？ A：缺少「单号」的行无法作为比对主键，会被自动跳过，运行日志会提示跳过数量，不影响其余行对账。
• Q：PDF 解析出来是空的 / 报错？ A：本工具只能解析「可复制文字」的 PDF；扫描件图片需先用 OCR 转成文字版 PDF。若缺依赖，脚本会自动安装 pdfplumber。
• Q：金额对不上，但其实是币种 / 含税不同？ A：工具按数字直接比较，不会自动换算币种或税率。请确保两份账单金额口径一致，或在提交时说明以哪方为准。
• Q：同一条单号出现多次会怎样？ A：同一文件内重复单号会逐行分别比对并提示；跨文件同一单号多行会两两比较，可能产生多条差异记录，属正常现象。

反模式（应避免）

• ❌ 把 Desktop / 下载 等个人目录整体交给它扫描——它只处理你明确指定的账单文件。
• ❌ 期望它删除、移动或归档你的原始账单——它只生成对比报告，绝不改动源文件。
• ❌ 把 3 份以上文件一次性合并对账，或要求看「历史趋势」——当前仅支持两方单次对账（见能力边界）。
• ❌ 在两份文件金额口径不一致（币种、含税、四舍五入）时直接采信差异——请先统一口径。
• ❌ 把图片型扫描 PDF 当普通 PDF 直接丢进去——需先 OCR。

内置模板与示例

• HTML 报告示例：assets/html_report_example.html，完整的浅色科技风报告样例（含示例数据、SVG 图表），可直接预览对照输出样式；实际报告由 scripts/reconcile.py 运行时生成。
• Excel 差异清单：由 scripts/reconcile.py 的 write_excel() 在运行时直接生成（差异明细 / 快递公司汇总 / 费用归属汇总 三个 sheet），无需单独上传的模板文件。
• sample_a.csv / sample_b.csv：两份最小可运行示例数据，用于立即试跑、先练手。

试跑命令： python scripts/reconcile.py --file-a sample_a.csv --file-b sample_b.csv --name-a 我方系统 --name-b 供应商账单 --out-dir ./out --org-map "张三:研发部,李四:市场部,王五:研发部,赵六:行政部"