docs: 擴充 README 架構、資料夾結構與 API 說明

補上 monorepo 位置、完整目錄樹、Mermaid 架構圖、API 端點表、
資料流與快取策略，並重整目錄與快速開始章節。

README.md

@@ -1,133 +1,451 @@
-# MacroScope — 總經指標儀表板
+# MacroScope — 總經儀表板 · 學習 · 個股 · 復盤 · 日曆
 
-一個給初學者看的美國總體經濟儀表板。資料來自美國聖路易聯儲的 **FRED**（免費、公開），
+一個給初學者用的美國總體經濟 + 投資學習工具箱。資料主要來自美國聖路易聯儲 **FRED**（免費、公開）、Yahoo Finance、SEC EDGAR 等官方與公開來源。全中文介面、每張卡片與檢查都有白話解釋，並用透明公式算出「總經健康分數」。
-全中文介面、每張卡片都有白話解釋，並用透明公式算出「總經健康分數」。
 
-> 為什麼需要一個後端？FRED 官方 API 不允許瀏覽器直接呼叫（沒有 CORS），而且金鑰不能放在前端外洩。
+強調「照問題學、不要硬背名詞」：從總經水位、財報健檢、六層投資地圖、交易復盤等實際任務出發，隨時可跳轉回對應的投資原則與名詞。內建市場日曆（含自訂追蹤財報）與可帶頁面上下文的 AI 助手（支援 Grok 與 OpenCode Go）。
-> 所以這裡用一支很小的 Node 伺服器當「代理」：金鑰只留在伺服器，瀏覽器只跟自己的 `/api/macro` 溝通。
+
+> **為什麼需要後端？** FRED 官方 API 不允許瀏覽器直接呼叫（沒有 CORS），且金鑰不能放在前端。本專案用一支很小的 Node 伺服器當代理：金鑰只留在伺服器，瀏覽器只跟自己的 `/api/*` 溝通。
 
 ---
 
-## 三步驟啟動
+## 目錄
 
-### 1. 申請免費的 FRED 金鑰（約 1 分鐘）
+- [快速開始](#快速開始)
-到 <https://fred.stlouisfed.org/docs/api/api_key.html> 註冊帳號，取得一組 32 碼的金鑰。免費、即時核發。
+- [主要功能](#主要功能)
+- [專案在整體 repo 中的位置](#專案在整體-repo-中的位置)
+- [資料夾結構](#資料夾結構)
+- [系統架構](#系統架構)
+- [API 端點](#api-端點)
+- [資料流與快取](#資料流與快取)
+- [建立知識庫](#建立知識庫)
+- [環境變數](#環境變數)
+- [技術棧](#技術棧)
+- [指標與資料來源](#指標與資料來源)
+- [常見問題](#常見問題)
+- [免責聲明](#免責聲明)
+
+---
+
+## 快速開始
+
+### 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` 再填入：
+啟動後到頂部 **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，把需要的 API key 換成你的金鑰
+# 編輯 .env 填入金鑰
 ```
 
 ### 3. 安裝並啟動
 
 ```bash
 npm install
+npm run build:knowledge   # 學習教材前置（需 emmy 知識庫，見下方）
 npm start
+# 開發模式（自動重啟）：npm run dev
 ```
 
-看到 `MacroScope 已啟動 → http://localhost:3000` 後，用瀏覽器打開該網址即可。
+瀏覽器開啟 `http://localhost:3000`。看到 `MacroScope 已啟動` 即成功。
 
-> 還沒設定金鑰也能啟動，畫面會直接顯示設定教學，照著做即可。
+> 還沒設 FRED 金鑰也能啟動，總經頁會顯示設定教學。
 
 ---
 
-## Emmy 投資台：四大模組
+## 主要功能
 
-頂部分頁可切換四個視圖（用 hash 路由：`#/`、`#/learn`、`#/stock`、`#/journal`）：
+頂部分頁使用 **hash 路由**（無前端框架）：
 
-- **總經**：原本的 FRED 總經儀表板。
+| 路由 | 視圖 | 說明 |
-- **學習教材**：把 `emmy/` 知識庫（學習分類、案例、110 條投資心法、538 個名詞、218 家公司、單集筆記）整理成可瀏覽、可站內跳轉、可搜尋的教材，含互動式練習題庫。
+|------|------|------|
-- **個股工具**：輸入一個股票代號，四個子分頁共用：
+| `#/` | 總經儀表板 | 31 項 FRED 指標、健康分數、殖利率曲線 |
-  - **價格走勢**：收盤線圖，可切 3 月／1 年／5 年／全部等區間。
+| `#/calendar` | 市場日曆 | FOMC/CPI/非農等 + 自訂追蹤財報 |
-  - **財報健檢**：自動抓真實財報（SEC EDGAR 為主、Yahoo 為輔），照「財報基本功」五步驟給紅綠燈，每條檢查連回名詞／心法。
+| `#/learn` | 學習教材 | Obsidian 知識庫快照、wikilink、知識圖譜 |
-  - **投資地圖**：把「投資底層邏輯」六層漏斗（總經→產業→商業模式→管理層→估值→交易紀律）做成互動判斷流程：逐層用「是／不確定／否」作答，閘門題答否該層即「出局」，每題連到對應心法，底部彙整總結論並可一鍵「存成交易紀錄」。
+| `#/stock` | 個股工具 | 財報、走勢、健檢、投資地圖、回測 |
-  - **回測**：機械式策略回測（買進持有／定期定額／均線趨勢／逢大跌進場），畫策略 vs 買進持有兩條權益曲線並列出總報酬、年化、最大回撤、在場比例、勝率等統計。
+| `#/journal` | 交易復盤 | 交易紀錄、損益、勝率、分組統計 |
-- **交易復盤**：手動記錄進出與理由，自動算已實現損益、勝率、賺賠比，並依「交易/投資」「是否犯錯」「依據心法」分組復盤。資料存在本機 `data.db`。
+| `#/settings` | AI 設定 | 金鑰、provider、模型清單 |
 
-> 個股工具與財報健檢、回測皆會把抓到的資料存進 `data.db` 快取：歷史股價日線預設 6 小時內沿用、財報季報依「軟/硬 TTL + SEC 申報探針」判斷是否需重抓，盡量節省外部 API。所有工具僅供學習，**不構成投資建議**。價格／回測資料來源以 Yahoo 為主，被限流（429）時自動改用 Nasdaq 免金鑰歷史（美股最完整）。
+右下角常駐 **AI 助手**，會依目前頁面自動帶入上下文。
 
-### 建立知識庫（學習教材的前置步驟）
+### 總經儀表板
 
-學習教材與財報健檢的連結，來自 `emmy/` 的內容快照。`emmy/` 在 `web/` 之外，所以用建置腳本產生 `data/knowledge.json` 與 `data/notes.json`：
+- 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
 ```
 
-> `emmy/` 內容有更新時，重跑這個指令即可。若沒先執行，學習教材分頁會提示你建立。
+產出：
+
+- `data/knowledge.json` — 索引、分類、linkMap
+- `data/notes.json` — 全文（key = `kind:id`）
+
+`emmy/` 更新後重跑即可。未建置時學習頁會提示，且 `/api/health` 的 `knowledge: false`。
 
 ---
 
-## 專案結構
+## 環境變數
 
-```
+見 `.env.example`：
-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 → 渲染`
+| `FRED_API_KEY` | — | 必填（總經） |
-- 財報：`/api/fundamentals/:symbol → EDGAR/Yahoo → fincheck 規則 → 紅綠燈 JSON`
+| `PORT` | `3000` | 伺服器埠 |
-- 價格：`/api/price/:symbol → Yahoo/Nasdaq（DB 快取）→ 收盤線圖`
+| `CACHE_TTL_SECONDS` | `3600` | 總經整包快取 |
-- 回測：`/api/backtest/:symbol → 用快取歷史跑 backtest → 權益曲線 + 統計`
+| `FUND_SOFT_HOURS` | `12` | 財報軟 TTL |
-- 地圖：`/api/investmap → investmap 設定 + 知識庫原則 → 前端互動六層漏斗 → 可存成交易`
+| `FUND_HARD_DAYS` | `3` | 財報硬上限 |
-- 復盤：`/api/trades(.../stats) → SQLite trades 表 → 自動算損益與統計`
+| `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 序列（利率、通膨、就業、成長、貨幣信用等）。
+絕大多數指標對應 FRED 序列；黃金改用 Yahoo 期貨（FRED 無良好日線）。
-黃金因 FRED 無良好日線來源，改用 Yahoo Finance 期貨報價（伺服器端呼叫、免金鑰）。
 
-### 免費替代指標（畫面上會標示「替代」）
+### 免費替代指標（卡片標「替代」）
-有少數指標屬於付費／專有資料，無法免費取得，因此用公認的免費等價指標替代，並在卡片上明確標示：
 
-- **ISM 製造業 PMI** → 費城聯儲製造業景氣指數（`GACDFSA066MSFRBPHI`），大於 0 為擴張
+| 理想指標 | 替代序列 | 說明 |
-- **世界大型企業聯合會 消費者信心 CCI** → 密西根大學消費者信心指數（`UMCSENT`）
+|----------|----------|------|
-- **領先指標 LEI** → 紐約聯儲殖利率曲線衰退機率模型（`RECPROUSM156N`）
+| ISM 製造業 PMI | `GACDFSA066MSFRBPHI` | 費城聯儲製造業景氣 |
+| 世界大型企業聯合會 CCI | `UMCSENT` | 密西根消費者信心 |
+| 領先指標 LEI | `RECPROUSM156N` | NY Fed 衰退機率模型 |
 
-此外加入「工業生產年增（`INDPRO`）」作為實體經濟的補充指標。
+另含工業生產年增（`INDPRO`）作實體經濟補充。
 
----
+### 總經健康分數
 
-## 總經健康分數怎麼算？
+從 **50 分（中性）** 出發，依殖利率曲線、衰退機率、通膨、就業、信用利差等規則加減，限制 0–100。中性參考指標（美元、油價等）不計分。
 
-從 50 分（中性）出發，依殖利率曲線、衰退機率、通膨、就業、信用利差、金融條件、製造業、
+| 分數 | 燈號 |
-成長、波動率等規則加減分，最後限制在 0–100。每一條規則都會列在分數的「?」說明裡，
+|------|------|
-方向中性的指標（如美元、油價、股市本身）不計入分數，只作為參考。
+| ≥ 65 | 景氣穩健 |
+| 50–64 | 溫和成長 |
+| 35–49 | 景氣放緩 |
+| < 35 | 衰退風險高 |
 
-- 65 分以上：景氣穩健
+教學用簡化模型，**不構成投資建議**。
-- 50–64：溫和成長
-- 35–49：景氣放緩
-- 35 以下：衰退風險高
-
-> 這是教學用的簡化模型，**不構成任何投資建議**。
 
 ---
 
 ## 常見問題
 
-- **畫面顯示「設定 FRED 金鑰」？** 代表 `.env` 還沒設定或金鑰錯誤，照畫面步驟做即可。
+- **總經顯示要設定金鑰？** → AI 設定頁填 `FRED_API_KEY` 或編輯 `.env` 後重整。
-- **某些卡片顯示抓取失敗？** 個別序列偶爾延遲或維護，其餘仍是真實資料；按右上角「↻ 更新」可重抓。
+- **學習頁空白？** → 確認 `finance/emmy/emmy` 存在，執行 `npm run build:knowledge`。
-- **資料多久更新？** 後端快取 1 小時；FRED 多數指標本身就是每日／每週／每月更新。
+- **個股或卡片抓取失敗？** → 按「↻ 更新」；多數有 stale 回退。
+- **AI 沒帶頁面資料？** → 設定 provider + model，在對應視圖（個股／學習筆記）再開 AI 面板。
+- **要改指標或分數規則？** → 編輯 `lib/indicators.js`、`lib/score.js`，重啟 server。
+
+---
+
+## 免責聲明
+
+本專案所有內容、工具、AI 回覆、回測與統計**僅供個人學習與研究**，不構成投資、財務、稅務或任何專業建議。投資有風險，請以 FRED、SEC、Yahoo 等官方來源為準。過去績效不代表未來表現。