Spaces:
Sleeping
Sleeping
|
Download guide/12-debugging-guide.md from WorstCardGame/worst-card-game: direct link, hf CLI and curl.
- Browser
- Download file 9.12 kB
-
https://huggingface.co/spaces/WorstCardGame/worst-card-game/resolve/main/guide/12-debugging-guide.md
- Command line
-
hf download hf://spaces/WorstCardGame/worst-card-game/guide/12-debugging-guide.md
-
curl -L -o 12-debugging-guide.md https://huggingface.co/spaces/WorstCardGame/worst-card-game/resolve/main/guide/12-debugging-guide.md
9.12 kB
| # 12 — 全端除錯指南(Frontend → Backend) | |
| > 一套可照做的除錯流程。核心觀念:**先分層定位,再深入**——不要一看到畫面怪就改前端。 | |
| > 本專案的結構讓除錯很有優勢:`battle-core` 是**決定性純函式**,大多數規則 bug 可以**不開瀏覽器**、用單元測試重現。 | |
| --- | |
| ## 0. 四層架構(先記住 bug 可能落在哪一層) | |
| ``` | |
| [web 前端] 顯示 / 互動 / WS 收發 packages/web/src (App.tsx, PvpScreen.tsx, pvpClient.ts) | |
| │ | |
| [server 後端] 連線協調 / 房間 / 計時 / 反作弊 packages/server/src (server.ts, pvpHub.ts, pvpMatch.ts, ghostService.ts) | |
| │ | |
| [battle-core] 純規則 / 決定性 / 三模式共用 packages/battle-core/src (engine, player, effects, pvpResolve...) | |
| │ | |
| [build/部署] dist 編譯 / cards.json / HF Spaces | |
| ``` | |
| **第一鐵則**:**UI 顯示錯 ≠ 規則錯。** 先判斷在哪一層,80% 的時間省在這一步。 | |
| --- | |
| ## 1. 分層定位表(症狀 → 嫌疑層 → 先查哪裡) | |
| | 症狀 | 最可能的層 | 先查 | | |
| |---|---|---| | |
| | 卡牌效果數值不對(ATK/DEF/抽牌/硬幣) | battle-core | `effects.ts`(runOps)、`data/cards.ts`、`player.ts` | | |
| | **只有 PvP 錯、單人正常** | server 協調層 | `pvpResolve.ts`、`pvpMatch.ts`、`pvpHub.ts` | | |
| | **只有鬼影(第12關)錯** | opponent/ghost | `opponent.ts`(ghost 重建)、`engine.ts` turnLog | | |
| | 畫面數字與實際狀態不符 | web 顯示 | `App.tsx`/`PvpScreen.tsx` 的 render | | |
| | 點了沒反應 / 狀態沒更新 | web 事件或 reducer | `pvpClient.ts` reduce、dispatch、WS 有沒有送出 | | |
| | 計時 / 倒數怪 | server 計時 + web | `pvpHub` deadline、`pvpClient` PHASE_START、`useCountdown` | | |
| | 連線斷 / 配對失敗 | server WS | `server.ts` `/ws/pvp`、`pvpHub` 房間 | | |
| | **改了程式線上沒變** | build/部署 | dist 是否重建、HF Spaces build log | | |
| **最強定位法 —「哪些模式出現?」**(三模式共用同一份 `battle-core`): | |
| - 三模式都錯 → 幾乎一定在 **battle-core**。 | |
| - 單人對、PvP 錯 → 在 **PvP 協調層**(`pvpResolve`/`pvpMatch`/`pvpHub`),不是規則。 | |
| - 單人對、鬼影錯 → 在 **ghost 重建 / turnLog**。 | |
| --- | |
| ## 2. battle-core 層(規則)— 最該優先、最好查 | |
| **為什麼先查這層**:純函式、決定性、零相依 → 可以用**最小重現測試**抓,不必開瀏覽器、不必連後端。 | |
| **重現步驟**: | |
| 1. 寫一個最小 golden test(`packages/battle-core/test/`):固定 seed `createGame({classType:"WARRIOR", seed: N})` → 套一串 `step(s, action)` → `expect` 狀態。 | |
| 2. `npm run test:watch -w @wcg/battle-core`(存檔即跑)。 | |
| 3. 用 `replay(seed, actions)`(`engine.ts`)驗**決定性**:同輸入必同輸出;不同則代表有非決定性來源(多半是誤用 `Math.random()`)。 | |
| **這層的高頻 bug**: | |
| - 出牌順序(必須**先移出手牌再結算**;`09 G3/G6`)。 | |
| - 旗標結算時機 / 沒清除(出傷時 `onDealDamage`、回合末 `onTurnEndResolve`、重置 `resetForNextTurn`)。 | |
| - 亂數消費順序(`effects.ts` 的 DRAW/RANDOM_*、洗牌;見 `08 §6`)。 | |
| - `handCount`/`handEmpty` 是否含本張。 | |
| **檢查清單**: | |
| - [ ] 能用 golden test 穩定重現嗎?(不能穩定 = 非決定性,先抓亂數) | |
| - [ ] 同 seed 跑兩次結果一致嗎?(`replay`) | |
| - [ ] 數值是否與 `02`/`08` 設計一致? | |
| --- | |
| ## 3. server 層(連線 / 協調 / 計時) | |
| **單元測試(首選,完全可控)**:`pvpHub`/`pvpMatch` 的相依都可注入—— | |
| - `genSeed`/`now`/`scheduler` 注入假值(見 `test/pvpHub.test.ts` 的 harness:假 `send` 收訊息、假 `scheduler` 不真的計時)。 | |
| - 用 `types(msgs.A)` 看伺服器**送了哪些訊息、順序對不對**(PHASE_START / RESOLVE_RESULT / DRAFT_CHOICE…)。 | |
| **e2e**:`test/pvpWs.e2e.test.ts` 開真 WebSocket,驗端到端收發。 | |
| **反作弊 / 對局重算**:用 `replay(seed, actions)` 重跑,對比 server 記的 `actionLog`。 | |
| **這層的高頻 bug**: | |
| - 計時:`deadlineTs`(改用 `durationMs` 由 client 自算,避免時鐘偏差)。 | |
| - 四相狀態機相位轉換(PLAN→LOCK→RESOLVE→ADVANCE)。 | |
| - draft 流程(DRAFT_CHOICE/PICK/WAIT、雙方完成才開戰)。 | |
| - 斷線 / 投降 / 房間清理。 | |
| **檢查清單**: | |
| - [ ] 用假 scheduler/seed 能單測重現嗎? | |
| - [ ] 伺服器送出的訊息序列符合預期嗎?(印 `msgs`) | |
| - [ ] seed 有沒有不小心外洩給 client?(`JSON.stringify(msg)` 不該含 "seed") | |
| --- | |
| ## 4. web 層(前端) | |
| **先分清三種前端 bug**: | |
| 1. **顯示 bug**:狀態對、畫面畫錯 → 看 render(`App.tsx`/`PvpScreen.tsx`)。 | |
| 2. **reducer bug**:收到訊息但 state 沒更新對 → 看 `pvpClient.ts` `reduce`(漏 case?)。 | |
| 3. **事件沒送**:點了沒反應 → dispatch / `send` 沒被呼叫,或 WS 沒連上。 | |
| **工具**: | |
| - React DevTools 看 `game`(單人 GameState)、`usePvp` 的 `state`。 | |
| - `console.log` 印 `GameState` / `PvpView`;單人甚至可在瀏覽器 console 直接 import 跑 `battle-core`(因前端就 import 它)。 | |
| - **瀏覽器 DevTools → Network → WS**:看 `/ws/pvp` 的 frames(收發的 `DRAFT_CHOICE`/`PHASE_START`/`RESOLVE_RESULT`…),確認「是後端沒送」還是「前端沒處理」。 | |
| **這層的高頻 bug**: | |
| - `reduce` 漏處理某訊息類型(狀態不動)。 | |
| - 倒數時鐘(`useCountdown` 用 `deadlineTs - Date.now()`;時鐘偏差)。 | |
| - React key 重複 / stale closure。 | |
| - 顯示用衍生值算錯(例:`displayNextReq`、`pileView`)。 | |
| **檢查清單**: | |
| - [ ] 問題是「沒收到訊息」(看 WS frames)還是「收到沒更新」(看 reduce)還是「更新了沒畫對」(看 render)? | |
| - [ ] state 在 React DevTools 裡是對的嗎? | |
| --- | |
| ## 5. build / 部署層 | |
| > 「明明改了卻沒效果」最常見的兇手。web/server 吃的是**編譯後的 `dist`**。 | |
| - **dist 過期**:改了 `battle-core/src` 一定要 `npm run build`(或至少 build battle-core)。驗證法:`grep` 你的新程式碼/註解是否進了 `packages/battle-core/dist/*.js`;或比對 `src` 與 `dist` 的 mtime。 | |
| - **cards.json 沒重產**:改 `data/cards.ts` 後要 `npm run gen:cards -w @wcg/battle-core`。 | |
| - **HF Spaces**:看 Space 的 build log(Docker);`app_port 7860`;部署細節見 `../DEPLOY.md`。 | |
| - **健康檢查**:`GET /api/health` 應回 `{ ok: true, ghosts: N }`。 | |
| **檢查清單**: | |
| - [ ] `npm run build` 跑過了嗎?dist 有你的改動嗎? | |
| - [ ] 線上版本 = 最新 commit 嗎?(GitHub/HF 都 push 了?Spaces 重建完成了?) | |
| --- | |
| ## 6. 工具箱(常用指令) | |
| ```bash | |
| # 在 repo 根目錄 worst-card-game/ | |
| npm run typecheck # 全套件型別檢查(先跑,最快抓錯) | |
| npm test # 全部測試(battle-core + server) | |
| npm run test:watch -w @wcg/battle-core # 規則層 watch 模式(改卡/改效果時) | |
| npm run build # 重建 dist(web/server 吃 dist) | |
| npm run gen:cards -w @wcg/battle-core # data/cards.ts → cards.json | |
| ``` | |
| - `git diff` / `git log --oneline`:對照「上次能動」與「現在」之間改了什麼。 | |
| - 全文搜尋症狀關鍵字(訊息型別、旗標名、卡 id)快速定位。 | |
| --- | |
| ## 7. 標準除錯流程(SOP) | |
| ```mermaid | |
| flowchart TD | |
| S([遇到 bug]) --> M{哪些模式會發生?} | |
| M -- 三模式都錯 --> C[battle-core:寫最小 golden test 重現] | |
| M -- 只有 PvP --> P[server 協調層:pvpResolve/hub 單測 + WS frames] | |
| M -- 只有鬼影 --> G[opponent/ghost 重建 + turnLog] | |
| M -- 只有畫面 --> W[web:WS frames? reduce? render? 三選一] | |
| C --> R{能穩定重現?} | |
| R -- 否 --> ND[抓非決定性:Math.random? 用 replay 比對] | |
| R -- 是 --> FIX[定位根因 → 修] | |
| P --> FIX | |
| G --> FIX | |
| W --> FIX | |
| ND --> FIX | |
| FIX --> T[加/更新 golden test 釘行為 → typecheck+test 全綠] | |
| T --> B[npm run build 重建 dist → 三模式手測] | |
| B --> D[commit/push → 線上驗證] | |
| D --> E([關閉]) | |
| ``` | |
| --- | |
| ## 8. 實戰案例(本專案真實 bug,當教材) | |
| **案例一:「好的開始沒抽」** | |
| - 症狀:單人打出後手牌數不增。→ 分層:三模式皆有 ⇒ battle-core。 | |
| - 重現:golden test「手牌滿 5 時打出抽牌卡」→ 抽 0。 | |
| - 根因:效果在「牌仍在手牌」時結算,`hand.length>=5` 卡住 DRAW。 | |
| - 修:出牌**先移出手牌**再結算(對齊原版)。 | |
| - 驗:測試 + 三模式;順手發現 5 個測試把舊 bug 當規格(改成正確值)。 | |
| **案例二:「PvP 時間有錯誤」** | |
| - 症狀:PvP 倒數不準。→ 分層:只有 PvP + 顯示 ⇒ web/server 計時。 | |
| - 根因:server 送**絕對 `deadlineTs`(server 時鐘)**,client 用**自己時鐘**倒數 → 偏差。 | |
| - 修:server 改送**剩餘時長 `durationMs`**,client `Date.now()+durationMs` 自算。 | |
| **案例三:「改了卻沒變」** | |
| - 先驗 `dist` 是否最新(`grep` 新註解進 dist?mtime?)→ 排除 build/部署層,再深入。 | |
| --- | |
| ## 9. 回報 bug 的最小資訊(給未來的你/隊友) | |
| 附上這些,任何人都能快速重現: | |
| - **模式**(單人 / 鬼影 / PvP)、**seed**(若有)。 | |
| - **操作序列**(出了哪些牌、按了什麼)。 | |
| - **預期 vs 實際**。 | |
| - **console / WS frames log**(PvP 尤其要 WS frames)。 | |
| - 線上版本 commit / 本機 `git log -1`。 | |