跳转到内容

记录交易

一笔交易在账户之间转移金额:工资到账、付午饭钱、还信用卡账单。你可以用任意文本编辑器把交易写进账本文件,也可以在网页界面中录入。无论哪种方式,交易最终都以纯文本保存在你的文件中。

本指南使用一个小型家庭账本。完整语法见交易。

data/2024-03.zhang
2024-03-01 * "ACME Corp" "三月工资"
Assets:Bank:Checking 12,000.00 CNY
Income:Salary
  • 首行包含日期、标记、收款方和摘要。* 表示已完成的交易,! 表示还需要核对的交易。
  • 其下每一个缩进行是一条记账行:一个账户和一个金额。
  • 一笔交易的记账行在每种商品上都必须相加为零。这里 Income:Salary 没有金额,张记账会给它填上使交易平衡的金额:-12,000.00 CNY。
  • 一笔交易只能有一条记账行省略金额,而且其余记账行的合计必须只有一种商品。否则张记账无法确定该填什么:它会报告错误,并把这笔交易排除在账本之外。
  • 金额可以用 , 或 _ 分隔数位,也可以使用简单的算术:-(2 * 420) CNY 即 -840 CNY。

标记后只有一个字符串时,这个字符串是摘要:

2024-03-10 ! "打车"
Assets:Cash -35 CNY
Expenses:Travel 35 CNY

交易用到的每个账户都必须先用 open 开设。每种商品都必须用 commodity 声明,主货币除外。

2024-03-09 * "酒店" "杭州两晚" #trip-hangzhou ^booking-8812
invoice: "INV-2024-0309"
Liabilities:CreditCard -840 CNY
Expenses:Travel
receipt: "hotel.pdf"
  • 标签(#trip-hangzhou)按主题归组交易,例如一次旅行或一个项目。链接(^booking-8812)把同一件事的多笔交易联系在一起,例如一笔预订和它的退款。标签和链接写在摘要之后,顺序不限。
  • 元数据行是 key: value 形式的键值对。紧跟在首行下面的行属于交易(invoice)。缩进比记账行更深的行属于该记账行(receipt)。
  • 在流水页面中,选中一个标签或链接即可按它筛选流水。
  • 在查询中,'trip-hangzhou' IN tags 选出带该标签的记账行,entry_meta('invoice') 读取交易的元数据,meta('receipt') 读取记账行的元数据。
  • document 元数据会把一个文件附加到交易上。见文档。

张记账账本中的日期可以带上一天中的时间,写作 HH:MM 或 HH:MM:SS:

2024-03-02 12:30 * "面馆" "午餐" #work
Liabilities:CreditCard -48 CNY
Expenses:Food 48 CNY
  • 时间使用账本的时区,即 timezone 选项。它默认是运行张记账的机器的时区。
  • 条目按日期和时间排序。没有时间的条目视为当天的开始(00:00:00)。日期和时间相同的条目保持它们在文件中的顺序。
  • 时间对余额断言最重要,余额断言检查的是它所标注时刻的余额。
  • Beancount 的日期没有时间。在 Beancount 账本中,张记账把 time: "12:30:00" 元数据读作时间,写入时也用这种方式记录时间。

账本变大后,可以把账户和每个时期的交易分别放在单独的文件中,再在主文件中用 include 引入它们:

main.zhang
option "title" "Household"
option "operating_currency" "CNY"
include "accounts.zhang"
include "data/*.zhang"
  • 相对路径相对于引入它的文件。
  • * 只在一个目录内匹配:data/*.zhang 读取直接位于 data/ 中的所有 .zhang 文件,但不读取 data/2024/ 中的文件。模式的限制见 include。
  • 主文件的扩展名决定账本中每个文件的语法:main.zhang 使用张记账语法,main.bean 使用 Beancount 语法。

选择侧边栏顶部的新建交易,然后填写:

  • 日期:选择哪一天。新交易会带上当前的时间。日期和时间都是账本的,即账本 timezone 时区的时间,与浏览器的时区无关:编辑交易时不改日期,时间就保持不变。
  • 收款方和摘要。
  • 分录:每条记账行的账户和金额,金额写作“金额 货币”的形式,例如 -28 CNY,读法与账本文件相同:1,000 CNY 和 (10 + 2) / 4 USD 也可以;只写数字时,货币为运营货币。留空一个金额,张记账会自动填上。
  • 分录详情(点开记账行的详情按钮):它的成本和价格,写法与账本文件相同(成本如 {150 USD}、{{1500 USD}} 或 {},价格如 @ 6 USD 或 @@ 60 USD,见批次与成本基础),行尾的注释,以及它的元数据。
  • 元数据:交易的键值对。

输入时,张记账会按保存后账本检查交易的方式检查它,并在表单中显示结果:

  • 预览显示将写入文件的文本。
  • 张记账读不懂的字段(例如成本缺少花括号)会标出原因;修正之前无法保存这笔交易。
  • 如果分录不平衡,记账行下方会显示相差多少。每条记账行按账本的方式计算权重,即按成本或价格折算,并按各货币的精度舍入。因此 10 AAPL {150 USD} 与 -1500 USD 是平衡的。
  • 表单还会列出账本会报告的其他错误,例如账户在交易日期已关闭,或卖出时没有可卖的批次。这样的交易仍可保存,就像你可以把它写进文件一样。

表单中没有标签和链接的字段。需要这些时,请在文件中编写交易,例如使用编辑页面在浏览器中编辑账本文件。

要修改一笔交易,在流水页面中打开该行的菜单,选择编辑。张记账会把修改后的交易写回原处,即它所在的文件。它根据表单重写整笔交易:每条记账行的成本、价格、注释、元数据和标记都会保留,未写金额的记账行也保持原样;只有原文的排版和记账行之间(或首行末尾)的注释行不会保留;当编辑会丢弃这类注释行时,张记账会先请你确认。插件生成的交易不能编辑:它不在账本的任何文件中,编辑会被拒绝,不会写入任何内容。

API 也是如此:PUT /api/transactions/{id} 为每条记账行接受同样写法的 cost、price 和 comment;省略这些字段时保留该记账行原有的值,传 null 则删除。请求中的 datetime 是账本时区的墙上时间,不带时区偏移("2024-01-02T07:00:00"),与所有响应一致;带偏移或 Z 的时间点仍可读取,按它在账本时区的墙上时间处理。记账行的 unit 可以是对象 {"number": "-28", "commodity": "CNY"},也可以是金额的文本,例如 "-28 CNY",读法与表单相同。POST /api/transactions/preview 和 POST /api/transactions/{id}/preview 接受与创建、更新相同的请求体,返回表单的检查结果,不写入任何内容:

  • text:将写入的文本。
  • field_errors:创建或更新会拒绝的每个字段:所属记账行和字段、kind(如 invalid_amount 或 beancount_commodity)及其涉及的 value,以及 400 响应的消息。
  • unbalanced:交易相差多少。
  • errors:账本会报告的错误。

张记账把你在网页界面中记录的内容追加到一个文件中,这个文件由条目的日期和 directive_output_path 选项决定。默认值是 data/{{year}}/{{month_str}}.{{ext}},其中 ext 是主文件的扩展名。记在 2024 年 4 月 3 日的一杯咖啡会写入 data/2024/04.zhang:

data/2024/04.zhang
2024-04-03 13:15:00 * "Coffee Lab" "澳白"
Assets:Cash -28 CNY
Expenses:Food
  • 如果账本还没有读取这个文件,张记账还会在主文件末尾加上 include "data/2024/04.zhang"。
  • 网页界面新增的其他条目也都写到同一个位置:在账户页面或用批量对账工具写入的余额断言,以及上传到账户的文档。
  • 换一个模板就能改变文件布局。option "directive_output_path" "data/{{year}}.{{ext}}" 每年一个文件。模板可以使用 year、month、month_str、day、day_str、type(条目的种类)和 ext。
  • 在 Beancount 账本中,文件使用主文件的扩展名,例如 .bean,并以 Beancount 语法写入,一天中的时间记在 time 元数据中。

张记账每次加载账本时都会检查它。

  • 条目中的问题会进入账本的错误列表。侧边栏中的总览项显示问题的数量,总览页面列出这些问题:选中一个即可查看它所涉及的条目,并在编辑页中打开它所在的文件、定位到那一行。常见的问题有交易不平衡、账户未开设和商品未声明。错误码逐一解释了每种错误。
    • 不平衡的交易仍留在账本中,在流水中标记为不平衡。
    • 无法补全缺失金额的交易,例如有两条记账行都没有金额,在你修正之前会被排除在账本之外。
  • 语法错误会让整个账本无法加载。张记账启动时遇到语法错误会退出,并给出错误以及发现它的文件、行和列。张记账运行期间出现语法错误时,它会继续提供最后一次成功加载的版本,只在日志中记录错误:网页界面不显示错误。如果你的修改没有出现,请查看终端或 docker logs。

对于本地磁盘上的账本,zhang serve 会监视账本目录,在账本的某个文件变化时重新加载,因此你在文本编辑器中的修改一两秒内就会出现:哪些变化会触发重新加载,见本地文件系统。在网页界面中记录内容,或在编辑页面中保存文件,也会重新加载账本。

重新加载账本按钮,即侧边栏中账本标题旁的圆形箭头,可以随时重新加载账本。账本存放在 S3、WebDAV 或 GitHub 上时请使用它:在这些地方,张记账不会察觉其他程序所做的修改。