持倉區 — 使用說明

這區把「你的交易紀錄」自動變成「持倉總覽 + 報酬率」，Obsidian 跟網站兩邊都看得到。

📄 現有資料：國泰綜合證券美股複委託對帳單 2025/02–2026/06（84 筆買/賣/配息）已整理進 transactions.csv， 淨持股已與最後一期券商庫存表逐檔核對一致。之後新對帳單照格式往下加即可。

你唯一要做的事：記帳

編輯 transactions.csv，只記買賣事實，一筆交易一列：

date,market,ticker,action,shares,price,fee,currency,note
2025-01-15,US,AAPL,BUY,10,172.50,1.0,USD,
2025-03-20,TW,2330,BUY,1000,780,145,TWD,
2025-06-02,US,AAPL,SELL,5,205.00,1.0,USD,獲利了結

• market：US 或 TW
• ticker：美股代號（AAPL）；台股填純數字（2330），腳本自動補 .TW
• action：BUY / SELL（DIV 見下）
• shares：股數（台股 1 張 = 1000 股）
• price / fee：原幣別金額
• 加碼、分批就是多加幾列，XIRR 會自動把每筆的時間算進去。

報酬率、年化、市值一律不要手填 —— 全部由 compute.py 算。

自動化流程（不用你動手）

transactions.csv → GitHub Actions（每日 台灣時間 17:00）
   → compute.py 抓即時報價 + 股利 → 算 XIRR
   → 覆寫 持倉總覽_dashboard.md 的 AUTO 區塊
   → commit 回 main → Cloudflare Pages 重建 → 網站更新

想「馬上更新」不等排程：GitHub repo → Actions 分頁 → Portfolio Update → Run workflow。

股利

目前採 對帳單實領金額（最準，已含真實預扣稅）：每筆配息在 CSV 記成一列 DIV：

2026-01-26,US,ORCL,DIV,9,0.5000,1.35,USD,一般除息(已扣30%預扣稅)

• shares = 除息時持股、price = 每股配息率、fee = 預扣稅。
• 現金流 = shares×price − fee = 對帳單「實際應收」淨額（如上例 9×0.5−1.35 = 3.15）。
• 之後有新對帳單，把新的配息列照樣加進來即可。

若哪天想讓程式自動抓沒記到的股利（yfinance 估算），把 compute.py 的 AUTO_FETCH_DIVIDENDS 改成 True（只對「完全沒有 DIV 列」的標的生效，美股套 US_DIV_WITHHOLDING 30%）。 預設 False，因為對帳單已是實領完整紀錄。

本機 / 驗證

pip install -r requirements.txt
python3 compute.py --self-test   # 驗證 XIRR 數學（不需網路）
python3 compute.py               # 實際抓價更新 dashboard（需能連 Yahoo Finance）

名詞

• 未實現損益 / %：目前持股帳面賺賠（市值 − 成本），直覺、不含時間。
• 年化 XIRR：money-weighted 年化報酬率，考慮每筆現金流時間 + 股利，分批買進時的正確年化指標。

⚠️ 若某次 Actions 抓價失敗（Yahoo 偶爾擋 IP），該檔顯示 —，下次 cron 會再試；數字不會亂掉。