statement-reconciler

对账单核对器

目录

• 概述
• 输入约定
• 对账恒等式
• 工作流
• 诊断
• 输出约定
• 防护措施

概述

无法对平的对账单，说明解析有误。此技能会强制执行一项检查，一次性捕捉解析器的所有故障模式：期初余额 + Σ（交易）= 期末余额。若检查失败，它会诊断原因——缺少交易、符号翻转、重复计入某一行、外币换算产生的舍入误差——以便记账人员在提交脏数据前修复问题或升级处理。

输入约定

调用方提供解析器的输出：

• account_id、period_start、period_end。
• opening_balance_cents、closing_balance_cents。
• transactions — {id, date, amount_cents, description_raw} 数组。
• tolerance_cents（默认值为 100 = $1.00）。
• account_type — 会影响符号约定（见下文）。

对账恒等式

对于现金账户和信用账户：

closing_balance_cents = opening_balance_cents + Σ transactions.amount_cents

符号约定：

账户类型	流出（例如，购买、付款、取款）	流入（例如，存款、收到的付款）
checking / savings	负数	正数
credit_card（家庭账本视图）	购买为负数	信用卡付款为正数
credit_card（发卡机构余额视图）	正数（余额增加）	负数（余额减少）

此技能对现金和信用卡使用家庭账本视图：流出为负数，流入为正数。如果解析器对信用卡使用了发卡机构视图，请先翻转符号再进行对账。

此技能不适用于经纪账户 / 401k / HSA 持仓对账单（这些反映的是某一时点，而非资金流）。请跳过。

工作流

Reconciliation Progress:
- [ ] Step 1: Confirm account_type is in {checking, savings, credit_card, mortgage}
- [ ] Step 2: Sum signed amount_cents
- [ ] Step 3: Compute computed_closing = opening + sum
- [ ] Step 4: Compute diff = closing − computed_closing
- [ ] Step 5: If |diff| <= tolerance, return ok: true
- [ ] Step 6: Else, run diagnostics
- [ ] Step 7: Emit reconciliation report

步骤 1–5

非常简单。大多数对账单在步骤 5 就能通过。

步骤 6 — 诊断

按顺序执行以下检查；第一个能解释差额的诊断优先。

诊断 A — 疑似符号翻转。 如果 |diff| / 2 与任一单笔交易的绝对值相差不超过 $0.50，则该笔交易在提取过程中很可能被翻转了符号。报告：sign_flip_suspect: tx_id_X。

诊断 B — 疑似缺少交易。 如果 |diff| 与对账单上的某条 “Fees” 或 “Interest” 汇总行金额相符，但未提取到对应的单笔交易，则解析器遗漏了该行。报告：missing_transaction_suspect: <amount> <description>。

诊断 C — 重复计入交易。 如果输入中同一组 (date, amount, description) 三元组出现两次，且 |diff| 与该金额相符，则删除其中一笔并重新核对。报告：double_counted: tx_id_X。

诊断 D — 遗漏费用/扣款。 如果 diff 较小（≤ $50）且与常见费用相符，请查找可能遗漏的 “Service Charge” / “Monthly Fee” / “Foreign Transaction Fee” 行。

诊断 E — 舍入误差累积。 如果 |diff| ≤ tolerance × N/100，其中 N 为交易笔数，则可能累积了逐行舍入误差。整数分值通常不会出现这种情况，但外币交易行可能会。报告：rounding_drift_suspect。

诊断 F — 期间不匹配。 如果 period_end 与对账单上打印的期末日期不符，则期初余额或期末余额可能配错了。报告：period_mismatch_suspect。

如果没有任何诊断符合条件，则返回 ok: false 和 diagnostic: "unknown"，以便记账人员升级处理。

步骤 7 — 容差策略

默认容差：$1.00（100 分）。

对于发卡机构精确到分进行对账的信用卡对账单，将容差收紧至 0。仅在用户明确要求时才放宽至 $5，并显示精确差额，以便用户了解。

输出约定

{
  "account_id": "acc_chk_001",
  "period_start": "2025-12-15",
  "period_end": "2026-01-14",
  "opening_balance_cents": 1124300,
  "closing_balance_cents": 1247500,
  "transactions_sum_cents": 123200,
  "computed_closing_cents": 1247500,
  "diff_cents": 0,
  "tolerance_cents": 100,
  "ok": true,
  "diagnostic": null,
  "suggestions": []
}

失败示例：

{
  "account_id": "acc_cc_001",
  "period_start": "2025-12-15",
  "period_end": "2026-01-14",
  "opening_balance_cents": 0,
  "closing_balance_cents": -284300,
  "transactions_sum_cents": -283100,
  "computed_closing_cents": -283100,
  "diff_cents": -1200,
  "tolerance_cents": 100,
  "ok": false,
  "diagnostic": "missing_transaction_suspect",
  "suggestions": [
    {
      "type": "missing_transaction",
      "expected_amount_cents": -1200,
      "hint": "statement summary lists 'Foreign Transaction Fee $12.00' but no transaction extracted with that amount",
      "action": "re-parse PDF page 3, look for fee line"
    }
  ]
}

守护规则

• 绝不擅自放宽容差。 如果差异超过容差，核对器必须检查失败——由记账 Agent 决定是否升级处理或重新解析。
• 绝不提交无法核对的对账单。 记账 Agent 必须暂存数据，直到核对成功。核对失败时会在 reports/alerts/ 中创建一条记录，绝不会静默丢弃。
• 经纪账户 / 401k / HSA / 税务表格不在范围内。 持仓对账单和税务表格没有单一的期末余额恒等关系；它们有其他由各自 Agent 负责的一致性检查。
• 幂等性。 使用相同输入调用核对器两次会产生相同输出。
• 差异符号的含义。 负的 diff_cents 表示计算出的期末余额高于报告余额（也就是说，我们有交易记录表明现金比对账单所示的更多）——通常是缺少流入，或流出方向符号错误。