订单归集与对账助手（Order Recon）
功能概述
面向没有专职财务的小机构（5-30 人，教培/健身/美容/零售等），把"打开 Excel 苦熬三天的对账"变成"对 WorkBuddy 说一句话，几分钟拿到统一台账、自动匹配结果与差异清单"。
核心能力一句话：多平台订单与账单 → 统一台账 → 三级自动匹配 → 差异清单（短款/长款/金额不符）→ 逐笔核销 → 对账报告。全流程本地处理，数据不出你的工作区。
使用前提
- 运行环境：Python 3.8+（WorkBuddy 内置运行时即可，无需单独安装）；
- 连接器：无需任何连接器（不依赖腾讯文档、企业微信等）；
- API Key：无需配置任何密钥；
- 前置数据：订单/账单文件（CSV 或 JSON），或可直接粘贴的表格文本。无文件时可先用内置示例数据体验（见快速开始第 5 步）；
- 数据范围：单批次建议不超过 5000 条（超出请分批导入）。
快速开始
- 说："导入这份订单 CSV" + 附上文件 → 工具自动识别列名、清洗、去重入库；
- 说："再导入这份账单 CSV" + 附上文件；
- 说："对一下这个月的账" → 自动执行三级匹配，返回匹配笔数与差异分布；
- 说："有哪些对不上的" → 查看差异清单（短款/长款/金额不符），逐笔或批量核销；
- （可选）说"跑个演示" → 用内置样例数据完整走一遍对账流程，最快 1 分钟看到效果。
使用手册
核心功能与操作示例
功能1：导入订单与账单
- 触发方式：用户提供 CSV/JSON 文件或粘贴表格文本，说"导入订单/账单"
- 操作示例：
> 用户：帮我导入这份订单 CSV（附：orders.csv）
> 技能：已导入订单 10 条（新增 10 / 跳过重复 0 / 警告 0），来源自动识别为 POS。当前台账共 10 条。 - 自动能力：中英文列名自动映射（订单号/金额/日期/客户/商品等，学页导出模板可直接导入）、全角转半角、金额去货币符号、中文日期归一化、按「来源+单号+金额+时间」指纹去重（重复导入自动跳过）
- 注意事项：金额列带 ¥/$ 符号或中文日期格式都能识别；同一文件重复导入不会产生重复记录
功能2：自动对账
- 触发方式：说"对一下这个月的账 / 开始对账 / 月结对账"
- 操作示例：
> 用户：对一下 2026 年 7 月的账
> 技能：对账完成（批次 REC-20260731-001）：订单 10 笔 / 账单 13 笔 → 匹配 7 笔，差异 5 笔共 ¥1,679.00（短款 2 / 长款 2 / 金额不符 1）。差异清单已生成，可说"有哪些对不上的"查看明细。 - 三级匹配规则：① 单号精确（账单备注命中订单单号）→ ② 金额+时间窗口（金额一致且时间差 ≤30 分钟）→ ③ 金额容差（差额 ≤ 手续费容差默认 ±2 元且时间差 ≤240 分钟）
- 注意事项：退款单自动识别并关闭、不计入差异；疑似重复（同金额同时间多笔候选）不自动分配，留待人工复核，防止误匹配
功能3：差异清单与核销
- 触发方式：说"有哪些对不上的 / 差异清单"，确认无误后说"这笔确认没问题 / 作废 / 是退款"
- 操作示例：
> 用户：有哪些对不上的？
> 技能：共 5 笔差异：
> - O-1004 短款 ¥299.00（订单在，账单缺失）→ 建议核实是否未到账
> - TXN-2000 长款 ¥880.00（账单在，无对应订单）→ 建议核实是否漏录订单
> - O-1005 金额不符 ¥500.00 vs ¥450.00 → 建议核对优惠/折扣
> 用户：TXN-2000 这笔我核实过，是现金收款漏录了，确认没问题
> 技能：已核销 TXN-2000（confirm，备注：现金收款漏录）。剩余差异 4 笔。 - 三种核销动作：
确认无误（人工核实）/作废（无效记录）/标记退款（不计入差异）；支持同类型差异批量处理 - 注意事项：已核销记录不再计入差异统计，但始终可追溯查询
功能4：对账报告与经营汇总
- 触发方式：说"出个对账报告 / 按渠道汇总一下"
- 操作示例：
> 用户：出这个月的对账报告
> 技能：已生成 Markdown 报告 + CSV 对账底稿：reports/REC-20260731-001_report.md、REC-20260731-001_diffs.csv，可直接存档或发给财务。
> 用户：按渠道汇总一下
> 技能：渠道汇总：POS ¥5,200（46.4%）/ 微信 ¥3,100（27.7%）/ 银行转账 ¥2,900（25.9%）… - 产出物：Markdown 差异报告（含原因与处理建议）、CSV 对账底稿（Excel 可开）、台账 CSV 导出、按渠道/品类/日期的经营汇总
功能5：配置与状态查询
- 触发方式：说"查看配置 / 把手续费容差改成 3 块 / 现在什么状态"
- 操作示例：
> 用户：把手续费容差改成 3 元
> 技能：已更新 matching.fee_tolerance = 3.0，下次对账生效。 - 可配置项：手续费容差（默认 2）、时间窗口（默认 30/240 分钟）、去重键、币种符号等
- 注意事项：修改配置后对已有批次需用
--force重跑才按新规则生效（重跑前会二次确认）
数据说明
台账数据（工作区 order-recon-runtime/ 目录，可随时导出 CSV）
| 实体 | 文件 | 关键字段 |
|---|---|---|
| 订单 Order | orders.csv |
order_no（业务单号）、source（来源渠道）、customer（客户/学员）、item（商品/课程）、amount、currency、paid_at（支付时间） |
| 账单 Statement | statements.csv |
channel（渠道）、txn_no（交易号）、direction（收/支，退款=out）、amount、fee（手续费）、txn_time（交易时间） |
| 匹配结果 | matches/<批次>.json |
match_type（exact_order_no/amount_time/amount_tolerance/short/extra/mismatch）、diff_amount、status（pending/closed/void/refunded） |
| 对账批次 | runs.json |
period（周期）、order_total、stmt_total、matched、diff_count、diff_breakdown |
| 操作日志 | audit.log |
append-only，全流程留痕可追溯 |
状态流转：导入（重复跳过）→ 已归集 → 对账批次 → 已匹配 / 有差异 → 核销（确认/作废/退款）。退款单自动关闭不计差异；疑似重复留待人工复核。
多币种口径：台账含币种字段，不同币种不交叉匹配；V1 不做自动汇率换算，学页（东南亚/中东）场景建议按币种分组对账。
常见问题
Q1：没有订单/账单文件，怎么试用？
A：直接说"跑个演示"（或 python ~/.workbuddy/skills/order-recon/scripts/cli.py demo），内置 10 订单 + 13 账单样例数据，覆盖长短款、金额不符、退款、疑似重复、脏数据全部场景。
Q2：导入时报"无法解析"的警告，数据丢了吗？
A：不会。无法解析的行会跳过并在警告中列出行号与原因（如缺必填字段），可在源文件修正后重新导入。
Q3：同一文件不小心导入了两次，会不会出现重复记录？
A：不会。按「来源+单号+金额+时间」指纹自动去重，第二次导入显示"跳过重复 N 条"，台账无变化。
Q4：对账结果和实际情况差得远？
A：先检查三处：① 对账周期是否选对；② 手续费容差是否过小/过大（recon config show 查看，可改）；③ 订单与账单币种是否一致（不同币种不匹配）。仍有问题可在差异清单中逐笔核对原始记录。
Q5：为什么有的差异不让自动匹配？
A：疑似重复场景（同金额同时间出现多笔候选）出于防误匹配考虑不会自动分配，需要你人工确认哪笔是真实对应。这是刻意的安全设计。
Q6：能导出 Excel 给财务吗？
A：可以。差异清单和对账底稿均输出 CSV（Excel 直接打开），报告为 Markdown 格式，导出台账用 recon export。
Q7：数据安全吗？
A：所有数据仅存于你的工作区 order-recon-runtime/ 目录，纯本地处理，无任何网络调用，导出由你主动发起。工具输出供参考，最终以原始凭证为准。
技能指令（开发者参考）
以下为 AI 执行本技能时的工作流指令。
1. 角色定位
- 你是财务对账助手，不是会计系统：负责订单/账单的归集、匹配、差异识别与核销闭环；
- 用户角色：机构主理人（老板）、兼职财务/运营。多数人非财务专业，对话要直白、摘要化；
- 内核：
scripts/recon_core.py纯 Python 标准库，零第三方依赖，本地沙箱执行，无任何网络调用； - 数据红线：数据仅存用户工作区
order-recon-runtime/目录，绝不外传；导出由用户主动发起； - 免责声明：工具输出供参考，最终以原始凭证为准，不替代审计。
2. 目录结构
Skill 本体（安装于 ~/.workbuddy/skills/order-recon/）：
order-recon/
├── SKILL.md # 本文件（工作流入口 + 使用手册）
├── scripts/
│ ├── recon_core.py # 核心引擎（导入/清洗/匹配/核销/报表/日志）
│ ├── cli.py # 命令行入口（WorkBuddy 通过它驱动全流程）
│ └── tests/ # 单元测试（32 用例，覆盖验收清单）
│ ├── test_import.py
│ └── test_reconcile.py
├── templates/
│ ├── orders_sample.csv # 示例订单（含刻意脏数据：全角/货币符号/中文日期）
│ ├── statements_sample.csv # 示例账单（退款/手续费/长短款/疑似重复）
│ ├── xueye_orders_template.csv # 学页订单导出模板（学员/课程/课时口径）
│ └── config.default.json # 默认规则配置
└── references/
├── schema.md # 数据模型与字段口径
└── matching_rules.md # 匹配规则与计算逻辑详解
运行期数据（在用户当前工作区生成，不入 Skill 包）：
<工作区>/order-recon-runtime/
├── config.json # 用户配置副本（可改，改完即生效）
├── orders.csv # 归一化订单台账
├── statements.csv # 归一化账单台账
├── runs.json # 对账批次索引
├── matches/<run>.json # 每批匹配结果（含核销状态）
├── diffs/<run>.csv # 每批差异清单
├── reports/ # 报告输出目录
└── audit.log # 操作日志（append-only）
3. 核心工作流
WF-1 初始化
首次使用时执行 recon init（在用户当前工作区创建 order-recon-runtime/）。
说明：如工作区已有 runtime 目录则直接复用；--runtime <dir> 可指定其他目录。
WF-2 导入订单/账单（F-1）
用户提供 CSV / JSON 文件或直接粘贴表格文本时执行 recon import：
- 自动识别常见列名（订单号/金额/日期/客户/商品…中英文同义词，见 references/schema.md）；
- 自动清洗：全角转半角、金额去货币符号转 Decimal、日期统一 ISO、去除多余空白；
- 自动去重：按
来源+单号+金额+时间指纹比对已有台账，重复导入直接跳过； - 每次导入输出摘要（新增 N 条 / 跳过重复 M 条 / 警告 K 条），不刷屏；
- 学页订单可先用
templates/xueye_orders_template.csv作为导出模板，再导入本工具。
WF-3 自动对账（F-3）
用户说"对一下这个月的账 / 开始对账 / 对账"时执行 recon reconcile --period YYYY-MM：
- 三级匹配（规则引擎详见 references/matching_rules.md）：
1. 单号精确：账单备注/参考号命中订单单号 → 金额差在容差内即匹配；
2. 金额+时间窗口：无单号时金额一致且交易时间差 ≤ 30 分钟；
3. 金额容差：差额 ≤ 手续费容差（默认 ±2 元）且时间差 ≤ 240 分钟，归因手续费/优惠分摊。 - 差异自动分类：短款（订单无账单）/ 长款（账单无订单）/ 金额不符（单号对上金额对不上）；
- 退款单（方向 out 或备注含退款标记）自动识别并关闭，不计入差异统计；
- 疑似重复（同金额同时间多笔候选）不自动分配，标记待人工复核，防误匹配；
- 输出批次摘要（参与笔数 / 匹配笔数 / 差异分布与金额），并生成差异清单；
- 幂等：同周期已有批次时重跑需
--force（覆盖该批次，结果按最新台账重算，与首次一致）。
WF-4 差异核销（F-4）
用户询问"有哪些对不上的 / 差异清单"时执行 recon diffs --run <id>，然后按需逐笔或批量核销：
recon close --run <id> --match <match_id> --action confirm|void|refund [--reason ...]- confirm：人工确认无误（如电话核实）；
- void：确认无效记录，作废；
- refund：标记为退款，不计入差异；
recon batch-close --run <id> --action confirm --type extra：同类型差异批量处理；- 核销写操作日志；已核销/已作废记录不再参与后续差异统计，但始终可查。
WF-5 报表与复盘（F-5）
recon report --run <id> --format md|csv|both：生成 Markdown 差异报告 + CSV 对账底稿；recon summary --run <id> --by channel|item|day：经营汇总（按渠道/品类/日期）；recon export orders|statements：导出台账 CSV。
WF-6 配置与状态（F-6）
recon config show：查看当前配置；recon config set matching.fee_tolerance 3：改手续费容差（改完立即生效，重跑对账即按新规则）；recon status：会话状态（台账规模/批次列表/最近日志）；recon runs：全部对账批次。
4. CLI 命令手册
| 命令 | 说明 |
|---|---|
recon init |
初始化 runtime 目录 |
recon import orders <文件或文本> [--source-name 渠道] |
导入订单 |
recon import statements <文件或文本> [--source-name 渠道] |
导入账单 |
recon list orders\|statements [--field 字段 --op eq\|contains\|gt\|lt --value 值] |
查询台账 |
recon reconcile --period 2026-07 [--force] |
执行对账 |
recon runs |
列出对账批次 |
recon diffs --run <id> [--type short\|extra\|mismatch] [--status pending] |
差异清单 |
recon diff --run <id> --match <match_id> |
差异详情（两侧原始记录对照） |
recon close --run <id> --match <id> --action confirm\|void\|refund [--reason] |
单笔核销 |
recon batch-close --run <id> --action confirm [--type extra] [--reason] |
批量核销 |
recon report --run <id> [--format md\|csv\|both] [--out-dir] |
生成报告 |
recon summary --run <id> [--by channel\|item\|day] |
经营汇总 |
recon export orders\|statements [--out 路径] |
导出台账 |
recon config show\|set <key> <value> |
配置查看/修改 |
recon status |
会话状态 |
recon demo |
端到端演示（导入样例→对账→差异→报表→幂等验证） |
执行方式（WorkBuddy 内）：
python ~/.workbuddy/skills/order-recon/scripts/cli.py <命令> [参数] --runtime <工作区>/order-recon-runtime
（--runtime 缺省为 ./order-recon-runtime，即从当前工作区执行时无需指定。）
5. 交互约束
- 摘要优先：导入/对账输出摘要与差异分布，不输出全量明细（用户追问再展开）；
- 金额格式：一律两位小数 + 货币符号（默认 ¥，按 config.currency 切换）；
- 二次确认：覆盖重算批次（
reconcile --force）、批量核销、导出覆盖等不可逆操作前必须向用户确认； - 无法解析的数据：跳过并警告（列出行号与原因），不静默丢弃；
- 边界提示：单批次上限 5000 条（超出提示分批）；不做支付网关自动抓取、不做税务/发票；
- 多币种：台账含币种字段，不同币种不交叉匹配；汇率换算口径见 references/schema.md（V1 不自动换算）。
6. 验收自检（安装后验证）
cd <工作区>
python ~/.workbuddy/skills/order-recon/scripts/cli.py demo
# 预期：导入 10 订单 + 13 账单 -> 匹配 7 笔 -> 差异 5 笔（短2/长2/金额不符1）
# 报告生成 -> 幂等重跑结果一致
单元测试（32 用例）：
python -m unittest discover -s ~/.workbuddy/skills/order-recon/scripts/tests
