Aurelio 基金穿透与 ETF 累积/分配全解析:ETF 重叠、组合 X 光与红利记账的源码级实现
Aurelio 基金穿透与 ETF 累积/分配全解析:ETF 重叠、组合 X 光与红利记账的源码级实现
本篇围绕 Aurelio 的「ETFs and funds」主题展开:一边讲清 ETF 重叠(ETF overlap)与组合 X 光(look-through)如何从发行人的原始持仓文件出发,按你今天的真实市值加权,算出国家、行业、货币、公司与重叠敞口;另一边讲清累积型(Acc)与分配型(Dist)ETF 的差别,以及 Aurelio 如何把红利记进你的账本。读完后你可以独立完成两件事:判断自己持有的多只基金是否在同一批公司上重复下注,以及正确设置一只基金的分配政策、读懂 App 记下的那笔红利为什么是"毛额、估算、日期在除息日"。
一个篮子的两面
原始文档只有一句核心判断:基金是一个篮子,两个名字不同的篮子可以装着同样的东西。这句话拆成两个工程问题:
- 篮子里到底有什么,以及两个篮子之间重复了多少 —— 对应 ETF overlap and portfolio X-ray;
- 篮子把赚到的东西怎么处理 —— 对应 Accumulating vs distributing ETFs。
在仓库里,这两件事分别落在 composition.py(穿透与重叠)、issuers.py(发行人持仓文件适配)、catalogue.py(基金身份注册表与「双胞胎」归并)、pac.py(红利捕捉与记账)与 dividend_pairs.py(手工流水与系统红利的配对)中。下面按这两个问题逐层展开。
一、怎么检查 ETF 重叠:为什么看「前十大」不够
原文给出的快速办法是比两只基金的前十大持仓,但它天生低估:某只基金里排第 11 的公司,在另一只基金里可能排第 3,两边的前十大都看不到它。完备的做法需要三件事:
- 每只基金的每一个持仓,而不只是前十大;
- 每只基金按你今天实际持有的市值加权;
- 同一家公司在两份文件里写法略有差异时,要能被识别成同一家。
Aurelio 对能从发行人原始文件读到的基金(iShares 基金,以及已知的 Vanguard 基金)把这三件事都做全,并在只能拿到前十大时明确说出来,而不是假装完整。
数据来源的服务瀑布
一只基金的构成按「谁回答了就用谁」的顺序获取,这条瀑布写在 composition.py 的 _resolve_and_fetch 里:
| 顺序 | 来源 | 覆盖范围 | 深度 |
|---|---|---|---|
| 1 | 发行人自己的文件(issuers.py) | Aurelio 知道如何解析的 iShares / Vanguard 基金 | iShares 每日刷新、每一条持仓,含国家与行业;Vanguard 月末数据(约滞后三周)、4000+ 行 |
| 2 | justETF | 发行人文件未覆盖的 UCITS 基金 | 国家、行业与前十大持仓 |
| 3 | Trackinsight | 无 ISIN、只有 ticker 时 | 国家、行业、前 25 条(TRACKINSIGHT_TOP_HOLDINGS)与真实持仓数量 |
| 4 | Yahoo Finance | 兜底 | 只有行业与前十大,没有国家轴 |
源码里对这个顺序有两处明确注释,值得记住:
- 发行人优先是因为「公布的前十大既浅又有时是错的」。仓库记录了一个具体案例:检查时,justETF 给 iShares Edge MSCI World Min Volatility 的前十大里列了 NVIDIA,而 iShares 自己的文件把 NVIDIA 排在第 12、把 Microsoft 排在第 7。任何建立在前十大之上的东西——尤其是基金之间的重叠——都会继承这类错误(见 issuers.py)。
- Morningstar(
mstarpy)已从这条路径上移除:自 v10 起它通过打开真实浏览器窗口来建立会话,在本地桌面应用里点一次"更新"就会弹出一个 morningstar.com 页面。现在这条路径上全是普通 HTTP 调用。
ISIN 才是解锁最佳来源的钥匙
原文强调:ticker 只是让一只持仓在某一个交易所被定价,ISIN 才识别基金本身,无论它在哪儿交易。代码里这两件事被刻意分成两个字段,而不是让一个字段兼职(composition.py):
_lookup_key(p):有 ticker 就用 ticker,没有就退回 ISIN(composition.py);_resolve_isin(ticker, errors):先用 justETF 的整表目录(约 4500 只 UCITS 基金,内存缓存 24 小时),再用 Trackinsight 的免费 JSON;两者都查不到时,把一句可执行的补救话术写进错误列表:"No ISIN found for 'XXX'. Add the fund's ISIN to this holding to unlock the country breakdown."(composition.py)。
这条错误文案会一路存进缓存、被前端读出来展示,因此「X 光打不开一只基金」时,操作路径非常明确:在 Records → Wealth 里给这只持仓补上 ISIN。
缓存 15 天,但绝不因刷新而变差
- 完整结果缓存 15 天(
CACHE_TTL_DAYS);缺少国家轴的降级结果只缓存 1 天(PARTIAL_TTL_DAYS)。理由写在注释里:一次瞬时失败不该把「没有国家分布」的降级视图冻住两周(composition.py)。 _ttl_for(row)直接读数据里有没有countries来决定给哪个 TTL —— 缓存策略不需要额外的字段(composition.py)。- 刷新永不把条目变得更差:
_poorer()判定两种情况为"更差"——从「列出全部持仓的来源」(_COMPLETE_HOLDINGS = {"issuer", "equity"})掉到「只公布摘要的来源」,或者丢掉了缓存里已有的国家/行业轴。此时保留旧条目、把拒绝时间写进refused_at,下一次尝试至少等 1 天(composition.py、#L465-L479)。 - 在同一个来源类别内部,刷新总是替换缓存:发行人几周后确实可能少列几十行,那是真实更新,用条数去拒绝它反而是错的。
界面上对应的是 Portfolio 页「↻ Update composition」按钮,它走 GET /api/dashboard/portfolio/composition?refresh=true(dashboard.py、composition.ts,前端为首次穿透把超时设到 120 秒)。
二、组合 X 光到底加总了什么
权重按今天的市值,不按成本
_aggregate 里权重只有一行:
total_value = sum(p.current_value for p in held) or 1.0
weight = p.current_value / total_value
注释把理由说得很直接:一只翻了三倍的基金,携带的敞口是买入时的三倍;按成本加权会把真实风险报成三分之一(composition.py)。返回字段里的 total_value 曾经叫 total_book,改名正是为了避免「名字说成本、数字是市值」这种误读。
五个轴与一个矩阵
Portfolio 页「Look-through (real exposure)」展示的内容,全部来自 _aggregate 的返回值:
- Countries / Sectors:把每只基金的国家、行业占比乘以该基金的组合权重后累加,小于 0.01% 的行被过滤掉(
_ranked)。 - Currency exposure:不额外请求数据,而是由国家的权重推导——
geo.currency_of(country)给出一个国家通常计价用的货币,未知国家返回Other而不是猜(geo.py)。美元份额的基金如果持有大量美国公司,就会被正确地读成美元敞口。 - Issuers(公司轴):每一条被判定为「股票」的持仓,按公司名归并后乘以权重累加,得到单一公司在整个组合中的占比。
- Asset class × region 矩阵:
matrix<a href="https://link.gitcode.com/i/fbee28b0cf7c09d2e338450b307e50fa" target="_blank">(asset_class, geo.region_of(country))]累加,区域被设计成最多 5 个桶以保证可读([geo.py)。 - Overlap:同一家公司在两只及以上不同基金中出现,并列出是哪几只基金。
Overlap 的过滤条件有一个关键细节:len(e<a href="https://link.gitcode.com/i/6dacbf0699fa91c6ca4fccf71b37e7ac" target="_blank">"fund_ids"]) >= 2,比的是基金而不是持仓。否则「同一只基金在两个账户里各记一笔」会和它自己重叠,逐公司地刷满整个列表([composition.py)。这种情况不会被静默合并,而是由 _held_more_than_once 生成一句人话提问:"…is held as two positions: …. The same fund in two places, or one purchase entered twice?"(composition.py)——两个账户和重复录入在这里长得一模一样,只有你本人知道是哪种。
名字匹配:SAP SE 与 SAP 是一家,Alphabet A 与 C 不是
_company_key 的做法是:转大写、去掉标点、丢掉法人后缀(INC, CORP, PLC, LTD, LLC, SA, AG, NV, SE, AB, ASA, OYJ, SPA 等),再拼回去(composition.py)。注释里写了两件事:
- iShares 写 "NVIDIA CORP"、Vanguard 写 "NVIDIA Corp",原始字符串匹配会把它们当成两家公司——这正是组合里最大的一笔共同持仓从重叠列表里消失的原因;
- 股份类别被刻意不合并:Alphabet A 与 C 是两行,读者应该看到它们各自的位置(测试 test_composition.py 把这条规则固定下来)。
- 还有一条不显然但很实际的规则:
REGS被当作法人后缀处理。债券 ETF 会把 "Italy (Republic Of)" 和 "Italy (Republic Of) Regs" 列成两条——同一发行人按两种法规发行,在「一个名字占组合多少」这个轴上它们是同一个名字。
国家名的归一化同理放在 geo.py 的 canonical_country:"SK"、"Slovak Republic"、"Slovakia" 归成一个国家,未知值原样透传而不是塞进 Other。行业名则归到 GICS 口径(_canonical_sector,composition.py),否则 Yahoo 的 "Technology 13.6%" 和发行人的 "Information Technology 12.8%" 会被读成两个行业——「同一个错误在高一层重演」。未知标签原样保留,因为债券基金里的 "Treasury" 是真实类别,不是拼错的股票行业。
一条线是股票还是债券
债券基金会把发行人的债券列在发行人名字下。如果只按名字归并,某公司的债券(在债基里)和它的股票(在股基里)会被读成「同一只股票被持有两次」。所以发行人文件里的 assetClass 被保留为 kind,_a_share() 只让 Equity 或未说明类型的行进入公司轴与重叠轴;债券、现金、期货仍计入国家与行业(composition.py、issuers.py)。
直接持有的股票:它自己就是 100% 的自己
直接持有的一只股票没有持仓文件,也永远不会有——但它不需要:一股 Apple 就是 100% 美国、100% 科技。_resolve_and_fetch 会在假设"这是个基金"之前先问「这是什么」:如果 Yahoo 的 quoteType == "EQUITY",就直接解析成单一国家、单一行业、单一持仓(source: "equity",holdings_count: 1)。这也让直接持股与基金内部的同名公司能在 Issuers / Overlap 那一行相遇(composition.py、#L547-L577)。在 demo 数据里,直接持有的 SAP 与 MSCI World 基金里的 SAP 就是这样汇到一行的。
对一家连国家、行业都拿不到的公司,SHARE_WITH_NO_PLACE 会把它作为"一只没有归属地的股票"说出来,而不是套用基金来源那句「去补 ISIN」的补救——对股票来说,那个补救根本不成立(composition.py、test_a_share_is_never_told_to_add_a_funds_isin.py)。
三、它看不到什么(诚实的边界)
原文的四条限制在代码里都有对应机制,值得逐条对照:
- 币,以及没有 ticker 也没有 ISIN 的持仓:没有任何东西可以打开,于是整块保留,
undecomposed_pct与coverage_pct明确说出穿透实际覆盖了组合的百分之多少。 - 只有前十大时的"下限重叠":
_aggregate会检查同一份结果里是否同时存在「全量来源」和「摘要来源」的基金,只在真的同时存在时追加一句提示:Overlap is a floor: … contributed only the top holdings their source publishes, … every position held.注释解释了为什么不是常驻提示:一直挂在屏幕上的警告最终没人读(composition.py,测试 test_composition.py)。 - 公司在哪儿赚钱:货币敞口跟随公司所属国家,不看收入来源;也不处理对冲——一只欧元对冲份额仍然显示其持仓本身的货币(schemas.py 的字段说明同样写明了这条限制)。
- 空轴必须有解释:如果确实分解成功、但国家轴是空的(只有行业来源回答过),会生成一条 note 并附上各来源的拒绝原因,因为「一张空图没有解释」会被读成「你在那些地方什么都没有」(composition.py)。
还有一条容易忽略的健壮性规则:Undecomposable(无人能分解,如加密货币、极少数上市品种)是一个答案而不是一次失败,它会被缓存,并把每个来源的拒绝理由一起存下来。注释给出了实测代价:一个加密持仓曾让一次本应 0.00 秒/标的的穿透花掉 12.56 秒(composition.py、#L502-L537)。只有确认市场可达(prices.market_reachable())时才把「没人能回答」写进缓存,避免一次网络抖动被记成标的的永久属性。
四、买之前:同一套 X 光向前推演
原文提到「同一个 X 光能在买入前回答问题」。对应实现是 weigh_purchase 与 weigh_change(composition.py):
- 把拟买入的金额构造成一个「被考虑的持仓」(
_Considered),与现有持仓一起跑一遍_aggregate,得到买入后的读法; - 输出
Moves:国家、行业、货币、公司四个轴上变化最大的 5 个名字(MOVES = 5),每项同时给出before_pct与after_pct; - 输出
already_held_through_other_positions:这只新基金里、你已经通过其他持仓持有的公司,以及是通过哪些持仓持有的; - 输出
coverage_before_pct/coverage_after_pct:穿透实际能看进去的比例,买之前和买之后; - 一只无法被穿透的标的(商品、币)会被照实称重并标注
looked_inside: false与why_not,而不是给出一个只因为它变大就整体缩小各轴的假图。
weigh_change 在此之上支持「卖出一部分」(Sale),并会明确拒绝超额卖出或不存在的持仓(ValueError / LookupError);如果同一只基金在两个账户里各有一笔,卖出从较大的那一笔扣,并在结果里说明是哪一笔。
五、累积 vs 分配:只差一件事
| 累积(Accumulating) | 分配(Distributing) | |
|---|---|---|
| 分红去向 | 在基金内部再投资 | 打进你的账户 |
| 你的现金 | 不动 | 每次派息后增加 |
| 份额价格 | 包含再投资的股息 | 除息日大约下跌相当于股息的幅度 |
| 再投资 | 基金自动完成 | 由你操作,并承担券商费用 |
| 适合谁 | 还在积累、暂时不需要这笔现金流 | 靠收益生活,或不卖份额也要拿到现金 |
两者没有普遍意义上的优劣,取决于三件事:你现在是否需要这笔收入;你所在国家如何对两者征税(很多国家在派息当年就征,累积型的再投资收入可能只在卖出时征,但也有一些国家每年对累积型的收入征税);以及每次再投资的手续费和精力成本。
切
换版本只能卖出一只再买入另一只——它是一次普通卖出,可能产生税,也要付两笔交易费。
双胞胎在 Aurelio 里始终并列
大多数大型 ETF 都有两个版本。基金选择器里,累积型与分配型总是成对出现,因为它们名字相同、只在分红处理上不同;只显示其中一个,等于让人在不知道存在选项的情况下做选择。
实现上,catalogue.py 用一个 family_key 把「同名但只差分红政策」的两行归到一起:
_TWIN_MARKERS = re.compile(
r"\b(acc|accumulating|dist|distributing|inc|income|thesaurierend|ausschüttend)\b",
re.IGNORECASE,
)
family_key(name) 只剥掉这些标记与标点,其余原样保留。于是 iShares Core MSCI World UCITS ETF USD (Acc) 与 (Dist) 得到同一个 key,而 ... Small Cap UCITS ETF USD 不会被卷进来(测试 test_catalogue.py 两个方向都验证了)。
注册表里的统计也是可复算的事实:某个刷新版本中 4,544 行里有 1,124 行与同族兄弟共享名字、分布在 560 个 family 中,而源码把产出这个数字的 SQL 查询一并写在注释里——数字会随每次刷新变化,查询不会。
search() 返回的是 families 而不是 rows,_families() 按 family_key 取出全部成员并排序(ORDER BY distribution_policy IS NULL, distribution_policy, name),因此接口层面就不可能只返回一只(catalogue.py);测试 test_the_twins_always_travel_together 直接断言返回的两个成员的政策是 <a href="https://link.gitcode.com/i/0ce6948518acf013f7b4f75c0230fba5" target="_blank">"acc", "dist"]([test_catalogue.py)。前端 InstrumentPicker.tsx 遍历 f.members 逐行渲染,并显示每只的 policy。
顺带一个容易踩的坑:注册表知道的是身份(ISIN、全名、acc/dist),不是报价。它下发的 share_class_currency 对 VWCE 说是 USD,而 VWCE 在米兰以 EUR 报价;base_ticker 也不是 Yahoo 代码。所以一次选择只填名字、ISIN 和政策,不碰 symbol(catalogue.py)。
六、Aurelio 如何记红利
每只持仓在 Records → Wealth 里有一个分红政策:
- Distributing:App 跟随基金的分红;
- Accumulating:不记任何红利,因为基金已经把它们再投资了;
- From its history(留空):由该持仓自己的分红历史决定。这是没有政策的持仓所遵循的规则,也适用于一只没有政策可选的股票——它要么派息要么不派。
对应代码是 _follows_dividends(h)(pac.py),它是一段可以逐行读的判定:
if not h.symbol or h.quantity is None:
return False
if h.distribution_policy:
return h.distribution_policy == "dist"
return (h.asset_class or "") != "crypto"
两个细节:加密资产不会被问(每天一次请求换零收益);「Stocks & ETF」在系统里都归为 equity,所以没有政策的基金也会跟随自身历史,而不是静默地什么都不记。
份额数从哪来:从当天生效的 situation 重建
对需要跟随的持仓,App 在启动时从 Yahoo 读分红历史(每个 ticker 每天最多一次,回答当天缓存),并对每个除息日,用除息日之前你持有的份额数 × 每股股息给账户现金记账。份额数由「除息日当时生效的 situation」加上 ledger 重建,因此即使你几个月后才打开 App,那笔红利仍会被记上(pac.py 的 execute_dividends 文档字符串,以及按每个 ex-date 所在区间取单位数的 _due 逻辑)。
钱到账的日期与「不重复」
- 除息日之后几天到几周,钱才进账户。对给出付款日的市场(美股),行被记在付款日:仓库记录的实测是除息日后 14 到 69 天(2026 年 10 月测量的 12 只)。对其他市场和基金,Yahoo 不给可用付款日,行就记在除息日,你按券商对账单修正时把它移到到账日。
- 两种情况下红利都保留自己的
ex_date,这正是 App 判断「这笔已经记过」的依据——永远不会记两次(_record_dividend在持有 SQLite 写锁的情况下再查一次,实测两次并发 catch-up 曾是 10/10 双写,pac.py)。 - 如果账户最新余额正好落在一笔红利的「窗口」内、而付款日未知,App 会问你:这笔钱是否已经在那份余额里,而不是猜。
窗口:手工录入如何与系统红利配对
dividend_pairs.py 是一个纯函数模块(无数据库、无时钟),核心是 windows():
REACH = datetime.timedelta(days=70) # 实测最长付款滞后 69 天,向上取整
NO_SPACING = datetime.timedelta(days=365) # 只列过一次派息时的假定间隔
- 每个除息日的窗口是「从除息日到下一个除息日与
除息日 + 70 天中较晚的那个」;最后一个除息日到「70 天与按中位间隔推算的正常间距中较晚的那个」。 - 为什么不能简单截到下一个除息日:有两只 ADR 按月派息、除息日相隔 1 到 33 天,每次都晚于下一个除息日一两个周期才付款;窗口若止于下一个除息日,会把一笔到账错配给后一笔分红。
- 配对双向唯一才算识别成功:这笔流水是该红利窗口里唯一的一笔,且该红利是窗口能容纳这笔流水的唯一一笔。其他所有情况都提问,App 在你回答前不写任何东西;你回答过「这不是同一笔」的组合会被记住,不再重配(
pair()的apart参数)。
pac.py 里 _pairing、_recognise、_questions、_balance_question 就是把这些纯函数的结论落成数据库动作与前端问题。
毛额、估算,然后是你自己的数字
- App 自己记的红利天生是毛额并标记为
estimated:市场并不知道在钱到你手上之前被扣了多少税。当你用券商实际入账的净额修正它时,净额替换毛额、estimated标记在同一步里消失。 - 对仍然停留在市场毛额上的红利,Profile 里有一个你申报的 dividend withholding rate。它产生的估算显示在你的合计旁边、从不进入合计,并且费率明文可见;它只作用于仍然标记为估算的红利——你手工修正过的那笔不会被二次征税。Profile 可以建议你所在国家的税率作为起点,但从不自动应用(tax.py 的
dividends_estimated * rate / 100与缺失项提示)。 - 以外币支付的红利,按它自己除息日的汇率换算,而不是今天的汇率(
fx_as_of与estimated一起记录在行上)。
为什么 demo 里那只欧元国债 ETF 记不到红利
原文给了一个很好的反例:它是一只以「总额」记录、没有 ticker 的分配型基金,所以红利无法被跟随——因为没有任何东西能说明它在每个除息日持有多少份额。这正好把整套机制的前提讲清楚了:跟随红利需要一个 ticker 和一个数量。
七、自己动手:三条可验证的操作路径
- 跑起来看穿透:按 README.md 的方式以 demo 数据启动(
./start.sh --demo,Windows 用./start.ps1 -Demo),打开 http://localhost:8000,进入 Portfolio 页,看「Look-through (real exposure)」的 Coverage 百分比与 Overlap 列表;改动后在portfolio/composition?refresh=true下会看到refused_at机制保住更完整的旧数据。 - 让一只基金被穿透:在 Records → Wealth 给该持仓补上 ISIN。缺 ISIN 是「X 光打不开一只基金」的常见原因,错误信息本身就会这么说(
_resolve_isin)。补上后不必等缓存过期——get_composition对Undecomposable的缓存做了例外:如果调用方这次带来了之前缺失的那个 ISIN,会立刻重新尝试(composition.py)。 - 配对红利政策:在 Records → Wealth 设定
Distributing/Accumulating,或者留空让它跟随历史。判断标准见 schemas.py 的字段说明;填错不会破坏数据,只会决定是否去 Yahoo 询问分红历史。
八、延伸阅读与源码索引
- 两个子主题的完整说明:ETF overlap and portfolio X-ray、Accumulating vs distributing ETFs
- 穿透与来源瀑布:composition.py、issuers.py
- 身份注册表与双胞胎归并:catalogue.py、InstrumentPicker.tsx
- 红利捕捉与记账:pac.py、dividend_pairs.py、tax.py
- 地理与货币口径:geo.py
- 接口与数据形状:dashboard.py、schemas.py
- 行为验证:test_composition.py、test_catalogue.py、test_what_a_purchase_would_weigh.py
Educational information, not regulated financial advice.