---
title: "持倉區使用說明"
type: note
specialty: FIN
tags: [finance, portfolio, howto]
created: 2026-07-10
updated: "2026"
modified: 2026-07-10
---

# 持倉區 — 使用說明

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

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

## 你唯一要做的事：記帳

編輯 [`transactions.csv`](transactions.csv)，**只記買賣事實**，一筆交易一列：

```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`：

```csv
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`，因為對帳單已是實領完整紀錄。

## 本機 / 驗證

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

## 名詞

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

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