worst-card-game / guide /12-debugging-guide.md
freeguy2006's picture
Claude Opus 4.8
feat(ui)+docs: 牌堆檢視翻頁箭頭/選卡不放大;規格資料夾改名 guide
f7c0e6c
|
Raw History Blame Contribute Delete
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`。