# Skills & Best Practices - Math City Project

此文件記錄本專案開發過程中的技術規範、設計模式、教學設計哲學與除錯經驗，供後續開發參考。

## 1. 技術架構與規範 (Tech Stack & Guidelines)

### 核心技術
*   **核心**: HTML5 Canvas + Vanilla JS (ES6+)。
*   **樣式**: Tailwind CSS (CDN read-only 模式) + Custom CSS (for animations/glassmorphism)。
*   **字體**: 'Orbitron' (數字符號/標題), 'Noto Sans TC' (中文內文)。
*   **建置**: 無須 Build Tool (No Webpack/Vite)，保持單檔可執行 (`.html`)，方便老師分享與部署。

### 程式碼規範
*   **語言**: 註解與文件說明嚴格使用**繁體中文**，變數與函數名稱使用**英文**。
*   **檔案結構**: 保持扁平，html 檔包含 CSS/JS 為主 (方便單檔攜帶)，通用素材放 `Assets/`。
*   **狀態管理**: 使用整數常數定義狀態機 (`const STATE = { INIT: 0, PLAYING: 1 ... }`)，避免字串混淆。

## 2. 視覺與互動設計 (UI/UX Patterns)

### 視覺風格：Glassmorphism (玻璃擬態)
*   背景使用 `backdrop-filter: blur(12px)` 搭配半透明深色背景 (`bg-slate-900/90`)。
*   邊框使用亮色且低透明度 (`border-cyan-500/30`) 營造科技質感。
*   善用 `box-shadow` 與 `drop-shadow` 營造霓虹發光效果。

### Canvas 渲染優化
*   **High-DPI 支援**: 
    *   在 Retina 螢幕上，務必處理 `devicePixelRatio`。
    *   Canvas 屬性寬高 = CSS 寬高 * dpr。
    *   Context 縮放: `ctx.scale(dpr, dpr)`。
    ```javascript
    const dpr = window.devicePixelRatio || 1;
    canvas.width = width * dpr;
    canvas.height = height * dpr;
    canvas.style.width = width + 'px';
    canvas.style.height = height + 'px';
    ctx.scale(dpr, dpr);
    ```

### 行動裝置適配 (Mobile Adaptation)
*   **禁止捲動/縮放**:
    *   CSS: `touch-action: none; user-select: none; -webkit-user-select: none;`
    *   JS: 監聽 `touchstart` / `touchmove` 並執行 `e.preventDefault()` (需加 `{ passive: false }`)。
*   **虛擬鍵盤 (Virtual Keypad)**:
    *   iOS/Android 預設軟鍵盤會推擠版面，破壞全螢幕體驗。
    *   **解決方案**: 自製 DOM 虛擬鍵盤，支援拖曳 (Draggable) 與自動定位。
    *   **點擊穿透處理**: 鍵盤點擊事件需 `e.stopPropagation()`。

## 3. 遊戲邏輯與物理 (Game Mechanics)

### 物理引擎 (Physics)
*   **Coyote Time (土狼時間)**:
    *   在玩家離開平台的一小段時間內 (例如 0.13秒) 仍允許跳躍，增加操作手感容錯率。
    *   實作: 設置 `coyoteTimer`，只要在地上就重置，離地後遞減，大於 0 時仍視為可跳躍。
*   **時間步長 (Time Step)**:
    *   目前使用簡易的 `requestAnimationFrame` 迴圈。若需更精準物理，考慮導入 Delta Time (`dt`)。

### 遊戲反饋 (Juice & Feedback)
*   **動畫選擇**: 
    *   錯誤提示避免使用滑稽的 `bounce`，改用嚴肅且有質感的 `pulse` (呼吸燈) + 紅色邊框。
*   **音效合成 (Web Audio API)**:
    *   不依賴外部 mp3 檔案，使用 `OscillatorNode` 即時合成音效 (Sine, Square, Sawtooth)。
    *   優點：無載入時間、檔案極小、可動態改變頻率 (Pitch Bend)。
    *   **注意**: 必須使用者互動 (Click/Touch) 後才能 `resume()` AudioContext。

## 4. 數學教學設計 (Pedagogy Design)

### 鷹架理論 (Scaffolding)
*   **不僅僅是給答案**: 錯誤訊息應轉化為引導問題。
    *   *Bad*: "答錯了！"
    *   *Good*: "如果 x=2, y=11, 但公式是 y=2x+b, 所以 b 是多少？"
*   **變數分離**: 
    *   在解 $y=ax+b$ 時，先令 $x=0$ 解 $b$，再令 $x=1$ 解 $a$，避免同時處理雙變數的認知負荷。

### 視覺化連結 (Visual-Algebra Connection)
*   **多重表徵連結**: 當計算出代數答案 (例如 y=35) 時，程式應同步強調圖表上的對應幾何點 (10, 35)，強化「數形合一」的概念。

### 正向回饋 (Positive Feedback)
*   避免挫折感，將艱澀的計算任務後的獎勵極大化 (例如：華麗的煙火、Phase 6 的節奏遊戲)，讓大腦獲得多巴胺釋放。

## 5. Agent 開發工作流 (Agent Workflow)

### 任務邊界 (Task Boundary)
*   使用 `task_boundary` 明確區分 **PLANNING** (規劃)、**EXECUTION** (執行) 與 **VERIFICATION** (驗證) 階段。
*   **Context Management**: 保持對話專注，一個 Task 解決一個具體問題。

### Artifacts 使用
*   **Implementation Plan**: 修改複雜邏輯前，先撰寫 `implementation_plan.md` 讓使用者確認設計思路。
*   **Walkthrough**: 完成功能後，建立 `walkthrough.md` 展示成果與測試截圖。

## 6. 已知問題與解決 (Troubleshooting Log)

*   **問題**: 平台消失後的透明牆導致玩家卡住。
    *   **解法**: 物理碰撞檢測時，需過濾掉 `active: false` 的平台物件。
*   **問題**: Home 鍵在全螢幕模式下難以點擊。
    *   **解法**: 確保 UI 層級 (`z-index`) 正確，並添加 `pointer-events-auto` 到按鈕本身，而容器保持 `pointer-events-none`。
*   **問題**: 數列峽谷中，只有前兩項有提示，後續太難。
    *   **解法**: 設計意圖就是強制計算。但為了公平，統一了所有平台的視覺 (碎石紋理)，避免玩家嘗試「辨色」而非「計算」。

---
*Created by Antigravity Team for Project 11402*