[feat·B路線] 帳戶級績效(含現金):現金 ingestion + Modified Dietz TWR + IRR + cash drag — #154 B 路線落地規格

[atomchung]

來源

#154 於 2026-07-12 owner 拍板：正式啟動 B 路線（帳戶級、含現金），解除該 issue「待討論/決策點 1」的保留（原標記「另議」）。本 issue 是 B 路線的落地規格，對稱於 #164 之於 A 路線。

分工回顧（#154 已定）：

• A 路線 = [feat·績效三柱] 已部署資金 XIRR(分季+年化) + TWR vs 大盤上卡 + 踏空揭露 — #154 A 路線落地規格 #164：已部署資金 XIRR（買賣現金流 + 期末持倉市值），不含現金，答「選中的部位滾多快」。
• B 路線 = 本 issue：帳戶級，含閒置現金，答「連現金一起，你的錢實際滾多快」+「該不該乾脆買指數」（TWR vs 大盤）。

前置基礎設施（已在，降低工程量）

• ledger.py append-snapshot POS.json [--cash JSON] 已支援現金錨點（L27 CLI、L330 接受 {"as_of":.., "positions":[...], "cash":..}）。B 路線的現金餘額錨點不用從零建。
• 多市場幣別傳導 + 匯率 gate 已 merged（feat(engine): 多市場幣別傳導 + 匯率 gate — 台股美股混倉不再靜默算錯 (PR-2a of #129) #132 / PR-2a of [tracking·Phase B] 完整取代每週 trade view — 需求盤點 + 帳本方案定稿 #129），混幣聚合入 USD 視圖的慣例已在。
• [research/design] 帳戶績效衡量的終局:TWR(對大盤) + IRR(實際報酬) — 交易-only 近似的盲點與現金流分離需求 #154 已定公式與方法：外部現金流 = 期末現金 − 期初現金 + 買入總額 − 賣出總額 − 股息；Modified Dietz（近似 TWR，不需每日 NAV）；鏈接多期 → TWR vs 大盤；有日期現金流序列 → 解 IRR。

可行性發現（2026-07-12 掃全 Firstrade CSV）

• CSV 本來就含 ~370 筆現金流 row（171 筆 Other/Financial、107 筆 Dividend/Financial、83 筆 Interest/Financial、少數 Deposit），每筆 Amount 欄即現金增減。engine 現在在 trade_recap.py:117 的 RecordType != "Trade" 把它們全部丟棄（進 skip_non_trade 計數）。
• 最乾淨算法：完整 CSV 下 cash = Σ Amount（買賣的 Amount 已是含手續費淨額）。
• 關鍵風險 — 完整性：last_state.json 的 holdings.is_complete: false 表示持倉靠 snapshot 錨點重建、CSV 非從開戶第一天完整。現金同理——漏一筆 deposit 整個 cash weight 就錯。⇒ 正確設計必須以「當前現金餘額錨點」為準（複用 ledger --cash），交易流只做錨點之後的疊加，不做全期盲算。

分階段 PR（各自獨立可 review）

• PR-1 現金地基（先做，服務 owner 的真痛點「新入金該不該部署」）：Step 0 抓現金餘額錨點寫進 ledger --cash → cash_balance 累加 → cash_weight = cash / (持倉市值 + cash) 指標 + build_state 欄位 + card-spec 的「這筆入金是解集中度還是加深集中度」判讀；分散度分母可選改為含現金。
• PR-2 TWR：外部現金流分離（[research/design] 帳戶績效衡量的終局:TWR(對大盤) + IRR(實際報酬) — 交易-only 近似的盲點與現金流分離需求 #154 公式）→ Modified Dietz 當期報酬 → 鏈接多期 → 累積 TWR vs 大盤 上卡（TW=^TWII，對齊 per-market）。
• PR-3 帳戶級 IRR：含現金流時序解 IRR（MWR）。與 [feat·績效三柱] 已部署資金 XIRR(分季+年化) + TWR vs 大盤上卡 + 踏空揭露 — #154 A 路線落地規格 #164 已部署 XIRR 並存、命名區分：閒置現金越多 → 帳戶 IRR 應低於已部署 XIRR，這個分岔本身是給用戶的訊號。
• PR-4 cash drag：閒置現金拖累報酬的量化（帳戶 IRR vs 已部署 XIRR 的差額歸因）。

多幣別現金

USD 現金與 TWD 現金分開記（對齊 #51/#129 原幣記帳），聚合時入 USD 視圖；缺匯率照 honesty_ledger 既有路子誠實標近似。

事實鏈路（改動時照 CLAUDE.md 連動）

engine（現金 ingestion + TWR/IRR 模組 + honesty_ledger cash-drag key）↔ SKILL Step 0（收現金錨點）+ Step 1 欄位 ↔ card-spec 帳戶級三柱講法 ↔ test_tr_json_contract 的 TR_JSON_KEYS / HL_KEYS ↔ EVALS/eval-design。TR_JSON 頂層新增欄位 = 動契約測試。

驗收

• mock persona：含現金流的 CSV → cash_weight 正確；帳戶級 IRR 與 [feat·績效三柱] 已部署資金 XIRR(分季+年化) + TWR vs 大盤上卡 + 踏空揭露 — #154 A 路線落地規格 #164 已部署 XIRR 顯著分岔且方向正確（閒置現金多 → 帳戶 IRR < 已部署，手算核對）。
• 離線：缺 last_px / 缺現金錨點 → 誠實降級（只出交易-only 版或標「無現金錨點，帳戶級無法算」），不猜。
• 混幣：USD/TWD 現金分桶，聚合入 USD 視圖。
• 全 mock persona 跑一輪產卡核對數字（engine 改動硬紀律）。

refs #154 · 承接 #164（A 路線）· 前置 #163 已合（成本基礎歸一）· ledger --cash 已支援

[atomchung]

現金 ingestion 地基層 → PR #174（OPEN）

#171 的第一塊（現金 ingestion）拆成地基 → 呈現兩層，PR #174 完成地基層。

已落地（engine 吃得到現金了）

• load_cash_flows：讀 CSV 每筆現金增減（買賣 + 存提息費股利，靠 Amount 欄），去重骨架同 load()
• cash_position：錨點優先 / 無錨點 csv_sum 標 reliable=False / cash_weight / recent_net_deposit（入金判讀）
• 接進 main（讀 TR_CASH 錨點 JSON + 混幣 fx 換聚合幣別）+ 存 build_state 頂層 cash 欄位
• 契約：STATE_KEYS +cash；test_engine_units +7、test_tr_json_contract state.cash。run_all 十套綠

關鍵設計（下個 session 接呈現要知道）

• 現金餘額錨點是可信的前提：無錨點只靠 CSV Σamount → 買入為主帳戶會算出負現金（入金沒記全），故降級 reliable=false。錨點靠環境變數 TR_CASH={"as_of","amount","currency"} 傳入，SKILL Step 0 要收（對帳單上的現金餘額）。
• 無錨點負現金 weight 降級 None（不報垃圾）；有錨點負現金 = 真融資 margin，weight 負照報。
• 證據（sample_noisy_broker.csv）：有錨點 balance $19,284 / weight 0.29 / reliable；無錨點 -$27,411 / null / unreliable。

呈現層（未做，下個 session）

1. honesty_ledger 加 cash_unanchored key（engine，HL_KEYS 契約）
2. build_card_data 上卡 + render 顯示（engine，TR_JSON_KEYS 契約）
3. SKILL Step 0 收現金餘額錨點的互動 UX（讓功能真正通電的關鍵）
4. card-spec 入金判讀講法（判定進 engine、文案留 Claude）
5. 全 13 mock persona 卡面核對

#171 剩餘（現金 ingestion 之後）

Modified Dietz TWR + IRR + cash drag（B 路線帳戶級績效三柱，見 #154/#164）。

[atomchung]

2026-07-12 owner 拍板:B 路線績效算法規格(下個 session 從這接手動工)

現金地基三塊已 merged(#174/#175/#177/#178,main 5804ab6),剩餘的 TWR / IRR / cash drag 規格四點拍板如下。

拍板一:TWR 切期 = daily 鏈式,Modified Dietz 不做(修正本 issue 標題的原假設)

每日 V_t = 持倉市值(昨日持股×今日價) + 現金餘額,剝離當日 deposit/withdrawal 後逐日連乘。MD 是「拿不到期中估值」世界的近似;engine 有 yfinance 日價 + 日精度金流,daily 與 _port_daily_returns、α/β 回歸、#168 pnl_curve 同一骨架。帳戶級的兩個結構性紅利:

1. 買賣不再是外部流(只是現金↔持股換桶,V 連續)——持倉視角「買入當天被排除」的縫在帳戶級不存在,要剝離的只剩 deposit/withdrawal。
2. [feat·績效三柱] 已部署資金 XIRR(分季+年化) + TWR vs 大盤上卡 + 踏空揭露 — #154 A 路線落地規格 #164 縫 A(踏空/躲跌)自動閉合:空倉期帳戶=100% 現金,V_t 照走,「對比僅涵蓋持倉日」的揭露只剩持倉柱需要。

新縫與 gate:歷史現金餘額 = TR_CASH 錨點往回滾(錨點日餘額 − 其後累積金流),CSV 漏記入金 → 整段餘額平移污染 TWR。帳戶級績效可用性直接繼承 cash reliable 三態:csv_sum 不出帳戶柱(只出持倉柱)、partial 出 + honesty 揭露缺錨點幣別、anchored 全出。

拍板二:帳戶級不配新大盤基準(鏈式歸因)

「該不該乾脆買指數」已由 per-market 柱回答(US→SPY、TW→^TWII,#129 不合成拍板不動)。帳戶級的增量資訊是 帳戶TWR − 全帳戶持倉TWR = cash drag 這個 gap;全帳戶持倉 TWR(混市場 USD 聚合)是新算的中間量,只當 drag 參照,不自己找大盤比。零合成權重、零新任意參數。

拍板三:cash drag 主定義 = TWR 分岔

drag = 帳戶TWR − 全帳戶持倉TWR(pp),逐日恆等式 r_acct = w_hold·r_hold + w_cash·r_cash 可精確拆、可測試(同 Brinson mimic 拆帳品味)。跌市自然翻號=「現金擋了 X pp」,不用特判。輔助上卡:機會成本金額換算($N,反事實假設標明)。帳戶 IRR vs 已部署 XIRR 的分岔(#154 已拍=訊號)天然並列,不另定義。

拍板四:kind=other(ACH/Transfer)計入帳戶 IRR 外部現金流

有 Amount 的 other 就是真金流(純證券轉入 Amount 為空、進不了 load_cash_flows)。與 recent_net_deposit 排除 other 的行為判讀口徑分開,各自成立:IRR 是對帳算術,漏計真入金會虛高。

推薦即做默認(owner 未逐一拍,可推翻)

• 混幣估值用每日 fx 序列(TWD=X 歷史)、USD 聚合、含匯率損益([P2·邊界] 非美股/多幣別:台股港股 CSV 會靜默算錯 — 至少明示邊界 + 偵測警告 #51 慣例時間軸延伸);fx 歷史缺 → 降級即期 fx + 註記
• 期間 = 數據窗全期一個數;分季只留給 [feat·績效三柱] 已部署資金 XIRR(分季+年化) + TWR vs 大盤上卡 + 踏空揭露 — #154 A 路線落地規格 #164 已部署 XIRR,帳戶 TWR 不分季(卡面密度)
• XIRR solver 寫一次兩邊用([feat·績效三柱] 已部署資金 XIRR(分季+年化) + TWR vs 大盤上卡 + 踏空揭露 — #154 A 路線落地規格 #164 已部署 XIRR + 本 issue 帳戶 IRR;單調區間二分、狀態側零依賴,horizon.py 前例)

分期 PR

1. PR-1:XIRR solver 模組 + 帳戶 V_t 序列基建(daily 估值 + 現金滾動重建 + 每日 fx)
2. PR-2:帳戶 TWR + cash drag 上卡(TR_JSON 欄位 + honesty key + card-spec 講法)
3. PR-3:帳戶 IRR(與 [feat·績效三柱] 已部署資金 XIRR(分季+年化) + TWR vs 大盤上卡 + 踏空揭露 — #154 A 路線落地規格 #164 已部署 XIRR 並列上卡,命名鐵律:閒置現金越多 → 帳戶 IRR < 已部署 XIRR,分岔即 cash drag 訊號)

#168 pnl_curve 不阻塞、先行合入;PR-2 後可順手升級帳戶級曲線。事實鏈路照 repo CLAUDE.md 連動:TR_JSON_KEYS / HL_KEYS / card-spec / EVALS / eval-design。

[atomchung]

認領:本 session 開工實作上面拍板的剩餘三塊(branch claude/quizzical-kirch-b4e02e,base 5804ab6)。原分期 PR-1~3 併一個 PR 交付:三塊共用同一 TR_JSON 欄位/card-spec 段/契約測試面(~90% 表面重疊),拆三個 stacked PR 的手續稅與風險(前例 #177/#178 dance)高於單 PR review 負擔;commit 分層=engine 核心 → 接線+呈現+鏡像。與 open PR #168(pnl_curve)無檔案衝突,唯一語意交點=TR_JSON_KEYS 各加一 key,後合者 rebase 即可。