現實人生
單人大富翁遊戲，用一場人生（25 歲到老年）體驗財務決策，學習理財與資產分配。
- 前端：純 HTML / CSS / JavaScript（不需建置）
- 後端：Vercel Serverless Functions（
api/）
- 資料庫：Firebase Firestore（事件牌、每局抽牌紀錄、全服排行榜）
- AI 評分：Claude API（
claude-haiku-5-5）
瀏覽器 ──► Vercel（靜態網頁 + /api/*）──► Firestore
└──► Claude API
瀏覽器不會直接連 Firestore 或 Claude；所有金鑰只存在 Vercel 的環境變數裡。
設定步驟
1. Firebase（Firestore）
- 到 Firebase Console →「新增專案」（Google Analytics 可關閉）。
- 左側「建構 → Firestore Database」→「建立資料庫」→ 選 正式版模式（production mode），位置建議
asia-east1（台灣）。
- 「專案設定 ⚙ → 服務帳戶 → 產生新的私密金鑰」，下載 JSON 檔。
這個檔案等同資料庫的最高權限，不要放進專案資料夾或提交到 git。
- 把 JSON 轉成 base64（PowerShell）：
[Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\路徑\服務帳戶.json")) | Set-Clipboard
剪貼簿裡的字串就是下面要用的 FIREBASE_SERVICE_ACCOUNT。
- 部署安全規則（拒絕瀏覽器直接存取資料庫）：
firebase login
firebase use --add
npm run deploy:rules
2. Claude API
- 到 Claude Console → Settings → API Keys → 建立金鑰。
- 在 Billing 儲值，並建議設定每月消費上限（Limits）。
- 這把金鑰就是
ANTHROPIC_API_KEY。
3. 本機環境變數與匯入事件牌
npm install
複製 .env.example 為 .env.local，填入上面兩個值（.env.local 已在 .gitignore）。接著把 1,020 張事件牌上傳到 Firestore：
npm run import-cards
修改 docs/event-cards.md 後重新執行這行即可更新牌組；npm run import-cards:dry 只檢查格式、不上傳。
4. Vercel
vercel login
vercel link
vercel env add ANTHROPIC_API_KEY
vercel env add FIREBASE_SERVICE_ACCOUNT
（env add 時 Production、Preview、Development 三個環境都勾選。）
- 本機開發：
npm run dev（等同 vercel dev），開啟 http://localhost:3000
- 正式部署：
vercel --prod，或在 Vercel Dashboard 連結 GitHub repo，之後 push 到 main 就會自動部署
選填環境變數
| 變數 | 預設 | 說明 |
|---|
CLAUDE_MODEL | claude-haiku-5-5 | AI 評分使用的模型 |
EVAL_DAILY_LIMIT | 20 | 每位玩家每天最多 AI 評分幾局（控制 API 費用） |
AGENT_DAILY_LIMIT | 60 | 每位玩家每天最多和 AI 保險業務員對話幾則 |
ADVISOR_DAILY_LIMIT | 40 | 每位玩家每天最多問階段結束時的 AI 理專幾則 |
後端 API
| 方法 | 路徑 | 說明 |
|---|
| POST | /api/games | {jobId, playerId} → {gameId}，開始新的一局 |
| POST | /api/games/:id/draw | {kind: "chance"|"fate", stage} → {card}；該階段抽完回傳 404 exhausted |
| POST | /api/games/:id/draws/:cardId | {accepted}，記錄機會牌的選擇 |
| POST | /api/agent | {gameId, playerId, context, messages} → {reply, recommendations}，AI 保險業務員對話 |
| POST | /api/advisor | {gameId, playerId, context, messages} → {reply}，階段結束時的 AI 理專問答 |
| POST | /api/evaluate | {gameId, playerId, record} → {evaluation, rank}，Claude 評分並寫入排行榜 |
| GET | /api/leaderboard?playerId= | {top, me}：全服前 20 名（不含玩家 id，只標示自己）與自己的名次 |
Firestore 資料結構
| 集合 | 文件 | 內容 |
|---|
cardDecks | youth-chance 等 6 份 | 一整副牌（cards 陣列）；抽牌只需讀一份文件 |
games | 每局一份 | playerId、jobId、drawn（抽過的牌）、choices（機會牌選擇）、evaluation、score |
players | 每位玩家一份 | bestScore（個人最高分）、gamesEvaluated、每日評分次數 |
抽卡不重複
抽牌在 Firestore 交易（transaction） 中進行：讀取本局 drawn → 從剩下的牌隨機挑一張 → 寫回 drawn。兩次抽牌同時發生時，Firestore 會重試交易，保證同一局不會抽到重複的牌。
AI 評分與全服排名
- 遊戲結束後，結算頁呼叫
/api/evaluate。
- 伺服器用
js/score.js 的計分標準算分（和離線的本機評分同一套），再把分數明細、結算數據、玩家決策與伺服器記錄的抽牌與選擇交給 Claude，由 Claude 撰寫總結、決策回顧與建議（Structured Outputs 保證回傳格式）。
- 分數寫入
games 與 players.bestScore。
計分標準（100 分，不計入剩餘資產）
| 項目 | 配分 | 計算方式 |
|---|
| 壽命 | 20 | 結束年齡 ÷ 100 × 20 |
| 幸福指數 | 20 | 全程平均幸福 × 0.2 |
| 健康指數 | 20 | 全程平均健康 × 0.2 |
| 保險決策 | 20 | 保障缺口 8（醫療 35 歲前、重大疾病 40 歲前、意外 40 歲前、長照或年金 50 歲前投保得滿分，晚買得部分分數；舊保單不算）、保費占月薪 5–15% 得 4、醫療支出被理賠的比例 × 4、沒有停效 4 |
| 理財決策 | 10 | 保有 3 個月以上生活費的比例 × 4、投資 2 檔以上 3（1 檔 1.5）、沒被強制賣股也沒破產 3 |
| 保險知識 | 10 | 特殊格知識題答對率 × 10（沒遇到給 5 分） |
- 排名 = 個人最高分比你高的玩家數 + 1。
- 同一局只會評分一次；重新整理會直接回傳之前的結果。
- 已開啟 Claude 的 refusal fallback（
fallbacks: "default"）：若請求被安全分類器拒絕，會自動改用建議的備援模型。
無法連線伺服器（直接開啟 HTML、API 失敗、超過每日次數）時，結算頁會改用 js/ai.js 的本機規則評分，並標示「不列入排名」。
費用與限制（估計）
- Claude：每局評分約數千到一萬多個輸入 token 加上思考與輸出，約 US$0.05–0.15 一局；可用
EVAL_DAILY_LIMIT 與 Console 的消費上限控制。
- Firestore 免費額度：每天 5 萬次讀取、2 萬次寫入。每次抽牌約 1 讀 1 寫，一局約 100～200 次抽牌，免費額度大約可支撐每天 100 多局；超過需升級 Blaze（用量計費）方案。
- 防作弊：玩家 id 是瀏覽器裡的匿名 id，結算數據也由前端送出，有心人可以偽造分數。若要正式比賽，需改成伺服器端模擬或加入登入機制。
遊戲規則（目前數值）
- 一圈 60 格 = 5 年，一格 = 1 個月；三個人生階段共用同一圈，每走一格自動領薪並扣生活費
- 青年 25–40 歲（3 圈）→ 中年 40–65 歲（5 圈）→ 老年 65 歲以上
- 中年收入 ×1.3；老年改領退休金（月薪 70%，隨物價調整）；青年、中年每圈健康自然恢復（+5、+3），老年每圈 −2；幸福每圈 −3～−4，存款不到 3 個月生活費再 −6
- 每個人生階段結束（40、65 歲）與遊戲結束時，顯示「階段結算與檢討」（模板見
js/review.js），分三個分頁：結算（階段初／末成績單、保單、資產配置、健康幸福與緊急預備金）、檢討（依階段的檢核項目給 ✅⚠️❌ 與 A–D 等第、本階段理賠與最大支出）、理專建議（依未達成項目給建議與下一階段重點，可問理專最多 6 題；連得上伺服器時由 /api/advisor 的 Claude 回答，離線時常見問題改用模板回答）。遊戲結束時沒有理專分頁
- 平衡模擬：
node scripts/simulate.mjs 用「不做規劃」與「有做規劃」兩種策略各跑 2,000 局，統計失敗率（破產、幸福歸零、75 歲前健康歸零）。目前數值：不做規劃約 59%、有做規劃約 15%。調參數可用 --set economy.inflation=0.01 試算
- 幸福指數（0–100，起始 70）約等於心理健康：人際、休閒、壓力、悲傷等事件牌增減幸福，運動、飲食、疾病、受傷等增減健康（共 242 張牌由健康改為幸福，對照表在
docs/幸福指數對照表.md，由 scripts/happiness-cards.mjs 產生）
- 職業風險：
js/data.js 的 jobs[].risk 調整事件機率，例如外送員意外 ×2、工程師心血管 ×1.3、心理壓力 ×1.4；命運牌在伺服器端依此加權抽牌，重大疾病的發生率也會套用
- 職業事件：每個職業在青年、中年各有 6 張專屬牌（
docs/event-cards.md 第四篇，例如外送員摔車、老師聲帶結節、醫師醫療糾紛），只有該職業抽得到，權重為一般牌的 jobCardWeight（8）倍，約占抽牌的 15%
- 通膨與利息：物價每年上漲 2%，生活費、事件牌與住院費用跟著物價調整；薪資（含退休金）每圈只調升 1%；正的現金每月以年利率 1.5% 計息（
js/data.js 的 economy）
- 經濟劇本：股市依真實歷史事件的順序演出（網路泡沫 2000、SARS 2003、金融海嘯 2008、歐債 2011、中國股災 2015、新冠 2020、升息 2022、AI 熱潮 2023），每格有 30% 機率改成未來情境；事件會讓股價急跌再逐年回升，也可能影響現金、健康、幸福、物價與生病機率（
marketStory）
- 結束條件：現金歸零（破產，會先強制賣股）、健康歸零、幸福歸零（失去生活動力），或活到 100 歲
| 格子 | 數量 | 效果 |
|---|
| 起點 | 1 | 無 |
| 機會 | 19 | 抽機會牌，可接受或放棄 |
| 命運 | 16 | 抽命運牌，抽到即發生 |
| 保險業務員 | 5 | 和 AI 業務員對話（可提問、推薦險種並直接投保）；連不上伺服器時改為隨機介紹 3 種險種 |
| 住院 | 2 | 擲骰決定住院天數（點數 × 2 天），醫療費每天青年 1,000／中年 2,000／老年 3,000（再依物價調整），醫療險可理賠；下回合暫停移動 |
| 特殊格 | 9 | 保單健檢、觀念挑戰各 2 格；理財講座、貴人相助、保險優惠、保單整理日、錯過優惠各 1 格（js/data.js 的 specialTiles） |
| 休息（含 3 個角落） | 8 | 什麼事都沒發生 |
特殊格的現金獎懲依人生階段給不同金額（青年約為中年、老年的 1/5），並和事件牌一樣依物價調整（specialTiles）。保單健檢與觀念挑戰會出保險知識題（js/quiz.js，限時 20 秒）；保險優惠與錯過優惠在下一次投保時結算。股票漲跌顏色可在首頁設定切換（預設台股紅漲綠跌）。
事件牌共 1,020 張（各階段 300 張，另有青年、中年的職業事件 120 張），原稿在 docs/event-cards.md。
保險
十一種可投保險種與 5 種初始舊保單的數值都在 js/data.js 的 insurance，邏輯在 js/insurance.js。金額以「每月」、時間以「月」設定，遊戲再依每格月數換算。
| 險種 | 25 歲月繳 | 費率 | 繳費 / 保障 | 理賠 |
|---|
| 定期壽險 | 600 | 平準 | 繳到 65 歲 / 65 歲 | 身故 300 萬，計入「留給家人」 |
| 意外險 | 300（廚師、農夫 450；外送員 600） | 依職業 | 每圈續約 / 80 歲 | 意外醫療每次 3 萬、意外身故 300 萬 |
| 醫療險 | 800 | 自然（每圈依年齡調整） | 每圈續約 / 85 歲 | 醫藥費 80%，每次最多 15 萬 |
| 重大傷病險 | 700 | 平準 | 20 年 / 終身 | 癌症、心肌梗塞、中風、洗腎一次 100 萬 |
| 特定傷病險 | 500 | 平準 | 20 年 / 85 歲 | 心肌梗塞、中風、洗腎各 100 萬（不含癌症） |
| 癌症險 | 400 | 平準 | 20 年 / 終身 | 確診 50 萬，之後每月 1 萬共 12 個月 |
| 長照險 | 900 | 平準 | 20 年 / 終身 | 進入長照 3 個月後給付 30 萬，之後每月 3 萬 |
| 投資型保險 | 自選 3,000／5,000／10,000 | 彈性 | 可停繳 / 85 歲 | 帳戶跟著台灣50 ETF；身故 100 萬與帳戶價值取高 |
| 住院日額險 | 350 | 自然（每圈依年齡調整） | 每圈續約 / 85 歲 | 住院每天 2,000，每次最多 30 天（沒有天數的事件依醫藥費估算） |
| 終身壽險（分紅） | 980 | 平準 | 20 年 / 終身 | 身故 100 萬與解約金取高；解約金依累計保費 × 年度倍數（參考真實建議書） |
| 年金險 | 自選 3,000／5,000／10,000 | 2% 累積 | 繳到 65 歲 / 終身 | 65 歲起每月領年金，保證 20 年 |
-
初始保單：開局依機率抽保單類型（無 25%、基礎 35%／1 張、一般 30%／2 張、進階 10%／3 張），從舊保單池（小額終身壽險、舊型住院日額、學生團保延續意外險、舊型防癌險、手術險）抽不重複的已繳清保單；「保單整理日」特殊格再抽 1 張。
-
保險頁：右上角「保險」列出已投保保單與可投保險種（不分頁），可自己投保或解約。商品內容只寫在「產生建議書」（proposal.html）：正式文件版面（標楷體），依序為要保資料、重要事項說明（保險期間、猶豫期、等待期、保障範圍、給付方式、除外責任、但書、核保與停效）、逐年保費試算、聲明及簽章欄，可列印或另存 PDF。條款是 js/proposal.js 的固定模板，數字從 js/data.js 帶入、保費以公式試算，不呼叫 AI。
-
AI 業務員：踩到保險業務員格時開啟對話（/api/agent，Claude 依玩家年齡、職業、健康、病史、現有保單與報價回答），推薦以按鈕呈現，玩家按下才會投保；每次來訪最多問 6 題。
-
投保：其他年齡的保費線性內插；健康低於門檻拒保，低於 70 加費 30%（壽險 30–49 加費 60%）；有相關病史的險種拒保。
-
扣款：保費每月與生活費一起扣；現金不足有 1 個月寬限期，之後停效（投資型改停繳、年金險改為不再繳費）。保費超過月薪 10% 時提醒（雙十原則）。
-
疾病標籤：命運牌依 js/data.js 的 cardTags 分為意外、一般住院、癌症、心肌梗塞、腦中風、末期腎病，保險依標籤理賠。牌組裡的重大疾病很少，所以每回合另外依年齡與健康擲一次 majorIllness（會停薪數個月）。
-
長照：健康 ≤ 30 進入長照狀態，之後每月多 3 萬照護費。
-
身故：壽險、意外身故、投資型、年金險的給付計入結算的「留給家人」，不算玩家自己的淨資產；投資型與年金帳戶在其他結局計入淨資產。
檔案結構
api/ Vercel Serverless Functions
_lib/firebase.js Firebase Admin 初始化
_lib/decks.js 讀取牌組（含快取）
_lib/http.js 共用驗證與錯誤格式
games/index.js 建立遊戲
games/[id]/draw.js 抽牌（交易保證不重複）
games/[id]/draws/[cardId].js 記錄機會牌選擇
agent.js AI 保險業務員對話（推薦以 tool use 回傳）
advisor.js 階段結束時的 AI 理專問答
_lib/catalog.js 讓伺服器讀取 js/data.js 的險種資料
evaluate.js Claude 評分 + 排行榜
scripts/import-cards.mjs 事件牌匯入 Firestore（解析共用 scripts/lib/cards.mjs）
scripts/simulate.mjs 遊戲平衡模擬（無畫面版的回合流程）
js/score.js 計分標準（本機評分與伺服器評分共用）
js/review.js 人生階段結算與檢討的模板（檢核項目、理專建議、常見問答）
docs/event-cards.md 事件牌清單原稿
firestore.rules Firestore 安全規則（全部拒絕瀏覽器存取）
vercel.json Function 設定（評分最長 120 秒）
css/ js/ *.html 前端（js/world.js 產生不規則人生圈的地圖幾何，js/quiz.js 為保險知識題庫；遊戲頁拆成 js/game/ 底下的模組，說明見 js/game.js 開頭）
