RFC：重新设计账单导入（云端格式模板 + 本地个人规则）

[fatsheep2]

RFC：重新设计 DEG 的账单导入 —— 云端格式模板 + 本地个人规则

状态：草案，征求意见
范围：translate（Go provider）与 import（runtime 模板）两条导入路径的统一设计
调研基线：double-entry-generator 97a4f65（已含 #223、#231），deg-provider-template dev-v3（a00f7c1）
附录（逐账单格式特征、能力矩阵、已知问题清单、外部参考）见 0001-appendix.md
文中示例语法均为草案，字段名和写法以讨论结果为准

0. 摘要

问题

• 同一件事（读账单 → 判断方向 → 分类 → 记账）在 23 个 Go provider 里各实现了一遍。每家的规则字段、默认账户、出错方式都不一样，已知 bug 散落各处。
• runtime 模板（v3）把格式解析、个人分类、分录生成放进同一套规则语言；金额先取绝对值，再由 from/to 决定方向。结果是：个人规则要按收入、支出各写一遍；格式知识被复制到用户本地，用户的账户却写进了云端模板；还有若干情况会静默产出错账。
• 跨行能力（退款配对、换汇配对、去重、余额断言）两条路径都基本没有。

提议

1. 一条固定的导入管线：识别 → 读取 → 规范化 → 关联 → 分类 → 记账 → 校验。
2. 中间统一成一种"规范交易"：金额带符号（正数 = 钱进本账户），本账户用 account_key 标识。
3. 云端模板只描述账单格式（读取、字段映射、方向、关联声明、commodity 规则），不出现任何个人账户。
4. 本地只有三样东西：账户绑定表、一组分类规则、少量参数。一条分类规则同时适用于收入和支出。
5. 分录形态（普通、手续费、转账、换汇、证券交易）由引擎内置；出错一律报错或标记待复核，不静默。

路线：先修正确性（Go 主干止血、v3 引擎 fail-closed），再引入规范交易和本地绑定，最后补读取层、关联层和证券分录。见第 13 节。

1. 背景与调研方法

DEG 目前有两条导入路径：

• translate --provider X：23 个 Go provider 包，按变体拆开约 29 种账单——支付平台 4 种、国内借记卡 9 种、国内信用卡 6 种、海外银行 5 种、证券/加密 5 种。
• import <模板>：runtime 模板引擎（[feature] 新增基于规则的 provider #231），模板放在 deg-provider-template，dev-v3 分支目前有 26 个模板。

这次调研做了：

• 读完全部 provider、analyser、示例输入输出、示例配置和文档；读完全部 dev-v3 模板。
• 用 master 二进制和 dev-v3 所用引擎分别跑全部样例；对可疑点构造边界输入复现；投资类输出用 beancount 3 的 bean-check 校验。
• 调研 OFX、QIF、camt.053、MT940 等格式，以及 beangulp、beancount-import、hledger CSV rules、Firefly III、Actual Budget、GnuCash、BeanHub、china_bean_importers 等工具的设计（链接见附录 D）。

社区里反复出现的问题也指向同一组根因：#162（账单重复）、#124（微信退款怎么配规则）、#103（targetAccount 与 defaultCashAccount 的增减关系）、#134（规则能覆写哪些字段）、#200（规则文档冲突）、#194（本地怎么新增解析器）。

2. 现状：问题和证据

2.1 Go provider

逐条清单和代码链接见附录 C，这里只按类型归纳：

类型	例子
规则字段声明了但不参与匹配，等于恒为真	citic、bocom_credit 的 peer，icbc 的 item。一条只写 peer 的 ignore 规则会丢掉整个文件（已复现）
加一条无关规则会改变默认账户	abc、bmo、bocom_credit、ccb、citic、cmb、hsbchk、icbc、td：没有规则时用 defaultMinus/Plus，有任意一条规则后改用 defaultCashAccount
金额精度	alipay、mt 用 float32 解析（1234567.89 → 1234567.88）；jd 删掉小数点后按整数解析
格式写死	alipay 写死跳过 22 行，较新的导出多一行说明，master 已解析失败；bmo 靠行号区分信用卡/借记卡
关键字截断	cib、spdb 只要整行包含"说明"/"合计"就停止读取，后面的交易静默丢失
静默兜底	cib 不认识的币种当 CNY；boc 非人民币一律 USD；icbc、citic 的币种没进 IR；ccb 冲正行金额变 0
崩溃	hsbchk 5 列文件 panic；huobi 手续费为空 panic
分录	证券成本按单价 %.3f、数量 %.2f 截断，碎股和高精度价格不平；港股数字代码、合约地址被直接当作 commodity
命名和语义不一致	tag/tags、status/orderStatus 并存；time 在 oklink 表示日期区间；hxsec 首条命中即停，其余是后者覆盖前者

结论：每家银行一套 Go 代码，等于同一条管线写了 23 遍，也有 23 套各不相同的 bug 和配置写法。

2.2 runtime 模板（v3）

dev-v3 模板依赖若干尚未合入 master 的引擎能力（如表头定位、postingsMode），下文称"开发中引擎"。

verify 结果。 用开发中引擎跑 26 个模板：16 个与 expected 一致，9 个不一致，1 个报错。10 个异常都已定位，没有一个是读表本身的问题：

原因	模板
空 metadata 被输出成 key: ""，Go 版跳过	abc_debit、alipay、hsbchk-credit、hxsec
编译器改为总是输出 payee 和 narration 两段，expected 由旧编译器生成	icbc-credit、icbc-debit-v1、icbc-debit-v2
模板把描述放进了 payee，应放 narration	hsbchk-debit
xlsx 库版本（开发分支仍是 excelize 2.5，master 已是 2.11）；format 不支持补零	htsec
缺 options.title；.number 无法解析 131.77(已退款89.84)	alipay、jd

一致也不等于正确：spdb 的 expected 是用模板重新生成的，与 Go 输出相比已经丢了 tag；citic、boc 的模板把 Go 的币种 bug 一起照抄了。

静默产出错账的路径（均已复现；最后一列是 master 97a4f65 上的复现结果）：

现象	复现	master
冲正行的负号被取绝对值，退回的钱被记成又支出一次	ccb 支出=-67；cib 隔日冲账 -5.50；最小样例 -5.00 输出 Expenses 5.00	同样存在
没有规则判定方向时，输出没有账户的分录，不报错	bocom 借贷列出现模板没覆盖的值；mt 的"不计收支"；hxsec 未知业务类型	同样存在
表头与模板不一致时不报错	用 icbc-debit-v1 模板导入 v2 账单：退出码 0、输出 0 笔交易、没有任何提示（行级错误被 skipInvalidRows 全部吞掉）	同样存在
未声明日期格式时逐行猜	td 模板没写 dateFormat：同一文件里 13/05/2023 按日/月、05/01/2023 按月/日解析。日期解析失败时只报 "rule did not set date"，不带行号和原值	同样存在
条件里日期按算式比较	date > "2025-01-01" 得到 false	不存在，仅开发中引擎
表达式出错静默	master 不支持 .replace，开发中引擎在逗号后有空格时失效；两者都把参数原样拼进结果，不报错	同样存在
不做平衡校验	引用不存在的列，生成一条省略金额的自动平衡腿	同样存在
ledger 目标	runtime 导入用 -t ledger 时，分录里的账户全部丢失（ledger 编译器不处理 Postings）	同样存在

规则繁琐。 金额先取绝对值，再由 from/to 决定方向，所以同一个分类要按收入、支出各写一条：

模板	dev-v3 personalRules 条数	说明
abc_debit	10	Go 示例配置是 5 条
bocom_debit	11	按"贷/借"成对
hsbchk-debit / citic-credit	13 / 13	约 7 个分类
boc-debit	27	每个卡号尾号收、支各一条
alipay / jd	28 / 36	每种付款方式 2～3 条

云端和本地放反了。

• 云端模板里写死了个人数据：BMO、TD、HSBC 的本人账户；ccb 的样例账号、icbc 的卡别名、cmb-credit 的年份 2024/<记账日>（2025 年的账单会被记成 2024 年，已复现）；mt 的 starter 规则里还有带个人 ID 的账户名。
• 用户本地的 personalRules 里反而是格式知识：微信提现服务费的拆分（按银行复制了三份）、支付宝用 订单号 ~ "_" 丢弃退款（部分退款和跨文件退款会静默消失）、"忽略新增证券"。config init 把它们复制到本地之后，就不再随云端更新。

分录是手写的 beancount 文本。 证券、币币交易的分录形态几乎一样，每个模板却手写 2～4 遍 {…} @@ 语法，精度和 commodity 的 bug 跟着一起被复制；这些文本也没办法输出成 ledger。

2.3 根因

1. 一套规则语言同时承担规范化、分类和分录生成。 模板作者和用户写的是同一种东西，边界无从划分。
2. 金额取绝对值，方向由 from/to 决定。 符号信息丢了，规则必须收支各写一遍，冲正必然出错。
3. 规则条件读的是前面规则改过的值。 结果依赖规则顺序，难以预测。
4. 没有文件级上下文，也没有跨行阶段。 表头上方的账号、币种、账单年月读不到；退款、换汇、去重无处表达。
5. 没有存放"本人账户"的地方。 只能写死在模板或规则里。
6. 默认是"出错也继续"。 静默跳过、静默兜底、静默输出原值。

2.4 值得保留的部分

精确小数运算；registry 按日期固定模板版本（pin）；能力声明遇到不认识的就拒绝；表头定位要求唯一匹配；模板和个人规则分文件存放的方向；现有的契约测试写法。

3. 目标与非目标

目标

• 完整：覆盖现有 29 种账单，并能扩展到 OFX、XML、多段表格等常见格式。
• 简单：用户只写"我的账户是哪个"和"这个商户记到哪"；一个商户一条规则。
• 可靠：认不出就报错；拿不准就标记待复核；每笔分录保证平衡；能用账单自带的余额和合计核对。
• 分工清楚：格式知识在云端，可以随银行改版更新；个性化在用户自己的账本仓库里。
• 两种输出等价：beancount 和 ledger 用同一套分录。

非目标（本 RFC 不做）

• 机器学习自动分类。规范交易和复核标记为以后接入留了口子。
• 交互式复核界面。DEG 只输出标记和报告，任何编辑器或 Fava 都可以使用。
• 开放银行 API 拉取。DEG 处理的是文件。
• 引擎内置 PDF 解析。先规范外部转换器的输出，见第 12 节。
• 图灵完备的规则语言。

4. 总体架构

4.1 三部分职责

部分	在哪	谁维护	内容
引擎	DEG 二进制	DEG 维护者	各格式的读取器、规范化函数、关联算法、分录形态、校验、报告
格式模板	deg-provider-template（云端，按版本发布）	模板贡献者	每种账单怎么读、字段怎么映射、方向怎么判断、要做哪些关联、commodity 怎么命名，以及样例和期望输出
本地配置	用户自己的账本仓库	用户	账户绑定表、分类规则、少量参数

判断一样东西放哪，问两个问题：

• 换一个用户还成立吗？ 成立就放云端（例如"招行信用卡账单里正数是消费"）；不成立就放本地（例如"尾号 1234 是 Liabilities:CMB"）。
• 银行改版会影响它吗？ 会，就必须放云端，用户才不用手改。

4.2 管线

识别 detect      按文件指纹选模板和变体；认不出就报错，不猜
  ↓
读取 read        表格行 + 表头前元信息（context）+ 尾部停止；支持多文件、多段、XML、OFX
  ↓
规范化 normalize  每行 → 一条规范交易（第 5 节）；方向、币种、日期在这一步确定，且只确定一次
  ↓
关联 link        退款/冲正配对、多行聚合、换汇/互转配对、去重（模板声明，引擎实现）
  ↓
分类 classify    本地规则：对方账户、payee、narration、tags、ignore
  ↓
记账 post        引擎按 kind 生成分录，保证平衡、commodity 合法
  ↓
校验 check       余额断言、账单合计核对；输出复核报告

阶段	输入	输出	谁来配置	失败时
识别	文件	模板 id + 变体	云端 detect	报错，列出最接近的模板
读取	文件	原始行 + context	云端 read / context	报错，带行号
规范化	原始行	规范交易	云端 fields / rows	报错，带行号和原值
关联	规范交易流	合并、标记后的交易流	云端 link + 本地参数	有歧义就不合并，标记待复核
分类	规范交易	加上对方账户等	本地 rules	没命中就用默认账户（如 Expenses:FIXME）并标记
记账	分类后的交易	分录	引擎	不平衡、空账户、非法 commodity 直接报错
校验	分录 + 余额/合计	断言、报告	云端 checks	不符时报错，或写进报告（由 --strict 决定）

为什么拆成这么多阶段： 每个阶段只看上一阶段的输出，写在哪一层就只影响那一层。分类规则拿到的永远是已经确定了方向和币种的交易，不需要知道这份账单原来是"收/支两列"还是"借贷方向列"。

5. 规范交易（Canonical Transaction）

规范交易是规范化阶段的输出，也是分类规则唯一能看到的东西（另外可以只读访问 raw）。

字段	类型	必填	含义	为什么需要
source	{template, variant, pin, file, row}	引擎填	来源	复现、报告、去重；输出为 deg-src 元数据
account_key	类别/值	是	本账户标识，如 card/1234、method/花呗、sub/002、addr/0x…、acct/U123456	不同用户的账户不同，交给本地绑定表决定账户名
date	日期	是	交易日
time	时间	否	交易时间	按时段分类；同日排序
tz	时区	模板声明	默认取模板	不再依赖运行机器的时区
booked_date	日期	否	记账日、入账日、交收日	信用卡交易日与记账日不同；证券交收
amount	精确小数，带符号	是	正数 = 钱进本账户，负数 = 钱出本账户	唯一的方向约定。冲正自然正确；一条分类规则同时管收支
currency	ISO 代码或 commodity	是	记账币种	多币种账户
original	{amount, currency}	否	原币金额	外币消费以人民币入账时保留原币
fees	[{amount, currency, kind}]	否	附带费用	微信提现服务费；证券佣金、印花税；IBKR 佣金币种与成交币种不同
counterparty	{name, account, bank}	否	对手方，三项分开	不再把户名和卡号拼在一起（boc），按卡号尾号匹配不会误中
description	字符串	否	摘要、商品说明
channel	字符串	否	资金渠道原文，如"招商银行信用卡(1234)"	跨来源去重（同一笔同时出现在微信和银行流水里）
kind	枚举	是，默认 normal	normal transfer refund reversal fee interest dividend tax fx trade adjust	决定分录形态和默认对方账户
status	枚举，另有 status_raw	否	booked pending closed failed	统一的状态过滤
ids	{order, merchant_order, txn, trade, hash, serial}	否	账单自带的 ID	去重、退款配对、幂等导入
balance	{amount, currency}	否	该行之后的余额	生成余额断言
trade	{security, side, qty, price, total, settle_date}	kind=trade 时	证券或币币交易	由引擎生成标准证券分录
related	{refund_of, reversal_of, group, pair}	关联阶段填	行间关系
raw	只读字典	引擎填	原始单元格 + context	规则能读不能改；排查问题
flags	列表	引擎填	unclassified ambiguous_pair possible_duplicate unknown_type …	复核报告

给规则用的派生字段（只读）：direction（in / out）、abs_amount、weekday。

两条关键约定：

• 金额只在规范化阶段定一次符号。 账单的三种方向表示（带符号金额、收入/支出两列、单独的方向列）都在模板里转成带符号金额，之后谁也不再取绝对值。
• 本账户和对方账户分开处理。 本账户由 account_key 经本地绑定表得到；对方账户由分类规则或按 kind 的默认值得到。引擎根据 amount 的符号决定谁在借方、谁在贷方。

6. 云端格式模板

6.1 目录与发布

registry.yaml                    id、名称、分类、latest、pins、sha256、最低引擎版本
<id>/<pin>/
  template.yaml
  README.md                      这种账单怎么导出
  fixtures/<case>/
    bill.*                       脱敏样例
    local.yaml                   样例用的本地配置
    expected.beancount
    expected.ledger

6.2 template.yaml 的结构

段	作用
schema id name pin requires	元信息。requires 列出用到的引擎能力，引擎不支持就拒绝加载
detect / variants	指纹：表头前文本的正则、必需表头。一个 id 下可以有多个变体（icbc 借记 v1/v2、wechat csv/xlsx），按指纹自动选择
read	格式、编码、分隔符、sheet、表头定位、尾部停止、单元格清洗、是否多文件、行序
context	从表头前的元信息里取值：账号、子账户、币种、账单年月、合计数
maps	值映射表：中文币种名 → ISO、类型 → kind/方向。可以引用引擎内置表
fields	规范交易各字段的取值表达式
rows	格式层面的逐行规则：按类型定 kind；跳过（交易关闭、冻结、"新增证券"）；拆出手续费
link	关联声明：退款、冲正、聚合、配对、去重键
slots	除本账户外还需要用户绑定的账户槽位，如证券的 position fee pnl
commodity	commodity 命名规则：交易所前缀、补零、映射表
checks	余额断言、账单合计核对
params	可以被本地覆盖的参数及默认值（换汇配对窗口、是否保留退款对、用交易日还是记账日）

6.3 示例：招行信用卡

只描述格式，不出现任何个人账户：

schema: deg/template/2
id: cmb-credit
name: 招商银行信用卡
pin: 2026-10-01

detect:
  preamble: '^招商银行信用卡对账单'
  headers: [交易日, 记账日, 交易摘要, 人民币金额, 卡号末四位]

read:
  format: csv
  header: { locate: [交易日, 记账日, 交易摘要, 人民币金额, 卡号末四位] }

context:
  period: { preamble: '(\d{4})年(\d{2})月' }     # 账单年月，用来补全 MM/DD 的年份

fields:
  date:        { value: coalesce(<交易日>, <记账日>), format: MM/DD, yearFrom: ctx.period }
  booked_date: { value: <记账日>, format: MM/DD, yearFrom: ctx.period }
  amount:      -num(<人民币金额>)       # 账单里正数 = 消费；取反后正数 = 钱进本账户
  currency:    CNY
  description: <交易摘要>
  account_key: card/<卡号末四位>

rows:
  - when: description ^= "还款"
    kind: transfer
  - when: description ~ "年费"
    kind: fee

yearFrom 是引擎内置语义：账单月份是 1 月、交易是 12 月时，年份自动减 1。现在的模板只能写死 2024/<记账日>。

6.4 示例：兴业借记卡（多文件 + 换汇配对）

read:
  format: xlsx
  multiFile: true                      # 同一账户各币种的文件合并成一条流
  header: { locate: [交易时间, 记账日, 支出, 收入, 账户余额, 摘要] }
  stop:   { firstCell: 说明 }          # 只看首列，摘要里出现"说明"不会误停

context:
  account:    { label: 账户账号 }      # 取"账户账号"右边一格
  subAccount: { label: 卡内账户 }      # 如"002 活期储蓄存款 港币 现汇"

maps:
  ccy: builtin:zh-currency             # 人民币→CNY、港币→HKD、美元→USD…；未知名称报错

fields:
  date:     { value: <交易时间>, format: 'YYYY-MM-DD HH:mm:ss', fallback: <记账日> }
  amount:   num(<收入>, 0) - num(<支出>, 0)   # 支出列的 -5.50（冲正）自然变成 +5.50
  currency: map(ccy, extract(ctx.subAccount, '(人民币|港币|美元|欧元|日元|英镑)'))
  account_key: sub/extract(ctx.subAccount, '^(\d+)')
  balance:  num(<账户余额>)
  counterparty: { name: <对方户名>, bank: <对方银行>, account: <对方账号> }
  description:  join(' ', <摘要>, <用途>, <备注>)   # 跳过空值

rows:
  - when: amount == 0
    skip: 零金额

link:
  - pair: fx
    when: raw.摘要 in ["购汇", "结汇"]
    same: [ctx.account]
    differ: [currency]
    window: param.fxWindow
    ambiguous: flag                    # 一笔能配上多笔时不合并，标记待复核

params:
  fxWindow: 3m

checks:
  balance: { order: ascending }

6.5 示例：证券交割单（槽位 + 内置分录）

slots: [cash, position, fee, pnl]      # 具体账户由用户在本地绑定

commodity:
  security:
    value: pad(<证券代码>, 6)           # 不依赖 xlsx 的显示格式来补零
    prefix: { when: <股东账号> ^= "A", then: SH, else: SZ }

maps:
  side: { 买: buy, 卖: sell }           # 其他值报错

fields:
  kind: trade
  account_key: acct/<资金账号>
  trade:
    security: commodity.security
    side:     map(side, <操作>)
    qty:      num(<成交数量>)
    price:    num(<成交价格>)
    total:    num(<成交金额>)
  fees:
    - { amount: num(<手续费>, 0), kind: commission }
    - { amount: num(<印花税>, 0), kind: tax }

分录由引擎生成：现金腿、持仓腿 {成本}、费用腿，卖出时再加盈亏腿。成本按 total 写总额，数量和价格保留账单的原始精度。模板不再手写 {…} @@。

6.6 模板里的表达式

表达式只在云端模板里使用，用户的本地规则不需要算术和字符串处理。

• 引用：<列名>、ctx.名字、param.名字、raw.列名、已经算出的规范字段。
• 函数：num(x[, 空值默认])、coalesce(…)、join(分隔符, …)（跳过空值）、extract(x, 正则)、replace(x, a, b)、trim、pad(x, 宽度)、map(表, 值[, 默认])、lower、upper。
• 运算：精确小数的 + - * /。结果的小数位按输入中最多的那个，不会出现 10.0000。
• 出错就报错：num 遇到认不出的文本、extract 不匹配、map 找不到键（且没给默认值）、参数语法不对，都带行号报错。

为什么改用函数调用，而不是现在的 <列>.method() 链： 参数里的空格、引号、逗号都按普通语法解析，不会再有"逗号后加空格就失效"这类问题；类型也更明确。

7. 本地配置

7.1 结构

本地配置是一个文件，放在用户自己的账本仓库里，可以用 include 拆分：

version: deg-rules/2

output:
  title: 我的账本
  operatingCurrency: CNY
  bookingMethod: FIFO

accounts:                              # 本人账户绑定：<模板>:<account_key 或 slot>
  cmb-credit:card/1234:      Liabilities:CreditCard:CMB:1234
  cmb-credit:card/*:         Liabilities:CreditCard:CMB       # 通配兜底
  alipay:method/余额:         Assets:Alipay:Balance
  alipay:method/花呗:         Liabilities:Alipay:Huabei
  alipay:method/招商银行信用卡(1234): Liabilities:CreditCard:CMB:1234
  cib_debit:sub/*:           Assets:Bank:CIB
  htsec:slot/cash:           Assets:Broker:HTSEC:Cash
  htsec:slot/position:       Assets:Broker:HTSEC:Stocks
  htsec:slot/fee:            Expenses:Broker:Fees
  htsec:slot/pnl:            Income:Broker:PnL

defaults:                              # 规则没命中时，按交易种类决定对方账户
  out:      Expenses:FIXME
  in:       Income:FIXME
  transfer: Equity:Transfers
  fee:      Expenses:Fees
  interest: Income:Interest

params:                                # 覆盖模板参数
  alipay:    { keepRefundPairs: true }
  cib_debit: { fxWindow: 5m }

rules:
  - when: counterparty ~ "国网" || counterparty ~ "电费"
    account: Expenses:Utilities:Electricity

  - when: counterparty ~ "滴滴" && time >= 22:00
    account: Expenses:Transport:Taxi
    tags: [late-night]

  - when: source == "cmb-credit" && description ~ "支付宝"
    ignore: 以支付宝账单为准          # ignore 必须写原因，原因会出现在报告里

  - when: source == "wechat" && direction == in && abs_amount < 1
    account: Income:RedPacket

对比现状：dev-v3 的 cmb-debit 里，"电费"要写成"电费支出"和"电费收入"两条。上面第一条规则对缴费和退费都生效，退费时引擎自动把同一个账户放到另一侧。

7.2 账户绑定表

• key 的格式是 <模板 id>:<类别>/<值>，值可以用 * 通配，精确匹配优先于通配。
• 本账户找不到绑定时报错，并列出所有缺失的 key。原因：本账户是唯一不能猜的东西，猜错会让余额整体错位。
• deg init <模板> <账单> 扫一遍账单，把发现的卡号、付款方式、子账户、槽位全部写进本地文件的骨架，用户只需要填账户名。
• 多张卡、多种付款方式、多币种子账户、多个钱包地址、多个券商账户，都是同一种写法。不再需要每个 provider 各自发明 methodAccount、cashAccount、positionAccount。

7.3 分类规则

条件语法

expr := expr '||' expr | expr '&&' expr | '!' expr | '(' expr ')' | cmp
cmp  := field op value
op   := ==  !=  ~(包含)  !~  ^=(开头)  $=(结尾)  =~(正则，RE2)  <  <=  >  >=  in [..]

• 可用字段：第 5 节的规范字段和派生字段、source（模板 id）、key（account_key）、raw.列名、ctx.名字。
• 字段有类型：日期按日期比较，时间按 HH:MM 比较，金额按精确小数比较，其余按字符串比较。不会再把日期当成算式。

动作

动作	多条规则命中时
account	对方账户，后命中的覆盖先命中的
payee narration flag	后者覆盖
tags links	累加并去重
metadata	按 key 覆盖
slots	覆盖本笔交易的槽位账户（例如某只 ETF 记到另一个持仓账户）
ignore: <原因>	命中就丢弃，原因写进报告

语义

1. 所有规则读的是同一份不可变的规范交易，规则之间看不到彼此的输出。规则顺序只决定"同一个字段谁覆盖谁"。
2. 动作的值只能是字面量或简单插值（如 narration: "{description} - {counterparty}"），没有算术。
3. 配置里出现不认识的键、字段、运算符，在读账单之前就报错。

为什么这样定：

• 不可变输入消除了"前一条规则改了 payee，后一条规则因此命中或不命中"的问题，这是现在 v3 行为最难预测的地方。
• 不给本地规则算术和自由文本分录：本地文件越简单，模板升级时越不容易坏；需要算术的地方几乎都是格式知识，应该放在模板里。
• Go 主干那批"字段写了不生效"的 bug，根本原因是 YAML 里不认识的键被静默忽略。加载时校验能一次性消除这一类问题。

7.4 拆分分录（待讨论）

少数场景需要把一笔拆到多个对方账户（例如合租的房租）。建议用结构化写法，而不是 beancount 文本：

  - when: counterparty ~ "房东"
    split:
      - { account: Expenses:Housing:Rent, ratio: 0.5 }
      - { account: Assets:Receivable:Roommate, ratio: 0.5 }

8. 引擎内置能力

类别	内容
读取器	csv/tsv、xls、xlsx（解析库版本锁定并纳入回归测试）、xml（按元素名或路径选行，属性映射成列）、ofx 1.x/2.x、多段表格、多文件合并
规范化	精确小数解析；严格日期（只按模板声明的格式）；时区；内置中文币种名表；yearFrom 补年份
关联	退款（订单号或 ID 前缀 + 金额）；冲正（同账户、金额相反、时间窗口）；聚合（按 key 合并多行，如同一 txHash、新股中签拆成的两行）；配对（跨行、跨文件，按 key、时间窗口、金额或汇率容差）；去重
分录	normal 两腿；有 fees 时加费用腿（费用可以是另一种币种）；transfer；fx（@@ 总价）；trade 买、卖（成本写总额、保留原始精度、费用腿、卖出盈亏腿）；dividend + tax
commodity	校验是否合法（如不能以数字开头）；按模板规则加前缀、补零、映射；不合法就报错
校验	每笔分录平衡；账户不为空；余额断言（按日取最后一行，在次日生成 balance）；账单合计核对
输出	稳定排序（先按日期，再按文件内顺序）；元数据 deg-id、deg-src；空元数据不输出；beancount 与 ledger 用同一套分录
报告	读取、记账、跳过的行数及原因；待复核清单；校验结果；--strict 下有未决项就失败；--report 输出 JSON

报告示例：

alipay@2026-05-23  bill.csv
  读取 412 行：记账 380，跳过 32（交易关闭 20 / 退款对已合并 10 / 零金额 2）
  待复核 17：未分类 14（Expenses:FIXME）/ 配对有歧义 2 / 疑似重复 1
  校验：账单合计 收入 1,234.00 / 支出 5,678.90，与表头一致

8.1 去重与幂等

1. 有账单 ID 就用 ID：deg-id: "<模板>:<account_key>:<id>"。
2. 没有 ID 时，用稳定字段的哈希：模板、account_key、日期、金额、币种、描述，再加上"同样内容在本文件里是第几次出现"。
3. 重复导入时用 --existing main.bean 读取已有账本里的 deg-id，跳过已经导入的交易。
4. 模糊匹配（日期接近、金额相同）只标记，不自动删除。

为什么分级： 只有账单 ID 能确定是同一笔；哈希能防止同一份文件导两次；模糊匹配误删的代价远高于漏删，所以只提示。

8.2 跨来源重复

同一笔消费会同时出现在微信/支付宝账单和银行卡、信用卡流水里（#162）。第一步用 channel 字段加本地 ignore 规则解决，例如"招行信用卡流水里描述含'支付宝'的，以支付宝账单为准"。自动的跨来源配对放到以后，等收集到足够的真实样例再设计。

9. 出错策略（fail-closed）

情况	行为
认不出文件格式；表头与模板不符	报错，列出最接近的模板和缺少的表头。只有模板显式声明 headerless 时才按列位置读
日期、金额解析失败；map 找不到值；表达式出错	报错，带文件名、行号、原值
某行既没定出方向也没定出 kind	报错（属于模板 bug）；或者按模板的 unknown: flag 记到 FIXME 并标记
本账户没有绑定	报错，列出缺失的 key
分类规则都没命中	记到 defaults 对应的账户，打 ! 标记，计入报告
配对有歧义	不合并，标记
分录不平衡、账户为空、commodity 不合法	报错
尾部行、零金额行、格式层面的忽略	跳过，按原因计数写进报告
配置里有不认识的键	加载时报错

现在的 skipInvalidRows（跳过一切出错的行）拆成两件事：一是模板显式声明的尾部和跳过规则，二是真正的错误。后者不能静默。

10. 版本与分发

几个概念要分开：

概念	含义	例子
id	机构 + 产品	icbc-debit
variant	同一 id 下的格式变体，按指纹自动识别	icbc-debit 的 13 列版和 15 列版
pin	模板包的冻结版本	icbc-debit@2026-10-01
模板 schema	模板文件格式的版本	deg/template/2
本地协议	本地配置文件格式的版本	deg-rules/2
capability	模板或本地文件用到的引擎能力	read.xml、link.pair

现在 icbc 用 -v1/-v2 两个 id 区分格式，选错也不报错。改成同一个 id 下的变体后，用户不需要知道银行改过几次版。

registry 与缓存

• 每个文件带 sha256，下载后校验；声明最低引擎版本。
• 本地缓存，可以离线使用；网络请求有超时；--offline 只用缓存。
• 输出文件头记录用到的模板和 pin，结果可以复现。

模板仓库的 CI

• 每个 fixture：引擎输出与 expected 一致、bean-check 通过、ledger 输出也通过检查。
• lint：模板里不能出现具体账户名（只能用槽位），不能出现个人信息。
• 改动导致输出变化时，必须同时更新 expected，并在 PR 里说明原因。
• 银行改版时，新增变体或发布新 pin，latest 指向新版本，旧 pin 保留。

11. 兼容与迁移

• translate --provider X 继续可用。Go provider 冻结，只修 bug；对应模板通过与 Go 输出的对照测试后，改为调用新引擎；最终删除各银行的 Go 代码，只保留通用读取器。
• 提供 deg migrate，把旧配置转换成新的本地配置：

旧字段（Go config）	新写法
defaultCashAccount，或作本账户用的 defaultMinusAccount	accounts 绑定
methodAccount + method	accounts 绑定 method/…
cashAccount positionAccount commissionAccount pnlAccount	accounts 绑定 slot/…
peer	counterparty ~ …
item	description ~ …
type / txType / category	raw.列名 == …，或 kind == …
status / orderStatus	status == …
time / timestamp_range	time >= … && time <= … / date >= … && date <= …
minPrice / maxPrice	abs_amount >= … / abs_amount <= …
sep + 多个值	in [...] 或 ||
fullMatch	==（不写则是 ~）
targetAccount	account
tag / tags	tags
ignore	ignore: <原因>

• dev-v3 的 rules.yaml：收支成对的规则合并成一条；格式知识（服务费拆分、退款判断、"忽略新增证券"）移回模板；模板里写死的账户移到 accounts。转换器拿不准的地方输出注释，让用户确认。

12. 其他账单格式

优先级	格式	理由
1	OFX / QFX / QBO	一个通用模板就能覆盖 BMO、TD 和绝大多数北美银行；自带唯一 ID（FITID）、余额、币种，比各家的 CSV 可靠
2	XML、多段 CSV	IBKR Flex，以及以后要接入的券商
3	PDF / 邮件账单	中行、交行、招行、民生等的借记卡和信用卡主要只提供加密 PDF 或邮件。先把 bill-file-converter 的输出固定成一种格式并纳入测试，引擎暂不内置 PDF 解析
4	加密交易所 CSV（Binance、OKX、Coinbase）	一笔交易拆成多行，需要聚合
5	camt.053 / MT940、PayPal、Wise、云闪付	欧洲银行；多币种钱包；云闪付与银行流水重复的风险高

抖音支付、拼多多、携程，以及光大、平安、邮储等银行，没有找到可靠的导出格式资料，需要用户提供脱敏样例。

13. 路线图

步骤	内容	验收	完成后可以迁移的模板
A. Go 主干止血	alipay 按表头定位；alipay/mt/jd 金额改精确小数；ccb 冲正；cib/spdb 的尾部判断改为只看首列；币种不再静默兜底；hsbchk、huobi 的 panic；配置里不认识的键先告警	每个修复带回归样例	无（修的是用户正在用的路径）
B. v3 引擎 fail-closed	第 2.2 节的全部静默问题；ledger 目标；空元数据；稳定排序；锁定 xlsx 库版本	verify 改为对照 Go 输出，并跑 bean-check	无
C. 规范交易 + 本地配置	带符号金额；account_key 与绑定表；不分方向的分类规则；deg init；内置 normal/transfer/fee 分录；deg-rules/2；deg migrate	现有 fixture 在新格式下的输出与 B 一致	bmo×2、td、hsbchk×2、abc_debit、bocom_debit、cmb-debit、mt、wechat
D. 读取层	context、尾部停止、变体识别、值映射、多文件、多段、XML、OFX	icbc v1/v2 合并为一个 id；cmb-credit 不再写死年份	cmb-credit、icbc×3、ccb、spdb、citic、cgb、boc×2、bocom_credit、jd、alipay
E. 关联层	退款/冲正配对、聚合、配对、去重、余额断言、合计核对	支付宝的部分退款、跨文件退款不再丢失；cib 换汇合并成一笔	alipay/jd/wechat 的退款处理、cib
F. 证券/外汇分录 + commodity	内置 trade/fx/dividend；成本写总额、保留原始精度；commodity 校验与映射	投资类 fixture 全部通过 bean-check	htsec、hxsec、huobi、ibkr、oklink

A 和 B 可以并行，也可以在本 RFC 定稿之前开始。C 是规则格式的分水岭：之后的步骤只增加能力，不再改变用户的写法。

14. 考虑过的其他方案

方案	不选的原因
在现有 v3 规则语言上继续加能力	第 2.3 节的根因 1～3 不解决，能力加得越多越难预测
每家银行继续写 Go provider	就是现状：同一条管线写 23 遍，bug 和配置写法各不相同
像 beangulp 那样用 Python 写导入器	DEG 是单个 Go 二进制并支持 WASM；模板需要作为数据安全地在线分发，代码插件还需要沙箱
照搬 hledger CSV rules	声明式、适合单表 CSV，本 RFC 借鉴了它处理收支两列和条件规则的方式；但它没有跨行处理和文件级上下文
本地规则保留 postings 文本	用户文件会依赖 beancount 语法，没法输出 ledger，也没法做平衡校验；改用结构化的 split
机器学习自动分类（如 smart_importer）	不在本 RFC 范围。规范交易和 flags 让它以后可以作为一个可选的分类步骤接入

15. 待讨论

1. account_key 的写法（card/1234 还是 card:1234），以及通配语法。
2. 本账户没有绑定时，是报错，还是记到 Assets:FIXME:<key> 并标记？本 RFC 倾向报错。
3. 本地规则能不能读 raw.列名？允许的话，本地规则会依赖账单列名，模板改版时可能失效。倾向于允许，但模板升级时对用到 raw 的规则给出提示。
4. --existing 去重是解析完整账本，还是只扫描 deg-id 元数据行。
5. 跨来源重复（微信/支付宝与银行流水）什么时候做自动配对。
6. PDF：继续依赖外部转换器，还是引擎内置。
7. translate 和 import 两个命令最终是否合并。
8. 是否需要英文版。

[fatsheep2]

RFC 0001 附录

配合 0001-import-pipeline.md 阅读。

• 代码链接固定到 double-entry-generator 97a4f65 和 deg-provider-template dev-v3 a00f7c1。
• 标"已复现"的条目是用构造的输入实际跑过的；标"未验证"的是读代码得出的结论或常识，还需要确认。

A. 逐账单格式特征

#	账单	文件	方向怎么表示	币种来源	表头前元信息	余额	唯一 ID	需要特别处理
1	alipay	csv，gb18030	收/支列（收入/支出/不计收支），金额恒正	固定 CNY	姓名、账户、起止时间、笔数和收支合计	无	交易订单号、商家订单号	退款配对（订单号前缀 + 金额）；交易关闭；不计收支要细分方向；付款方式决定资金账户
2	wechat	csv / xlsx	收/支列（含 / 中性交易）	固定 CNY	昵称、起止时间、笔数和收支合计；xlsx 多一行时区说明	无	交易单号、商户单号	备注里的服务费要拆出来；退款不配对；¥；单元格内有 Tab
3	jd	csv，BOM	收/支列（支出/收入/不计收支）	固定 CNY	账号、日期区间、合计	无	交易订单号	金额后缀 (已退款x)；冻结/解冻；先享后付的 0 元行；付款方式嵌套（"微信-招商银行信用卡"）
4	mt	csv，BOM	收/支列	固定 CNY	账号、合计	无	无	订单金额与实付金额；全角 ￥；退款不配对；与微信账单重复
5	abc_debit	csv（由 PDF 转换）	带符号，必须有 +/-	固定 CNY	无（转换时丢失）	有	日志号（结息行不唯一）	交易时间可为空；-- 表示空
6	bocom_debit	csv（由 PDF 转换）	借贷列（借 Dr / 贷 Cr），金额无符号	固定 CNY	无	有	序号	Go 把户名和账号拼成 payee
7	spdb_debit	xls	存入/取出两列	固定 CNY	账号、账户类型、日期范围（目前被丢弃）	有	顺序号	日期和时间在同一格、中间两个空格；尾部"合计"
8	cib_debit	xlsx/xls，每个币种一个文件	收入/支出两列，可以为负（冲正）	表头前的"卡内账户"	户名、账号、卡内账户、起止日期	有	无	多文件；购汇两条腿配对；尾部"说明"
9	ccb	xls（另有 csv 路径）	收入/支出两列，用 0 表示没有	表头前"币种"，每行也有币种列（中文）	开户机构、币种、账号	有	无	对手方打码，真实商户只出现在"交易地点"；冲正
10	boc-debit	csv	带符号	币别列（中文）	标题	有	无	倒序；---- 占位；Go 把户名和卡号直接拼接
11	cmb-debit	csv（由 PDF 转换）	带符号	货币列	无	有（联机余额）	无	导出时列可选，要按表头名对齐
12	icbc-debit v1	csv	收入/支出两列	币种列（中文）	卡号、卡别名、子账户序号和类别	有	无	尾部合计；单元格尾随空格和 Tab；行尾逗号
13	icbc-debit v2	csv	同 v1	同 v1	同 v1	有	无	比 v1 多"交易详情""对方账户"
14	cmb-credit	csv（由 PDF 转换）	带符号，正数 = 消费	CNY；交易地金额带地区后缀	标题里有账单年月	无	无	日期只有 MM/DD，要用账单年月补年份；还款行没有交易日；卡号末四位
15	citic	xls	带符号，正数 = 消费	交易币种 / 结算币种（中文）	标题	无	无	倒序；卡末四位；应按结算金额记账
16	bocom_credit	csv（由邮件转换）	金额无符号，方向看摘要的第一个词	金额格里写"币种 金额"	无	无	无	原币和入账币两列；未知类型
17	cgb_credit	csv（由 PDF 转换）	入账金额带符号，正数 = 消费	交易货币 / 入账货币（中文）	无	无	无	摘要开头括号里写类型
18	icbc-credit	csv	收入/支出两列	币种列	卡号、卡别名	有（负数表示欠款）	无	交易日与记账日
19	boc-credit	csv	存入/支出两列	币种列	标题里有账单年月	无	无	一份账单多张卡；Go 用记账日
20	bmo-credit	csv	带符号，正数 = 消费	无（CAD）	1 行说明 + 空行	无	无（Item # 只是序号）	卡号用单引号包住
21	bmo-debit	csv	带符号，另有 CREDIT/DEBIT 列	无	1 行说明 + 空行	无	无	表头带前导空格；描述右侧补空格
22	td	csv，无表头	取出/存入两列	无	无	有	无	日期 mm/dd/yyyy；倒序
23	hsbchk-credit	csv	带符号，另有 Credit/Debit 列	每行 Billing currency	无	无	无	金额后面带 Tab、有千分位；日期 dd/mm；有状态列
24	hsbchk-debit	csv	带符号	每行一个币种，一个文件里混多个币种	无	有（含余额币种）	无	日期 dd/mm；按币种分子账户；账户内换汇
25	htsec	xlsx	操作列（买/卖）	无（CNY）	无	有（资金、股份）	合同号、成交号	新股中签拆成两行；代码要补零；四项费用；按股东账号判断 SH/SZ
26	hxsec	扩展名 xls，实为 GBK 编码的 TSV	业务类型列	有币种列（Go 未使用）	无	有	成交编号	="…"；逆回购；ETF 份额合并；红利
27	huobi	csv，BOM	买入/卖出	交易对	无	无	无	手续费是"数字+币种"连在一起；1INCH 这类以数字开头的币
28	oklink	csv	由用户自己的地址推出	代币符号（未认证代币是合约地址）	无	无	txHash	同一 txHash 多条记录；ETH/TRON 两种表头；不含 gas
29	ibkr	xml（Flex Query）	quantity 符号 + buySell	currency；佣金有自己的币种	多个 FlexStatement（多账户）	无	tradeID、transactionID	多种资产类别；外汇交易；股息与预扣税

B. 能力矩阵

能力	需要它的账单（编号见 A）	runtime 引擎现状
读取表头前元信息（context）	14（账单年月）、12/13/18（卡号、别名）、9（币种、账号）、8（币种）、7（账号）；1/2/3（合计数，用于核对）	没有，模板只能写死
尾部停止标记	7、8、9、12、13	没有，靠 skipInvalidRows 把所有行级错误一起吞掉
按指纹自动识别格式变体	12/13、10/19、11/14、20/21、2（csv/xlsx）	没有，拆成多个 id，选错不报错
保留金额符号	全部；冲正尤其依赖（8、9）	取绝对值
值映射表	中文币种名（8、9、10、12、15、17）；类型 → 方向（16、17、26）	没有
严格日期、时区、补年份	22、23、24（日月顺序）；14（补年份）；全部（时区）	未声明格式时逐行猜；时区依赖本机
退款配对	1、2、3、4、23	没有
多行聚合	25（中签两行）、28（同一 txHash）	没有
跨行/跨文件配对	8（购汇）、24（换汇）、本人账户互转	没有，只能单文件
XML、多段表格	29	没有
证券/外汇分录、commodity 清洗	25～29	手写 beancount 文本
余额断言	5～13、18、22、24、25、26	没有
去重 ID	1、2、3、25、26、28、29	没有
由本人地址推出方向	28	只能在个人规则里写死地址

C. 已知问题清单

修复建议都只有一句，展开讨论建议各自开 issue。

C.1 Go provider（master 97a4f65）

链接前缀：https://github.com/deb-sig/double-entry-generator/blob/97a4f653347dcacfc383580ab00d78d7e8eeda8f/

级别	位置	问题	建议
P0	cib_debit/cib_debit.go#L107、#L184	整行任意单元格含"说明"就停止读取，后面的交易静默丢失（已复现）	只在首列等于"说明"时停止
P0	ccb/parse.go#L116-L164	支出列为负（冲正）时金额被置为 0（已复现）	按 收入 − 支出 计算带符号金额
P0	hsbchk/parse.go#L23、#L80	只检查 len < 5，却读取 line[5]，5 列文件直接 panic（已复现）	检查改为 < 6，或让余额币种可选
P0	huobi/parse.go#L60-L61	手续费为空时数组越界 panic（已复现）	先判空
P1	spdb_debit/spdb_debit.go#L103	整行含"合计"就停止读取	只看首列
P1	alipay/alipay.go#L82	写死跳过 22 行。deg-provider-template 里的样例账单多一行说明，master 解析失败（已复现）	按表头内容定位
P1	alipay/parse.go#L36、mt/parse.go#L29	用 float32 解析金额，1234567.89 变成 1234567.88（已复现）；mt 按字节切掉 ¥，遇到全角 ￥ 报错	改用精确小数，统一清洗货币符号
P1	jd/jd.go#L197	删掉小数点后按整数解析，50、50.5 这类金额会差 10～100 倍（京东是否导出这种金额未验证）	改用精确小数
P1	cib_debit/parse.go#L10-L20	不认识的币种一律当 CNY	用币种表映射，认不出就报错
P1	boc/parse.go#L21-L23	非人民币一律当 USD（港币被记成 USD，已复现）	同上
P1	citic/parse.go#L31-L35	币种取结算币种，金额却取交易金额，外币交易金额错误；币种也没传进 IR	用结算金额记账，原币写进 metadata
P1	icbc/convert.go#L13-L21	币种没有进 IR，美元交易被记成 CNY（已复现）	映射成 ISO 后写进 Currency
P1	analyser/citic#L70-L74、analyser/bocom_credit#L70-L74、analyser/bmo#L69-L74、analyser/td#L69-L74	只匹配 item/type，peer 不参与匹配，只写 peer 的规则会匹配全部交易；bocom_credit 一条 peer + ignore 规则丢掉整个文件（已复现）。这几家的文档示例用的都是 peer	实现该字段，或者加载时对不支持的字段报错
P1	analyser/icbc#L73-L88	只用了 peer/type/txType/status。status 依赖从未写入的 metadata，永远不命中；只写 item 的规则命中全部交易（已复现）	同上
P1	analyser/abc_debit#L43-L56	没有规则时返回 DefaultMinus/Plus，有任意规则后改用 defaultCashAccount。bmo、bocom_credit、ccb、citic、cmb、hsbchk、icbc、td 是同一写法（未逐一附行号）	不论有没有规则，都先按方向套用本账户
P1	hsbchk/config.go#L16	用的是 yaml: tag，viper/mapstructure 读不到 sep（已复现）；oklink 同理	改用 mapstructure: tag
P1	hsbchk/parse.go#L118-L120	DEBIT 一律取负；金额符号与方向列不一致时输出 --12.00（已复现）	用带符号金额，方向冲突时报错
P1	bmo/bmo.go#L57-L68	按行号区分信用卡和借记卡；没有前导说明行时丢一行，并把入账日期当成金额（已复现）	按表头内容判断
P1	ibkr/ibkr.go#L86-L87	不是 STK/CASH 的资产类别（OPT、FUT、BOND…）被静默丢弃（已复现）	告警或报错
P1	ibkr/ibkr.go#L136-L137	佣金按成交币种记账，忽略 ibCommissionCurrency；外汇交易的佣金没有入账（已复现）	佣金单独一条腿，用自己的币种
P1	compiler/beancount/template.go#L143	证券成本按单价 %.3f、数量 %.2f 输出，碎股和高精度价格不平（ibkr、huobi 已复现）；htsec、hxsec、ibkr 共用这个模板	成本写总额，保留原始精度
P1	oklink/oklink.go#L283	未认证代币的合约地址被直接当作 commodity，样例输出约 940 笔语法错误	commodity 映射或清洗，或者默认忽略
P1	oklink/oklink.go#L916	规则里的 currency 会把资产腿的币种一起改掉（已复现）	删掉该字段，或只作用于对方腿并加价格
P1	htsec/htsec.go#L80-L109	WASM 入口没有做中签两行合并，CLI 和 WASM 结果不同	抽成公共函数
P1	compiler/ledger	不处理 runtime 模板产生的 Postings，import -t ledger 输出没有账户的分录（已复现）	与 beancount 编译器共用结构化分录
P2	oklink/oklink.go#L149	解析失败的行只打日志就跳过	报错，或在汇总里计数
P2	wechat/parse.go#L15	服务费取备注里第一个两位小数，备注里有别的数字时会取错	锚定"服务费"之后的数字
P2	bocom_credit/util.go#L89	一个未知类型（例如年费）就让整个文件失败	记到 FIXME 并标记，或者补全类型

另外还有：tag 与 tags、status 与 orderStatus 并存；time 在 oklink 里表示日期区间；hxsec 首条命中即停，其他 analyser 是后命中覆盖先命中。多家文档示例里的字段或取值实际不存在（htsec、hxsec、huobi、mt、ccb 等）。

C.2 runtime 模板引擎

"master" 一列是在 97a4f65 上复现的结果。"未核对"表示只在开发中引擎上复现过。

问题	master
forceAmountDirection 把金额取绝对值，冲正方向反了	同样存在
没有规则设置 from/to 时，输出没有账户的分录	同样存在
posting 引用不存在的列，生成省略金额的腿；不做平衡校验	同样存在
import -t ledger 分录里的账户丢失	同样存在
未声明 dateFormat 时逐行猜日期格式，01/02 优先于 02/01	同样存在
日期解析失败只报 "runtime v2 rule did not set date"，不带行号和原值	同样存在
skipInvalidRows 吞掉所有行级错误；表头不一致时把首行当数据、按位置映射。icbc v1 模板 + v2 账单：退出码 0、0 笔交易	同样存在
未知方法、参数解析失败时静默丢弃，参数原样拼进结果	同样存在
条件里 ISO 日期被当作算式比较	不存在，仅开发中引擎
空 metadata 输出成 key: ""	不存在，仅开发中引擎
编译器总是输出 payee 和 narration 两段	仅开发中引擎（新行为更符合 beancount 语义，但 expected 需要重新生成）
< 运算符与 <列名> 写法冲突：amount < 100 && <x> == "a" 报错	未核对
加法让小数位膨胀（0.85000000）；format 不支持宽度和补零，失败时返回原值	未核对
金额为正时类型推断仍然返回"支出"	未核对
日期解析依赖本机时区	未核对
registry：不校验 sha256，没有缓存和超时，不检查 versions 列表	未核对
开发分支的 excelize 是 2.5.0，master 已经是 2.11.0，读到的证券代码丢前导零	开发分支问题，rebase 后应能解决

C.3 dev-v3 模板

链接前缀：https://github.com/deb-sig/deg-provider-template/blob/a00f7c1ce5bfc7b3b008d9329761d1159df4f505/

模板	问题
cmb-credit rules.yaml#L8、#L17	年份写死 2024/<记账日>，2025 年的账单被记成 2024 年（已复现）
ccb rules.yaml#L15	accountNum 写死样例值
icbc-debit-v2 rules.yaml#L12	cardName 写死样例值
mt rules.yaml#L72	starter 规则里有带个人 ID 的账户名（同文件还有两处）
bmo-、td、hsbchk-、abc_debit、htsec、hxsec、huobi 等	本人账户写死在 templateRules 里
td	缺 dateFormat，同一文件混用日/月与月/日（已复现）
hsbchk-debit	描述放进了 payee，应放 narration（verify DIFF 的原因）
icbc-*	没有设置 narration；用 skipInvalidRows 当作尾部过滤器
bocom_credit	用子串判断方向，"退货 消费退款"同时命中收入、支出两条规则，最后被记成支出（已复现）；未知类型输出没有账户的分录
citic-credit、boc-debit	照抄了 Go 的币种 bug（交易金额 + 写死 CNY；非人民币当 USD）
alipay	用 交易订单号 ~ _ 丢弃退款，部分退款和跨文件退款静默消失（已复现）；缺 options.title；skipLeadingRows: 22 换成表头定位后新旧账单都能解析
wechat	服务费拆分写在 personalRules 里，按银行复制了三份；只支持 xlsx
jd	用 .number 解析 131.77(已退款89.84) 失败（verify FAIL）；只为凑样例的 payee 规则放在了 templateRules
spdb_debit	expected 是用模板重新生成的，与 Go 输出相比丢了 tags
hxsec	sourceHeaders 用英文别名加位置映射，真实中文表头完全不校验
huobi	同币种手续费从现金账户扣，照抄了 Go 的写法；成本按单价写，bean-check 不平（已复现）
大部分模板	个人规则收入、支出各写一条（条数见 RFC 2.2）

D. 外部格式与工具参考

D.1 格式

格式	要点	参考
OFX / QFX / QBO	1.x 是 SGML，2.x 是 XML；TRNAMT 带符号；FITID 唯一；LEDGERBAL 余额；有银行把信用卡的符号导反	ofxtools、信用卡符号反转的讨论
QIF	没有币种、没有 ID；投资交易的数量永远为正，方向看动作	Wikipedia
camt.053 / MT940	金额无符号，方向由借贷标识决定；有期初、期末余额；一个文件可以有多个账户	camt.053、MT940
BAI2	按记录类型分层；方向由类型码决定；88 号是续行记录	Huntington
IBKR Flex	多个段、多个账户；佣金有自己的币种；IBKR 会新增字段，解析时宜宽松	ibflex
开放银行 API	各家符号约定相反（Plaid 正数 = 流出，SimpleFIN 正数 = 流入）；pending 与 booked 分开	Plaid、SimpleFIN、GoCardless
国内账单导出方式	多家银行只提供加密 PDF 或邮件账单；招行已出账单是 PDF	china_bean_importers、各平台账单导出方法、Beancount-Trans 文档

D.2 工具

工具	本 RFC 借鉴的地方	参考
beangulp	导入器接口分成 identify / extract；按日期窗口和金额判断重复	importer.py、similar.py
smart_importer	分类可以作为一个独立的可选步骤	repo
beancount-import	未知的一腿记 FIXME；跨数据源合并同一笔交易；复核界面	repo
hledger CSV rules	收支两列、条件规则、余额断言的声明式写法；也说明了只用"最新日期"做去重的局限	manual
ledger-autosync	每条分录带来源 ID，用于幂等导入	repo
Firefly III	给列指定角色；按外部 ID 或内容哈希去重	roles、duplicates
Actual Budget	导入的原始 payee 永远不变；规则分阶段执行	rules、importing
GnuCash	记住"文件账户 → 账本账户"的映射；导入前逐条确认	manual
BeanHub	解析和分类分成两个库；交易带 import-id，可以原地更新	blog、beanhub-extract
china_bean_importers	用白名单/黑名单避免支付 App 与银行卡流水重复记账；按卡号末四位找账户；PDF 密码	repo