Spaces:
Sleeping
Sleeping
File size: 9,120 Bytes
f7c0e6c | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 | # 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`。
|