# 流程摘要

## 架構概覽

```
stocks-report（本 skill）
│
├── SKILL.md          報告產生流程定義（Claude Code 讀取）
├── CLAUDE.md         專案說明與架構文件
│
└── 依賴 stocks-query skill
    └── scripts/      所有資料擷取腳本（12 支）
```

本 skill 不含程式碼，所有邏輯定義在 `SKILL.md` 中，由 Claude Code 依照流程執行。

## 執行流程

```
1. 資料收集 ─────────────────────────────────────────────
   │  平行執行 stocks-query 的 9～12 支腳本
   │  同時檢查本地持股紀錄 (<代號>-TW.md)
   ▼
2. 組裝專業版 Markdown ──────────────────────────────────
   │  整合所有腳本輸出為結構化報告
   │  → stocks/<代號>-report-YYYYMMDD.md
   ▼
3. 轉換專業版 PDF ───────────────────────────────────────
   │  markdown + weasyprint，CJK 字型排版
   │  → stocks/<代號>-report-YYYYMMDD.pdf
   ▼
4. 組裝白話解讀版 Markdown ──────────────────────────────
   │  問句式標題、術語翻譯、生活化比喻
   │  純文字標記（禁止 emoji）
   │  → stocks/<代號>-report-YYYYMMDD-beginner.md
   ▼
5. 轉換白話解讀版 PDF ──────────────────────────────────
   │  字體 14px、行距 1.8，適合閱讀
   │  → stocks/<代號>-report-YYYYMMDD-beginner.pdf
   ▼
6. 回覆使用者 ───────────────────────────────────────────
   回報四個檔案路徑與大小
```

## ETF 與個股的差異

| 步驟 | ETF（`00` 開頭） | 個股 |
|------|------------------|------|
| 額外腳本 | `yahoo-etf-holdings.py` | `twse-monthly-revenue.py`、`twse-pe-pbr.py` |
| 報告區段 | ETF 持股與配置（前十大、行業、資產） | 月營收、本益比／股價淨值比 |
| 跳過項目 | 月營收、本益比 | ETF 持股 |

## 雙版本差異

| 項目 | 專業版 | 白話解讀版 |
|------|--------|-----------|
| 標題風格 | 標準術語 | 問句式（「大咖們在幹嘛？」） |
| 表格 | 純數據 | 多一欄「白話意思」 |
| 技術指標 | 直接列數值 | 搭配生活化比喻 |
| 總結 | 偏多／偏空／震盪 | 評分表 + 紅綠燈判斷 |
| 字體大小 | 13px / 12px | 14px / 13px |
| 行距 | 1.6 | 1.8 |
| 符號 | 無限制 | 禁止 emoji，使用 `[+]`/`[!]`/`[-]` |

## PDF 轉換技術細節

- 工具：Python `markdown` 套件 → HTML → `weasyprint` → PDF
- 字型優先順序：PingFang TC → Heiti TC → Microsoft JhengHei → Noto Sans CJK TC
- 已知限制：不可使用 emoji 字元，否則 weasyprint 會嵌入 Apple Color Emoji 導致 PDF 閱讀器報錯