hsa-receipt-vault

HSA 收据库

目录

• 概览
• 为何重要
• 输入约定
• 符合条件的支出类别
• 工作流
• 输出约定
• 防护措施

概览

HSA“鞋盒”策略：自掏腰包支付医疗账单，保存收据，让 HSA 数十年免税增长，然后随时自行报销——只要支出发生在开设 HSA 之后，HSA 报销就没有时间限制。此技能负责维护账本、验证条目，并展示当前尚未报销的总额。

为何重要

账本中的每一美元，都是家庭今后可随时从 HSA 免税提取的一美元——这实际上让 HSA 对于相当于医疗支出的金额发挥类似 Roth IRA 的作用；如果退休前需要现金，也可以选择提前报销。

输入约定

两种模式：

A — 添加单张收据：

{
  "date": "2026-03-10",
  "amount_cents": 18500,
  "provider": "Dr. Smith DDS",
  "description": "Dental cleaning",
  "receipt_path": "receipts/2026/2026-03-10-smith-dds.pdf",
  "paid_from_account_id": "acc_chk_001",
  "tx_id": "tx_20260310_004"
}

B — 批量核对（扫描 category: health.* 交易）：

{
  "transactions": [...],
  "existing_vault": [...],
  "hsa_open_date": "2018-01-15"
}

在批量模式下，此技能会遍历 category: health.* 交易，为尚未记入账本的交易提出入库条目，并通过输出请用户逐项确认。

符合条件的支出类别

IRS Publication 502 规定了符合 HSA 条件的支出。此技能会依据以下高层类别进行验证：

符合条件	示例
医疗护理	医生就诊、住院、手术、救护车
牙科	洗牙、补牙、拔牙、正畸
视力	眼科检查、眼镜、隐形眼镜、LASIK
心理健康	心理治疗、精神科治疗、处方住院治疗
处方药	处方药、胰岛素（自 2020 年起，非处方胰岛素也符合条件）
非处方药和经期用品	自 2020 年《CARES 法案》起允许
医疗设备	拐杖、助听器、CPAP、血压监测仪
长期护理	保费（在 IRS 限额内）及符合条件的护理
针灸、脊椎按摩	符合条件
戒烟	符合条件
针对特定疾病的减重	仅限因糖尿病、高血压等而开具处方的情况

通常不符合条件：

• 健身房会员资格（除非针对特定医疗状况开具处方，并附有医疗必要性证明信）。
• 美容手术。
• 维生素和补充剂（除非开具处方用于治疗特定病症）。
• 婚姻／家庭咨询。
• 保险保费（少数例外：COBRA、领取失业救济期间，以及 65 岁及以上人士的 Medicare）。

如果某项候选支出存在歧义，请将 qualification: unclear 作为标记，附上 IRS Pub 502 参考信息，并让用户确认。

工作流

HSA Vault Progress:
- [ ] Step 1: Validate receipt date is after HSA open date
- [ ] Step 2: Map description to a qualified-expense category
- [ ] Step 3: Confirm receipt_path exists or note it's pending
- [ ] Step 4: Confirm amount paid from a non-HSA account (else not a vault entry)
- [ ] Step 5: Generate id and append to ledger
- [ ] Step 6: Update running unreimbursed_total
- [ ] Step 7: Emit warnings for ambiguous qualifications

第 1 步 — 日期检查

日期早于开设 HSA 日期的收据，不符合免税报销条件，无论 HSA 之后增长了多少。请拒绝该条目并明确警告。

第 2 步 — 类别映射

根据描述和商户类别映射到符合条件的类别。如果无法映射，请标记为 qualification: unclear，并在适用时建议用户附上医疗必要性证明信。

第 3 步 — 收据路径

必须保留收据——报销后，IRS 可能在法定时效期内要求提供证明材料。可接受的收据格式：PDF、JPG、PNG。相对于 household-finance 根目录存储路径：receipts/YYYY/YYYY-MM-DD-provider.ext。

如果缺少 receipt_path，请接受该条目，但标记为 receipt_status: pending 并发出警告。请勿将 pending 条目计入当前尚未报销总额；附上收据后即可计入。

第 4 步 — 资金来源账户

只有从非 HSA 账户支付的收据才能存入收据库。直接通过 HSA 借记卡或 HSA 账单支付功能支付的费用，已经属于免税分配；不应放入鞋盒。

第 5 步 — 追加

生成 id: rcpt_<year>_<seq>，追加到 hsa.json.receipt_vault[]。绝不修改之前的条目；如需更正，追加一条包含 correction_of: <prior_id> 的记录。

第 6 步 — 运行总额

unreimbursed_total_cents = Σ amount_cents WHERE receipt_status = "ok" AND reimbursed = false。

这是最重要的数字——家庭随时可以免税提取的金额。

第 7 步 — 警告

• qualification: unclear — 提醒用户。
• 添加时收据日期距今超过 1 年 — 仅供参考；有些用户会批量补录，这是可以的。
• 单张收据金额超过 $1,000 — 仅供参考；确保收据涵盖全部金额。
• 日期、服务提供方和金额都与现有条目相同 — 可能重复；请用户确认。

输出约定

模式 A（单条添加）：

{
  "added": {
    "id": "rcpt_2026_0014",
    "date": "2026-03-10",
    "amount_cents": 18500,
    "provider": "Dr. Smith DDS",
    "description": "Dental cleaning",
    "category": "dental",
    "qualification": "ok",
    "receipt_path": "receipts/2026/2026-03-10-smith-dds.pdf",
    "receipt_status": "ok",
    "paid_from_account_id": "acc_chk_001",
    "tx_id": "tx_20260310_004",
    "reimbursed": false,
    "tax_year": 2026
  },
  "running_totals": {
    "unreimbursed_total_cents": 4435500,
    "by_year_cents": {
      "2024": 1820000,
      "2025": 2150000,
      "2026": 465500
    }
  },
  "warnings": []
}

模式 B（批量核对）：

{
  "proposed": [
    {
      "tx_id": "tx_20260118_005",
      "amount_cents": 4500,
      "provider": "CVS Pharmacy",
      "description_raw": "CVS/PHARMACY #04123",
      "suggested_category": "prescription_drugs",
      "qualification": "ok",
      "needs_receipt_upload": true
    },
    {
      "tx_id": "tx_20260201_002",
      "amount_cents": 8500,
      "provider": "Equinox",
      "description_raw": "EQUINOX MONTHLY DUES",
      "suggested_category": null,
      "qualification": "not_qualified",
      "rationale": "Gym memberships are not qualified unless prescribed for a specific medical condition with a Letter of Medical Necessity."
    }
  ],
  "running_totals": {
    "unreimbursed_total_cents": 4435500
  }
}

防护措施

• 必须检查 HSA 开户日期。 开户前的费用绝不能免税报销。
• 必须检查付款账户。 直接从 HSA 支付的收据绝不能录入收据库。
• 收据留存由用户负责。 如实记录 receipt_path；标记缺失的收据；不要将其计入未报销总额。
• 仅追加的账本。 绝不修改。使用 correction_of 进行更正。
• 未报销总额代表潜在金额，而非已实现的金额。 将其显示为“随时可用于免税报销的金额”。只有实际报销后，它才会出现在纳税申报表中。
• 不要建议何时进行报销。 这是由用户与储蓄债务和投资退休 Agent 共同决定的资金管理事项（现金需求与 HSA 持续增长之间的权衡）。
• 非处方药和经期用品在 2020 年之后属于合格支出。 不要想当然地拒绝。