Aurelio 个人理财 App 核心数据模型解析:锚点+事件规则,为什么财富不是流水余额(dated.py 完整源码解读)
Aurelio 个人理财 App 核心数据模型解析:锚点+事件规则,为什么财富不是流水余额(dated.py 完整源码解读)
Aurelio 是一款开源的个人理财应用(personal finance app),它在你自己的电脑上追踪净资产、投资、ETF、现金和负债,并提供 AI 财务顾问。本文将解读它最核心的一个模块 backend/app/dated.py——一条名为"锚点 + 事件"(anchor + events)的规则,回答了这个问题:为什么财富的账面数字,不能靠流水余额累加得出?
为什么"流水余额"这种算法靠不住?
先想一个场景:你在 3 月 1 日拍了一张"持仓照片"(记录当天所有持仓),之后陆续买入、卖出、转入、转出。要算"今天"的财富,最直觉的做法是把所有流水从头加一遍。但 Aurelio 的设计者发现,财富本质上不是一条流水余额:
- 流水(买入/卖出/转账/分红)只记录"发生了什么",它本身无法回答"我现在持有什么";
- 一旦某条流水记错,所有后续余额全部跟着错,而且你无法定位错误发生在哪一步;
- 手动维护一个"总余额"字段,意味着这个数字必须被无条件信任。
Aurelio 在 docs/how-aurelio-reasons.md 里把这条核心思想写得非常直白:
Wealth is not a running balance.(财富不是一条运行中的余额。)
它的替代方案只有一句话:某日状态 = 最新一张照片(锚点) + 严格发生在照片之后的事件。
anchor(一张带日期的照片)
+
events dated after the anchor(锚点之后的事件:流水、转账)
=
today
新拍一张照片(锚点前移),计算自动"重新基准化",重复计数从机制上被杜绝。这也是为什么 Aurelio 的每个机构(银行/券商)下都有带日期的 snapshots(快照/情况),以及独立的 cash_anchors 现金锚点表。
五个命名操作:dated.py 的全部家底
dated.py 的模块注释(L1-L33)交代了它的诞生背景:在同一条规则存在期间,"锚点+事件"曾经被手写复制了 11 次——7 份"取每个父级最新一条"的重复代码,外加 5 种对"严格在锚点之后"这个条件的不同写法(两个半开区间、两个无右边界、一个只是变量名不同)。任何一份写错了,都不会有任何东西报警。
这个模块把它们收敛成 4 个命名操作 + 1 个辅助函数,每个都强制要求"在哪一天问的"这个日期参数:
| 函数 | 回答的问题 | 关键约束 |
|---|---|---|
today() |
"今天"的唯一写法 | L46-L56,让"指代今天"的调用方可以被整体检索到 |
latest_per_parent |
每个父级在某一日期生效中的那条记录(锚点照片) | on_or_before 参数必填 |
latest_on_or_before |
在某日生效中的那条记录(锚点本身) | 日期含当天:今天拍的照片描述今天 |
carry_forward |
跨父级求和"生效中"的值 | 用于房产估值、负债余额等 |
events_after |
锚点没有算进去的事件 | 区间左开右闭:(anchor, until] |
其中最关键的设计是:"生效中"(in force)和"最新存在"(latest there is)是两个不同的问题。历史上有人问的是前一个却问了后一个,结果一张日期为未来 11 天的照片成了 App 对"今天"的回答,空照片则把整个投资组合清零。现在 on_or_before 是必填参数,错误问题在语法层面就写不出来了(L96-L98):
def latest_per_parent(
db: Session, model: type[T], parent_col: Any, *, on_or_before: str
) -> dict[Any, T]:
stmt = (
select(model)
.where(model.date <= on_or_before)
.order_by(parent_col, model.date)
)
一条 SQL 回答所有父级,也顺带消灭了原来"逐父级查询"造成的 N+1 问题。
核心规则:events_after 的左开右闭
events_after 是整个 App 的中枢不变量(L180-L213),返回的区间是左开右闭 (anchor, until],两个边界都"用 bug 换来的":
- 严格在锚点之后(左边开):1 月 1 日拍的照片已经包含当天发生的一切,如果 1 月 1 日的买入还被叠加一次,同一笔钱就被算了两次。所有投影(现金和持仓)都是
anchor + events_after(anchor)的形式。 - 包含
until当天(右边闭):某个日期的曲线点必须展示"那一天结束时"的样子——当天发生的卖出,到日终时已经发生。
真正想要相反规则的唯一场景是分红计算(需要除息日之前严格持有的份额),它被留在 pac.py 里单独以带文档的 replay(..., until=...) 表达,而不是在这里塞一个没人读得懂的 flag。
测试文件 backend/tests/test_dated.py 把这条规则固化成断言,而不是注释:
def test_the_anchors_own_date_is_already_in_the_photograph():
anchor = _Rec("2026-03-01", "anchor")
assert [r.tag for r in dated.events_after(anchor, ROWS)] == ["c"]
规则如何落地:现金与持仓的投影
这条规则不是抽象的。现金账户的投影在 analytics.py 中:
anchor = dated.latest_on_or_before(inst.cash_anchors, as_of_iso)
...
moved = dated.events_after(anchor, transfers, until=as_of_iso)
for t in dated.events_after(anchor, ledger, until=as_of_iso):
...
projected = anchor + income − expenses + transfers_in − transfers_out
− buys + sells
这就是 CashAnchor 模型注释里说的"对账"效果:新加一个锚点 = 重新基准化,只有严格晚于锚点日期的事件才会被叠加,同一笔钱不可能被数两次。
投资组合的投影在 positions.py:先 latest_per_parent_of 取每个机构在截止日生效的快照,再对每只持仓用 events_after 找出照片之后的买入/卖出/分红,把"照片里的存量 + 账本里的变动"合并成一个带成本、盈亏、分红的完整持仓视图。净资产曲线(analytics.py)则逐日调用这套投影,每个历史点都用当天的汇率转换,绝不用今天的汇率重述过去——这是同一条"照片只描述它自己那天"的哲学。
对新手用户意味着什么?
这条规则的价值最终落在体验上:
- 错误可追溯:一个错误数字,要么来自一张错误的照片,要么来自一条错误的事件,没有第三种可能(见 how-aurelio-reasons.md)。
- 你只需"拍照",不用维护余额:定期更新快照和现金锚点,中间的现金增减由收入、支出、转账和投资流水自动推演。
- 历史可回放:任何日期的净资产、现金、持仓都能按"那天生效的照片 + 那天之后发生的事"复现,且每个数字都带着它的来源日期。
如果你想亲自验证,完整推理规则文档在 docs/how-aurelio-reasons.md,核心模块在 backend/app/dated.py(含详细模块注释),配套测试在 backend/tests/test_dated.py。
小结
Aurelio 的数据模型可以用一句话概括:财富 = 锚点照片 + 严格发生在照片之后的事件。dated.py 把这条曾经散落 11 处的规则收敛成 4 个强制带日期的命名操作,用"必填参数"把错误问题变成编译期错误,用左开右闭区间杜绝重复计数。对于任何想自建理财工具的人,这都是一个值得抄作业的范本:先定义清楚"状态"和"事件"的边界,比多写十张余额表更重要。
