自適應難度、單次遊玩規則與進度獎勵

開發此功能時遵循了嚴謹、專業的「分層軟體工程生命週期」。透過走過這些步驟，我們能保證程式碼品質、保持業務邏輯與框架的分離，並完全避免程式邏輯錯誤 (Bugs)。

+------------------+     +------------------+     +------------------+     +------------------+
| 1. 需求收集      | --> | 2. 規格設計      | --> | 3. 測試驅動 (TDD) | --> | 4. 分層程式碼實作 |
| (The Idea)       |     | (The Spec Doc)   |     | (先寫測試再開發) |     | (Implementation) |
+------------------+     +------------------+     +------------------+     +------------------+
                                                                                    |
                                                                                    v
                                                                           +------------------+
                                                                           | 5. 靜態分析與驗證|
                                                                           | (Lint & Typecheck|
                                                                           +------------------+

1. 第一步：需求收集 (Requirements Gathering)： 我們從高層級的用戶需求出發，定義了自適應練習、即時重試、單次遊玩時限與進度獎勵的核心概念。
2. 第二步：規格設計 (Specification Design)： 在撰寫任何實作程式碼之前，我們先編寫了規格書 specs/003-adaptive-difficulty/spec.md。這奠定了邊界條件、邊緣情況 (Edge Cases)、資料結構與功能性需求 (Functional Requirements)。
3. 第三步：測試驅動開發 (TDD)： 我們先撰寫單元測試（例如：adaptive-selector.test.ts），在程式碼尚未實作前就先驗證選題機率、快速重試機制與報告計算邏輯是否正確。
4. 第四步：分層實作 (Layered Implementation)：
   • 領域邏輯層 (Shared Domain)： 純 TypeScript 邏輯，包含選題狀態機、得分判定與徽章計算規則。
   • 呈現層 (Phaser/Angular UI)： Phaser 協調繪製掉落字卡物理特性、雷射擊中動畫與計時器倒數；Angular 負責彈出對話框、徽章列表和家長設定面板。
   • 資料儲存層 (Firebase)： Firestore 雲端函式 (Cloud Functions) 永久儲存玩家解鎖的徽章與比賽歷史紀錄。
5. 第五步：靜態分析與 pre-flight 檢查： 在提交代碼前運行靜態代碼分析（pnpm lint、pnpm typecheck），確保沒有任何邏輯衝突或編譯錯誤。

啟動此軟體開發週期的原始需求如下：

為了引導 AI 編碼助理精確、無歧義地實作程式碼，我們將需求拆解為我們功能工作區中的具體規格：

功能性需求 (Functional Requirements)

• FR-AD-001： 系統必須在單次遊玩中追蹤玩家的答題正確性，將題目分類為 correctPool（答對題庫）與 incorrectPool（答錯題庫）。
• FR-AD-002： 當兩個題庫都有資料時，系統必須以 3:1 的比例（75% 的機率）優先從 incorrectPool 抽取題目。
• FR-AD-003： 當玩家答錯或漏掉題目時，系統必須顯示視覺化錯誤回饋，呈現完整的數學算式（例如：6 x 7 = 42）。
• FR-AD-004： 系統必須立即觸發答錯題目的快速重試（重新生成掉落字卡），重試次數限制為 2 次。
• FR-AD-005： 系統必須在畫面右上角的 HUD 中顯示 10 分鐘倒數計時器。
• FR-AD-006： 當計時器達到 0:00 時，系統必須觸發休息提醒並暫停遊戲。
• FR-AD-007： 系統必須在遊玩結束時生成包含錯題清單與專屬學習建議的績效報告。
• FR-AD-008： 系統必須支持可解鎖徽章（streak_master、hero_10_min），並將其儲存至 Firestore 的玩家個人檔案中。
• FR-AD-009： 在桌上型電腦（Desktop）模式下，系統必須將左右兩側的 HUD 面板限制為 10% 的左右邊界間距 (Margin)，使其更靠近中央遊戲區域。

已解決的關鍵邊緣情況 (Edge Cases)

1. 初始題庫為空： 當新遊戲開始時，答對與答錯題庫皆無資料。選題器會自動退回使用一般的 eligible 題庫，避免程式崩潰或卡死。
2. 平滑的時間到中斷： 若 10 分鐘計時器在作答途中歸零，遊戲會等玩家完成當前題目的回答後，才會觸發休息提醒與生成績效報告。
3. 快速重試的保存規則： 在快速重試中答對可以獲得分數，但該題目不會被移出答錯題庫。這確保它在未來的標準遊戲回合中還會被抽中，直到在一般模式下答對為止。

你可以將這些新功能想像成一位在你身旁指導的個人數學教練：

+-----------------------------------------------------------------+
|                       1. 記憶卡牌抽取                           |
|                     (自適應選擇器)                              |
|  * 將答對的題目放入「已掌握」卡牌堆。                           |
|  * 將答錯的題目放入「需加強」卡牌堆。                           |
|  * 遊戲有 75% 的機率會從「需加強」卡牌堆中抽題。                |
+-------------------------------+---------------------------------+
                                | (生成特定的目標問題)
                                v
+-----------------------------------------------------------------+
|                       2. 即時重播糾錯                           |
|                    (錯誤回饋與重試循環)                         |
|  * 答錯時立即顯示完整算式："6 x 7 = 42" 。                       |
|  * 立即再次掉落相同的題目，讓你重新挑戰。                       |
+-------------------------------+---------------------------------+
                                | (檢查遊玩時間與限制)
                                v
+-----------------------------------------------------------------+
|                       3. 健康計時警報                           |
|                     (計時器與休息系統)                          |
|  * 進行 10 分鐘的倒數計時。                                     |
|  * 時間到時引導你休息，並顯示詳細的學習報告。                   |
+-----------------------------------------------------------------+

核心程式碼是如何在底層執行的：

• 自適應選擇器： 選題器透過 adaptive-selector.ts 運作，強制作答錯誤題目有 75% 的抽取偏向，並使用 lastPlayedAtMs 來抓取最久未複習的乘法事實。
• 即時糾錯與快速重試： 答錯時，Phaser 引擎會暫停重力物理掉落，播放閃爍音效並在上方顯示正確公式。隨後立即複製一個 round 啟動 wasQuickRetry = true 重新生成方塊。
• 遊玩時間控制： Angular 宿主在 gameplay-session.ts 中監聽倒數計時，每秒鐘遞減，並在歸零後平滑暫停 Phaser 物理場景。
• 閉環回饋（報告與徽章）： 賽後將分數與連勝次數提交給 Firebase，如果最高連勝次數（highestCombo）大於等於 10，雲端函式會自動頒發 streak_master 徽章。