EDD — Engineering Design Document

Ladder Room Online 工程設計文件

Document Control

§1 Executive Summary

§1.1 系統目的

Ladder Room Online 是一款基於 HTML5 Canvas 的多人線上爬樓梯抽獎系統，採用 WebSocket 長連接驅動即時遊戲狀態同步，支援最多 50 名玩家共享同一房間。系統設計目標為取代 LINE 原生爬樓梯的功能限制，支援異地多人同房、主持人掌控揭曉節奏、結果公正可驗證。

§1.2 技術選型總覽

client_type: web（瀏覽器端，HTML5 Canvas + Vanilla TypeScript）

§1.3 關鍵設計決策摘要

1. Vanilla TypeScript + Vite（無 UI 框架）— 確保最小 JS bundle，無框架冗餘依賴
2. WebSocket（ws 原生）（非 Socket.IO）— 雙向通訊，標準協定，無 polling fallback 需求
3. Redis 作為唯一持久層（非 in-memory）— Pod 重啟後狀態存活，跨 Pod Pub/Sub 廣播
4. Clean Architecture + packages/shared（核心邏輯前後端共用）— 算法一致性可驗證，結果可事後審計
5. Mulberry32 PRNG + djb2 seed + Fisher-Yates（確定性 PRNG）— 100% 客戶端結果一致，無舞弊空間
6. Kubernetes 兩 Pod 架構（server pod + client nginx pod）— 本機與生產環境統一，前後端分離部署

§2 System Architecture

§2.1 High-Level Architecture

系統採用四層架構：Client → Ingress → Fastify/WS Server → Redis。

• Client（Vanilla TypeScript + Vite + HTML5 Canvas）：瀏覽器端，透過 HTTPS 呼叫 REST API，透過 WSS 長連接接收即時事件。Canvas 2D 渲染梯子動畫。
• Nginx Ingress（Traefik）：TLS 終止、HTTPS/WSS 路由分派、sticky session（/ws 與 /api 路徑）、catch-all 路由至 Client Nginx Pod（/）。
• Fastify + ws（Server Pod）：HTTP REST（/api/*）及 WebSocket（/ws）共用進程。Fastify 處理 REST；ws 原生 WebSocket 處理即時通訊。
• Redis（StatefulSet）：房間狀態持久化（CRUD）、原子操作（WATCH/MULTI/EXEC）、Pub/Sub 跨 Pod 廣播。

§2.2 Component Diagram

graph TD
    subgraph Client["Client Browser"]
        TS["Vanilla TS + Vite"]
        Canvas["HTML5 Canvas"]
        WSClient["WsClient"]
        TS --> Canvas
        TS --> WSClient
    end

    subgraph Ingress["Traefik Ingress (ladder.local)"]
        NginxHTTP["HTTP /api/*\nFastify REST"]
        NginxWS["WebSocket /ws\nWS Upgrade"]
        NginxStatic["Static / (catch-all)\nClient Pod"]
    end

    subgraph K8sCluster["Kubernetes Cluster (namespace: ladder-room)"]
        SVC["Service: ladder-server-service\nClusterIP port:80→3000"]
        ClientSVC["Service: ladder-client-service\nClusterIP port:80"]

        subgraph ClientPod["Client Pod"]
            NginxPod["Nginx 1.27-alpine\nladder-client:local\nSPA static files"]
        end

        subgraph Pods["Fastify Pods (MVP: replicas=1)"]
            Pod1["Pod-1 Fastify+ws\nport:3000"]
        end

        SVC --> Pod1
        ClientSVC --> NginxPod

        subgraph Redis["Redis StatefulSet"]
            RedisMaster["Redis Master\nredis-0"]
            RedisReplica["Redis Replica\nredis-1 (Post-MVP)"]
            RedisMaster --> RedisReplica
        end

        Pod1 --> RedisMaster
        Pod1 --> |"PSUBSCRIBE room:*:events"| RedisMaster
    end

    WSClient --> |"WSS /ws?room=...&token=..."| NginxWS
    TS --> |"HTTPS /api/*"| NginxHTTP
    NginxHTTP --> |"sticky session"| SVC
    NginxWS --> |"sticky session"| SVC
    NginxStatic --> ClientSVC

§2.3 Data Flow Diagram

sequenceDiagram
    participant C as Client Browser
    participant N as Traefik Ingress
    participant F as Fastify Pod
    participant R as Redis

    Note over C,R: 建立房間 + 加入流程

    C->>N: POST /api/rooms { hostNickname, winnerCount }
    N->>F: HTTP forward
    F->>R: SETNX room:{code} (原子建立)
    R-->>F: OK / room data
    F-->>C: 201 { roomCode, playerId, sessionToken(JWT) }

    C->>N: POST /api/rooms/:code/players { nickname }
    N->>F: HTTP forward
    F->>R: HGET room:{code} → 驗證狀態、暱稱唯一
    F->>R: SADD room:{code}:players {playerId}
    R-->>F: OK
    F-->>C: 201 { playerId, sessionToken, colorIndex }

    C->>N: WSS /ws?room={code}&token={token}
    N->>F: WebSocket Upgrade（sticky session）
    F->>F: 驗證 JWT HS256 + kickedPlayerIds 攔截
    F->>R: HGET room:{code} load state
    R-->>F: Room JSON
    F-->>C: WS Connected
    F->>C: ROOM_STATE_FULL { room, players, ladder:null, selfPlayerId }

    Note over C,F: Host 開始遊戲

    C->>F: WS MSG: START_GAME
    F->>R: WATCH room:{code}
    F->>R: MULTI / SET status=running, seedSource=UUID, rowCount / EXEC
    R-->>F: EXEC OK (原子操作)
    F->>R: PUBLISH room:{code}:events ROOM_STATE(running, rowCount)
    R-->>F: 廣播至所有訂閱 Pod
    F-->>C: Broadcast ROOM_STATE { status: running, rowCount } (不含 seed/ladder)

    Note over C,F: Host 開始揭曉

    C->>F: WS MSG: BEGIN_REVEAL
    F->>F: 應用層計算 generateLadder + computeResults
    F->>R: Lua Script 原子寫入 ladder/results/status=revealing
    R-->>F: OK
    F->>R: PUBLISH room:{code}:events ROOM_STATE(revealing)
    F-->>C: Broadcast ROOM_STATE { status: revealing }

    Note over C,F: 逐步揭曉

    C->>F: WS MSG: REVEAL_NEXT
    F->>R: INCR room:{code}:revealedCount (原子)
    R-->>F: newCount
    F->>R: WATCH+MULTI/EXEC SET Room JSON (revealedCount=newCount)
    F->>R: PUBLISH REVEAL_INDEX { playerIndex, path, result }
    F-->>C: Broadcast REVEAL_INDEX

    Note over C,F: 結束本局

    C->>F: WS MSG: END_GAME (revealedCount === totalCount)
    F->>R: WATCH+MULTI/EXEC SET status=finished / TTL 延長 1h
    F->>R: PUBLISH ROOM_STATE { status: finished, seed, results[] }
    F-->>C: Broadcast ROOM_STATE (seed 首次公開)

§2.4 Deployment Architecture

Kubernetes 部署（namespace: ladder-room）：

graph TD
    subgraph NS["Namespace: ladder-room"]
        subgraph IngressLayer["Ingress Layer"]
            ING["Traefik Ingress\ningressClassName: traefik\naffinity: cookie (sticky session)\nwebsocket-services: ladder-server-service"]
        end

        subgraph ClientLayer["Client Layer"]
            CDEP["Deployment: ladder-client\nreplicas: 1\nimage: ladder-client:local\nimagePullPolicy: Never"]
            CPOD["Nginx 1.27-alpine Pod\nport:80\nSPA static files"]
            CSVC["Service: ladder-client-service\nClusterIP port:80"]
            CDEP --> CPOD
            CSVC --> CPOD
        end

        subgraph AppLayer["Application Layer"]
            DEP["Deployment: ladder-server\nreplicas: 1 (MVP)\nimage: distroless/nodejs20\nimagePullPolicy: Never"]
            POD1["Pod-1 Fastify+ws port:3000"]
            DEP --> POD1
            HPA["HPA (Post-MVP)\nminReplicas:2 maxReplicas:10\nmetric: ws_connections target:200"]
            HPA --> DEP
        end

        subgraph ServiceLayer["Service Layer"]
            SVC["Service: ladder-server-service\nClusterIP port:80→3000"]
        end

        subgraph StatefulLayer["Redis"]
            RSTS["StatefulSet: redis\nMVP replicas:1"]
            RPOD0["redis-0 master port:6379"]
            RSVC["Service: redis-svc ClusterIP"]
            RSTS --> RPOD0
        end

        subgraph ConfigLayer["Config"]
            CM["ConfigMap\nREDIS_HOST PORT LOG_LEVEL CORS_ORIGIN"]
            SEC["Secret\nJWT_SECRET REDIS_PASSWORD"]
        end

        ING --> |"/api /ws /health /ready"| SVC
        ING --> |"/ (catch-all)"| CSVC
        SVC --> POD1
        POD1 --> RSVC
        RSVC --> RPOD0
        POD1 --> CM
        POD1 --> SEC
    end

本機開發環境（Rancher Desktop）：

• 使用 Rancher Desktop 作為本機 Kubernetes 環境（containerd runtime）
• /etc/hosts 設定 127.0.0.1 ladder.local，透過 Traefik Ingress 存取 http://ladder.local
• 一鍵開發腳本：./scripts/dev-k8s.sh [up|down|restart|logs]
• up：docker build + kubectl apply（server + client image）
• down：kubectl delete + image 清理
• restart：重新 build 並 rolling restart
• logs：串流所有 Pod 日誌
• Docker image 策略：
• Server：Dockerfile（Distroless Node.js 20，多階段建構，imagePullPolicy: Never）
• Client：Dockerfile.client（Nginx 1.27-alpine，多階段建構，imagePullPolicy: Never）

§3 Technology Stack

§4 Module Design

§4.1 Server Modules

整體目錄結構（Clean Architecture 分層）：

packages/server/src/
├── infrastructure/
│   └── redis/
│       ├── IRoomRepository.ts    # 倉儲介面（IRoomRepository）
│       ├── RedisClient.ts        # ioredis singleton
│       └── RoomRepository.ts    # Redis CRUD + TTL + 原子操作；IRoomRepository 實作
├── application/
│   ├── services/
│   │   ├── RoomService.ts        # 業務邏輯協調（建立/加入/踢除/再玩一局）
│   │   └── GameService.ts        # 遊戲流程（START_GAME/BEGIN_REVEAL/REVEAL/END_GAME）
│   └── handlers/                 # （預留目錄，WS 路由邏輯內嵌於 main.ts）
├── domain/
│   └── errors/
│       └── DomainError.ts        # base typed error
├── container.ts                  # DI 工廠，組裝所有依賴
└── main.ts                       # 啟動入口：Fastify + ws.Server（含 JWT 驗證、速率限制、廣播邏輯）+ Pub/Sub 訂閱

實作說明（MVP）： WebSocket 升級/驗證、HTTP 路由、Pub/Sub 廣播等邏輯目前集中於 main.ts（< 800 行）；container.ts 組裝 DI；RoomService/GameService 封裝業務邏輯；Post-MVP 可按下列分拆方向重構：WsServer.ts（ws.Server 封裝）、PubSubBroker.ts（Pub/Sub）、presentation routes/schemas/plugins。

各模組單句職責：

§4.2 Client Modules

packages/client/src/
├── ui/
│   ├── lobby.ts              # 大廳頁面：建立/加入房間 UI 邏輯（含 localStorage 暱稱預填 + URL 房號解析）
│   ├── waitingRoom.ts        # 等待大廳：玩家列表、複製邀請連結、主持人控制
│   ├── game.ts               # 遊戲視圖：Canvas 容器、揭曉控制按鈕、結果展示
│   └── toast.ts              # Toast 通知元件（短暫提示訊息）
├── canvas/
│   ├── renderer.ts           # Canvas 2D 梯子繪製（rails、rungs、paths、winner stars）；requestAnimationFrame 動畫驅動
│   └── colors.ts             # 玩家色彩系統：colorFromIndex / colorFromIndexDim（最多 50 色）
├── state/
│   ├── store.ts              # 客戶端房間狀態（基於 ROOM_STATE_FULL / ROOM_STATE 更新）
│   └── LocalStorageService.ts # localStorage 讀寫（playerId、ladder_last_nickname）
├── ws/
│   └── client.ts             # WebSocket 連線管理、指數退避重連（1/2/4/8/30s）；事件分派至 UI
└── main.ts                   # 入口：初始化 WS client、store、UI 模組

localStorage Keys：

邀請連結規格：

• 格式：{window.location.origin}/?room={roomCode}
• 複製機制：優先 navigator.clipboard.writeText()；Fallback：<input> 全選手動複製

§4.3 Shared Package（packages/shared）

packages/shared/src/
├── use-cases/
│   ├── GenerateLadder.ts     # 梯子生成 use case（pure function）
│   ├── ValidateGameStart.ts  # N>=2, 1<=W<=N-1 驗證
│   └── ComputeResults.ts     # 路徑追蹤 → ResultSlot[]
├── prng/
│   ├── mulberry32.ts         # Mulberry32 PRNG 實作
│   ├── djb2.ts               # seed hash（string → uint32）
│   └── fisherYates.ts        # Fisher-Yates 洗牌
├── types/
│   └── index.ts              # 所有共用 TypeScript interface/type（Room、Player、LadderData 等）
└── index.ts                  # 公開匯出入口

主要匯出類型：

Import 規則：

• packages/client 可 import shared 的全部匯出
• packages/server 可 import shared 的全部匯出
• packages/shared 不得 import client 或 server；不得 import Node.js 內建 I/O 模組（fs、net、http 等）
• client 與 server 之間無直接 import（透過 WS/HTTP 通訊）

§5 Key Algorithms

§5.1 Ladder Generation Algorithm

函式： packages/shared/src/use-cases/GenerateLadder.ts

核心邏輯：

export function generateLadder(seedSource: string, N: number): LadderData {
  const seed = djb2(seedSource);
  const rng = createMulberry32(seed);

  const rowCount = Math.min(Math.max(N * 3, 20), 60);
  const colCount = N;
  const maxBarsPerRow = Math.max(1, Math.round(N / 4));

  // Bar density — fewer possible positions → lower density to preserve randomness
  // N=2 has only 1 position; without skipping, every row would be identical
  const possiblePositions = N - 1;
  const barDensity = possiblePositions <= 1 ? 0.50
    : possiblePositions <= 2 ? 0.65
    : possiblePositions <= 3 ? 0.75
    : 0.90;

  const segments: LadderSegment[] = [];

  for (let row = 0; row < rowCount; row++) {
    if (rng() > barDensity) continue;           // skip row if rng > barDensity

    const usedCols = new Set<number>();
    let barsPlaced = 0;

    for (let attempt = 0; attempt < maxBarsPerRow; attempt++) {
      let col = Math.floor(rng() * (N - 1));

      // Retry: linear scan up to N-1 attempts to find a free column
      let found = false;
      for (let retry = 0; retry < N - 1; retry++) {
        const candidate = (col + retry) % (N - 1);
        if (!usedCols.has(candidate) && !usedCols.has(candidate + 1)) {
          col = candidate;
          found = true;
          break;
        }
      }

      if (!found) break;

      usedCols.add(col);
      usedCols.add(col + 1);
      segments.push({ row, col });
      barsPlaced++;
      if (barsPlaced >= maxBarsPerRow) break;
    }
  }

  return { seed, seedSource, rowCount, colCount, segments };
}

關鍵參數：

seed 生成：

• seedSource：crypto.randomUUID()（START_GAME 時在 Server 端生成，UUID v4 hex 字串）
• seed：djb2(seedSource) >>> 0（轉為 unsigned 32-bit integer）
• 安全邊界：seed 及完整樓梯資料在 status=finished 前禁止傳送給任何客戶端（PRD NFR-05）

§5.2 Path Calculation Algorithm

函式： packages/shared/src/use-cases/ComputeResults.ts

從頂部追蹤到底部，遇到橫槓段（segment）則切換欄位：

for (let startCol = 0; startCol < colCount; startCol++) {
  let col = startCol;
  const path: PathStep[] = [];
  for (let row = 0; row < rowCount; row++) {
    if (segmentSet.has(`${row}:${col}`)) {
      path.push({ row, col, direction: "right" });  // 右側有橫槓 → 向右
      col++;
    } else if (col > 0 && segmentSet.has(`${row}:${col - 1}`)) {
      path.push({ row, col, direction: "left" });   // 左側有橫槓 → 向左
      col--;
    } else {
      path.push({ row, col, direction: "down" });   // 無橫槓 → 向下
    }
  }
  paths.push(path);
  endCols.push(col);
}

中獎指派（Fisher-Yates bijection）：

// Step 3: Fisher-Yates 洗牌決定哪些 endCol 為中獎（消耗 colCount 次 rng）
const indices = Array.from({ length: colCount }, (_, i) => i);
const shuffled = fisherYatesShuffle(indices, rng);
const winnerEndCols = new Set(shuffled.slice(0, winnerCount));

• bijection 保證：N 個起點對應 N 個唯一終點，無共用 endCol
• startColumn 指派：玩家依 joinedAt 由早到晚排序（相同時以 playerId 字典序升冪），依序指派打亂後的 startColumn

§5.3 Canvas Rendering

函式： packages/client/src/canvas/renderer.ts

繪製流程（drawLadder）：

1. Rails（垂直柱）：從頂到底繪製每條垂直線（N 條）
2. Rungs（橫段）：依 segments[] 繪製所有橫槓（連接 col 與 col+1）
3. Revealed paths（已揭曉路徑）：依 PathStep[] 逐格繪製走線動畫

• 自己的路徑：高亮色（每人一色）
• 他人路徑：對應色，globalAlpha=0.6（半透明）
• 未揭曉路徑：灰色虛線

1. Player names（玩家名稱）：頂部各列顯示玩家暱稱
2. Winner stars（中獎標記）：中獎者 shadowBlur=10 金色光暈效果

顏色系統（packages/client/src/canvas/colors.ts）：

• colorFromIndex(i)：每位玩家一個不重複色（最多 50 色）
• colorFromIndexDim(i)：淡化版（他人路徑，globalAlpha=0.6）

FPS 目標：

• 桌機（1080p Chrome）：≥ 30fps
• 手機（Chrome DevTools Moto G4 throttling，10 秒平均）：≥ 24fps

PRNG 實作（djb2 + Mulberry32 + Fisher-Yates）：

// djb2 hash
export function djb2(str: string): number {
  let hash = 5381;
  for (let i = 0; i < str.length; i++) {
    hash = (Math.imul(hash, 33) + str.charCodeAt(i)) | 0;
  }
  return hash >>> 0;
}

// Mulberry32 PRNG
export function createMulberry32(seed: number): () => number {
  let s = seed >>> 0;
  return function next(): number {
    s += 0x6d2b79f5;
    let t = Math.imul(s ^ (s >>> 15), 1 | s);
    t ^= t + Math.imul(t ^ (t >>> 7), 61 | t);
    return ((t ^ (t >>> 14)) >>> 0) / 0x100000000;
  };
}

// Fisher-Yates shuffle
export function fisherYatesShuffle<T>(arr: readonly T[], rng: () => number): T[] {
  const result = [...arr];
  for (let i = result.length - 1; i > 0; i--) {
    const j = Math.floor(rng() * (i + 1));
    [result[i], result[j]] = [result[j], result[i]];
  }
  return result;
}

§6 WebSocket Protocol

§6.1 Message Types

連線端點： WSS /ws?room={code}&token={sessionToken}

Server Upgrade 階段驗證 JWT token，失敗直接 403。

Server → Client 事件（WsEventType）：

Client → Server 訊息（WsMsgType）：

訊息格式：

// Server → Client
interface ServerEnvelope<T = unknown> {
  readonly type: WsEventType;
  readonly ts: number;
  readonly payload: T;
}

// Client → Server
interface ClientEnvelope<T = unknown> {
  readonly type: WsMsgType;
  readonly ts: number;
  readonly payload: T;
}

安全限制：

• maxPayload: 65536（64KB），超過則拒絕並關閉連線（PRD NFR-05）
• 速率限制：60 msg/min/連線，超限 WS close code 4029

§6.2 Connection Lifecycle

connect
  → JWT 驗證（main.ts ws.Server upgrade handler）
  → kickedPlayerIds 攔截（close 4003 if kicked）
  → Origin 驗證（CORS_ORIGIN 白名單）
  → WS session 建立（roomSessions map）
  → unicast ROOM_STATE_FULL

game loop
  JOIN_ROOM → ROOM_STATE（廣播）
  START_GAME → ROOM_STATE（running）
  BEGIN_REVEAL → ROOM_STATE（revealing）
  REVEAL_NEXT / auto-timer → REVEAL_INDEX（廣播）
  REVEAL_ALL_TRIGGER → REVEAL_ALL（廣播）
  END_GAME → ROOM_STATE（finished，seed 公開）

disconnect handling
  ws close event → player.isOnline = false → 廣播 ROOM_STATE
  60s grace period → HOST_TRANSFERRED（Post-MVP）
  最後一位斷線 5 分鐘 → EXPIRE room:{code} 300

reconnect
  帶 playerId → ROOM_STATE_FULL（狀態快照）
  同一 playerId 新連線 → SESSION_REPLACED 至舊連線
  kickedPlayerId → close 4003

WS 重連策略（Client）
  指數退避：1s / 2s / 4s / 8s / 30s（上限）
  5 次失敗後停止，顯示「無法連線」+ 手動重試按鈕

§7 Data Models

§7.1 Redis Key Schema

§7.2 Room Object

interface Room {
  code: string;                          // 6-char room code
  status: RoomStatus;                    // waiting/running/revealing/finished
  hostId: string;                        // Host playerId
  readonly players: readonly Player[];   // max 50，含 isOnline=false 的斷線玩家
  winnerCount: number | null;            // W（1 <= W <= N-1）；null 直到 Host 設定
  ladder: LadderData | null;             // null 直到 BEGIN_REVEAL
  results: readonly ResultSlot[] | null;
  revealedCount: number;                 // 已揭曉數（快照；唯一計數來源為 :revealedCount key）
  revealMode: "manual" | "auto";
  autoRevealIntervalSec: number | null;  // 1-300s；null 為手動模式
  readonly kickedPlayerIds: readonly string[];  // 本局被踢玩家 playerId，RESET_ROOM/PLAY_AGAIN 後清空
  createdAt: number;
  updatedAt: number;
}

§7.3 Player Object

interface Player {
  id: string;              // UUID v4
  nickname: string;        // 1-20 chars
  colorIndex: number;      // 0-49
  isHost: boolean;         // 派生：id === room.hostId
  isOnline: boolean;
  joinedAt: number;        // Unix ms
  result?: string | null;  // null 直到揭曉；winner/loser 字串由 GameService 寫入
}

§7.4 Game State 生命週期

stateDiagram-v2
    [*] --> waiting : POST /api/rooms 建立

    waiting --> waiting : player_joined / player_left / host updates prizes
    waiting --> running : host START_GAME\nN>=2 AND 1<=W<=N-1\n原子: seed生成（不含梯子）

    running --> revealing : host BEGIN_REVEAL\n此時原子生成 LadderData + ResultSlots\nbcast ROOM_STATE status:revealing

    revealing --> revealing : REVEAL_NEXT（手動）/ auto-timer（自動）\nrevealedCount < N\nbcast REVEAL_INDEX path result
    revealing --> revealing : SET_REVEAL_MODE 切換手動↔自動
    revealing --> revealing : REVEAL_ALL_TRIGGER\nbcast REVEAL_ALL（剩餘路徑）

    revealing --> finished : host END_GAME\n（revealedCount === totalCount）\nbcast ROOM_STATE status:finished 含 seed\nTTL 延長 1h

    finished --> waiting : host PLAY_AGAIN\n剔除 isOnline=false 玩家\n清空 kickedPlayerIds\nbcast ROOM_STATE waiting

    waiting --> waiting : host RESET_ROOM（任意狀態可觸發）\n清空結果與 kickedPlayerIds\nbcast ROOM_STATE waiting
    running --> waiting : host RESET_ROOM
    revealing --> waiting : host RESET_ROOM
    finished --> waiting : host RESET_ROOM

    waiting --> [*] : room TTL expired
    running --> [*] : all disconnected 5 min
    finished --> [*] : room TTL expired 1h

§8 API Design Overview

§8.1 HTTP REST Endpoints

所有端點掛載於 /api/（無版本前綴），回應格式為直接 JSON（無 success/data/error 包裝）。

JWT TTL：6 小時（exp = iat + 21600）。

Rate Limiting：

• 全域：100 req/min/IP（@fastify/rate-limit 全域套用）

§8.2 Authentication

• JWT HS256（jose 套件），payload：{ playerId, roomCode, role: "host" | "player", exp }
• Host 操作雙重驗證：JWT role=host AND Redis room.hostId === playerId（防止 token 偽造或 host 轉移後舊 token 濫用）
• WS Upgrade：JWT 驗證在 main.ts 的 ws.Server upgrade handler 完成；WS 連線建立後不重驗 exp（MVP 接受的安全取捨）

§9 Performance Design

§9.1 Redis Usage

TTL 策略：

Redis 記憶體估算（100 並發房間）：

單房間：
  Room JSON (50 players × 200 bytes)  ~10 KB
  Ladder data (N=50, ~600 segments)   ~5 KB
  Results (50 players × 120 steps)    ~72 KB
  小計                                ~90 KB

100 房間：100 × 90 KB = 9 MB
Pub/Sub overhead: ~1 MB
總計 ~10 MB（maxmemory: 512mb 配置）

§9.2 WebSocket Scaling

MVP（單 Pod）：

• 目標：100 並發房間 × 50 人 = 5,000 WS 連線
• 自動揭示 timer 由 GameService 的 setInterval 管理（Pod 本地記憶體）
• Redis Pub/Sub 退化為本地自訂閱，overhead 可忽略

Post-MVP（HPA 多 Pod）：

• Kubernetes HPA：minReplicas: 2, maxReplicas: 10，metric: ws_active_connections 目標 200
• Traefik sticky session（cookie affinity）確保同一房間玩家路由至同一 Pod
• 自動揭示 timer 以 Redis SETNX 分散式鎖確保單一 Pod 持有計時器
• Redis StatefulSet 升級至 2 replicas（master + replica）

WebSocket QPS 推算：

加入房間高峰（前 5 分鐘）：100 房 × 50 人 / 300s ≈ 17 HTTP QPS
揭示階段廣播：100 房 × 1 揭示/s × 50 人 = 5,000 WS 發送/s
Redis 操作：< 500 ops/s（Redis 可承受 100k+ ops/s）

§10 Security Design

§10.1 OWASP Top 10 對應措施

§10.2 Seed 防洩漏機制

§10.3 JWT Security

• Token 有效期：6 小時（exp = iat + 21600）
• WS 連線建立後不重驗 exp（MVP 取捨：房間生命週期通常遠低於 6h）
• host 轉移後舊 token 仍需以 room.hostId 雙重驗證，防舊 token 濫用
• WS Upgrade 前 Origin 驗證（CORS_ORIGIN 環境變數白名單）

§11 Error Handling Strategy

§11.1 HTTP 錯誤碼

§11.2 WebSocket 重連策略

§11.3 Redis 失敗降級策略

• RoomRepository 所有方法拋出 SYS_REDIS_ERROR
• 觸發方收到 ERROR { code: "SYS_REDIS_ERROR" } 並保持 WS 連線
• 新的 HTTP 加入請求回傳 503 Service Unavailable
• GET /ready 回傳 { redis: "error" } 讓 Kubernetes readinessProbe 立即移除 Pod
• ioredis 內建指數退避重連；WS 客戶端重連後收到最新 ROOM_STATE_FULL

§12 Testing Strategy

§12.1 測試金字塔

§12.2 覆蓋率目標

§12.3 關鍵測試案例

§12.4 測試基準線

現有 Vitest 測試：171 tests（截至 2026-04-21）

CI 覆蓋率閘門：

coverage-gate:
  runs-on: ubuntu-latest
  needs: [unit-test, integration-test]
  steps:
    - name: Check coverage >= 80%
      run: npx vitest --coverage --reporter=json

§13 Deployment & Operations

§13.1 Kubernetes 本機開發流程

Prerequisites：

• Rancher Desktop（containerd runtime，kubectl + nerdctl 可用）
• /etc/hosts：127.0.0.1 ladder.local

一鍵操作：

# 啟動完整環境（build images + apply manifests）
./scripts/dev-k8s.sh up

# 停止並清理
./scripts/dev-k8s.sh down

# 重新 build 並 rolling restart
./scripts/dev-k8s.sh restart

# 串流所有 Pod 日誌
./scripts/dev-k8s.sh logs

手動步驟（等效）：

# 1. build server image
docker build -t ladder-server:local -f Dockerfile .

# 2. build client image
docker build -t ladder-client:local -f Dockerfile.client .

# 3. load images to Rancher Desktop
nerdctl image load -i <(docker save ladder-server:local)
nerdctl image load -i <(docker save ladder-client:local)

# 4. apply k8s manifests
kubectl apply -f k8s/

# 5. 驗證
kubectl get pods -n ladder-room
curl http://ladder.local/health

§13.2 兩個獨立 Pod 架構

§13.3 CI/CD Pipeline

graph TD
    Push["git push / PR opened"]

    subgraph CI["GitHub Actions: CI"]
        Checkout["checkout@v4 SHA-pinned"]
        Setup["setup-node@v4 node:20 cache:npm"]
        Install["npm ci --workspaces"]

        subgraph Parallel["Parallel Jobs"]
            Lint["lint\neslint + tsc --noEmit"]
            Audit["audit\nnpm audit --audit-level=high"]
            Unit["unit-test\nVitest + coverage v8"]
        end

        Integ["integration-test\ntestcontainers Redis\nVitest integration"]
        Build["build\nnpm run build\nDocker multi-stage\ndocker scout cves"]
        E2E["e2e\nDocker compose up\nPlaywright test"]
        Gate["coverage-gate\nfail if < 80%"]
        Release["tag-release\nmain only\ndocker push GHCR\ngit tag v{semver}"]
    end

    Push --> Checkout --> Setup --> Install --> Parallel
    Parallel --> Integ
    Parallel --> Build
    Integ --> Gate
    Build --> E2E
    E2E --> Release
    Gate --> Release

§13.4 環境變數

Appendix: ADR（Architecture Decision Records）

ADR-001: Vanilla TypeScript over React/Vue

決策： 前端採用 Vanilla TypeScript + Vite，不使用任何 UI 框架。

理由：

• 無框架冗餘依賴，確保 JS bundle < 80KB gzip（首頁）/ < 150KB gzip（遊戲頁）
• HTML5 Canvas 渲染邏輯本質上是命令式，React/Vue 的宣告式模型反而增加 overhead
• 目標瀏覽器（Chrome 110+）完整支援 Vanilla TS 所需的 Web API

取捨： 需手動管理 DOM 操作與事件處理，測試需自行模擬 Canvas API；後續加入 UI 框架的遷移成本相對較高。

ADR-002: WebSocket over SSE

決策： 即時通訊採用 WebSocket（ws 原生套件），不使用 Server-Sent Events（SSE）。

理由：

• 遊戲狀態需要雙向通訊：客戶端發送 START_GAME、REVEAL_NEXT 等操作，SSE 為單向（Server→Client）
• 主持人控制操作（踢人、揭曉控制）需要低延遲雙向通道
• 所有目標瀏覽器均原生支援 WebSocket，無需 polling fallback

取捨： 需自行實作心跳、重連、房間廣播邏輯；MVP 實作集中於 main.ts（roomSessions Map + broadcast helper）；複雜度可控。

ADR-003: Redis over In-Memory State

決策： 所有房間狀態儲存於 Redis，Pod 本地記憶體不快取業務狀態。

理由：

• Pod 重啟（rolling update、崩潰恢復）後狀態存活，客戶端指數退避重連後可恢復
• Post-MVP 多 Pod 水平擴展時，Redis 作為唯一共享狀態層，無需額外同步機制
• Redis WATCH/MULTI/EXEC 原子操作天然解決 concurrent update（多玩家同時加入等）

取捨： Redis 單節點為 MVP SPOF；Redis 失敗時所有操作降級（503）；ioredis 內建重連機制在 Redis 重啟後自動恢復。

ADR-004: packages/shared 前後端共用算法

決策： PRNG（Mulberry32、djb2、Fisher-Yates）、GenerateLadder、ComputeResults 封裝於 packages/shared，前後端共用相同實作。

理由：

• 確保算法一致性：前端 Canvas 渲染路徑動畫 = 後端計算結果，100% 一致（PRD NFR-03）
• 結果可事後審計：seed 公開後，任何人可用相同算法驗證本局結果
• 1,000 次 seed 自動化驗證 CI 閘門確保 bijection 特性

取捨： packages/shared 必須保持零 I/O（不得 import Node.js 內建模組），限制了可在共用層處理的邏輯。

ADR-005: JWT HS256 over Session Cookie

決策： Host 身份驗證採用 JWT HS256（jose 套件），而非 Session Cookie。

理由：

• 無狀態驗證：每個請求自帶 { playerId, roomCode, role, exp }，不需額外 Redis 查詢
• WS Upgrade 場景：JWT 可附在 URL query parameter，Cookie 在跨域 WS 場景較複雜
• jose 支援 Web Crypto API，瀏覽器端未來可直接驗證（可審計性）

取捨： JWT 一旦簽發無法提前撤銷；host 轉移後舊 token 在 exp 前仍有效，須以 room.hostId 雙重驗證。WS 連線建立後不重驗 exp（MVP 取捨：連線生命週期通常遠低於 6h）。

ADR-006: Traefik over NGINX Ingress（Rancher Desktop 本機環境）

決策： 本機 Kubernetes 環境採用 Traefik Ingress（Rancher Desktop 內建），不採用 NGINX Ingress Controller。

理由：

• Rancher Desktop 預設內建 Traefik，零額外安裝步驟
• Traefik 原生支援 WebSocket upgrade（無需額外 annotation）
• sticky session（cookie affinity）在 Traefik 與 NGINX 均可實現，切換成本低

取捨： 生產環境可能使用 NGINX Ingress；k8s manifest 中保留 NGINX 備選設定（已註解）供遷移參考。Post-MVP 升級時若切換 Ingress Controller，需驗證 sticky session 行為一致性。

EDD 版本：v2.0

生成時間：2026-04-21（devsop-autodev STEP-07：從 BRD v1.0 + PRD v1.0 + legacy-EDD v1.4 + legacy-ARCH v1.2 整合重建）

基於 BRD v1.0 + PRD v1.0 + legacy-EDD v1.4 + legacy-ARCH v1.3（Ladder Room Online）

變更追蹤

ECR-20260420-001：HOST copy 邀請 link（含 6 碼房號）+ localStorage 暱稱記憶，一鍵加入

• 狀態：✅ DONE
• 分類：ECR / 需求面
• 日期：2026-04-20
• 描述：HOST 開好房間後可 COPY 邀請 link（含 6 碼房號），受邀者點 link 自動帶入房號，名字欄位自動帶入上次輸入過的名字，一鍵加入。
• 影響範圍：§4.2 Client Modules（LocalStorageService）、邀請連結規格
• commit：70b1e66