Maintenance

維護指南（Maintenance）

面向維護者。核心：根 server.js 是 unified server（真正入口），同時服務 API 與 SPA。改東西前先確認你動的是後端 route、前端頁面、還是案例資料。

⚠️ README 與 CLAUDE.md 有 drift：以實際 package.json 與 CLAUDE.md 為準——script 是 install:all（冒號，非 install-all）、無 seed script、port 為 8080（非 README 寫的 5000）。

---

1. 環境與指令

需求：Node 16+、MongoDB。

npm run install:all      # 安裝 root + backend + frontend 依賴
npm run dev              # 後端 dev（nodemon，port 8080）
npm run dev:frontend     # 前端 Vite dev（port 5173）
npm run build            # 建置前端（cd frontend && npm install && npm run build）
npm start                # production（node server.js，port 8080）
cd frontend && npm run lint   # ESLint（**全 repo 唯一 lint/test tooling——無單元/E2E 測試**）

2. 環境變數

• 必要：MONGODB_URI（MongoDB 連線字串）
• 選用：PORT（預設 8080）、JWT_SECRET、CORS_ORIGIN（逗號分隔白名單；prod 未設則擋所有跨源）

3. Dev vs Prod API 連線

• Dev：Vite dev server 於 :5173；frontend/src/services/api.js 打 http://localhost:8080/api（可用 VITE_API_PORT 覆蓋）。要完整本地棧需同時跑後端 dev（8080）與前端 dev（5173）。
• Prod：前後端同源於 :8080（server.js 服務），前端以相對路徑 /api/* 呼叫（import.meta.env.PROD 分支）。

4. 架構 gotchas（改 code 前必讀）

• 改 *Fixed.js，不要改原始檔：backend/routes/cases.js 與 stats.js 仍存在但未掛載（server.js 掛的是 casesFixed.js / statsFixed.js）；改原始檔零效果。backend/server.js 也是 stale 未用入口（真正 server 是根 server.js）。
• 資料 route 用自開的原生 MongoClient，不是 Mongoose model：handler 內不要呼叫 Case.find()；每個 route 於 module load 非同步連線，並以 if (!db) return 500 防護。
• api.js 的 mockData.js fallback 是死碼（API_BASE_URL 恆 truthy，永不執行）。頁面若有資料但無成功 /api/* 呼叫，不是 mock 路徑造成，別誤判。
• helmet CSP 允許 blogspot/blogger iframe 且 frameguard:false 是刻意的（讓站可嵌 Blogger），勿還原。
• 中介層順序（server.js）：helmet → compression → CORS → rate limit（/api/* 200 req/15min）→ JSON parser → routes → 靜態檔 → SPA catch-all。
• statsFixed.js 有複雜的 $addFields/$switch/$regexMatch aggregation（禁賽期分類）。

5. 資料 seeding 與案例真實性

• backend/ 根目錄有 40+ 個一次性 seed/import 腳本（依年代 1980s/1990s EPO/2000s BALCO 與運動項目 MLB/NBA/舉重 組織），例：node backend/add_comprehensive_cases_batch1.js。
• 單一 collection cases。
• 案例真實性：新增/修正案例須走 案例真實性確認清單.md 流程；完整清單見 運動禁藥案例資料庫_完整清單.md（約 5,464 行）。改動案例資料要維持引用可追溯。

6. 部署（Zeabur）

• Multi-stage Dockerfile（frontend-build → backend-deps → production），unified server 同 port 服務 API + 靜態前端。
• zeabur.json 設 build/start 與 /api/health 健康檢查；以非 root（uid 1001）執行。
• MongoDB URI 必須在 Zeabur 環境變數設定。
• 有 /api/version 端點與 build 版本戳記，供部署後驗證 live build == HEAD。

7. 測試現況

目前無單元/E2E 測試框架（backend/test_db.js、test_route.js 是臨時腳本，非測試套件）。唯一自動化 tooling 是 frontend 的 ESLint。改後端 route 或 aggregation 後，暫時只能手動打 API 驗證。

8. 檔案結構速查

位置	職責
server.js（根）	unified server 真正入口（中介層 + route 掛載 + 靜態 + SPA）
backend/routes/*Fixed.js	實際掛載的 API route（改這些）
backend/models/Case.js	Case 資料模型（WADA 分類、index）
backend/data/*.json	education 內容（WADA 分類/測驗/專科）
backend/routes/tue.js	TUE 內容（inline 物件）＋ 藥物檢查器
backend/*（40+ 腳本）	一次性 seed/import/fix，非執行期程式
frontend/src/pages/	React 頁面（多為 lazy 載入）
frontend/src/services/api.js	API client（dev/prod 分支）
運動禁藥案例資料庫_完整清單.md / 案例真實性確認清單.md	案例內容與真實性來源