# 现金流角色：在 Beancount.io 中为账户分类

在账户的 `open` 指令中添加 `cash-flow-role` 元数据，以声明现金流量报告如何对该账户进行分类。一个键，四个值。没有该元数据的账户保持默认启发式规则。

```beancount
2000-01-01 open Assets:US:Brokerage
  cash-flow-role: "investing"

2000-01-01 open Assets:US:Marcus:Savings
  cash-flow-role: "cash"
```

## 键和值

| 键 | 位置 | 值类型 | 可接受值 |
| --- | --- | --- | --- |
| `cash-flow-role` | `open` 指令元数据 | 字符串 | `"cash"`、`"operating"`、`"investing"`、`"financing"` |

匹配区分大小写且要求完全一致。值必须是带引号的字符串。同一指令上的其他元数据键会被报告忽略，而这个键会被所有其他工具忽略。

## 每个值的作用

声明的角色同时回答两个问题：该账户是否属于现金池的一部分，以及如果不属于，它应归入哪个活动部分。

- `"cash"` — 该账户加入现金及现金等价物集合。现金账户永远不会作为活动行项目出现。报表的底线，即现金及现金等价物的净变动，等于它们期间变动的总和。两个现金账户之间的转账会相互抵消。用于名称启发式规则无法识别的账户，例如货币市场基金或稳定币钱包。
- `"operating"`、`"investing"`、`"financing"` — 该账户不属于现金，其期间变动作为该活动部分下的一个行项目出现。在名称启发式规则会视为现金的账户（如 `Assets:US:Bank:CD`）上声明其中一个值，既将其从现金集合中移除，又将其归入所声明的部分。

声明优先于会计惯例。一个 Equity 账户声明为 `"operating"` 会被原样采纳。

## 优先级

最高优先级生效：

1. 账户 `open` 指令上的 `cash-flow-role` 元数据。
2. 下面的内置默认启发式规则。

## 默认分类

没有声明角色的账户按其根账户分类，并通过名称检查决定是否属于现金：

| 账户根 | 默认活动 |
| --- | --- |
| `Income`、`Expenses` | 经营活动 |
| `Assets`（非现金） | 投资活动 |
| `Liabilities`、`Equity` | 筹资活动 |

名称中包含 `Cash`、`Checking`、`Savings` 或 `Bank` 的资产账户默认视为现金及现金等价物。声明的角色在两个方向上都会覆盖名称检查。

## 无效值

无法识别的值视为不存在。诸如 `"invsting"` 的拼写错误、非字符串值或错误的大小写会回退到默认启发式规则，报告会在状态面板中标记该账户并附上未知值说明。不会导致任何渲染失败，也不会被静默接受。

## 更改分类

分类不具有日期效力。任何期间的报表都使用当前的声明。要更改分类，编辑 `open` 指令即可；账本系统的版本控制会记录更改内容和时间。

## 声明的适用范围

一个共享的解析器为每个账户产生最终角色，所有消费方都从中读取：

- 现金流量报告：活动部分、现金及现金等价物集合以及底线对账。
- CSV、Markdown 和打印导出：相同的数字。只有仍由启发式规则解析的行才会出现分类为推断的披露说明。
- 概览现金流量图：`"cash"` 将账户从流量节点中排除，声明的活动角色对非 Income 账户生效。Income 保持为来源方，Equity 保持排除在图表之外；声明永远不会重新映射这两个账户。
- 账户状态面板：已声明的账户不再显示为未分类资产。

## 可移植性

`open` 指令上的元数据是 Beancount 核心语法。`bea check`、Fava 以及所有 v2/v3 工具都能解析它并忽略未知键，因此账本在 Beancount.io 之外仍然完全可用。有关通用元数据格式，请参见 [Beancount 语法](https://beancount.io/zh/docs/Basics/syntax)。
