451 lines
16 KiB
Markdown
451 lines
16 KiB
Markdown
# MacroScope — 總經儀表板 · 學習 · 個股 · 復盤 · 日曆
|
||
|
||
一個給初學者用的美國總體經濟 + 投資學習工具箱。資料主要來自美國聖路易聯儲 **FRED**（免費、公開）、Yahoo Finance、SEC EDGAR 等官方與公開來源。全中文介面、每張卡片與檢查都有白話解釋，並用透明公式算出「總經健康分數」。
|
||
|
||
強調「照問題學、不要硬背名詞」：從總經水位、財報健檢、六層投資地圖、交易復盤等實際任務出發，隨時可跳轉回對應的投資原則與名詞。內建市場日曆（含自訂追蹤財報）與可帶頁面上下文的 AI 助手（支援 Grok 與 OpenCode Go）。
|
||
|
||
> **為什麼需要後端？** FRED 官方 API 不允許瀏覽器直接呼叫（沒有 CORS），且金鑰不能放在前端。本專案用一支很小的 Node 伺服器當代理：金鑰只留在伺服器，瀏覽器只跟自己的 `/api/*` 溝通。
|
||
|
||
---
|
||
|
||
## 目錄
|
||
|
||
- [快速開始](#快速開始)
|
||
- [主要功能](#主要功能)
|
||
- [專案在整體 repo 中的位置](#專案在整體-repo-中的位置)
|
||
- [資料夾結構](#資料夾結構)
|
||
- [系統架構](#系統架構)
|
||
- [API 端點](#api-端點)
|
||
- [資料流與快取](#資料流與快取)
|
||
- [建立知識庫](#建立知識庫)
|
||
- [環境變數](#環境變數)
|
||
- [技術棧](#技術棧)
|
||
- [指標與資料來源](#指標與資料來源)
|
||
- [常見問題](#常見問題)
|
||
- [免責聲明](#免責聲明)
|
||
|
||
---
|
||
|
||
## 快速開始
|
||
|
||
### 1. 申請 FRED 金鑰（約 1 分鐘）
|
||
|
||
到 <https://fred.stlouisfed.org/docs/api/api_key.html> 註冊，取得 32 碼金鑰（免費、即時核發）。
|
||
|
||
### 2. 設定金鑰
|
||
|
||
啟動後到頂部 **AI 設定** 頁填入：
|
||
|
||
| 變數 | 用途 |
|
||
|------|------|
|
||
| `FRED_API_KEY` | 總經 + 部分日曆 |
|
||
| `GROK_API_KEY` / `OPENCODE_GO_API_KEY` | AI 助手（可擇一或都填） |
|
||
| `AI_ACTIVE_PROVIDER` | 預設 provider（`grok` 或 `opencode-go`） |
|
||
|
||
設定會寫入本機 `.env`，**不會出現在瀏覽器**。
|
||
|
||
或手動複製範例檔：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
# 編輯 .env 填入金鑰
|
||
```
|
||
|
||
### 3. 安裝並啟動
|
||
|
||
```bash
|
||
npm install
|
||
npm run build:knowledge # 學習教材前置（需 emmy 知識庫，見下方）
|
||
npm start
|
||
# 開發模式（自動重啟）：npm run dev
|
||
```
|
||
|
||
瀏覽器開啟 `http://localhost:3000`。看到 `MacroScope 已啟動` 即成功。
|
||
|
||
> 還沒設 FRED 金鑰也能啟動，總經頁會顯示設定教學。
|
||
|
||
---
|
||
|
||
## 主要功能
|
||
|
||
頂部分頁使用 **hash 路由**（無前端框架）：
|
||
|
||
| 路由 | 視圖 | 說明 |
|
||
|------|------|------|
|
||
| `#/` | 總經儀表板 | 31 項 FRED 指標、健康分數、殖利率曲線 |
|
||
| `#/calendar` | 市場日曆 | FOMC/CPI/非農等 + 自訂追蹤財報 |
|
||
| `#/learn` | 學習教材 | Obsidian 知識庫快照、wikilink、知識圖譜 |
|
||
| `#/stock` | 個股工具 | 財報、走勢、健檢、投資地圖、回測 |
|
||
| `#/journal` | 交易復盤 | 交易紀錄、損益、勝率、分組統計 |
|
||
| `#/settings` | AI 設定 | 金鑰、provider、模型清單 |
|
||
|
||
右下角常駐 **AI 助手**，會依目前頁面自動帶入上下文。
|
||
|
||
### 總經儀表板
|
||
|
||
- 31 項真實 FRED 指標，分 6 組（利率 & 殖利率、通膨、勞動、成長、貨幣 & 信用、市場情緒 & 大宗）。
|
||
- 每張卡片：最新值、變動%、sparkline、三段白話解釋、資料來源與更新頻率。
|
||
- **總經健康分數**（0–100）與景氣燈號，附完整 breakdown。
|
||
- 殖利率曲線 + 歷史事件標記（`EVENTS` / `EPISODES`）。
|
||
- 點卡片開走勢大圖 Modal，支援多區間與分數累積走勢。
|
||
|
||
### 市場日曆
|
||
|
||
- 未來約 60 天重要事件（央行、通膨、就業、四巫日、休市等）。
|
||
- **追蹤財報**：自訂股票代號 watchlist，earnings 顯示在對應日期。
|
||
- 多源抓取（官方 iCal、FRED、BLS、BEA、Nasdaq），伺服器每日快取。
|
||
|
||
### 學習教材
|
||
|
||
- 由 `emmy/emmy` Obsidian 知識庫建置快照（原則、案例、名詞、公司、單集、知識圖譜）。
|
||
- wikilink `[[目標]]` 站內跳轉、Markdown + Mermaid、個人筆記（localStorage）。
|
||
- 與總經、個股、復盤雙向連結。
|
||
|
||
### 個股工具
|
||
|
||
- **指標面板**：報價、三表、比率、Company Intel。
|
||
- **價格走勢**：多區間／日週月線圖（Yahoo 主力，Nasdaq 備援）。
|
||
- **財報健檢**：五步驟紅黃綠燈 + 連結知識庫。
|
||
- **投資地圖**：六層漏斗互動流程。
|
||
- **回測**：買進持有 / 定期定額 / 均線 / 逢大跌等策略。
|
||
|
||
### 交易復盤
|
||
|
||
- CRUD 交易紀錄，自動損益、勝率、Payoff、分組分析。
|
||
- 資料存於 SQLite `trades` 表。
|
||
|
||
### AI 助手
|
||
|
||
- Provider：Grok、OpenCode Go；可從 `/api/ai/models` 抓取可用模型。
|
||
- `/api/ai/context` 組裝目前頁面精簡摘要 → `/api/ai/chat` 轉發 LLM。
|
||
- 繁體中文、先結論再依據，一律附學習免責聲明。
|
||
|
||
---
|
||
|
||
## 專案在整體 repo 中的位置
|
||
|
||
本目錄是 `finance` monorepo 下的 **Web 應用**；學習內容來自同層的 Obsidian 知識庫：
|
||
|
||
```
|
||
finance/ # 父目錄（git repo 根目錄）
|
||
├── emmy/
|
||
│ └── emmy/ # Obsidian 投資知識庫（Markdown + wikilink）
|
||
│ ├── 投資原則/
|
||
│ ├── 名詞/
|
||
│ └── ...
|
||
└── web/ # ← 本專案（MacroScope）
|
||
├── server.js
|
||
├── index.html
|
||
├── app.js
|
||
├── lib/
|
||
├── data/ # build:knowledge 產物
|
||
└── data.db # 執行期 SQLite（.gitignore）
|
||
```
|
||
|
||
建置腳本預期路徑：`../../emmy/emmy`（相對 `web/scripts/`）。
|
||
|
||
---
|
||
|
||
## 資料夾結構
|
||
|
||
```
|
||
web/
|
||
├── index.html # 總經視圖 HTML 骨架 + 內聯渲染（卡片、Modal、圖表）
|
||
├── app.js # SPA 路由、五視圖 init、AI widget、Markdown/wikilink
|
||
├── app.css # 全站樣式（淺色、玻璃擬態 header）
|
||
├── server.js # Express：靜態檔 + 全部 /api + 快取 + AI proxy + .env 管理
|
||
│
|
||
├── lib/ # 領域邏輯（多數檔案開頭有職責說明）
|
||
│ ├── indicators.js # 31 指標字典 + 6 分組 + 卡片 tip
|
||
│ ├── fred.js # FRED 抓取、YoY/MoM、sparkline、殖利率曲線
|
||
│ ├── score.js # 健康分數、regime、breakdown、signals
|
||
│ ├── context.js # 依歷史序列產生白話脈絡
|
||
│ ├── events.js # 歷史事件 EVENTS、危機案例 EPISODES
|
||
│ ├── db.js # SQLite：cache / series / score_history / trades
|
||
│ ├── marketdata.js # Yahoo chart + Nasdaq 備援
|
||
│ ├── fundamentals.js # Yahoo quoteSummary + SEC EDGAR 正規化三表
|
||
│ ├── fincheck.js # 財報基本功五步驟規則引擎
|
||
│ ├── backtest.js # 四種策略回測與績效統計
|
||
│ ├── investmap.js # 六層投資地圖設定與問題
|
||
│ ├── calendar.js # 日曆事件彙整（多源）
|
||
│ ├── calendar-fred.js # FRED 相關日曆源
|
||
│ ├── calendar-market.js # 市場結構（四巫、休市等）
|
||
│ ├── calendar-i18n.js # 事件中文化
|
||
│ ├── calendar-cache.js # 日曆每日快取 + watchlist
|
||
│ ├── companyintel.js # 管理層、內部人、新聞等
|
||
│ ├── knowledge.js # 載入 knowledge.json / notes.json
|
||
│ ├── graph.js # wikilink → vis-network 圖譜
|
||
│ ├── learn-html.js # 學習路徑首頁渲染
|
||
│ └── glossary.js # 名詞提示
|
||
│
|
||
├── data/ # 建置產物（可 commit JSON，執行期讀取）
|
||
│ ├── knowledge.json # 課綱索引 + linkMap + 輕量條目
|
||
│ └── notes.json # 全筆記全文（kind:id → body）
|
||
│
|
||
├── scripts/
|
||
│ └── build-knowledge.mjs # 從 emmy/emmy 快照 → data/*.json
|
||
│
|
||
├── package.json
|
||
├── .env.example
|
||
├── .gitignore # 忽略 node_modules、.env、data.db
|
||
└── README.md
|
||
```
|
||
|
||
**執行期產生、不進版控：**
|
||
|
||
| 檔案 | 說明 |
|
||
|------|------|
|
||
| `data.db` | SQLite：快取、序列、分數歷史、交易、通用 JSON cache |
|
||
| `.env` | API 金鑰與設定（可由設定頁寫入） |
|
||
| `node_modules/` | npm 依賴 |
|
||
|
||
---
|
||
|
||
## 系統架構
|
||
|
||
### 分層概覽
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph Browser["瀏覽器（Vanilla JS SPA）"]
|
||
HTML[index.html]
|
||
APP[app.js + app.css]
|
||
HASH["Hash 路由 #/macro … #/settings"]
|
||
AIW[AI 浮動面板]
|
||
end
|
||
|
||
subgraph Server["Node.js + Express（server.js）"]
|
||
API["/api/* 路由"]
|
||
CACHE[記憶體 + SQLite 快取]
|
||
ENV[.env 讀寫]
|
||
end
|
||
|
||
subgraph Lib["lib/ 領域模組"]
|
||
FRED[fred + indicators + score]
|
||
MKT[marketdata + fundamentals]
|
||
CAL[calendar-*]
|
||
LEARN[knowledge + graph]
|
||
TRD[db trades + fincheck + backtest]
|
||
end
|
||
|
||
subgraph External["外部資料源"]
|
||
FREDAPI[FRED API]
|
||
YAHOO[Yahoo Finance]
|
||
SEC[SEC EDGAR]
|
||
LLM[Grok / OpenCode Go]
|
||
OFFICIAL[央行 / BLS / BEA / Nasdaq iCal]
|
||
end
|
||
|
||
subgraph Data["本機資料"]
|
||
JSON[data/knowledge.json + notes.json]
|
||
SQLITE[(data.db)]
|
||
end
|
||
|
||
Browser -->|fetch /api| Server
|
||
Server --> Lib
|
||
Lib --> FREDAPI
|
||
Lib --> YAHOO
|
||
Lib --> SEC
|
||
Lib --> OFFICIAL
|
||
Server --> LLM
|
||
Lib --> JSON
|
||
Lib --> SQLITE
|
||
EMMY[(emmy/emmy)] -.->|build:knowledge| JSON
|
||
```
|
||
|
||
### 前端模組職責
|
||
|
||
| 檔案 | 職責 |
|
||
|------|------|
|
||
| `index.html` | 總經頁 DOM、卡片/Modal/圖表渲染、頂部 nav |
|
||
| `app.js` | `VIEW_IDS` 路由、`initCalendar/Learn/Stock/Journal/Settings`、wikilink/Markdown、AI context |
|
||
| `app.css` | 各視圖版面與元件樣式 |
|
||
|
||
### 後端模組職責
|
||
|
||
| 檔案 | 職責 |
|
||
|------|------|
|
||
| `server.js` | 路由表、TTL 常數、`buildPayload` / `refreshAndCache`、財報/股價快取邏輯、AI summarizer、`SETTINGS_FIELDS` |
|
||
|
||
---
|
||
|
||
## API 端點
|
||
|
||
所有 API 前綴為 `/api`，回傳 JSON（錯誤時附 `error` 訊息）。
|
||
|
||
### 總經
|
||
|
||
| 方法 | 路徑 | 說明 |
|
||
|------|------|------|
|
||
| GET | `/api/macro` | 整包總經 payload；`?fresh=1` 強制重抓 |
|
||
| GET | `/api/series/:key` | 單一指標歷史（走勢大圖） |
|
||
| GET | `/api/score-history` | 每日健康分數累積 |
|
||
| GET | `/api/events` | 歷史事件與危機案例 |
|
||
|
||
### 學習
|
||
|
||
| 方法 | 路徑 | 說明 |
|
||
|------|------|------|
|
||
| GET | `/api/knowledge` | 知識庫索引與 metadata |
|
||
| GET | `/api/note/:kind/:id` | 單篇筆記全文 |
|
||
| GET | `/api/graph` | vis-network 節點與邊 |
|
||
|
||
### 個股與日曆
|
||
|
||
| 方法 | 路徑 | 說明 |
|
||
|------|------|------|
|
||
| GET | `/api/fundamentals/:symbol` | 三表、比率、財測等 |
|
||
| GET | `/api/price/:symbol` | 歷史 OHLC（`range`, `interval`） |
|
||
| GET | `/api/quote/:symbol` | 即時報價 |
|
||
| GET | `/api/profile/:symbol` | 公司簡介 |
|
||
| GET | `/api/company-intel/:symbol` | 管理層、內部人、新聞 |
|
||
| GET | `/api/backtest/:symbol` | 策略回測結果 |
|
||
| GET | `/api/investmap` | 六層地圖設定 |
|
||
| GET | `/api/calendar` | 日曆事件 payload |
|
||
| GET/PUT | `/api/calendar/watchlist` | 追蹤財報代號清單 |
|
||
|
||
### 復盤
|
||
|
||
| 方法 | 路徑 | 說明 |
|
||
|------|------|------|
|
||
| GET | `/api/trades` | 交易列表 |
|
||
| GET | `/api/trades/stats` | 統計摘要 |
|
||
| POST | `/api/trades` | 新增 |
|
||
| PUT | `/api/trades/:id` | 更新 |
|
||
| DELETE | `/api/trades/:id` | 刪除 |
|
||
|
||
### AI 與設定
|
||
|
||
| 方法 | 路徑 | 說明 |
|
||
|------|------|------|
|
||
| POST | `/api/ai/models` | 依 provider 列出可用模型 |
|
||
| POST | `/api/ai/context` | 組裝目前頁面上下文 |
|
||
| POST | `/api/ai/chat` | 帶 context 的對話 |
|
||
| GET | `/api/settings/env` | 讀取設定（金鑰遮罩） |
|
||
| POST | `/api/settings/env` | 寫入 `.env` |
|
||
| GET | `/api/health` | `{ ok, knowledge }` 健康檢查 |
|
||
|
||
靜態檔：根目錄 `index.html`、`app.js`、`app.css` 由 Express 直接提供。
|
||
|
||
---
|
||
|
||
## 資料流與快取
|
||
|
||
| 功能 | 路徑 | 外部來源 | 持久化 |
|
||
|------|------|----------|--------|
|
||
| 總經 | `/api/macro` | FRED + Yahoo（黃金） | 記憶體 + `cache`/`series`/`score_history` |
|
||
| 日曆 | `/api/calendar` | 多源 iCal / API | `cache` 表（24h） |
|
||
| 學習 | `/api/knowledge` | `data/*.json` | 建置時快照 |
|
||
| 財報 | `/api/fundamentals/:s` | Yahoo → SEC | 通用 cache + SEC 探針 |
|
||
| 股價 | `/api/price/:s` | Yahoo → Nasdaq | 日線 6h / 週月 1d TTL |
|
||
| 復盤 | `/api/trades` | — | `trades` 表 |
|
||
| AI | `/api/ai/chat` | Grok / OpenCode | 無持久（僅請求日誌於 console） |
|
||
|
||
**SQLite 表（`lib/db.js`）：**
|
||
|
||
- `cache` — macro 整包、fundamentals、hist、quote、calendar 等 JSON
|
||
- `series` — 各 FRED 指標完整歷史點
|
||
- `score_history` — 每日健康分數
|
||
- `trades` — 使用者交易復盤
|
||
|
||
**財報快取邏輯（`server.js`）：**
|
||
|
||
1. 軟 TTL（預設 12h）內：完全不連網，直接用 DB。
|
||
2. 超過軟 TTL：輕量 SEC `getLatestFilingInfo` 探針；無新申報則續用快取。
|
||
3. 硬上限（預設 3 天）或探針失敗且過期：重抓 Yahoo/EDGAR。
|
||
|
||
失敗時盡量回傳 stale 資料並標記 `degraded`，避免畫面卡住。
|
||
|
||
---
|
||
|
||
## 建立知識庫
|
||
|
||
學習教材、財報健檢連結、投資地圖原則、知識圖譜皆依賴 `emmy/emmy` 快照：
|
||
|
||
```bash
|
||
npm run build:knowledge
|
||
```
|
||
|
||
產出：
|
||
|
||
- `data/knowledge.json` — 索引、分類、linkMap
|
||
- `data/notes.json` — 全文（key = `kind:id`）
|
||
|
||
`emmy/` 更新後重跑即可。未建置時學習頁會提示，且 `/api/health` 的 `knowledge: false`。
|
||
|
||
---
|
||
|
||
## 環境變數
|
||
|
||
見 `.env.example`：
|
||
|
||
| 變數 | 預設 | 說明 |
|
||
|------|------|------|
|
||
| `FRED_API_KEY` | — | 必填（總經） |
|
||
| `PORT` | `3000` | 伺服器埠 |
|
||
| `CACHE_TTL_SECONDS` | `3600` | 總經整包快取 |
|
||
| `FUND_SOFT_HOURS` | `12` | 財報軟 TTL |
|
||
| `FUND_HARD_DAYS` | `3` | 財報硬上限 |
|
||
| `HIST_SOFT_HOURS` | `6` | 日線股價快取 |
|
||
| `QUOTE_TTL_SECONDS` | `60` | 報價快取 |
|
||
| `GROK_*` / `OPENCODE_GO_*` | — | AI provider |
|
||
| `AI_ACTIVE_PROVIDER` | `grok` | 預設 provider |
|
||
|
||
---
|
||
|
||
## 技術棧
|
||
|
||
| 層級 | 技術 |
|
||
|------|------|
|
||
| 執行環境 | Node.js ≥ 18（ESM） |
|
||
| 後端 | Express 4、`dotenv`、內建 `node:sqlite` |
|
||
| 前端 | 純 HTML/CSS/Vanilla JS，無 bundler |
|
||
| CDN | mermaid@11、vis-network@9 |
|
||
| 依賴數 | 僅 2 個 npm 套件（express、dotenv） |
|
||
|
||
外部 API 金鑰與抓取**全部經 server 代理**，不出現在瀏覽器。
|
||
|
||
---
|
||
|
||
## 指標與資料來源
|
||
|
||
絕大多數指標對應 FRED 序列；黃金改用 Yahoo 期貨（FRED 無良好日線）。
|
||
|
||
### 免費替代指標（卡片標「替代」）
|
||
|
||
| 理想指標 | 替代序列 | 說明 |
|
||
|----------|----------|------|
|
||
| ISM 製造業 PMI | `GACDFSA066MSFRBPHI` | 費城聯儲製造業景氣 |
|
||
| 世界大型企業聯合會 CCI | `UMCSENT` | 密西根消費者信心 |
|
||
| 領先指標 LEI | `RECPROUSM156N` | NY Fed 衰退機率模型 |
|
||
|
||
另含工業生產年增（`INDPRO`）作實體經濟補充。
|
||
|
||
### 總經健康分數
|
||
|
||
從 **50 分（中性）** 出發，依殖利率曲線、衰退機率、通膨、就業、信用利差等規則加減，限制 0–100。中性參考指標（美元、油價等）不計分。
|
||
|
||
| 分數 | 燈號 |
|
||
|------|------|
|
||
| ≥ 65 | 景氣穩健 |
|
||
| 50–64 | 溫和成長 |
|
||
| 35–49 | 景氣放緩 |
|
||
| < 35 | 衰退風險高 |
|
||
|
||
教學用簡化模型，**不構成投資建議**。
|
||
|
||
---
|
||
|
||
## 常見問題
|
||
|
||
- **總經顯示要設定金鑰？** → AI 設定頁填 `FRED_API_KEY` 或編輯 `.env` 後重整。
|
||
- **學習頁空白？** → 確認 `finance/emmy/emmy` 存在，執行 `npm run build:knowledge`。
|
||
- **個股或卡片抓取失敗？** → 按「↻ 更新」；多數有 stale 回退。
|
||
- **AI 沒帶頁面資料？** → 設定 provider + model，在對應視圖（個股／學習筆記）再開 AI 面板。
|
||
- **要改指標或分數規則？** → 編輯 `lib/indicators.js`、`lib/score.js`，重啟 server。
|
||
|
||
---
|
||
|
||
## 免責聲明
|
||
|
||
本專案所有內容、工具、AI 回覆、回測與統計**僅供個人學習與研究**，不構成投資、財務、稅務或任何專業建議。投資有風險，請以 FRED、SEC、Yahoo 等官方來源為準。過去績效不代表未來表現。 |