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. 工具箱(常用指令)

# 在 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)

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。