📥 持倉匯入指南 — 給接手的 AI

使用者要「記新交易 / 貼對帳單」時照這份做。使用者面向的說明見 README；分析筆記見 筆記守則。

---

0. 核心原則

• transactions.csv 是唯一真相：只記買/賣/配息的事實；所有報酬率由 compute.py 算，不手填。
• 不要在本地跑 compute.py（此環境 proxy 擋 Yahoo，抓價會失敗）。流程是：改 CSV → commit → push main → GitHub Actions 自動抓價、算 XIRR、更新 dashboard、產生走勢圖。
• 本地只能跑 python3 compute.py --self-test（驗 XIRR 數學，不需網路）。

---

1. CSV 格式

理財(FIN)/持倉/transactions.csv，欄位：

date,market,ticker,action,shares,price,fee,currency,note

• date：YYYY-MM-DD
• market：US / TW
• ticker：美股代號；台股填純數字（如 2330，腳本自動補 .TW）
• action：BUY / SELL / DIV
• shares：股數（台股 1 張 = 1000 股）
• price：每股價；DIV 時填每股配息率
• fee：手續費 + 交易稅；DIV 時填預扣稅
• currency：USD / TWD
• 以 # 開頭的行是註解，會被 load_transactions() 略過。

現金流語意（compute.py 依此算）：

• BUY → −(shares×price + fee)
• SELL → +(shares×price − fee)
• DIV → +(shares×price − fee) ＝ 對帳單「實際應收」淨額（fee 欄放預扣稅）。

---

2. 從券商對帳單匯入（國泰複委託 = 已驗證流程）

Step 1 — 抽文字（不要看圖 OCR 猜數字）

pdftotext -layout 對帳單.pdf out.txt

國泰月對帳單的「海外股票交易明細」每筆 = 3 行：

 2026/01/26  ORCL  USA  US  一般除息  USD  0.5000        3.15   ← 日期 ticker 市場 種類 幣別 價格/配息率 淨額
                          9.000000    4.5000  0.00  1.35        ← 股數 成交金額 手續費 交易稅費
              USD  1.0000  3.15                                 ← 實際幣別 匯率 實際淨額

Step 2 — 交易種類對應

對帳單「交易種類」	CSV action	備註
買進	BUY	fee = 手續費 + 交易稅費
賣出	SELL	fee = 手續費 + 交易稅費
一般除息	DIV	fee = 交易稅費欄（即預扣稅）；股數×配息率−稅 = 實領
證券代碼變更	不列	純改代號、非現金流 → 把舊代號在 CSV 全部改成新代號、刪掉變更列（範例：BACQ→MRLN）

Step 3 — 驗證（重要）

• 用最後一期對帳單的「海外股票庫存」表，逐檔比對「買進−賣出」後的淨持股是否吻合。
• 也可用 python3 離線載入 CSV、compute_position(..., live=False) 檢查 net_shares（不抓價、只驗數量）。範例做法見 git log 2026-07-10 的匯入 commit。

Step 4 — 寫入 + 推送

• 新交易 append 到 CSV 最下方（時間序不必嚴格，load_transactions() 會排序）。
• git add transactions.csv && git commit && git push origin main。
• 之後 dashboard 由 Actions 更新（每交易日台灣 17:00；或用 GitHub MCP actions_run_trigger 手動觸發 portfolio-update.yml 立即更新）。

---

3. 特殊情況速查

情況	處理
分批買 / 定期定額	每筆一列 BUY，XIRR 自動算時間
零股 / 碎股	shares 填小數（如 0.724）
證券代碼變更	舊代號改新代號、刪變更列（見上）
股票分割 split	少見；若發生，調整該日之後的 shares/price 並在 note 註明（回溯歷史走勢圖用 raw close，短窗內多無影響）
股利抓錯 / 要覆蓋	直接在 CSV 加/改 DIV 列（對帳單為準）
未來加台股	market=TW、currency=TWD、ticker 純數字；compute.py 已支援美台分列 + 合併 TWD

---

4. compute.py 重要開關

• AUTO_FETCH_DIVIDENDS = False（預設）：股利只用 CSV 的 DIV 列（對帳單實領最準）。改 True 才會對「沒 DIV 列」的標的用 yfinance 估算。
• US_DIV_WITHHOLDING = 0.30：僅 auto-fetch 時生效。
• COLOR_POS / COLOR_NEG：正負配色（預設台股慣例紅=正、綠=負）。

---

🔗 相關

• README（使用者面向）
• 持倉總覽 Dashboard
• 筆記守則（寫分析筆記）

---

本檔是「給維護 AI 的 SOP」，非投資內容。