From 7579a033ef5c35bc6ad7d19d4d25861e8740e39c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Jul 2026 19:05:27 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20=E5=B0=8D=E9=BD=8A=20README(?= =?UTF-8?q?=E4=B8=AD/=E8=8B=B1)/ROADMAP/HANDOFF=20=E2=80=94=20=E5=8F=8D?= =?UTF-8?q?=E6=98=A0=E8=BF=91=E5=85=A9=E8=BC=AA=E6=88=90=E6=9E=9C=E4=B8=A6?= =?UTF-8?q?=E7=B4=80=E9=8C=84=E5=BE=8C=E7=BA=8C=E6=8E=A5=E7=BA=8C=E5=B7=A5?= =?UTF-8?q?=E4=BD=9C?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit README.md / README.zh-TW.md: - 更新測試數 154→164、故障型錄「5 種」→「25 種、五大科別」。 - 戰情室補「人力短缺/罷工實效化」(缺工折抵現場作業面)。 - 教學設計補「獨立測驗模式」與「教師檢視面板＋掌握度個別鑽取」。 - 技術補「母港建設疊實境/漫畫背景」與 PWA/啟動安全網。 - 專案結構補 exam.ts/mastery.ts/records.ts、ExamModal/TeacherModal/PortModal、cloud/api.ts。 docs/HANDOFF.md: - 全面刷新:現況(main=PR #117、164 測試、dev branch 名)。 - 把 bearing/crew/exam/mastery-cloud/port 五項由「下一步候選」移到「已完成」。 - 重寫「後續接續工作」(立即可做/需後端/願景)並保留視覺驗證與模擬器蝴蝶效應備忘。 docs/ROADMAP.md: - 補 PR #116/#117 完成註記,更新測試數 154→164、複審日期。 - 新增「後續接續工作 — Next」接手清單章節。 Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01AC7ERcxjL7dhsYv9PncydP --- README.md | 24 +++++++---- README.zh-TW.md | 24 +++++++---- docs/HANDOFF.md | 109 ++++++++++++++++++++++-------------------------- docs/ROADMAP.md | 27 ++++++++++-- 4 files changed, 104 insertions(+), 80 deletions(-) diff --git a/README.md b/README.md index ced6737..5435473 100644 --- a/README.md +++ b/README.md @@ -23,8 +23,8 @@ An educational, *Uncharted-Waters*-style game that reframes offshore **wind-farm ### Gameplay loop - **One full work-order loop**: accept order → buy parts → mobilization-readiness check → sail out → board the tower → SCADA diagnosis quiz → SOP steps → finish / multi-day overhaul. - **Mobilization gate** — no teleporting: repair is locked until you've assigned a vessel, a matching-discipline engineer, the required part in stock and a weather window, then sailed out (travel time + boarding delay in rough seas). -- **Two-layer design** — a graded **7-mission campaign** (teacher opens it week by week) plus an always-open **Ops Center sandbox** that streams endless judgment situations and feeds the leaderboard. -- **Live Fleet Ops room** — every farm has **24 individual turbines**; dispatch engineers to parallel work orders, remote-reset soft faults, and run preventive inspections in real time. +- **Two-layer design** — a graded **7-mission campaign** (teacher opens it week by week) plus an always-open **Ops Center sandbox** that streams endless judgment situations and feeds the leaderboard, with a standalone **Exam Mode** on top for formal assessment. +- **Live Fleet Ops room** — every farm has **24 individual turbines**; dispatch engineers to parallel work orders, remote-reset soft faults, and run preventive inspections in real time. **Crew shortage / strike events bite for real**: a manpower shortfall cuts how many on-site work fronts you can run in parallel (not just a HUD number), recovering as the crew rests. - **First-time interactive onboarding tutorial** — the assistant **Lily** runs a hand-holding, mobile-game-style coach-mark walkthrough (spotlight the relevant button, dim the rest) through one complete work-order loop. Skippable, and replayable from the settings (⚙) menu. ### Decision support & learning loop @@ -44,12 +44,15 @@ An educational, *Uncharted-Waters*-style game that reframes offshore **wind-farm ### Teaching design - **Fault-diagnosis quiz + SOP** is the learning core: each fault is a SCADA alarm → 4-choice "what to check FIRST" quiz → 5-step SOP (first two pre-done: confirm weather window, LOTO lock-out). - **192-template judgment-task engine** across 7 categories (corrective / predictive / preventive / operational / weather / logistics / incident), most with trade-off choices, teaching feedback, and aid charts (trend / spectrum / radar). +- **Exam Mode** — a standalone, no-hint, single-attempt assessment that draws a balanced cross-category set (10 or 20 questions), grades A–F with a per-category breakdown and a miss-review, and feeds knowledge-point mastery & the mistake log **without** touching your game score. - **Codex** of cleared faults for revision, **Course Mode** for teachers (assign a week's fault, lock graded missions by week), knowledge-point tagging, and a **cloud class leaderboard** (free, no backend) via a Google Apps Script Web App with server-side validation; nickname + class-code login, per-user save isolation. +- **Instructor panel & mastery drill-down** — with a class + teacher code, read the whole class's latest progress (score / days / availability / generation), export CSV, and **click any student to drill into per-discipline / per-category accuracy** synced from the cloud (backend v2.2+). +- **Knowledge-point mastery & active-recall mistake log**, plus a per-discipline ability radar on the profile page. - **Bilingual (繁中 / English)**, character/dialogue system, procedural Web Audio SFX/BGM. ### Technical -- **Three background modes** — Simulation (animated CSS), Realistic (photos) and Comic (Uncharted-Waters illustrations); plus a 60° **aerial farm view**; turbines, vessels & substation rendered per scene on a 1600×900 scaling stage. -- Pure DOM/CSS UI (no game engine); art is layered SVG/CSS plus transparent PNG portraits. +- **Three background modes** — Simulation (animated CSS), Realistic (photos) and Comic (Uncharted-Waters illustrations); plus a 60° **aerial farm view**; turbines, vessels & substation rendered per scene on a 1600×900 scaling stage. In Realistic / Comic mode the **home-port build-out overlays a real harbour photo**, turning your upgrades into visible growth against a real backdrop. +- **PWA** (installable / offline), a mobile portrait layout, and a boot safety-net that prevents blank screens after an update. Pure DOM/CSS UI (no game engine); art is layered SVG/CSS plus transparent PNG portraits. ## Tech stack React 18 + TypeScript + Vite 6 + Tailwind CSS. Game state is a pure reducer (`src/state/game.ts`); persistence via localStorage with optional cloud save. @@ -60,7 +63,7 @@ npm install npm run dev # http://localhost:5173 npm run build # type-check + production build npm run typecheck # tsc --noEmit -npm test # dependency-free game-logic tests (test/run.mjs) — 154 passing +npm test # dependency-free game-logic tests (test/run.mjs) — 164 passing npm run sim # balance simulator: passive / active / full-crew strategies (test/sim.mjs) npm run stress # concurrency/load simulation for the cloud leaderboard backend (test/stress.mjs) ``` @@ -75,15 +78,18 @@ src/ │ ├─ farms.ts # 4 farms × 24 units each │ ├─ events.ts / incidents.ts # random events & fault catalogue (Fleet Ops) │ ├─ tasks.ts # 192-template judgment-task engine +│ ├─ exam.ts # Exam Mode engine (draw / grade, pure & deterministic) +│ ├─ mastery.ts / records.ts # knowledge-point mastery, achievements & bests │ └─ profile.ts / course.ts # login, class code, weekly unlock ├─ ui/ │ ├─ campaign.ts # 7-mission storyline (4 acts) -│ ├─ faults.ts # 5 fault types: quiz + SOP + part + discipline +│ ├─ faults.ts # 25 fault types across 5 disciplines: quiz + SOP + part │ ├─ data.ts # market parts catalogue │ ├─ screens/ # Hub / Market / Sail / Repair -│ ├─ FleetOpsModal / OpsCenterModal / FacilityModal # live ops, sandbox, facilities -│ └─ IntroRunner / TopBar / Portrait / Forecast # onboarding, HUD, dialogue, weather -├─ cloud/sheet.ts # Apps Script leaderboard client +│ ├─ FleetOpsModal / OpsCenterModal / ExamModal # live ops, sandbox, exam +│ ├─ TeacherModal / PortModal / FacilityModal # instructor drill-down, port build-out +│ └─ IntroRunner / TopBar / Portrait / Forecast # onboarding, HUD, dialogue, weather +├─ cloud/sheet.ts / cloud/api.ts # Apps Script leaderboard & cloud save / teacher client public/assets/ # characters, scenes, audio docs/ # design, manual, roadmap, walkthrough ``` diff --git a/README.zh-TW.md b/README.zh-TW.md index 05fb430..78d8e5b 100644 --- a/README.zh-TW.md +++ b/README.zh-TW.md @@ -23,8 +23,8 @@ ### 玩法循環 - **完整工單循環**：接單 → 備料 → 出勤就緒檢查 → 出海航行 → 登塔 → SCADA 診斷答題 → SOP 步驟 → 完工／多回合大修。 - **出勤就緒閘門** — 不能瞬移到風機：維修需先備妥船舶、對應科別技師、必備備品與天氣窗，並航行抵達（含航行時間、浪高登船延誤）。 -- **雙層架構** — 計分的**主線 7 關**（教師按週開放）＋永遠開放的**自由營運沙盒**（無限判斷型狀況、衝排行榜）。 -- **風場戰情室（即時營運層）** — 每座風場 **24 台個體機組**；即時派遣技師執行並行工單、遠端重啟軟性故障、執行預防性定檢。 +- **雙層架構** — 計分的**主線 7 關**（教師按週開放）＋永遠開放的**自由營運沙盒**（無限判斷型狀況、衝排行榜），另加獨立的**測驗模式**做正式評量。 +- **風場戰情室（即時營運層）** — 每座風場 **24 台個體機組**；即時派遣技師執行並行工單、遠端重啟軟性故障、執行預防性定檢。**人員短缺／罷工事件會真的影響決策**：缺工會折抵你能同時開的現場作業面（不只是 HUD 數字），並隨班組休整逐日回復。 - **首次互動式新手教學** — 助理**莉莉**以手機遊戲式的「聚光燈引導（coach-mark）」（高亮對應按鈕、其餘變暗）帶你走完一次完整工單循環；可跳過，並可從設定（⚙）選單重新播放。 ### 出海決策支援與學習迴路 @@ -44,12 +44,15 @@ ### 教學設計 - **故障診斷測驗 + SOP** 為學習核心：每個故障 = SCADA 告警 → 4 選 1「最先排查什麼」測驗 → 5 步 SOP（前兩步預設完成：確認天氣窗、LOTO 上鎖）。 - **192 題判斷型任務引擎**，七大類（故障搶修/監控判讀/預防保養/營運決策/天候處置/供應鏈人力/突發），多為取捨題＋教學回饋＋輔助圖（趨勢/頻譜/天氣雷達）。 +- **獨立測驗模式** — 跨類別均衡抽題（10 或 20 題）、**作答不給提示、單次作答**，結束才公布 A–F 等第、各類別對錯與錯題覆盤；計入知識點掌握度與錯題本，但**不影響遊戲分數**。 - **圖鑑**（已修故障複習）、**課程模式**（教師指派某週故障、按週鎖計分主線）、知識點標籤，以及**雲端班級排行榜**（免費免後端，Google Apps Script Web App＋伺服端防作弊）；暱稱＋班級碼登入、每人存檔獨立。 +- **教師檢視面板與掌握度鑽取** — 輸入班級碼＋教師碼即可唯讀檢視全班最新進度（分數／天數／可用率／發電量）、匯出 CSV，並可**點任一學生展開各科別／類別正確率鑽取**（雲端同步，後端 v2.2+）。 +- **知識點掌握度與錯題本主動回想**，個人檔案頁另有各科別能力雷達圖。 - **中英雙語**、人物對話系統、Web Audio 合成音效音樂。 ### 技術 -- **三種背景模式** — 模擬（會動 CSS）、實境（照片）、漫畫（大航海插畫）；另有 60° **俯瞰全景**；風機、船舶與變電站逐場景繪製，1600×900 等比舞台。 -- 介面為純 DOM/CSS（無遊戲引擎）；美術為 SVG/CSS 圖層加透明 PNG 立繪。 +- **三種背景模式** — 模擬（會動 CSS）、實境（照片）、漫畫（大航海插畫）；另有 60° **俯瞰全景**；風機、船舶與變電站逐場景繪製，1600×900 等比舞台。實境／漫畫模式下，**母港建設會疊在母港實景照片上**，把升級成果化為看得見的成長。 +- **PWA**（可安裝／離線）、手機直向精簡版面，以及防止更新後空白的啟動安全網。介面為純 DOM/CSS（無遊戲引擎）；美術為 SVG/CSS 圖層加透明 PNG 立繪。 ## 技術棧 React 18 + TypeScript + Vite 6 + Tailwind CSS。遊戲狀態為純 reducer（`src/state/game.ts`）；以 localStorage 存檔，可選雲端同步。 @@ -60,7 +63,7 @@ npm install npm run dev # http://localhost:5173 npm run build # 型別檢查 + 正式打包 npm run typecheck # tsc --noEmit -npm test # 免相依的遊戲邏輯測試（test/run.mjs）— 154 項全綠 +npm test # 免相依的遊戲邏輯測試（test/run.mjs）— 164 項全綠 npm run sim # 平衡模擬器：passive / active / full-crew 三策略（test/sim.mjs） npm run stress # 雲端排行榜後端的併發/負載模擬（test/stress.mjs） ``` @@ -75,15 +78,18 @@ src/ │ ├─ farms.ts # 4 座風場 × 每座 24 機組 │ ├─ events.ts / incidents.ts # 突發事件與故障型錄（戰情室） │ ├─ tasks.ts # 192 題判斷型任務引擎 +│ ├─ exam.ts # 測驗模式引擎（抽題／判分，純函式、可決定性） +│ ├─ mastery.ts / records.ts # 知識點掌握度、成就與最佳紀錄 │ └─ profile.ts / course.ts # 登入、班級碼、每週開放 ├─ ui/ │ ├─ campaign.ts # 主線 7 關（四幕） -│ ├─ faults.ts # 5 種故障：測驗 + SOP + 備品 + 科別 +│ ├─ faults.ts # 25 種故障、五大科別：測驗 + SOP + 備品 │ ├─ data.ts # 交易所備品型錄 │ ├─ screens/ # 母港 / 交易所 / 出海 / 維修 -│ ├─ FleetOpsModal / OpsCenterModal / FacilityModal # 戰情室、沙盒、設施 -│ └─ IntroRunner / TopBar / Portrait / Forecast # 新手教學、HUD、對話、天氣 -├─ cloud/sheet.ts # Apps Script 排行榜用戶端 +│ ├─ FleetOpsModal / OpsCenterModal / ExamModal # 戰情室、沙盒、測驗 +│ ├─ TeacherModal / PortModal / FacilityModal # 教師鑽取、母港建設、設施 +│ └─ IntroRunner / TopBar / Portrait / Forecast # 新手教學、HUD、對話、天氣 +├─ cloud/sheet.ts / cloud/api.ts # Apps Script 排行榜與雲端存檔／教師用戶端 public/assets/ # 角色、場景、音訊 docs/ # 設計、手冊、藍圖、攻略 ``` diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index c897c27..b792fa0 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -1,63 +1,54 @@ # 交接紀錄 — Session Handoff -> 給下一個開發 session 的快速接手筆記。最後更新:**2026-07-08**。 -> 完整藍圖見 [ROADMAP.md](ROADMAP.md);設計權威版見 [GAME_DESIGN.md](GAME_DESIGN.md) §17;專案現況見 `../STATUS.yaml`;測試紀錄見 [TEST_REPORT.md](TEST_REPORT.md)(注意:該檔測試數為較早快照,以 `npm test` 實跑為準)。 +> 給下一個開發 session 的快速接手筆記。最後更新:**2026-07-10**。 +> 完整藍圖見 [ROADMAP.md](ROADMAP.md);設計權威版見 [GAME_DESIGN.md](GAME_DESIGN.md)(§17 出海決策/§18 人力・軸承/§19 測驗・掌握度・母港);專案現況見 `../STATUS.yaml`。 +> 測試數以 `npm test` 實跑為準(目前 **164**);判斷任務題數以 `TASKS.length` 為準(**192**)。 ## 目前狀態 -- `main` 為最新;所有功能皆已合併(最新:PR #114)。`npm test` = **154 全綠**,typecheck / build 乾淨。 -- `npm run sim`(平衡)、`npm run stress`(併發)皆通過;`npm run sim` 建議在下次改動經濟數值後重跑一次(本輪修正了 sensor/pitch 備品與每日任務發獎時機)。 -- 開發分支:`claude/screen-loading-after-update-1wnuss`(每次 PR 合併後從最新 `main` reset 同步)。 -- GitHub Pages 部署來源已鎖定為 **GitHub Actions**(`deploy.yml` 內 `actions/configure-pages`,`enablement: true`);若日後又被誤切回「Deploy from a branch」,下次部署會自動修正回來。**切勿用 Actions 頁面的「Re-run」重跑 Pages 部署**——會觸發「重複 github-pages artifact」錯誤,要重部署請用 `Run workflow` 開新的一次。 - -## 本階段(本輪)已完成 - -### A. 出海決策支援(讓玩家判斷「出不出海」「要不要撤」) -1. **出海前工期預估 vs 天氣窗**(`SailScreen`):航線/登船/檢查/維修的預估耗時 vs `workWindowMax()`(與現場維修共用同一公式),算出「保留餘裕」;附磨耗/疲勞/天氣窗擇日的判斷提醒。 -2. **半途成果保留(#carry,`REPLAN_RETURN`)**:審慎返港 = 進 1 天、不計安全事件、已完成的診斷/SOP 進度保留(擇日續修)。與「作業窗關閉才撤離」(`FAIL_REPAIR` = 進度全失+計安全事件)明確區隔。 -3. **加班搶修(#rush,`RUSH_SOP`)**:維修不利時第三選項——剩餘 SOP 一次趕完、耗時減半,但 25%(`RUSH_RISK`)機率安全近失事件。「搶修(快、險)vs 續作(穩)vs 返港(慢、保進度)」三選一。 - -### B. 學習迴路收斂 -4. **任務復盤(#debrief)**:完工給星級(依餘裕/答錯扣星)+ 量化摘要 + 一句 takeaway。 -5. **診斷連對 streak(#streak)**:`GameData.answerStreak`,首次作答連對 +1、答錯歸零,每次答對加 XP(封頂 10);維修診斷與營運中心皆顯示 🔥 徽章。 -6. **錯題本主動回想**:複習前先自我測驗(隱藏正解、二選一),答完才揭曉正解+教訓再寫檢討——比只看反思更利記憶保留。 - -### C. 無障礙 + 遊戲手感 -7. **減少動態**:`useReducedMotion()` 尊重系統 `prefers-reduced-motion`,個人檔案頁也可手動開關(localStorage 覆寫 + body class);場景影片改靜態首幀、CSS 動畫停用。 -8. **色覺友善雙重編碼**:海象預報改圖示(☀/⛅/🌀)、戰情室故障格加 ⚠ 徽章,不只靠顏色。 -9. **Juice**:完工/連對里程碑 toast、Toaster 改小佇列(不再互相蓋掉)、TopBar 預算增減短暫變色。 -10. **戰情室 SLA 季末風險 + 母港預算續航**提醒(inline,取代純輪播)。 - -### D. 內容系統全面查核與修正(事件/案例/任務/故障 × 消費端交叉驗證) -11. **每日任務改為日結算**(`DailyDef.deferred`):「零安全事件/健康度/妥善率」等維持型任務原本在 `ROLL_DAILY` 當下即可能為真 → 立即發獎(開局白拿);改為僅在隔日 roll **前**結算,須撐過一整天。 -12. **安全事件數夾 0**:`RESOLVE_TASK` 的 `dSafety` 負值(改善型選項)原本可把 `safetyIncidents` 打成負數 → `computeScore` 反向加分,可重複刷分。已夾底。 -13. **備品資料修正**:`sensor` 誤耗發電機碳刷→改風速計;`pitch`/`pitch_fault`(quiz/SOP 都在講後備電池)誤耗液壓油→改變槳後備電池。 -14. **主線防卡**:交易所預設依 Tier 過濾,但進行中工單的必備備品**永遠可見**。 -15. **移除 3 組重複任務模板**(`b_harmonics`/`g_medical_evac`/`c_dehumidify`);1 則案例研究「正解」誤植安全事件已修正;`yaw_motor`/`gen_brush` 展示庫存 0 的誤導修正。 -16. **已查核確認乾淨**:quiz 索引、跨檔 id 引用(incidents/faults/cases/parts)、i18n 完整性(zh/en 皆有)、Tier 閘門(無「故障出現但備品鎖住」)、派工守衛一致性、事件權重加總、案例去重。 - -### E. 部署基礎設施 -17. **Pages 部署硬化**:`deploy.yml` 加 `actions/configure-pages`(`enablement: true`)鎖定發佈來源;`concurrency.cancel-in-progress` 改 `false`。修復了「Pages 來源被切回分支模式,線上端出未 build 原始碼(index.html 指向 /src/main.tsx、整頁 404)」的事故。 - -## 下一步候選(未做,依需要程度排序) - -### B1. 設計決定後即可做(免後端) -- **bearing 類故障備品命名/Tier 重新設計** — `bearing`(主軸承振動)與 `gen_vibration`(發電機軸承磨損)目前共用 `pitch_bearing`(變槳軸承,權宜規避 Tier 閘門)。建議新增 Tier 3「發電機/主軸軸承」備品並重新指派 `part`;需確認對 Tier 3 經濟平衡的影響。 -- **crew_shortage / strike 事件實效化** — 目前只調整展示用 `techAvail`,`OPS_DISPATCH` 並不讀取此值,事件形同純展示。建議接上技師疲勞加成,或在派工時檢查可用人力上限。 -- **文件內殘留的舊統計數字** — `docs/TEST_REPORT.md`(140 項測試)、`docs/MANUAL.zh-TW.md`/`docs/WALKTHROUGH.md`(151 題判斷任務)為較早版本快照,本輪只更新了 README/ROADMAP/GAME_DESIGN/STATUS,這幾份文件下次一併校正為 `npm test`(154)/`TASKS.length`(192)實跑值。 -- **平衡回測**——本輪重跑 `npm run sim` 後,`active` 策略的妥善率數字與先前記錄不同(83%→67%)。已確認**非數值失衡**:`advance()` 的倉儲折舊迴圈依 `Object.entries(inventory)` 的**插入順序**逐一擲骰(`Math.random() < SPOIL_CHANCE`),而 sensor/pitch 的備品 id 變更改變了 inventory 物件的 key 順序,連帶讓固定種子(`mulberry32(20260622)`)重播出的隨機序列整段分岔(蝴蝶效應)。三策略排序(passive ≪ active ≪ full-crew)與健康度仍正常,判定為模擬器對「內容資料變更」的已知副作用,非迴歸;下次調整故障/備品資料後,預期 `npm run sim` 的絕對數字仍會因同樣原因跳動,只需確認**相對排序與梯度健康**,不必追求絕對數字穩定。 - -### 需後端(要先重新部署 Apps Script `docs/leaderboard-appsscript/Code.gs`) -- **教師端個別學生能力雷達鑽取** — 把 `GameData.mastery` 隨送分/存檔上雲(`src/cloud/sheet.ts` payload + `Code.gs` 多存一欄)→ `TeacherModal.tsx` 點學生展開 → 重用 `RadarChart.tsx`。建議只存彙整(各 disc 的 n/ok)而非整包。 -- **獨立測驗模式 Exam Mode** — 教師發布測驗、作答中隱藏即時回饋、結束生成診斷報告並同步教師端;動態參數(數值/價格隨帳號種子變動)防抄襲(可重用 `accountSeed()`)。 - -### 免後端、較小 -- 母港 `PortScene` 疊到母港實景背景(目前僅在 PortModal 預覽)。 -- 戰情室停機折抵「現金」收入的設定開關(目前只折抵淨發電)。 -- 無障礙延伸:鍵盤操作、更全面的色盲友善配色審查、對話/音效字幕。 - -## 開發備忘 -- **每次改版請把 `public/sw.js` 的 `CACHE = "wfg-cache-vN"` 版本號 +1**(避免更新後舊快取殘留造成空白;目前 **v6**)。 -- 新功能務必在 `test/run.mjs` 補對應測試(純資料/reducer 為主);新 reducer action 記得也加進 `test/run.mjs` 的 fuzz 動作池(`randomAction`)。 -- 視覺驗證:`npm run build` → 將 `dist/` 放到 `serve/windFarm-Go/` 以 `python3 -m http.server` 提供 → 用 `playwright-core` + 預裝 Chromium 截圖;guest 存檔 key = `windfarm-go-save::/guest1`。 -- 指令:`npm test`(單元 154)、`npm run sim`(平衡)、`npm run stress`(併發)、`npm run build`、`npm run live-check`(線上後端,需本機跑;沙盒代理擋 script.google.com)。 -- 內容資料若新增/修改故障(`incidents.ts`/`faults.ts`)、備品(`data.ts`)或任務模板(`tasks.ts`),務必交叉檢查:`part` 是否存在於 `PARTS`、`discipline` 是否與 UI 呈現一致、`minTier` 是否形成「故障可見但備品鎖住」的閘門矛盾——本輪查核就是靠這套交叉驗證抓到多筆歷史資料誤植。 +- `main` 為最新;所有功能皆已合併(最新:**PR #117**)。`npm test` = **164 全綠**,`npm run typecheck` / `npm run build` 乾淨。 +- `npm run sim`(平衡)、`npm run stress`(併發)皆通過。⚠ `npm run sim` 的**絕對數字**會隨故障/備品/任務資料變動而整段跳動(見下「模擬器蝴蝶效應」),回測時只需確認**相對排序**(passive ≪ active < full-crew)與梯度健康,不必追求絕對值穩定。 +- 開發分支:**`claude/wind-farm-game-dev-ik3kt7`**(每次 PR 合併後從最新 `main` reset 同步,沿用同名分支)。 +- GitHub Pages 部署來源已鎖定為 **GitHub Actions**(`deploy.yml` 內 `actions/configure-pages`,`enablement: true`);若日後又被誤切回「Deploy from a branch」,下次部署會自動修正。**切勿用 Actions 頁面的「Re-run」重跑 Pages 部署**(會觸發「重複 github-pages artifact」錯誤);要重部署請用 `Run workflow` 開新的一次。 + +## 最近兩輪已完成 — Recently shipped + +### PR #116 — 邏輯完整性(把「純展示」事件接上機制) +1. **人力短缺/罷工事件實效化(#crew,`crewShortfallJobs`/`effectiveJobCapOf`)**:`crew_shortage`(−3)/`strike`(−6) 原本只調整展示用 `techAvail`,`OPS_DISPATCH`/`OPS_INSPECT` 不讀 → 事件形同純展示。現在缺工**直接折抵戰情室「可同時開的現場作業面」**:`effectiveJobCapOf = max(1, jobCapOf − ⌈(techTotal−techAvail)/CREW_PER_JOB⌉)`(`CREW_PER_JOB=4`)。滿編不懲罰、下限 1(短手仍可派一組、遠端重啟不占名額、主線不受限)、每日休整回復;開局改滿編 30/30、tech 升級同步 techAvail;`FleetOpsModal` 顯示缺工折抵。 +2. **軸承備品正名(#bearing,`drive_bearing`)**:主軸承振動(`bearing`)與發電機振動(`gen_vibration`)原本權宜共用「變槳軸承」(`pitch_bearing`)。新增 Tier 3「傳動軸承組(發電機/主軸)」(`drive_bearing`, ◎130 萬)並重新指派,與 Tier 4 主軸承全換(`main_bearing`)語意區隔;新增 `pitch_bearing_wear` 事件讓 `pitch_bearing` 保有真實消費端(呼應 `cs_pitch_bearing_wear` 案例),不成孤兒。 + +### PR #117 — 三項延伸候選收尾 +3. **獨立測驗模式(#exam,`state/exam.ts` + `ui/ExamModal.tsx`)**:跨類別均衡抽題(round-robin、排除需輔助圖者)、固定 10/20 題、**作答不給提示不揭示對錯**,結束才公布 A–F 等第/各類別對錯/錯題覆盤。純函式引擎 `buildExam`(可決定性種子)/`gradeExam`;作答經 **`RECORD_EXAM`** 批次計入掌握度與錯題本,但**不動 xp/answerStreak**(評量與遊戲經濟隔離);最佳成績 `bestExam` 存 records、個人檔案頁顯示。入口在 ⚙ 課程模式。 +4. **掌握度雲端同步・教師端個別鑽取(#mastery-cloud)**:存檔上傳夾帶掌握度精簡摘要(`masterySummary`/`parseMasterySummary`,只帶 n>0 的格、`[n,ok]` 元組);`TeacherModal` 點學生列展開,沿用 `masteryRows(disc/cat)` 顯示各科別/類別正確率條。**向後相容**(舊後端不回傳 → 優雅降級)。⚠ **需重新部署後端**:`Code.gs` 已升級 v2.2(`saves` 第 9 欄 `mastery`,`teacher` 回傳),見「後續接續工作」與 [CLOUD_SETUP.md](CLOUD_SETUP.md)。 +5. **母港建設疊實境/漫畫背景(#port)**:`PortScene` 依全域背景模式選底——實境→`harbor.jpg`、漫畫→`comic_harbor.jpg`,建設 sprite 疊其上+下半暗化保可讀;模擬維持原 CSS 漸層(向後相容)。App→PortModal→PortScene 傳遞背景模式並顯示提示。 + +> 驗證:兩輪皆 `npm test`(164)/typecheck/build 通過;PR #117 兩個視覺功能另以 **Playwright + 預裝 Chromium** 端到端截圖實測(測驗跑到結果頁、母港於實境模式疊 `harbor.jpg`)。 + +--- + +## 後續接續工作 — Next(給下一個 session) + +依「立即可做 → 需後端 → 願景」排序。細節與設計脈絡見 [ROADMAP.md](ROADMAP.md)「後續接續工作」段與 [GAME_DESIGN.md](GAME_DESIGN.md)。 + +### 立即可做(免後端) +- **戰情室停機折抵「現金」收入的設定開關** — 目前停機只折抵淨發電(少賺+扣分);提供設定把戰情室層也接入售電現金流(需與設計者確認經濟平衡)。 +- **每機獨立健康度 / RUL 預測性維護** — 由全場 `fleetHealth` 延伸到每台機組的健康指標與剩餘壽命(Remaining Useful Life)建模,深化 CBM/預測性維護教學。中大型工作,建議先出設計草案再動手。 +- **無障礙延伸** — 鍵盤操作(Tab/Enter 走完工單循環)、更全面的色盲友善配色審查、對話/音效字幕與旁白。 +- **文件內殘留舊統計校正** — `docs/TEST_REPORT.md`(舊記 140/154 項)、`docs/MANUAL.zh-TW.md`、`docs/WALKTHROUGH.md`(舊記 151 題)為較早快照;本輪已對齊 README/ROADMAP/GAME_DESIGN/STATUS/HANDOFF,這三份下次一併校正為 `npm test`(164)/`TASKS.length`(192)實跑值。 + +### 需後端(先重新部署 Apps Script `docs/leaderboard-appsscript/Code.gs`) +- **⚠ 啟用教師端掌握度鑽取(唯一的部署待辦)** — client 與 `Code.gs` v2.2 皆已就緒且向後相容,但要讓教師面板**看到鑽取資料**,需把後端更新到 v2.2 並在「管理部署作業 → 編輯 → 版本:**新版本**」重部署(見 [CLOUD_SETUP.md](CLOUD_SETUP.md) v2.2 段)。未部署時前端一切照舊、教師面板顯示「尚無掌握度資料」提示。 +- **Exam Mode 進階版(教師發布 + 雲端報告)** — 目前為**本機評量**(不上雲、不影響遊戲分)。進階:教師發布指定測驗、結束生成診斷報告並同步教師端、動態參數(數值/價格隨帳號種子變動)防抄襲(可重用 `accountSeed()`)。 +- **掌握度鑽取改雷達視覺** — 教師端目前以長條呈現各科別正確率;可重用 `RadarChart.tsx` 改成能力雷達(與個人檔案頁一致)。 + +### 願景(未排程 / speculative) +- 多人 / 班級競賽賽季(限時、合作或對抗)、CC0 實體音樂與各地點專屬美術、**內容編輯器**(教師以資料驅動新增故障/題目/週次,免改程式碼)。 + +--- + +## 開發備忘 — Dev memos +- **改動 app 程式碼/資產時,把 `public/sw.js` 的 `CACHE = "wfg-cache-vN"` 版本號 +1**(避免更新後舊快取殘留造成空白;目前 **v6**)。純文件變更不需動。 +- 新功能務必在 `test/run.mjs` 補對應測試(以純資料/reducer 為主);新 reducer action 也加進 fuzz 動作池(`randomAction`)。純函式引擎(如 `exam.ts`)最好給可決定性種子測試。 +- **視覺驗證流程**:`npm run build` → 把 `dist/` 以 symlink 掛成 `/windFarm-Go/`(base 是 `/windFarm-Go/`)→ `python3 -m http.server` 提供(比 `vite preview` 在無頭瀏覽器下穩) → 用 **`playwright-core`** + 預裝 Chromium(`executablePath: /opt/pw-browsers/chromium-1194/chrome-linux/chrome`,`PLAYWRIGHT_BROWSERS_PATH=/opt/pw-browsers`)截圖;`newContext({ serviceWorkers: "block" })` 避免 SW 干擾。guest 登入點「訪客試玩」;背景模式存於 `localStorage['wfg-mode']`(sim/real/comic)。 +- 指令:`npm test`(單元 164)、`npm run sim`(平衡)、`npm run stress`(併發)、`npm run build`、`npm run typecheck`、`npm run live-check`(線上後端;沙盒代理擋 script.google.com,需本機跑)。 +- **內容資料交叉驗證**:新增/改故障(`incidents.ts`/`faults.ts`)、備品(`data.ts`)、任務(`tasks.ts`)時務必檢查:`part` 是否存在於 `PARTS`、每個備品是否有消費端(避免孤兒)、`discipline` 是否與 UI 一致、`minTier` 是否形成「故障可見但備品鎖住」的閘門矛盾——`test/run.mjs` 已含這套不變式測試(如 incident.part tier ≤ incident tier)。 +- **模擬器蝴蝶效應(已知、非迴歸)**:`advance()` 的倉儲折舊迴圈依 `inventory` 物件的**插入順序**逐一擲骰;只要備品 id 集合或順序變,固定種子(`mulberry32(20260622)`)重播的隨機序列就整段分岔,`npm run sim` 絕對數字隨之跳動。回測看**相對排序與梯度**即可。 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 76960fd..cfa2482 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -2,7 +2,7 @@ > 以 zh-TW 為主、English secondary。本藍圖依現況（[STATUS.yaml](../STATUS.yaml)、[GAME_DESIGN.md](GAME_DESIGN.md)）盤點已完成與待辦，並提出**規劃方向**。 > ⚠ 標示為**規劃中／推測（speculative）**者尚未實作，請勿當成現況；本文為**規劃**而非承諾。 -> Lead with zh-TW; English summaries follow. Last reviewed: 2026-07-08. +> Lead with zh-TW; English summaries follow. Last reviewed: 2026-07-10. --- @@ -27,7 +27,28 @@ - 已查核確認乾淨：quiz 索引、跨檔 id 引用、i18n 完整性、Tier 閘門、派工守衛一致性、事件權重、案例去重。 - **Pages 部署硬化**：`deploy.yml` 新增 `actions/configure-pages`(鎖定發佈來源為 GitHub Actions，避免誤切回「Deploy from a branch」導致線上端出未 build 原始碼)；`concurrency.cancel-in-progress` 改 false。 -**本輪續作已完成（原留待下次的兩項）**：bearing 類故障備品正名（新增 Tier 3「傳動軸承組」`drive_bearing`，主軸承振動/發電機振動不再權宜共用「變槳軸承」，並補 `pitch_bearing_wear` 事件避免孤兒備品）；`crew_shortage`/`strike` 事件實效化（缺工直接折抵戰情室「可同時開的現場作業面」，滿編不懲罰、下限 1、可休整回復）。詳見 [GAME_DESIGN.md](GAME_DESIGN.md) §18。 +**續作已完成（PR #116，原留待下次的兩項，見 §18）**：bearing 類故障備品正名（新增 Tier 3「傳動軸承組」`drive_bearing`，主軸承振動/發電機振動不再權宜共用「變槳軸承」，並補 `pitch_bearing_wear` 事件避免孤兒備品）；`crew_shortage`/`strike` 事件實效化（缺工直接折抵戰情室「可同時開的現場作業面」，滿編不懲罰、下限 1、可休整回復）。 + +**再一輪已完成（PR #117，收尾三項延伸候選，見 §19）**：**獨立測驗模式**（跨科別均衡抽題、無提示單次作答、A–F 等第＋各類別對錯＋錯題覆盤；`RECORD_EXAM` 計入掌握度與錯題本但不動遊戲分數）；**掌握度雲端同步・教師端個別鑽取**（存檔夾帶掌握度摘要、後端 `Code.gs` v2.2 存/回、教師面板點列展開各科別正確率，向後相容）；**母港建設疊實境/漫畫背景**（`PortScene` 依背景模式疊 `harbor.jpg`/`comic_harbor.jpg`）。 + +--- + +## 後續接續工作 — Next（給下一個 session 的接手清單） + +> 依「立即可做 → 需後端 → 願景」排序；交接細節見 [HANDOFF.md](HANDOFF.md)。 + +**立即可做（免後端）** +- **戰情室停機折抵「現金」收入的設定開關** — 目前停機只折抵淨發電；提供設定把戰情室層接入售電現金流（需確認經濟平衡）。 +- **每機獨立健康度 / RUL 預測性維護** — 由全場 `fleetHealth` 延伸到每台機組健康指標與剩餘壽命建模，深化 CBM／預測性維護教學（中大型，建議先出設計草案）。 +- **無障礙延伸** — 鍵盤操作、更全面色盲配色審查、對話／音效字幕與旁白。 +- **舊文件統計校正** — `docs/TEST_REPORT.md`、`docs/MANUAL.zh-TW.md`、`docs/WALKTHROUGH.md` 內殘留的舊測試數/題數，下次校正為 `npm test`(164)／`TASKS.length`(192)。 + +**需後端（先重新部署 Apps Script `Code.gs`）** +- **⚠ 啟用教師端掌握度鑽取（唯一部署待辦）** — client 與 `Code.gs` v2.2 皆就緒且向後相容；要讓教師面板**顯示鑽取資料**，需把後端更新到 v2.2 並「**新版本**」重部署（見 [CLOUD_SETUP.md](CLOUD_SETUP.md)）。未部署時前端照舊、教師面板顯示「尚無掌握度資料」。 +- **Exam Mode 進階版（教師發布＋雲端報告）** — 目前為本機評量；進階為教師發布指定測驗、結束生成報告並同步教師端、動態參數防抄襲。 +- **掌握度鑽取改雷達視覺** — 教師端目前用長條，可重用 `RadarChart.tsx` 改雷達。 + +**願景（未排程）**：多人／班級競賽賽季、CC0 音樂與各地點美術、內容編輯器（教師資料驅動新增故障）。 --- @@ -59,7 +80,7 @@ - **直升機進場 / 電網限電真實權衡任務**：自由營運沙盒新增 8 題真實運維判斷——直升機吊掛進場(封船海象/遠海急件/作業限值/成本效益)與電網限電(負電價降載/限電補償/低電壓穿越 FRT/順勢維修)。 *Real-ops tradeoffs: helicopter access & grid-curtailment judgment tasks.* - **呈現**：三模式背景（模擬/實境/漫畫）、60° 俯瞰、多場景登塔（機艙/塔架/輪轂/甲板，含實景/漫畫情境圖與出海/大修場景影片）、Web Audio 音效音樂、中英雙語。母港左側「設施／風場動態」面板可各自獨立收合，設施項目皆有專屬圖示（含技師人物立繪）。 -- **工程**：自動化測試 `npm test`（154 項）、平衡模擬器 `npm run sim`、併發壓力測試 `npm run stress`、PR CI（typecheck/test/build）。完整系統測試紀錄見 [TEST_REPORT.md](TEST_REPORT.md)（測試數為本文撰寫時的既有紀錄，隨版本增加，以 `npm test` 實跑結果為準）、壓測細節見 [STRESS_TEST.md](STRESS_TEST.md)。 +- **工程**：自動化測試 `npm test`（164 項）、平衡模擬器 `npm run sim`、併發壓力測試 `npm run stress`、PR CI（typecheck/test/build）。完整系統測試紀錄見 [TEST_REPORT.md](TEST_REPORT.md)（測試數為本文撰寫時的既有紀錄，隨版本增加，以 `npm test` 實跑結果為準）、壓測細節見 [STRESS_TEST.md](STRESS_TEST.md)。 --- From bca7b7f30aff5bb227e0c35998057602bd8a9133 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Jul 2026 19:07:47 +0000 Subject: [PATCH 2/2] =?UTF-8?q?docs:=20=E4=BF=AE=E6=AD=A3=20HANDOFF/ROADMA?= =?UTF-8?q?P=20=E8=A4=87=E5=AF=A9=E6=97=A5=E6=9C=9F=E7=82=BA=202026-07-14?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01AC7ERcxjL7dhsYv9PncydP --- docs/HANDOFF.md | 2 +- docs/ROADMAP.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/HANDOFF.md b/docs/HANDOFF.md index b792fa0..e43889d 100644 --- a/docs/HANDOFF.md +++ b/docs/HANDOFF.md @@ -1,6 +1,6 @@ # 交接紀錄 — Session Handoff -> 給下一個開發 session 的快速接手筆記。最後更新:**2026-07-10**。 +> 給下一個開發 session 的快速接手筆記。最後更新:**2026-07-14**。 > 完整藍圖見 [ROADMAP.md](ROADMAP.md);設計權威版見 [GAME_DESIGN.md](GAME_DESIGN.md)(§17 出海決策/§18 人力・軸承/§19 測驗・掌握度・母港);專案現況見 `../STATUS.yaml`。 > 測試數以 `npm test` 實跑為準(目前 **164**);判斷任務題數以 `TASKS.length` 為準(**192**)。 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index cfa2482..0428567 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -2,7 +2,7 @@ > 以 zh-TW 為主、English secondary。本藍圖依現況（[STATUS.yaml](../STATUS.yaml)、[GAME_DESIGN.md](GAME_DESIGN.md)）盤點已完成與待辦，並提出**規劃方向**。 > ⚠ 標示為**規劃中／推測（speculative）**者尚未實作，請勿當成現況；本文為**規劃**而非承諾。 -> Lead with zh-TW; English summaries follow. Last reviewed: 2026-07-10. +> Lead with zh-TW; English summaries follow. Last reviewed: 2026-07-14. ---