Aurelio 个人理财 App 核心数据模型解析:锚点+事件规则,为什么财富不是流水余额(dated.py 完整源码解读)

原创2026-11-02 11:26:191,923 阅读

Aurelio 个人理财 App 核心数据模型解析:锚点+事件规则,为什么财富不是流水余额(dated.py 完整源码解读)

Aurelio 是一款开源的个人理财应用(personal finance app),它在你自己的电脑上追踪净资产、投资、ETF、现金和负债,并提供 AI 财务顾问。本文将解读它最核心的一个模块 backend/app/dated.py——一条名为"锚点 + 事件"(anchor + events)的规则,回答了这个问题:为什么财富的账面数字,不能靠流水余额累加得出?

Aurelio 个人理财应用界面:净资产构成、基金国家分布与 AI 财务建议

为什么"流水余额"这种算法靠不住?

先想一个场景:你在 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)则逐日调用这套投影,每个历史点都用当天的汇率转换,绝不用今天的汇率重述过去——这是同一条"照片只描述它自己那天"的哲学。

对新手用户意味着什么?

这条规则的价值最终落在体验上:

  1. 错误可追溯:一个错误数字,要么来自一张错误的照片,要么来自一条错误的事件,没有第三种可能(见 how-aurelio-reasons.md)。
  2. 你只需"拍照",不用维护余额:定期更新快照和现金锚点,中间的现金增减由收入、支出、转账和投资流水自动推演。
  3. 历史可回放:任何日期的净资产、现金、持仓都能按"那天生效的照片 + 那天之后发生的事"复现,且每个数字都带着它的来源日期。

如果你想亲自验证,完整推理规则文档在 docs/how-aurelio-reasons.md,核心模块在 backend/app/dated.py(含详细模块注释),配套测试在 backend/tests/test_dated.py。

小结

Aurelio 的数据模型可以用一句话概括:财富 = 锚点照片 + 严格发生在照片之后的事件。dated.py 把这条曾经散落 11 处的规则收敛成 4 个强制带日期的命名操作,用"必填参数"把错误问题变成编译期错误,用左开右闭区间杜绝重复计数。对于任何想自建理财工具的人,这都是一个值得抄作业的范本:先定义清楚"状态"和"事件"的边界,比多写十张余额表更重要。

登录后查看全文
aurelio-finance