finance-dashboard/README.md

# MacroScope — 總經指標儀表板

一個給初學者看的美國總體經濟儀表板。資料來自美國聖路易聯儲的 **FRED**（免費、公開），
全中文介面、每張卡片都有白話解釋，並用透明公式算出「總經健康分數」。

> 為什麼需要一個後端？FRED 官方 API 不允許瀏覽器直接呼叫（沒有 CORS），而且金鑰不能放在前端外洩。
> 所以這裡用一支很小的 Node 伺服器當「代理」：金鑰只留在伺服器，瀏覽器只跟自己的 `/api/macro` 溝通。

---

## 三步驟啟動

### 1. 申請免費的 FRED 金鑰（約 1 分鐘）
到 <https://fred.stlouisfed.org/docs/api/api_key.html> 註冊帳號，取得一組 32 碼的金鑰。免費、即時核發。

### 2. 設定金鑰
可以直接啟動後到頂部的 **AI 設定** 頁填入 FRED、OpenCode Go、Grok 等 API key；頁面會把金鑰寫入本機專案的 `.env`，金鑰不會放在瀏覽器前端。AI provider 填好 key 後可按「抓取模型」，系統會向 provider 的 `/models` 端點取得你帳號實際可用的 model。

若想手動建立，也可以把範例檔複製成 `.env` 再填入：

```bash
cp .env.example .env
# 然後編輯 .env，把需要的 API key 換成你的金鑰
```

### 3. 安裝並啟動

```bash
npm install
npm start
```

看到 `MacroScope 已啟動 → http://localhost:3000` 後，用瀏覽器打開該網址即可。

> 還沒設定金鑰也能啟動，畫面會直接顯示設定教學，照著做即可。

---

## Emmy 投資台：四大模組

頂部分頁可切換四個視圖（用 hash 路由：`#/`、`#/learn`、`#/stock`、`#/journal`）：

- **總經**：原本的 FRED 總經儀表板。
- **學習教材**：把 `emmy/` 知識庫（學習分類、案例、110 條投資心法、538 個名詞、218 家公司、單集筆記）整理成可瀏覽、可站內跳轉、可搜尋的教材，含互動式練習題庫。
- **個股工具**：輸入一個股票代號，四個子分頁共用：
  - **價格走勢**：收盤線圖，可切 3 月／1 年／5 年／全部等區間。
  - **財報健檢**：自動抓真實財報（SEC EDGAR 為主、Yahoo 為輔），照「財報基本功」五步驟給紅綠燈，每條檢查連回名詞／心法。
  - **投資地圖**：把「投資底層邏輯」六層漏斗（總經→產業→商業模式→管理層→估值→交易紀律）做成互動判斷流程：逐層用「是／不確定／否」作答，閘門題答否該層即「出局」，每題連到對應心法，底部彙整總結論並可一鍵「存成交易紀錄」。
  - **回測**：機械式策略回測（買進持有／定期定額／均線趨勢／逢大跌進場），畫策略 vs 買進持有兩條權益曲線並列出總報酬、年化、最大回撤、在場比例、勝率等統計。
- **交易復盤**：手動記錄進出與理由，自動算已實現損益、勝率、賺賠比，並依「交易/投資」「是否犯錯」「依據心法」分組復盤。資料存在本機 `data.db`。

> 個股工具與財報健檢、回測皆會把抓到的資料存進 `data.db` 快取：歷史股價日線預設 6 小時內沿用、財報季報依「軟/硬 TTL + SEC 申報探針」判斷是否需重抓，盡量節省外部 API。所有工具僅供學習，**不構成投資建議**。價格／回測資料來源以 Yahoo 為主，被限流（429）時自動改用 Nasdaq 免金鑰歷史（美股最完整）。

### 建立知識庫（學習教材的前置步驟）

學習教材與財報健檢的連結，來自 `emmy/` 的內容快照。`emmy/` 在 `web/` 之外，所以用建置腳本產生 `data/knowledge.json` 與 `data/notes.json`：

```bash
npm run build:knowledge
```

> `emmy/` 內容有更新時，重跑這個指令即可。若沒先執行，學習教材分頁會提示你建立。

---

## 專案結構

```
index.html            前端骨架 + 總經視圖（向 /api/macro 取資料後渲染）
app.js                學習/個股工具/交易復盤視圖 + 主視圖路由 + Markdown 渲染 + 共用折線圖
app.css               新視圖的樣式（沿用總經的深色主題變數）
server.js             Express 伺服器：網頁 + 各 /api 路由（代理外部資料、快取）
lib/indicators.js     指標字典：序列代碼、中文名、分組、是否反向、解釋文字
lib/fred.js           抓取 FRED / Yahoo、做 YoY/MoM 換算、產生真實 sparkline
lib/score.js          用透明公式算出健康分數、景氣燈號與 5 個訊號
lib/db.js             SQLite 存取：快取、序列、分數歷史、交易復盤 trades 表
lib/knowledge.js      載入 data/knowledge.json / notes.json（學習教材）
lib/fundamentals.js   抓財報（SEC EDGAR 主、Yahoo quoteSummary 輔），正規化
lib/fincheck.js       財報基本功五步驟規則引擎，輸出紅綠燈 + 連回名詞/心法
lib/marketdata.js     抓歷史股價（Yahoo v8 主、Nasdaq 免金鑰輔），給價格走勢與回測共用
lib/backtest.js       機械式策略回測純函式：buyhold/dca/sma/dip + 績效統計
lib/investmap.js      投資地圖六層漏斗設定（每層提問清單 + 原則編號，由 server 補上標題/連結）
scripts/build-knowledge.mjs  把 ../emmy 快照成 data/*.json
data/                 build:knowledge 產生的知識庫快照（已 gitignore 友善）
```

資料流：
- 總經：`瀏覽器 → /api/macro → (持金鑰) FRED → 換算/計分 → JSON → 渲染`
- 學習：`build:knowledge 讀 emmy/ → data/*.json → /api/knowledge、/api/note → 渲染`
- 財報：`/api/fundamentals/:symbol → EDGAR/Yahoo → fincheck 規則 → 紅綠燈 JSON`
- 價格：`/api/price/:symbol → Yahoo/Nasdaq（DB 快取）→ 收盤線圖`
- 回測：`/api/backtest/:symbol → 用快取歷史跑 backtest → 權益曲線 + 統計`
- 地圖：`/api/investmap → investmap 設定 + 知識庫原則 → 前端互動六層漏斗 → 可存成交易`
- 復盤：`/api/trades(.../stats) → SQLite trades 表 → 自動算損益與統計`

---

## 指標與資料來源

絕大多數指標直接對應免費的 FRED 序列（利率、通膨、就業、成長、貨幣信用等）。
黃金因 FRED 無良好日線來源，改用 Yahoo Finance 期貨報價（伺服器端呼叫、免金鑰）。

### 免費替代指標（畫面上會標示「替代」）
有少數指標屬於付費／專有資料，無法免費取得，因此用公認的免費等價指標替代，並在卡片上明確標示：

- **ISM 製造業 PMI** → 費城聯儲製造業景氣指數（`GACDFSA066MSFRBPHI`），大於 0 為擴張
- **世界大型企業聯合會 消費者信心 CCI** → 密西根大學消費者信心指數（`UMCSENT`）
- **領先指標 LEI** → 紐約聯儲殖利率曲線衰退機率模型（`RECPROUSM156N`）

此外加入「工業生產年增（`INDPRO`）」作為實體經濟的補充指標。

---

## 總經健康分數怎麼算？

從 50 分（中性）出發，依殖利率曲線、衰退機率、通膨、就業、信用利差、金融條件、製造業、
成長、波動率等規則加減分，最後限制在 0–100。每一條規則都會列在分數的「?」說明裡，
方向中性的指標（如美元、油價、股市本身）不計入分數，只作為參考。

- 65 分以上：景氣穩健
- 50–64：溫和成長
- 35–49：景氣放緩
- 35 以下：衰退風險高

> 這是教學用的簡化模型，**不構成任何投資建議**。

---

## 常見問題

- **畫面顯示「設定 FRED 金鑰」？** 代表 `.env` 還沒設定或金鑰錯誤，照畫面步驟做即可。
- **某些卡片顯示抓取失敗？** 個別序列偶爾延遲或維護，其餘仍是真實資料；按右上角「↻ 更新」可重抓。
- **資料多久更新？** 後端快取 1 小時；FRED 多數指標本身就是每日／每週／每月更新。