---
title: "持倉匯入指南（給維護 AI）"
type: note
specialty: FIN
tags: [finance, portfolio, meta, ai-handoff, import]
created: 2026-07-10
updated: "2026"
modified: 2026-07-10
---

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

> 使用者要「記新交易 / 貼對帳單」時照這份做。使用者面向的說明見
> [[理財(FIN)/持倉/README|README]]；分析筆記見 [[理財(FIN)/筆記守則|筆記守則]]。

---

## 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 猜數字）
```bash
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`：正負配色（預設台股慣例紅=正、綠=負）。

---

## 🔗 相關

- [[理財(FIN)/持倉/README|README（使用者面向）]]
- [[理財(FIN)/持倉/持倉總覽_dashboard|持倉總覽 Dashboard]]
- [[理財(FIN)/筆記守則|筆記守則（寫分析筆記）]]

---

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