87 lines
3.5 KiB
Markdown
87 lines
3.5 KiB
Markdown
# MacroScope — 總經指標儀表板
|
||
|
||
一個給初學者看的美國總體經濟儀表板。資料來自美國聖路易聯儲的 **FRED**（免費、公開），
|
||
全中文介面、每張卡片都有白話解釋，並用透明公式算出「總經健康分數」。
|
||
|
||
> 為什麼需要一個後端？FRED 官方 API 不允許瀏覽器直接呼叫（沒有 CORS），而且金鑰不能放在前端外洩。
|
||
> 所以這裡用一支很小的 Node 伺服器當「代理」：金鑰只留在伺服器，瀏覽器只跟自己的 `/api/macro` 溝通。
|
||
|
||
---
|
||
|
||
## 三步驟啟動
|
||
|
||
### 1. 申請免費的 FRED 金鑰（約 1 分鐘）
|
||
到 <https://fred.stlouisfed.org/docs/api/api_key.html> 註冊帳號，取得一組 32 碼的金鑰。免費、即時核發。
|
||
|
||
### 2. 設定金鑰
|
||
把範例檔複製成 `.env`，填入你的金鑰：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 然後編輯 .env，把 FRED_API_KEY 換成你的金鑰
|
||
```
|
||
|
||
### 3. 安裝並啟動
|
||
|
||
```bash
|
||
npm install
|
||
npm start
|
||
```
|
||
|
||
看到 `MacroScope 已啟動 → http://localhost:3000` 後，用瀏覽器打開該網址即可。
|
||
|
||
> 還沒設定金鑰也能啟動，畫面會直接顯示設定教學，照著做即可。
|
||
|
||
---
|
||
|
||
## 專案結構
|
||
|
||
```
|
||
index.html 前端（純 HTML/CSS/JS，向 /api/macro 取資料後渲染）
|
||
server.js Express 伺服器：提供網頁 + /api/macro（代理 FRED、1 小時快取）
|
||
lib/indicators.js 指標字典：序列代碼、中文名、分組、是否反向、解釋文字
|
||
lib/fred.js 抓取 FRED / Yahoo、做 YoY/MoM 換算、產生真實 sparkline
|
||
lib/score.js 用透明公式算出健康分數、景氣燈號與 5 個訊號
|
||
```
|
||
|
||
資料流：`瀏覽器 → /api/macro → (持金鑰) FRED → 換算/計分 → 回傳 JSON → 渲染`
|
||
|
||
---
|
||
|
||
## 指標與資料來源
|
||
|
||
絕大多數指標直接對應免費的 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 多數指標本身就是每日／每週／每月更新。
|