Alignment Report

Generated: 2026-04-21 (STEP-22 re-scan)

Summary

• Total checks: 21
• Pass: 14
• Warn: 4
• Fail: 3

Level 1: Document Consistency

Level 2: Code-Test Alignment

Level 3: Version Consistency

Action Items（FAIL 項目）

FAIL-1：autoRevealIntervalSec 上限不一致（需統一決策）

衝突情況：

建議： 由產品確認最終規格（1-30 或 1-300），然後統一修改 BRD §3.4、PRD US-H05/FR-13-2/§8.4、SCHEMA.md §4.4 三處文件（或改 API.md 和 server 程式碼）。不強制修復，因牽涉產品決策。

FAIL-2：shared WsMsgType 缺少 END_GAME 和 PLAY_AGAIN

問題： packages/shared/src/types/index.ts 的 WsMsgType union 型別缺少 'END_GAME' 和 'PLAY_AGAIN'，導致型別不完整。

影響： 客戶端若依賴 WsMsgType 發送 END_GAME 或 PLAY_AGAIN 訊息，TypeScript 型別檢查不提示這兩個值為合法類型。

修復方向：

// packages/shared/src/types/index.ts
export type WsMsgType =
  | 'START_GAME'
  | 'BEGIN_REVEAL'
  | 'REVEAL_NEXT'
  | 'REVEAL_ALL_TRIGGER'
  | 'END_GAME'        // ← 缺少
  | 'PLAY_AGAIN'      // ← 缺少
  | 'SET_REVEAL_MODE'
  | 'RESET_ROOM'
  | 'KICK_PLAYER'
  | 'PING';

FAIL-3：shared WsEventType 缺少 PONG + server PING handler 未回應 PONG

問題 A： packages/shared/src/types/index.ts 的 WsEventType 缺少 'PONG'，但 API.md §3.6 明確定義 PONG 為 Server → Client 事件。

問題 B： server/main.ts 的 PING handler（case 'PING': break）收到 PING 後直接 break，未回傳 PONG，與 API.md §3.6 規格（"伺服器回應 PONG { ts: echo } 供 RTT 量測"）矛盾。

修復方向：

// packages/shared/src/types/index.ts
export type WsEventType =
  | 'ROOM_STATE'
  | 'ROOM_STATE_FULL'
  | 'REVEAL_INDEX'
  | 'REVEAL_ALL'
  | 'PLAYER_KICKED'
  | 'SESSION_REPLACED'
  | 'HOST_TRANSFERRED'
  | 'ERROR'
  | 'PONG';  // ← 缺少

// server/main.ts PING handler
case 'PING': {
  const tsPayload = (msg.payload as { ts?: number } | undefined)?.ts;
  send('PONG', { ts: tsPayload ?? Date.now() });
  break;
}

WARN 參考

• WARN：API.md Room 含 title/rowCount 欄位：API.md §1.5 的 Room interface 比 SCHEMA.md §2.6 和 shared 型別多了 title: string | null 和 rowCount: number | null；server 從未使用這兩個欄位。建議更新 API.md §1.5 Room 定義，移除 title 和 rowCount，與 SCHEMA.md 及 shared 保持一致。

• WARN：BDD features 使用 /api/v1 前綴：features/room-lifecycle.feature 和 features/player-management.feature 的部分 step 使用 /api/v1/rooms，但 API.md 和 server 均為 /api/rooms（無版本前綴）。建議修正 BDD steps 中的路徑。

• WARN：server HTTP 遊戲路由缺少 HTTP 層測試：game/start、game/reveal、game/reset、game/end、game/play-again、DELETE player 等路由的 HTTP 層未有獨立測試（main.ts 已從 coverage 排除），業務邏輯僅由 service 單元測試間接覆蓋。

• WARN：BDD features/ 無步驟實作：所有 .feature 檔案目前為純規格文件，無 cucumber/Playwright step definitions，無法直接作為自動化驗收測試執行。