# 快速開始

## 1. 確認依賴

### stocks-query skill

報告產生器依賴 `stocks-query` skill 的腳本，確認已安裝在 `../stocks-query/`：

```bash
ls ../stocks-query/scripts/yahoo-quote-browserless.py
```

### Python 套件

```bash
python3 -c "import markdown; from weasyprint import HTML; print('OK')"
```

若尚未安裝：

```bash
pip3 install markdown weasyprint
```

### CJK 字型

PDF 需要中文字型。macOS 內建 PingFang TC，無需額外安裝。Linux 環境需安裝 Noto Sans CJK TC：

```bash
# Ubuntu/Debian
sudo apt install fonts-noto-cjk
```

## 2. 透過 Claude Code 產生報告

最簡單的方式是直接在 Claude Code 中使用：

```
/stocks-report 2330     # 台積電完整報告
/stocks-report 00922    # ETF 報告
```

執行完成後會告知四個檔案路徑與大小。

## 3. 輸出位置

報告存放在工作目錄的 `stocks/` 資料夾：

```
stocks/2330-report-20260410.md
stocks/2330-report-20260410.pdf
stocks/2330-report-20260410-beginner.md
stocks/2330-report-20260410-beginner.pdf
```

## 4. 本地持股整合

若 `stocks/` 目錄中有 `<代號>-TW.md` 檔案，報告會自動讀取並計算：

- 平均成本與未實現損益
- 已領配息金額
- 含息總報酬
- 各批次是否符合配息資格（對照除息日）

持股紀錄格式範例請參考既有的 `*-TW.md` 檔案。

## 常見問題

| 問題 | 解法 |
|------|------|
| PDF 出現字型錯誤 | 確認報告內容不含 emoji，改用 `[+]`/`[!]`/`[-]` 標記 |
| `ModuleNotFoundError: weasyprint` | 執行 `pip3 install weasyprint` |
| 某區段顯示「無資料」 | 正常現象，該資料來源暫時無法取得（假日、ETF 不適用等） |
| PDF 中文亂碼 | 確認系統已安裝 CJK 字型 |