feat: 獨立測驗模式 + 掌握度雲端教師鑽取 + 母港疊實景背景

[dofliu]

概述

收尾三項 ROADMAP「後續延伸候選」，對應 GAME_DESIGN.md §19。三者相互獨立、皆向後相容。

1. 獨立測驗模式（#exam）

把判斷型題庫抽成一份正式評量：

• 純函式引擎 src/state/exam.ts：buildExam（可決定性種子、跨類別 round-robin 均衡抽題、排除需輔助圖者以純文字公平作答）、gradeExam（A–F 等第／各類別對錯／錯題清單）、isCorrect/examGrade。
• ExamModal：固定 10/20 題、作答不給提示不揭示對錯，結束才公布總分＋各類別表現條＋錯題覆盤（揭示正解與教訓）。入口在 ⚙ 課程模式。
• RECORD_EXAM action：批次計入知識點掌握度＋錯題本（供主動回想），但不動 xp/answerStreak → 評量與遊戲經濟隔離。最佳成績 bestExam 存 records（只增不減、cloud union 取大），個人檔案頁顯示。

2. 掌握度雲端同步・教師端個別鑽取（#mastery-cloud）

• client：masterySummary/parseMasterySummary（只帶 n>0 的格、[n,ok] 元組、容錯解析）；存檔上傳夾帶掌握度摘要（ProgressSummary.mastery）；ClassRow 增讀選填 mastery。
• 教師面板：點任一學生列展開鑽取，沿用個人檔案頁同一套 masteryRows(disc/cat) 顯示各科別/類別正確率條與最弱項；無資料時優雅降級並提示需後端 v2.2。
• 後端 Code.gs v2.2：saves 新增第 9 欄 mastery（save 寫入、teacher 回傳）。需「新版本」重部署才會有鑽取資料；未升級時前端照舊運作（見 CLOUD_SETUP.md）。

3. 母港建設疊實境/漫畫背景（#port）

PortScene 依全域背景模式選底——實境→harbor.jpg、漫畫→comic_harbor.jpg，母港建設 sprite 疊其上＋下半暗化保可讀；模擬模式維持原 CSS 漸層（向後相容）。App→PortModal→PortScene 傳遞背景模式並顯示提示。呼應 §16「後續可把 PortScene 疊到母港實景背景」。

測試與驗證

• npm test：164 passed / 0 failed（新增 5 項：exam buildExam/gradeExam/RECORD_EXAM、masterySummary 往返、records bestExam）
• npm run typecheck / npm run build：通過
• Playwright 端到端實測（訪客登入 → 真實瀏覽器）：
  • 測驗流程：課程 → 獨立測驗 → 作答 10 題 → 結果頁（100% A、各類別對錯 7 類、個人最佳、錯題本整合提示）✅
  • 母港建設於實境模式疊 harbor.jpg 背景、hint 顯示「背景：實境」✅

變更檔案

• 新增：src/state/exam.ts、src/ui/ExamModal.tsx
• 邏輯：game.ts（RECORD_EXAM）、records.ts（bestExam）、mastery.ts（雲端摘要）、cloud/api.ts（ProgressSummary/ClassRow）、GameContext.tsx（上傳摘要）
• UI：CourseModal（測驗入口）、TeacherModal（鑽取）、PortScene/PortModal/App（疊實景）、ProfileModal（bestExam）
• 後端/文件：Code.gs(v2.2)、CLOUD_SETUP.md、GAME_DESIGN.md(§19)、ROADMAP.md、STATUS.yaml
• 測試：test/run.mjs

相容性 / 部署備註

• 純加法，無破壞性變更；既有存檔相容（bestExam/mastery 皆選填，舊檔預設空）。
• 教師端掌握度鑽取需將 Apps Script 後端更新至 v2.2 並「新版本」重部署；未升級時其餘功能不受影響。

🤖 Generated with Claude Code

https://claude.ai/code/session_01AC7ERcxjL7dhsYv9PncydP

---

Generated by Claude Code