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`。