米赫瑪超吉情豹站 — Milkhama PawInfo Station
鋼嵐（Mecharashi）非官方WIKI — 資料庫查詢 · 配裝模擬器 · 攻略工具 · 版本時間軸
正式站：https://mecharashi.wiki
專案說明
本專案為鋼嵐（Mecharashi）遊戲的輔助工具站，提供玩家各類實用工具與資料庫查詢功能。
遊戲資料由管理後台人工建檔進 Firestore（圖片取自遊戲客戶端擷取的官方原檔），前台透過版本控制的快取層讀取，並經由 Cloudflare Worker 代理對外提供。
主要功能區塊：
- 資料庫：機師、機甲、武器、背包、模組、元件（含詳情頁與交叉引用）
- 配裝模擬器
/simulator：機體配裝與數值試算
- 科研設定
/research：神經驅動 / 科研配置
- 攻略工具
/tools、/guides：彩虹機規劃器、元件掉落查詢等
- 版本資訊
/news：改版時間軸與更新內容
- 文件站
/documents：專案技術文件與使用說明（由 docs/ 白名單複製而來）
- 個人中心 / 管理後台
/profile、/admin：資料編輯、變更歷史、系統日誌、使用統計
技術棧
| 層 | 內容 |
|---|
| 前端框架 | React 19 + TypeScript 6 |
| 建構工具 | Vite 8 |
| 樣式 | Tailwind CSS v4（CSS-first，無 tailwind.config.js）+ Floating UI |
| 路由 | React Router v7（basename={import.meta.env.BASE_URL}） |
| 後端 | Firebase Auth / Cloud Firestore / Storage |
| API 代理 | Cloudflare Workers（/api/*，同源掛在 mecharashi.wiki zone） |
| 部署 | GitHub Pages（自訂網域 + PR 預覽部署） |
| 資料蒐集 | 後台人工建檔 → Firestore；圖片由客戶端擷取匯入；台版官方公告由每週 CI 擷取 |
| 測試 | node --test（前端）、Vitest + @cloudflare/vitest-pool-workers（Worker）、Firebase Emulator（規則） |
架構重點
AuthProvider → GameDataProvider → ReferenceProvider
- AuthContext：Firebase Auth 登入狀態與角色，
AdminRoute 據此 gate /admin/*
- GameDataContext：全站遊戲資料的單一快取層（見下）
- ReferenceContext：實體引用（
EntityRef）的 hover 浮窗 / 釘選 / 手機 BottomSheet
2. 版本 gate 的三層資料快取
前台一律透過 src/hooks/useFirestore.ts 的 useXxx() hook 取資料，不直接呼叫 firestoreApi：
記憶體（本 session 已載入）
↓ miss
localStorage（mecharashi_gd_*，版本相符即可用）
↓ miss / 版本過期
Worker /api/data/:collection（或本機 dev 直連 Firestore）
版本來源為 meta/gameData，每集合一個版本號 + 全域 fallback；整個 session 只讀版本一次。
後台存檔後呼叫 bumpDataVersion(key) 讓所有 client 該集合快取失效。
用腳本批次改資料後，務必 bump 版本（node scripts/bump-data-version.mjs），否則使用者讀到舊快取。
3. Cloudflare Worker 代理（workers/）
公開遊戲資料不再由前端直連 Firestore，改打 /api/data/:collection。Worker 以 service account 走 Firestore REST 代讀，因此 Firestore 規則可收成僅管理員可讀，同時提供來源白名單與反爬守門。另有 /api/collect 收集匿名使用統計（含每日寫入預算與 kill switch）。
Worker 的 ARRAY_COLLECTIONS 必須與 GameDataContext 的 ALL_COLLECTION_KEYS 同步；漏一個 key 只會在正式站炸（本機 dev 直連 Firestore 看不出來）。
開發指令
npm install # 安裝依賴（postinstall 會設定 git hooks 與 commit template）
npm run dev # 開發伺服器（predev 先跑 generate-image-manifest + copy-docs）
npm run build # generate-image-manifest → copy-docs → tsc -b → vite build
npm run preview # 預覽 production build
npm run lint # ESLint
npm test # node --test，跑 src/**/*.test.ts
Firebase Emulator
npm run emu # 啟動 emulator（匯入/匯出 ./emulator-data）
npm run emu:fresh # 不匯入既有資料
npm run emu:seed # 灌入種子資料
npm run emu:slice # 匯出資料切片
npm run dev:emu # 前端連 emulator（--mode emulator）
npm run emu:test-rules # 驗證 Firestore 安全規則
資產與文件
npm run manifest:images # 掃 public/images/ 產生可用圖片清單
npm run images:webp # 圖片轉 WebP
npm run docs:copy # 依白名單把 docs/ 複製進 public/docs（route 為 /documents）
npm run docs:stamp # 為文件加上更新時間戳
資料與圖片
機師、機甲、武器等遊戲資料由後台（/admin）人工建檔；官網爬蟲已於 2026-10-11 退場。
node scripts/import-game-assets.mjs --id=<gameId> --art-key=<artKey> # 新機師官方原檔（預設 dry-run，加 --apply 才寫）
node scripts/import-game-assets.mjs --wap=<####> # 新機甲
node scripts/check-image-refs.mjs # 圖片引用掃描（壞路徑／舊路徑）
node scripts/bump-data-version.mjs <collection> # 用腳本寫入資料後務必 bump
Cloudflare Worker
cd workers
npm install
npm run dev # wrangler dev
npm test # vitest
npm run deploy # wrangler deploy（含 mecharashi.wiki/api/* route）
This is the beginning of the README. Read the rest at the original. Read the full README ↗
