PRD — 三公遊戲（Sam Gong 3-Card Poker）即時多人線上平台

<!-- SDLC Requirements Engineering — Layer 2：Product Requirements -->

Document Control

Change Log

1. Overview & Objectives

1.1 Product Vision

打造華人市場首款 Server-Authoritative 即時多人三公遊戲，以「絕對公平」為核心差異化，讓 35–55 歲華人玩家能跨平台（Web + Android + iOS）安心享受公平、流暢的三公對戰體驗，不再擔心發牌不公或對手作弊。

1.2 Link to BRD Objectives

BDD S-ID 預分配說明： BDD場景詳細內容於STEP-15生成；S-ID已預先保留，確保追溯鏈完整。Must Have REQs預分配：REQ-001→S-001, REQ-002→S-002, REQ-003→S-003, REQ-004→S-004, REQ-010→S-010, REQ-011→S-011, REQ-012→S-012, REQ-013→S-013, REQ-014→S-014, REQ-015→S-015, REQ-016→S-016, REQ-017→S-017（+IT-anticheat-001）, REQ-019→S-019（+IT-delete-001）, REQ-020a→S-020a, REQ-020b→S-020b, REQ-021→S-021。【F22】REQ-020b獨立BDD ID為S-020b（非S-020），確保與REQ-020a（S-020a）明確區分，避免測試追溯歧義。

1.3 Success Metrics（來源 BRD §7）

北極星指標（North Star）：

週活躍對戰場次（Weekly Active Rounds）— Launch+6M 目標：≥ 50,000 場/週

Go / No-Go 里程碑：

2. User Personas

Persona 1：Casual Player（休閒玩家）

Persona 2：Competitive Player（競技玩家）

Persona 3：Returning Player（回歸玩家）

3. Feature Specifications（REQ-001 to REQ-021）

REQ-001：洗牌系統（Fisher-Yates shuffle，Server-side）

Feature Name： Server 端 Fisher-Yates 亂數洗牌

User Story：

As a Casual Player（張先生）, I want the game deck to be shuffled on the server using a cryptographically unbiased algorithm so that I can trust no one—including the developers—can predict or manipulate card order.

Acceptance Criteria：

1. Server 以 Fisher-Yates（Knuth shuffle）演算法執行 52 張牌的洗牌；洗牌過程完全發生於 Server 端，Client 不接收任何洗牌種子或中間結果。
2. 洗牌亂度統計驗證（BRD F19）：樣本數 ≥ 10,000 次洗牌，對 52 張牌 × 52 個位置分佈進行卡方檢定（自由度 = 51），p-value > 0.05 為通過；此測試必須在 Alpha 驗收（2026-06-21）前完成，結果記入測試報告。
3. Client bundle 靜態代碼分析掃描（CI/CD 每次 build 執行）中，以下關鍵字命中數必須為 0：compareCards、calculatePoints、determineWinner、cardValue、handRank、shuffle、sortCards、suitRank、suitOrder、tieBreak、rakeFee、settlementCalc、bankerPayout、Math.random；工具：ESLint custom rule 或 grep；掃描 0 命中為 Pass。注意：中文命名函式不受關鍵字掃描保護，根本防護依賴F35架構隔離（server-only TypeScript package）。【F16 中文命名函式規避風險】 架構隔離（AC-7 TypeScript project references CI gate）為主要防護；若CI架構隔離配置錯誤，需有回退掃描（如TypeScript AST分析判斷遊戲邏輯模式是否出現在client package）；此回退掃描需在Security Review checklist（Alpha前）中列為必查項。
4. 每次洗牌使用加密安全亂數源（如 Node.js crypto.randomInt()），不使用 Math.random()。測試方法：(a) CI/CD 靜態掃描禁止關鍵字包含 Math.random（已納入 AC-3 禁止關鍵字清單）；(b) Server 單元測試 mock crypto 模組，驗證呼叫路徑使用 crypto.randomInt()；Pass 條件：掃描 0 命中 + 單元測試通過。

Out of Scope：

• Client 端洗牌邏輯（明確禁止）。
• 可驗證亂數（VRF）或可公開審計的鏈上洗牌（列入 v1.x 研究）。
• 洗牌種子日誌對外公開（v1.0 僅記錄於 Server DB，不對外開放）。

架構邊界約束（F35）： Server遊戲邏輯（洗牌、比牌、結算）必須位於獨立server-only TypeScript package；Client build系統不得import此package；透過TypeScript project references強制邊界，CI lint規則驗證（違反則阻擋build）。

AC-7（架構邊界 CI 驗證）： CI/CD pipeline 必須包含 TypeScript project references 邊界驗證步驟；若 Client package 成功 import server-only package 的遊戲邏輯模組，CI build 失敗（exit code 1）；工具：eslint no-restricted-imports rule 或 tsc --noEmit 驗證；Pass 條件：Client 端任何 import server-only 模組的嘗試均導致 CI build failure。

CI/CD安全管線（F50）： CI/CD pipeline必須包含：(1) npm audit（高危阻擋合併）；(2) SAST（Semgrep）；(3) 容器鏡像漏洞掃描（Trivy）；(4) OSS License合規檢查；任一失敗阻擋部署。

Dependencies： REQ-002（洗牌結果直接輸入發牌系統）

Priority： Must Have

REQ-002：發牌系統（Server deals 3 cards to each player）

Feature Name： Server 端發牌與手牌狀態管理

User Story：

As a Casual Player, I want the server to deal exactly 3 face-down cards to each player after shuffling so that my hand is secret until the showdown phase.

Acceptance Criteria：

1. 每局牌局開始後，Server 從已洗牌的 52 張牌中按座位順序依次發給每位玩家 3 張牌；發牌邏輯完全在 Server 執行，Client 僅接收「手牌已發」的狀態通知，不接收其他玩家的手牌內容。
2. 玩家在翻牌（Step 4）前，只能透過 Colyseus Room State 看到自己的 3 張手牌；其他玩家的手牌以「暗牌」狀態呈現（Client 無法從 Schema 推算其他玩家手牌）。
3. 每局所用牌數 = 玩家人數 × 3；一副 52 張牌不重複發牌（不放回抽樣）；任何重複牌出現視為嚴重 Bug（P0 級）。
4. 發牌完成後，Room State 更新至所有 Client 的延遲 ≤ 100ms（P95，亞太區用戶）。測試規格：工具 k6 或 Colyseus load test；測試環境：亞太區模擬（EC2 ap-northeast-1）；負載：500 CCU 持續 10 分鐘；樣本數 ≥ 10,000 次操作；通過條件：P95 ≤ 100ms 且 P99 < 500ms。

1. 手牌隔離安全測試（AC-5）：Alpha 驗收（2026-06-21）前執行封包截取測試（工具：Wireshark 或 mitmproxy）；模擬 6 人房間，記錄每位玩家收到的全部 WebSocket 幀；驗證每位玩家的發牌通知幀中僅含自己的 3 張手牌，不含其他玩家手牌資訊；Pass 條件：6 位玩家封包抽樣全通過，0 次手牌洩漏。

Out of Scope：

• 公牌（Community Card）機制（v1.0 不實作，見 BRD §5.5 公牌規則決策）。
• 多副牌（Shoe）機制。
• Client 端的發牌動畫邏輯（動畫屬 REQ-013 範圍）。

Dependencies： REQ-001（需洗牌完成）、REQ-011（Room State schema 同步）

Priority： Must Have

REQ-003：比牌系統（Server evaluates hands per BRD §5.5 rules）

Feature Name： Server 端三公比牌引擎

User Story：

As a Competitive Player（林小姐）, I want the server to evaluate all hands according to the official Taiwan Sam Gong rules so that the winner is determined fairly and transparently, without any possibility of client-side manipulation.

Acceptance Criteria：

1. Server 比牌邏輯完全依照 BRD §5.5 台灣標準版規則：三張牌點數相加 mod 10；A=1，2–9 面值，10/J/Q/K=0；三公（三張均為 10 點牌）為最大牌型；比牌順序：三公 > 9 點 > 8 點 > … > 1 點 > 0 點（非三公）。
2. 同點數平手決勝規則（D8）實作：第一步比最大單張花色（黑桃 > 紅心 > 方塊 > 梅花）；花色相同時第二步比最大單張點數（K > Q > J > 10 > 9 > … > 2 > A，A 為最小）；兩步皆同則平手退注；此規則適用於所有同點情境包含三公 vs 三公（D10）。
3. Server 比牌引擎自動化測試：提供 ≥ 200 個預定義測試向量（含邊界情境：三公 vs 三公、平手、0 點 vs 0 點、同花色不同點數），每個向量指定輸入手牌和預期結果；CI 執行所有向量通過率 = 100% 視為 Pass；向量集在 Alpha（2026-06-21）前完成並納入版本控制。
4. 比牌計算不使用浮點運算，全程整數運算，誤差容忍 = 0。

Out of Scope：

• Client 端任何比牌計算邏輯（明確禁止）。
• 地區性公牌規則（v1.0 不實作）。
• AI 對手（v1.0 僅真人 vs 真人）。

Dependencies： REQ-002（需手牌資料）、REQ-001（間接依賴）

Priority： Must Have

REQ-004：結算系統（Settlement per BRD §5.5 payout model，rake 5%）

Feature Name： Server 端三步驟結算引擎（含抽水）

User Story：

As a Casual Player, I want the server to automatically calculate and distribute chips after each round according to the payout table so that I always receive the correct amount without disputes.

Acceptance Criteria：

1. 結算依 §5.3 三步驟原子性執行：Step 6a 確認每位閒家比牌結果；Step 6b 從輸家閒家下注額加總中扣除 5% 抽水（floor(輸家下注額加總 × 0.05)，最少 1 籌碼）；空底池守衛（AC-1）：若底池（輸家閒家下注額加總）= 0，則抽水 = 0，最少1籌碼條款不適用；最少1籌碼僅在底池 > 0時生效；Step 6c 依序支付（閒家勝：莊家直接支付本金 1× + N× 賠率，不經底池；閒家敗：閒家下注額歸底池扣抽水後給莊家）。事務隔離：使用PostgreSQL SERIALIZABLE隔離等級或READ COMMITTED + SELECT FOR UPDATE行級鎖；並發安全測試：100個並發結算請求，驗證籌碼守恆誤差 = 0。【F1 莊家預扣時機（AC-1補充）】莊家下注確認後（§5.1 Step 2），Server立即預扣（escrow）banker_bet_amount：banker chip_balance -= banker_bet_amount（預扣至托管態）；Step 6c支付贏家時從預扣額及剩餘餘額中順序支付；破產判斷以Step 2後的chip_balance為準。
2. 籌碼守恆驗證：每局結算後，全體玩家籌碼淨增減之和必須等於 -(抽水額)；誤差容忍 = 0 籌碼；驗證在結算事務提交後同步執行；失敗時：(1) 立即回滾結算事務；(2) 寫入CRITICAL log含game_id和差異金額；(3) 觸發PagerDuty告警，SRE響應SLA ≤ 15分鐘。
3. 莊家破產規則（先到先得，D13）：若莊家籌碼不足以支付所有贏家，依閒家順時鐘座位順序逐一支付贏家；每位贏家依序收取本金（1×下注額）+N×下注額賠付；莊家籌碼歸零後，後續排隊贏家所得為零（不按比例分配，不取回本金，得零）；抽水 = floor(莊家破產前已實際完成結算的輸家閒家下注額加總 × 0.05)，最少1籌碼（底池 > 0 時）；莊家破產後未完成結算的輸家下注額不計入抽水底數；移除任何「按比例」抽水語言。破產後得零贏家的結算廣播使用insolvent_winners陣列（見§7 settlement廣播schema）。【F1 破產判定（AC-3補充）】破產判定：若莊家Step 6c支付過程中chip_balance + escrow_amount < 本次應支付額，觸發D13先到先得；後續贏家得零。（注：Step 2後chip_balance為逐筆支付起點；Step 6c支付過程中escrow_amount隨每筆支付逐步釋放，故可用資金 = 當前chip_balance + 未釋放escrow_amount，與AC-1「Step 2後chip_balance為準」指同一基準資金池）
4. 結算完成後，Server 在 100ms 內廣播最終狀態至所有 Client，包含每位玩家的籌碼變動明細。測試規格：工具 k6 或 Colyseus load test；測試環境：亞太區模擬（EC2 ap-northeast-1）；負載：500 CCU 持續 10 分鐘；樣本數 ≥ 10,000 次操作；通過條件：P95 ≤ 100ms 且 P99 < 500ms。

Payout Table（台灣標準版）：

1. 平手玩家通知（AC-5）：平手閒家出現在settlement廣播的ties陣列中（見§7 settlement廣播schema）；Client收到後退回該閒家下注額至籌碼餘額並顯示平手動畫；平手不計入底池、不計入抽水底數；Server驗收：測試向量含平手情境，驗證ties陣列正確包含平手玩家，winner/loser陣列不含該玩家。

Out of Scope：

• 真實金錢結算（明確禁止）。
• 籌碼兌換（明確禁止）。
• 客服手動調籌碼（屬後台 Admin 工具，不在 v1.0 PRD 範圍）。

Dependencies： REQ-003（需比牌結果）、REQ-011（Room State 廣播）

Priority： Must Have

REQ-005：（保留編號）

Feature Name： 保留給好友系統（BRD §5.3 Should Have，DEFERRED至v1.x）

Priority： Should Have（v1.x Backlog，v1.0 DEFERRED）

Note： 本REQ-ID保留給好友系統功能；v1.0依賴私人房間ID邀請（REQ-010 AC-4）作為替代方案。詳見§10 O5。好友系統v1.0 DEFERRED決策見BRD Decision Log D15（2026-04-21）；v1.0不實作，保留至v1.x。

REQ-006：排行榜系統（Leaderboard）

Feature Name： 排行榜系統（週榜 / 月榜）

Priority： Could Have

User Story：

As a Competitive Player（林小姐）, I want to view weekly and monthly leaderboards so that I can track my ranking and compete with others.

Acceptance Criteria：

1. 排行榜資料更新延遲 ≤ 1 分鐘（從籌碼變動到榜單反映的端對端時間）。測試規格：使用 k6 或 Playwright 模擬；場景：觸發 ≥ 100 次已知籌碼變動事件；Pass 條件：P95（≥95次）的排行榜更新在 60 秒內反映；測試環境：非 CCU 壓測狀態下的 Staging 環境。
2. 支援週榜 / 月榜切換；週榜每週一 00:00 UTC+8 重置；月榜每月1日 00:00 UTC+8 重置。
3. 排行依據：週榜 = 本週淨籌碼收益；月榜 = 本月淨籌碼收益。
4. 顯示 Top 100 名玩家。
5. 同籌碼收益平手決勝：依達成時間先後（先達成者排名較前）。
6. 隱私選項：玩家可在帳號設定選擇「不顯示於排行榜」；選擇後從榜單中隱藏，不計入排名序號。
7. 測試方法：模擬已知籌碼變動後驗證排行榜更新延遲（≤ 1 分鐘）及排序正確性（依淨收益降冪、同收益以時間先後）。
8. 淨籌碼收益定義（AC-8）：本週（UTC+8週一00:00至週日23:59:59（UTC+8））內所有tx_type=game_win/game_lose的Transaction amount加總；daily_gift、rescue、iap、task_reward、ad_reward、refund、tutorial、admin_adjustment類型均不計入；同收益值平手決勝：依最早達成同淨收益值時的game_win記錄時間戳先後排序；相同淨收益時，較早達到該分數者（timestamp較小）排名較前，與AC-5「先達成者排名較前」保持一致；測試：預置已知遊戲交易序列，驗證排行榜排序與公式計算一致。

Out of Scope： 好友榜（v1.x）；即時榜（毫秒級更新）。

Dependencies： REQ-014（帳號系統）、REQ-004（結算系統，籌碼變動事件）

REQ-007：聊天室系統（In-Room Chat）

Feature Name： 房間內聊天室（含關鍵字過濾與舉報機制）

Priority： Could Have

User Story：

As a Casual Player, I want to send messages in the game room so that I can communicate with other players.

Acceptance Criteria：

1. 敏感關鍵字過濾覆蓋率 ≥ 95%（測試方式：以100條含敏感詞測試訊息驗證過濾命中率）。測試向量集維護：100條敏感詞測試訊息由Ops團隊維護，存放於/docs/content-policy/test-vectors.json，與關鍵字清單同目錄；Alpha驗收（2026-06-21）前完成初始版本；向量集更新需重新執行過濾驗證；版本號與關鍵字清單同步。【F10 Pass條件計算與多語言覆蓋】 Pass條件計算：100條測試向量中命中過濾的條數≥95條（95/100）；測試向量語言覆蓋：繁中為主（80條），含常見簡中混入詞（15條）及英文（5條）；CI每次向量集更新後自動重跑。
2. 舉報後審核處理 SLA ≤ 24 小時（Ops人工審核）。
3. 訊息留存 30 日後自動刪除。
4. 單條聊天消息最大長度200字元（AC-4）；超長消息Server端拒絕並返回{error:'message_too_long', max_chars:200}；Client提前截斷顯示。
5. 聊天消息Rate Limit（AC-5）：每玩家每秒≤2條；超限靜默丟棄（不提示），同一玩家超限累計3次觸發10秒冷卻。
6. 斷線重連後不推送歷史消息（AC-6）；僅推送重連後的新消息（避免消息洪水）。

聊天訊息隱私合規（F12）： (1) 30日自動刪除由定時任務執行，Ops監控執行率100%（SLA：每日驗證）；(2) 聊天訊息含player_id，屬個資法「間接識別」資料，適用NFR-11刪除義務（帳號刪除時聊天訊息隨帳號一併刪除或匿名化）；(3) 傳輸由TLS保護（引用NFR-04）。

Out of Scope： 跨房間廣播；語音聊天；表情包。

Dependencies： REQ-011（Room State）、REQ-014（帳號系統）

REQ-008：（保留編號）

Feature Name： 保留給多語系支援（英文 / 簡中，v1.0 Won't Have）

Priority： Won't Have（v1.0）

Note： 本REQ-ID保留給多語系功能；v1.0 僅繁體中文。詳見§10 O9。

REQ-009：（保留編號）

Feature Name： 保留給第二遊戲品類（大老二 / 21點，v2.0）

Priority： Won't Have（v1.0）

Note： 本REQ-ID保留給未來遊戲品類擴展；詳見§10 O10。

REQ-010：配對系統（Matchmaking queue + room creation）

Feature Name： 大廳 Matchmaking 配對系統

User Story：

As a Casual Player, I want to quickly join a game through fast matchmaking or create a private room so that I can start playing within 30 seconds without manually searching for opponents.

Acceptance Criteria：

1. 快速配對（Quick Match）：依玩家持有籌碼量自動匹配相近等級的對手；相近等級 = 同一房間 tier 廳；同廳配對等待最長30秒；若不足（同廳等待玩家<2人），觸發擴展至相鄰廳級（上下各一級）；擴展後額外等待最長60秒；總最長等待=90秒；配對成功後自動進入 Room；等待時間中位數 ≤ 30 秒（500 CCU 壓測環境）；配對失敗率 ≤ 5%。配對失敗定義：配對請求發出後90秒內（配對超時窗口）未成功進入房間的請求；不含玩家主動取消；失敗率 = 失敗次數 / (失敗次數 + 成功次數)。
2. 配對等待超過90秒總上限（30秒同廳+60秒擴展）自動取消，返回大廳並提示「配對超時，請稍後再試」並附帶超時原因；玩家保留在大廳頁面。
3. 每房間人數：最少 2 人、最多 6 人；房間人數不足 2 人時停止接受新局；系統等待新玩家補入，等待上限 60 秒；60 秒內無新玩家加入則自動解散房間，並向剩餘玩家發送通知「房間已解散，請重新匹配」，玩家不損失本局下注額（本局未完成，下注退回）；所有玩家離開後房間立即銷毀。
4. 指定房間（Private Room）：玩家可建立並分享房間 ID 邀請特定玩家加入；房間建立後 60 秒內無人加入自動解散；建立者獨自等待 60 秒後房間自動解散，建立者收到通知「房間已解散，無玩家加入」並返回大廳；建立者籌碼無損失。
5. 中途跌破入場門檻的玩家，在當局結算後自動移出至大廳，不影響進行中的牌局（見 §5.4）。

Out of Scope：

• 觀戰模式（v1.0 明確排除）。
• 好友列表自動配對房間推薦（屬好友系統 Should Have）。
• 跨區伺服器配對（首版僅亞太區）。

Dependencies： REQ-011（Room State）、REQ-014（帳號系統，需知玩家籌碼等級）

Priority： Must Have

REQ-011：房間狀態系統（Colyseus Room State schema sync）

Feature Name： Colyseus Room State 即時狀態同步

User Story：

As a Competitive Player, I want the game room state (player seats, chip counts, betting phase, card phase) to be synchronized in real-time so that I always see an accurate, up-to-date view of the game.

Acceptance Criteria：

1. Room State 使用 @colyseus/schema 定義，包含：玩家列表（seat index、玩家 ID、籌碼餘額、本局下注額、連線狀態）、牌局階段（waiting / dealing / banker-bet / player-bet / showdown / settled）、自己的手牌（僅己方可見）、計時器剩餘秒數、以及以下補充欄位：banker_seat_index（INTEGER，當前莊家座位索引）、banker_bet_amount（BIGINT，莊家本局底注額，供閒家 Call 使用）、banker_rotation_queue（ARRAY of seat_index，順時鐘輪莊序列）、is_tutorial（BOOLEAN，是否教學模式）。結算消息 payload 詳見 §7 settlement 廣播 schema。手牌可見性透過Colyseus filterBy機制或私人消息實作（非全體schema廣播）；驗收：抓包驗證其他玩家WebSocket消息中不含非己方hand資料。Server收到banker_bet/player_call等消息時，必須驗證：(1) 下注金額 ≤ 發送者當前籌碼餘額；(2) 金額在房間tier合法範圍；(3) 當前遊戲階段允許此操作；驗證失敗返回error消息並記錄。
2. 玩家操作（下注、棄牌）至 Server 確認並廣播更新的端對端延遲 ≤ 100ms（P95，亞太區）。測試規格：工具 k6 或 Colyseus load test；測試環境：亞太區模擬（EC2 ap-northeast-1）；負載：500 CCU 持續 10 分鐘；樣本數 ≥ 10,000 次操作；通過條件：P95 ≤ 100ms 且 P99 < 500ms。
3. 斷線重連行為（BRD §5.3）：玩家斷線後有 30 秒重連窗口；30 秒內重連後，Room State 完整恢復（手牌、籌碼、本局下注額與 Server 記錄完全一致，差異容忍 = 0）；30 秒內重連成功率 = 100%（執行 100 次模擬測試驗證）；逾時未重連自動視為 Fold。
4. WebSocket 心跳：ping/pong 心跳間隔 ≤ 10 秒；客戶端斷線後自動重連最多 3 次（退避：1/2/4 秒）；超過 30 秒斷線觸發 §8.1 斷線 Mid-Game 行為處理。
5. 計時器同步機制（AC-5）：Server在計時器啟動時廣播{action_deadline_timestamp}（Server Unix timestamp ms）；Client以本地時鐘計算剩餘時間用於顯示；超時判定由Server執行（Server-authoritative）；Client顯示誤差容忍≤1秒；測試：Client本地時鐘偏移±5秒時驗證Server仍正確執行超時。

Out of Scope：

• 觀戰者 Schema（v1.0 不實作）。
• Server-sent Events / REST polling 替代 WebSocket（本系統使用 Colyseus WebSocket）。

Dependencies： REQ-001, REQ-002, REQ-003, REQ-004（所有遊戲邏輯均透過 Room State 廣播）

Priority： Must Have

REQ-012：新手引導系統（Tutorial with practice game，tutorial_mode=true）

Feature Name： 互動式新手引導教學

User Story：

As a Returning Player（王伯伯）, I want a guided tutorial that teaches Sam Gong rules and lets me practice a simulated hand so that I can confidently join real games without fear of making mistakes.

Acceptance Criteria：

1. 首次登入帳號自動觸發新手引導流程；引導包含：(a) 三公規則說明（文字 + 圖示）、(b) 籌碼系統說明（等級、房間、每日贈送）、(c) 3輪固定劇本模擬牌局（不消耗籌碼，見AC-5劇本規格）；完成全部三個步驟後解鎖正式對戰入口。
2. 模擬牌局邏輯由 Server 執行（tutorial_mode=true），籌碼扣除邏輯跳過；Client 呈現的動畫流程與正式牌局相同（Server-authoritative 路徑），不繞過 Server 驗證。
3. 新手引導完成率 ≥ 60%（量測時間點：Launch+1M 即 2026-09-21；分母為account_created_at在當月（UTC+8）的新註冊帳號數；分子為同批帳號中完成全部引導步驟的帳號數）。
4. AC-4a: 重複觀看引導教學說明步驟（規則說明文字）：玩家可在帳號設定頁重新觀看，任何時候可跳過說明文字頁面。

AC-4b: 模擬牌局（不消耗籌碼）：僅在首次進入帳號時必須完成（不可跳過）；後續可隨時從設定頁重新體驗但非強制；首次完成後解鎖正式對戰入口。

AC-4c: 測試方法：新帳號進入 App 後，在未完成模擬牌局前，正式對戰入口 UI 處於 disabled 狀態，點擊顯示提示「請先完成新手引導」。

1. Tutorial劇本規格（AC-5，Server端固定劇本）：共進行3輪模擬牌局；第1輪：教學者手牌預設三公，NPC莊家為7點（教學者必勝，展示三公牌型）（三公mod 10=0點，雖計算點數為0，但三公為最高牌型，優先於所有非三公牌型；0點三公 > 9點 > ... > 0點非三公）；第2輪：普通比牌（教學者5點 vs NPC莊家3點，展示普通比牌）；第3輪：平手退注示範（教學者和NPC莊家均為6點）；第3輪Server固定發牌序列必須確保D8兩步均平手：第一步（最大單張花色）相同且第二步（最大單張點數）亦相同。精確牌面序列由EDD指定（tutorial_hand_sequence設定）；Server透過固定發牌序列實現劇本，tutorial_mode=true時使用預設牌序而非隨機洗牌。

Out of Scope：

• AI 對戰模式（Tutorial 模擬牌局為 Server 生成劇本，非真實 AI 對手）。
• 多語系引導（v1.0 僅繁體中文）。

Dependencies： REQ-011（Room State，tutorial_mode Room）、REQ-014（帳號系統，首次登入判斷）

Priority： Must Have

REQ-013：UI / 動畫系統（Pixel-art UI，deal / flip / settle animations）

Feature Name： Cocos Creator 像素風 UI 與牌局動畫

User Story：

As a Casual Player, I want to see smooth card dealing, flip, and settlement animations in a retro pixel-art casino style so that the game feels polished and exciting rather than sterile.

Acceptance Criteria：

1. 主要美術風格：像素風（Pixel-art）為 v1.0 正式版風格；賭場風格僅製作大廳主頁、牌局主畫面、結算畫面共 2–3 個關鍵畫面的 A/B 測試素材（供 Beta 封測用，最終風格選擇於 2026-07-21 前由 PM + Art Director 依測試數據決定）。
2. 必要動畫列表及時長限制：各動畫時長預算：發牌動畫 ≤ 1.5 秒；翻牌動畫 ≤ 0.5 秒（每張）；結算動畫 ≤ 1 秒；三段合計 ≤ 3 秒。動畫播放期間不阻塞玩家操作計時器（計時器在 Server 端繼續倒數）。通過條件：自動化測試錄製各動畫段時長，每段不超標且合計 P90 ≤ 3 秒。測試方法：(a) Web 端：Playwright 錄製時間線測量動畫時長；(b) Native Android：ADB 屏幕錄製（adb screenrecord）+ 幀計算，或 Cocos Creator Performance Stats 面板；基準裝置：Android 8.0 2GB RAM 實機；每類動畫執行 ≥ 10 次取 P90 值；Pass 條件：P90 ≤ 各段上限且合計 P90 ≤ 3 秒。
3. 動畫流暢度：在中低階 Android 裝置（以 Android 8.0、2GB RAM 為基準機型）上達到 ≥ 30fps；旗艦機型目標 ≥ 60fps。
4. UI 響應式設計：移動端最小螢幕寬度 375px（iPhone SE）無任何 UI 元素重疊或截斷；Beta 封測視覺滿意度（in-app 5 星問卷「您對本遊戲視覺風格的滿意度」）有效樣本 ≥ 50 人，平均評分 ≥ 4.0/5.0。
5. 免責聲明顯示：以下畫面必須顯示免責聲明「娛樂性質，虛擬籌碼無真實財務價值」：大廳主頁、牌局主畫面、結算畫面、籌碼商店、教學完成頁（tutorial_complete）、排行榜頁（leaderboard）、帳號/玩家資料頁（含籌碼餘額chip_balance顯示）、每日任務獎勵發放彈窗（task reward popup）；最小字體12px；QA驗收：截圖 + 文字識別工具自動驗證覆蓋率100%。決策：帳號/玩家資料頁因顯示chip_balance屬涉及籌碼畫面，強制包含免責聲明；每日任務獎勵發放彈窗同樣須顯示免責聲明。注意：若未來新增涉及籌碼的新畫面，均需包含免責聲明，由QA在功能上線審查時確認。

Out of Scope：

• 3D 動畫或特效（v1.0 為 2D 像素風）。
• 觀戰視圖動畫（v1.0 不實作）。
• 英文 / 簡中 UI 文字（v1.0 僅繁體中文）。

Dependencies： REQ-011（Room State 狀態驅動動畫觸發）

Priority： Must Have

REQ-014：帳號系統（Guest + Google / Facebook OAuth，age verification OTP）

Feature Name： 帳號系統（遊客 + OAuth + 年齡驗證）

User Story：

As a Casual Player, I want to quickly start playing as a guest and later link my Google or Facebook account so that I don't lose my progress, while also confirming I'm an adult before joining real games.

Acceptance Criteria：

1. 遊客帳號：玩家可不登入直接進入教學模式；正式對戰需完成帳號創建 + 年齡驗證；遊客轉正式帳號流程 ≤ 3 步驟（填入資料 → OTP 驗證 → 完成）。
2. OAuth 綁定：支援 Google OAuth 2.0 與 Facebook Login；綁定後現有虛擬籌碼與進度保留；一個 OAuth 帳號最多綁定 1 個遊戲帳號。
3. 年齡驗證閘（BRD §9.2）：所有新帳號必須完成年齡驗證後才可進入正式對戰；流程：① 玩家填入出生年份 → ② 系統判斷是否 ≥ 18 歲 → ③ 通過則發送手機 OTP（6 碼，5 分鐘有效）→ ④ OTP 驗證成功後帳號啟用；未完成驗證者只可進入教學模式，不可參與正式對戰；年齡驗證閘 100% 覆蓋新帳號。邊緣情況說明：v1.0 年齡計算採「currentYear − birthYear」（僅比較年份，不含月日）；通過條件：(currentYear - birthYear) ≥ 18；測試案例：birthYear=2008（currentYear=2026時通過），birthYear=2009（拒絕），birthYear=1950（通過）；此方式可能允許年內生日尚未到的 17 歲用戶通過（最多 11 個月誤差）。v1.0 接受此限制，法律意見書（2026-05-15）確認可行性；若法務要求更精確，v1.x 改為完整生日核驗（YYYY-MM-DD）。實作依賴法律意見書（2026-05-15確認）；在法律意見書出具前，實作設計應可快速切換至完整生日核驗（YYYY-MM-DD）模式，避免技術鎖定。
4. OTP 安全限制：同一 OTP 最多 3 次錯誤後自動失效（需重送）；重送間隔 ≥ 60 秒；同一手機號每日最多 5 次 OTP 請求（次日 00:00 UTC+8 重置）；超過每日 5 次 OTP 限制時，Server 返回 HTTP 429，body: {"error":"daily_otp_limit_exceeded","reset_at":"YYYY-MM-DDT00:00:00+08:00"}；Client 顯示：「今日OTP請求已達上限，請於次日UTC+8 00:00後重試」；同一 IP 10 分鐘內超過 3 支手機號請求觸發 Rate Limit（HTTP 429）。

Out of Scope：

• Apple Sign-In（v1.0 不實作，列入 v1.x Backlog）。
• 台灣自然人憑證 KYC（僅在法律意見書 2026-05-15 要求時升級，截止日 2026-08-13）。
• 多裝置同時登入限制（v1.0 不實作）。

Dependencies： REQ-016（Cookie同意須在帳號流程前顯示）

Priority： Must Have

REQ-015：防沉迷系統（2h reminder，daily display，underage 2h hard stop）

Feature Name： 防沉迷與遊玩時間管理

User Story：

As a Casual Player, I want the app to remind me when I've been playing for 2 hours and show my daily play time so that I can maintain healthy gaming habits, while underage accounts are protected by a mandatory daily limit.

Acceptance Criteria：

1. 連續遊玩計時器：每局結束後累計遊玩時間；連續遊玩滿 2 小時（120 分鐘）後，強制顯示休息提醒彈窗（文字：「您已連續遊玩 X 分鐘，請適度休息，注意健康。」）；玩家需主動點選確認後方可繼續；確認後計時器重置為 0 並重新累積；成人帳號可重複觸發（無總時數上限）。2小時提醒每達120分鐘連續遊玩觸發一次；離線不足30分鐘重連後計時器繼續累積（不重置）；例：遊玩119分鐘→離線10分鐘→重連遊玩1分鐘 = 累計120分鐘觸發提醒。測試向量：玩家遊玩120分鐘觸發第一次提醒→確認繼續→再遊玩120分鐘，驗證第二次提醒強制彈窗出現（Pass條件：≥5次重複觸發均通過）。
2. 計時器重置條件：玩家主動登出後重置；或離線（網路斷線 / App 關閉）超過 30 分鐘後重置；App 切換至背景超過 30 分鐘視為中斷並重置計時器。成人帳號連續遊玩計時器不在UTC+8午夜自動重置（成人無每日時數上限）；計時器僅在主動登出或離線>30分鐘時重置；今日累計遊玩時間（AC-4顯示值）每日00:00 UTC+8重置。【F9 測試規格】 使用Playwright+網路節流模擬；情境：玩家遊玩119分鐘後模擬離線31分鐘再重連，驗證連續遊玩計時器歸零（誤差≤30秒）；執行≥10次；Pass條件：10次全部計時器歸零。
3. 未成年帳號強制限制：年齡 < 18 歲帳號每日遊玩時數上限 2 小時，達上限後強制登出（UTC+8 次日 00:00 重置）；強制登出前 10 分鐘顯示警告。【F20 牌局進行中觸發規則】 未成年帳號在牌局進行中觸發2小時上限時，Server等待當局結算完成後觸發強制登出（不強制中斷進行中牌局）；測試向量：模擬未成年帳號遊玩119分鐘後開始新局，驗證本局結算後觸發強制登出。
4. 每日遊玩時間顯示：帳號主頁顯示今日累計遊玩時間；準確度 AC：連續遊玩 30 分鐘後，帳號頁顯示值與 Server Session Log 誤差 ≤ 1 分鐘（60 秒）。

[設計說明 — EDD細化] 未成年帳號偵測補充機制： 若Server偵測到帳號行為異常（如同設備指紋多帳號、遊玩時間模式異常），觸發suspicious_underage_flag人工審查標記；具體觸發邏輯將於EDD（STEP-07）細化並補充為正式AC；v1.0 PRD階段此機制無測試標準，不作為v1.0驗收條件。法律意見書（2026-05-15）確認後決定是否強制KYC升級。此機制為補充防護，v1.0主要依賴出生年份自填+OTP方案（詳見§9.3）。

Out of Scope：

• 週 / 月累計遊玩時間顯示（v1.0 僅顯示今日）。
• 家長控制面板（v1.0 不實作）。

Dependencies： REQ-014（帳號年齡欄位）、REQ-011（Session 時間追蹤）

Priority： Must Have

REQ-016：Cookie 同意系統（Cookie banner，consent log，GDPR for EU IPs）

Feature Name： Web 平台 Cookie 同意橫幅與同意記錄

User Story：

As a Casual Player accessing via web browser, I want to be informed about cookie usage and choose which types I consent to so that my privacy preferences are respected and the platform meets legal requirements.

Acceptance Criteria：

1. Web 平台首次載入時顯示 Cookie 同意橫幅；同意橫幅包含至少三類 Cookie 的獨立選項：必要性 Cookie（不可拒絕）、分析性 Cookie（可選拒絕）、行銷性 Cookie（可選拒絕）。
2. 歐盟用戶觸發條件：以 CloudFlare CF-IPCountry header 或 MaxMind GeoIP DB 偵測用戶 IP 所屬國家；若為歐盟成員國，強制顯示 GDPR opt-in 同意流程（明確 opt-in，非 pre-checked，不預設勾選任何可選類別）。
3. 同意記錄持久化：每筆同意紀錄包含時間戳（UTC）、IP hash、同意版本號、各類 Cookie 選擇結果；保留 3 年；用戶可隨時在帳號設定頁撤回同意（撤回確認後 ≤ 1 秒內，Server 停止記錄分析性與行銷性 Cookie 資料；Client 在下一次頁面載入前不再觸發對應追蹤腳本。測試方法：使用 Chrome DevTools Network 面板或 Charles Proxy，驗證撤回後 1 秒內無新的追蹤請求發出）。
4. 非歐盟用戶（如台灣）：依《個資法》告知義務顯示橫幅，但不強制 opt-in；預設接受必要性 Cookie，分析性與行銷性 Cookie 提示用戶選擇。
5. Native App（iOS / Android）同意管理：玩家撤回分析性 Cookie 同意後，App 於下次啟動時停用 Firebase Analytics 等個人化追蹤 SDK；iOS 遵循 ATT（App Tracking Transparency）框架；Android 遵循 Consent API；測試方式：撤回後重啟 App，網路抓包驗證無個人化追蹤請求（工具：Charles Proxy 或 mitmproxy）。

Out of Scope：

• Cookie 橫幅 A/B 測試樣式優化（v1.0 僅標準樣式）。

Dependencies： 無（Cookie同意為前置流程，不依賴帳號系統；已登入用戶的同意紀錄綁定由REQ-014提供，為REQ-016的選用整合而非硬性依賴）

Priority： Must Have

REQ-017：反作弊與速率限制（Anti-Cheat & Rate Limiting）

Feature Name： 反作弊機制與伺服器端速率限制

Priority： Must Have

User Story：

As a Competitive Player, I want the platform to detect and block cheating behaviors so that games remain fair and my competitive achievements are meaningful.

Acceptance Criteria：

1. Server消息速率限制：每玩家每秒 ≤ 10條WebSocket消息；超限觸發速率限制，返回rate_limit error消息。
2. 異常行為偵測（含量化門檻）：

• 重複請求：同一玩家同一動作在 1 秒內發送 ≥ 3 次觸發標記。
• 超速下注：單局內同一玩家 WebSocket 下注消息發送頻率 > 10 次/秒觸發標記。
• 非法金額：下注金額超過帳號餘額或房間限額時，立即拒絕並記錄日誌。
• 觸發後行為：第一次觸發 → 警告 + 記錄日誌；任意10局滾動窗口累計5次 = 同一玩家帳號在任意滾動10局時間窗口（Server端以局為計量單位）內累計出現≥5次異常標記（重複請求/超速下注/非法金額任一觸發均計一次）；跨房間、跨session累計；觸發條件達成後帳號臨時封號24小時（UTC+8時間）；封號通知帳號並記入稽核日誌；測試：模擬10局內5次異常觸發，驗證封號行為。

1. 帳號封鎖機制：確認異常行為後，系統可封鎖帳號（臨時或永久）；封鎖操作記錄於稽核日誌；受封鎖帳號嘗試操作時收到明確錯誤提示。

Out of Scope： AI行為模式深度分析（v1.x）；機器學習作弊偵測（v1.x）。

Dependencies： REQ-011（Room State）、REQ-014（帳號系統）

REQ-018：（保留編號）後台Admin工具

Feature Name： 後台Admin管理工具（保留編號）

Priority： Won't Have（v1.0）

Note： 後台Admin工具v1.0依賴SRE腳本和DB直接操作，v1.x納入範圍。本REQ-ID保留，待v1.x規劃時填入完整需求。

REQ-019：個資刪除與留存流程（Data Deletion & Retention）

Feature Name： 個資刪除請求處理與留存流程

Priority： Must Have

User Story：

As a Casual Player, I want to be able to request deletion of my personal data and have it processed in accordance with privacy regulations.

Acceptance Criteria：

1. DELETE /player/me API觸發7個工作日刪除流程；玩家收到確認Email，告知刪除時程與範圍。
2. 財務交易記錄（Transaction表）依法保留7年（匿名化處理，移除個人識別欄位，而非完全刪除）；其餘個人資料於7工作日內完成刪除。
3. 玩家提交刪除請求後立即收到確認Email，內容包含：請求受理時間、預計完成時間、保留資料說明。

Out of Scope： 即時刪除（法規允許7工作日處理期）；刪除後帳號恢復（不可逆）。

Dependencies： REQ-014（帳號系統）、REQ-016（Cookie同意系統）

REQ-020a：每日免費贈送 + 救濟機制（Daily Free Chips + Rescue Mechanic）

Feature Name： 每日贈送籌碼與救濟機制

Priority： Must Have（Note: BRD §5.3 MoSCoW原標注為Should Have；基於留存業務需求，PM決定升級為Must Have（2026-04-22，決策見BRD Decision Log D14（2026-04-22）及PRD Change Log v0.3-draft）；O2 RTM對應已更新）

User Story：

As a Returning Player, I want to receive free chips daily and get an emergency top-up when I'm about to run out so that I can always return to the game even after losing all my chips.

Acceptance Criteria：

1. 每日免費贈送（玩家主動領取模式）：每日免費籌碼採玩家主動領取模式（非自動發送）；大廳顯示「領取今日籌碼」按鈕；Server 驗證當日是否已領取（daily_chip_claimed_at 日期 ≠ 今日 UTC+8）；每日重置時間：00:00 UTC+8；超過 7 日未登入者不補發累積天數；每日領取率目標 ≥ 60% DAU（Launch+6M 量測）；領取率量測分母 = 當日 DAU，分子 = 當日成功領取唯一帳號數；每次領取贈送 5,000 籌碼。冪等性保護： 每日贈送請求使用複合Key（player_id + claim_date_utc8）作為唯一性約束；重複請求返回HTTP 200並附帶{already_claimed: true, chips_awarded: 0}（不重複發放）；DB使用INSERT ... ON CONFLICT DO NOTHING配合唯一約束實現冪等。
2. 救濟機制：當局結算後玩家餘額 < 500 籌碼時，Server 在下一局開始前自動補發 1,000 救濟籌碼（每帳號每日上限 1 次）；補發時廣播 Client 顯示提示「您的籌碼已不足，系統已補發 1,000 救濟籌碼」；救濟不觸發條件：餘額 500–999（此範圍顯示大廳提示，引導玩家透過每日任務恢復進房資格）。【F1 救濟觸發時機說明】 救濟觸發時機：每局結算完成後Server檢查chip_balance；大廳狀態下不觸發自動救濟（玩家需進入房間對戰後結算觸發）。

Out of Scope：

• IAP 籌碼購買（見 REQ-020b）。
• 廣告模式（見 REQ-020b）。
• 籌碼兌換現金或實體物品（明確禁止）。
• 好友間籌碼轉移（明確禁止，防洗籌碼）。

Dependencies： REQ-014（帳號系統，綁定籌碼錢包）、REQ-004（結算後觸發救濟判斷）、REQ-011（Room State）

REQ-020b：虛擬籌碼商店 IAP / 廣告模式（Virtual Chip Store — IAP or Ad Mode）

注意：本 REQ-020b 為獨立需求，AC 從 AC-1 起獨立編號（原AC-3/AC-4，已重新編號為獨立REQ-020b AC-1/AC-2）；REQ-020a 與 REQ-020b 共同構成完整的籌碼獲取需求，BDD 場景引用格式：REQ-020 BDD S-020a/S-020b。

Feature Name： 虛擬籌碼商店（IAP conditional + 廣告降級）

Priority： Should Have（條件依 Q1 法律意見書 2026-05-15）

User Story：

As a Returning Player, I want to optionally purchase more chips or watch ads to earn chips if I want to play at higher stakes.

Acceptance Criteria：

1. 虛擬籌碼 IAP（條件啟用）（原AC-3，已重新編號為獨立REQ-020b AC-1）： 依法律意見書（2026-05-15 完成）決定；若 IAP 合法：啟用籌碼購買包（金額組合由 Game Designer 定義）；IAP 交易成功率 ≥ 99%；支付失敗退款流程 ≤ 24 小時；若存在法律疑慮：IAP 停用，改用廣告模式。
2. 廣告降級模式（若 IAP 不可啟用）（原AC-4，已重新編號為獨立REQ-020b AC-2）： 使用 Google AdMob SDK；每次廣告獎勵 500 籌碼；每日廣告觀看上限 5 次；廣告播放完成率（已觀看廣告中完整觀看比例）≥ 80%（由 AdMob SDK 回傳確認）；DAU 廣告觀看人數 ≥ 20% DAU。

Out of Scope：

• 籌碼兌換現金或實體物品（明確禁止）。
• VIP 訂閱系統（v1.0 Out of Scope，列入 v1.x Backlog）。
• 好友間籌碼轉移（明確禁止，防洗籌碼）。

Dependencies： REQ-020a（每日贈送與救濟機制）、法律意見書 Q1（2026-05-15）

REQ-021：每日任務系統（Daily Task System）

Feature Name： 每日任務系統

Priority： Should Have（BRD §5.3）

User Story：

身為玩家，我希望完成每日任務獲得籌碼獎勵，以維持遊玩動力並在籌碼不足時恢復進房資格。

Acceptance Criteria：

• AC-1: 每日至少提供 3 個可完成任務（範例：完成 3 場對戰、連續登入 7 日、完成教學）；任務列表每日 00:00 UTC+8 重置；每項任務獎勵下限為500籌碼（確保500-999邊緣情況玩家可透過單一任務恢復進入青銅廳所需1,000籌碼資格）。注意：本AC完整版本待O6截止日2026-05-15 Game Designer完成任務清單配置後補入；在此之前，REQ-021 AC-1驗收暫緩，不作為Alpha（2026-06-21）阻斷條件；O6完成後需發布PRD 下一版本更新（待O6確認後）。【F3 Alpha/GA截止門控聲明】 本AC完整版待O6截止日2026-05-15補入；Alpha（2026-06-21）阻斷條件排除此AC；O6逾期未完成時，REQ-021自動降回Backlog（Should Have暫緩），並在PRD 下一版本更新（待O6確認後）中記錄。
• AC-2: 每項任務完成後發放 500–2,000 籌碼獎勵；獎勵即時到帳（Server push），Client 顯示動畫提示。
• AC-3: 任務完成率量測：Launch+3M 時 DAU 每日任務完成率 ≥ 40%。量測規格：使用Firebase Analytics或內部Analytics平台；事件名稱：task_completed（屬性：task_id, player_id, date_utc8）；Pass定義：Launch+3M期間連續7日移動平均DAU任務完成率≥40%；分母=當日DAU（日首次登入唯一帳號數）。
• AC-4: 500–999 籌碼邊緣情況：完成 1 個任務（最低獎勵 500 籌碼）後，玩家總籌碼 ≥ 1,000，可重新進入青銅廳。

Out of Scope v1.0： 任務難度等級制、任務成就徽章、任務社群分享。

依賴條件： O6（Game Designer任務配置，截止2026-05-15）完成後方可驗收REQ-021 AC-1；AC-1驗收暫緩不作為Alpha（2026-06-21）阻斷條件。

Dependencies： REQ-014（帳號系統）、REQ-011（房間狀態）

REQ-ID： REQ-021

4. Non-Functional Requirements（來源 BRD §8.3）

§4a 技術版本鎖定

引用 BRD §13.0；版本升級需 PRD 修訂並記入 Change Log。

5. Game Rules Specification（來源 BRD §5.5）

本章為實作就緒（Implementation-Ready）的遊戲規則規格。所有遊戲邏輯以 Server 端 TypeScript 實作，Client 端不得包含任何規則計算邏輯。

5.0 莊家機制（Banker Mechanism）

莊家機制（來自 BRD D9, D11, D12）

1. 首局莊家選擇：持有籌碼最多的玩家擔任莊家；若同籌碼則按進入房間的順序（先進先莊）。
2. 輪莊規則：每局結束後，莊家位置順時鐘移至下一位玩家（Fold玩家正常參與輪莊序列，不跳過）。
3. 中途加入：只要房間未滿（< 6 人），任何 phase 都允許加入（Server 不得於遊戲開始時鎖定房間）。中途加入者於當前局視為「排隊等待下一局」：不發牌、不下注、不跟注、不棄牌、不參與輪莊序列。待當前局結算並 resetForNextRound 後，排隊玩家才正式納入下一局並依規則參與輪莊（先進先莊 / 順時鐘輪替）。若房間已滿（6 人），仍依既有 room_full 處理（與 phase 無關）。
4. 莊家籌碼不足（< 本廳最低下注額）：跳過本局輪莊，移至下一位玩家（見 D9）。

5.1 牌局流程（Server 執行順序）

Step 1: Server 洗牌（Fisher-Yates）
        → 發牌（每人 3 張暗牌，按座位順序）

Step 2: 莊家查看手牌 → 下注底注（≥ 本廳最低下注，≤ 本廳最高下注；玩家實際下注不得超過其當前籌碼餘額）
        → 莊家計時器：30 秒；超時自動以本廳最低下注代為下注（D12）
        → 若莊家籌碼 < 本廳最低下注，自動輪莊至下一位（D9）
        → 【F1 莊家預扣（Escrow）時機】莊家下注確認後，Server立即預扣（escrow）banker_bet_amount：banker chip_balance -= banker_bet_amount（預扣至托管態）；Step 6c支付贏家時從預扣額及剩餘餘額中順序支付；破產判斷以Step 2後的chip_balance為準
        → 莊家下注確認後，Server立即更新Room State中的banker_bet_amount欄位並廣播至所有Client；閒家計時器（30秒，per D11）隨即啟動（見REQ-011 AC-1 banker_bet_amount欄位定義）

Step 3: 閒家依順時鐘順序逐一決策
        → 每人 30 秒計時；超時自動 Fold（D11）
        → Call：下注與莊家等額
          【F15 Call預扣機制】Call確認後，Server立即預扣閒家籌碼：player chip_balance -= banker_bet_amount（與莊家Step 2 escrow機制對稱）；預扣後玩家進入等待翻牌階段；結算時：勝→收取(1+N)×下注額（本金+N×倍率，由莊家支付）；敗→預扣額歸底池
        → Fold：選擇棄牌，不下注，手牌保持暗牌，無籌碼損失（棄牌下注額 = 0，不入底池）

Step 4: 所有未 Fold 玩家翻牌
        → Fold 玩家手牌保持暗牌（v1.0 不公開）
        → 結算動畫僅顯示未 Fold 玩家的手牌

Step 5: Server 比牌（依 §5.2 比牌規則）
        → 計算每位未 Fold 閒家與莊家的比牌結果

Step 6: 三步驟結算（原子性執行，見 §5.3）
        → **【F2 全閒家Fold特殊情境】** 底池=0，抽水=0，莊家底注退回（見§8.0）

5.2 比牌規則

5.3 三步驟結算規格

下注上限規則： 玩家實際下注金額不得超過其當前籌碼餘額；閒家和莊家均受此限制。Server端在接受下注請求時同步驗證，違規請求返回error消息。

Step 6a — 確認結果與底池構成：

• Server 確認每位閒家的比牌結果（贏 / 輸 / Fold）。
• 底池 = 莊家勝的閒家下注額加總（Fold閒家下注額=0，不入底池，不計入底池構成）。
• 莊家勝的閒家下注額 → 歸入底池（輸家底池）；棄牌（Fold）閒家下注額 = 0，不下注，不入底池。
• 莊家敗的閒家下注額 → 不入底池（由莊家從自身籌碼直接支付本金 + 賠率）。

Step 6b — 抽水（Rake）：

• 抽水底數 = 輸家閒家下注額加總（底池）。
• 抽水額 = floor(底池 × 0.05)，最少 1 籌碼。
• 空底池守衛（F3）： 若底池（輸家閒家下注額加總）= 0（即全部閒家均勝、全員棄牌、或勝者與棄牌者合計無任何輸家），則抽水 = 0，最少1籌碼條款不適用；最少1籌碼僅在底池 > 0時生效。
• 抽水進入遊戲維運基金（不返還給任何玩家）。

Step 6c — 籌碼分配：

莊家破產規則（D13）— 先到先得（Sequential）：

• 若莊家籌碼不足支付所有贏家：依閒家順時鐘座位順序逐一結算（先到先得）；每位贏家依序收取本金（1×下注額）+ N×下注額賠付；莊家籌碼歸零後，後續排隊贏家所得為零（不按比例分配，不取回本金，得零）；抽水 = floor(莊家破產前已實際完成結算的輸家閒家下注額加總 × 0.05)，最少1籌碼（底池 > 0 時）；莊家破產後未完成結算的輸家下注額不計入抽水底數；不按比例扣除。

5.4 賠率表（台灣標準版）

所有賠率計算以整數籌碼為單位，不使用浮點運算。

>

【F14 0點賠率說明】 0點（非三公）與1–8點同為最低點數類別，均適用1:1賠率（N=1）；0點非三公為比牌順序最末（最小），但賠率與1–8點相同。

5.5 籌碼經濟約束

房間級距與進場條件（權威版本）：

6. Data Models（High-Level）

完整 Schema 定義詳見 STEP-09 Schema 文件。本章僅描述關鍵實體與核心欄位。

Player（玩家）

Room（房間）

Game（牌局）

Hand（手牌）

Transaction（籌碼交易）

Session（會話）

7. API Endpoints（High-Level）

完整 API 規格（請求/回應 schema、錯誤碼）詳見 STEP-09 API 設計文件。

REST Endpoints

Colyseus Room Messages（Client → Server）

Colyseus Room Messages（Server → Client，Room State 廣播）

注：settlement廣播schema中net_chips: -bet表示負的下注金額，由Server計算後填入實際數值廣播（非字面字串）。

注：winners[].payout = (1+N)×bet（本局總取回籌碼，含本金+賠率）；net_chips = N×bet（本局淨利潤）——此區分可防止 Client 端渲染錯誤：payout 為玩家實際收到的總籌碼數（含本金返還），net_chips 為純利潤（不含本金）。

【All-Fold 場景補充說明】全員棄牌時（底池=0，莊家 net=0）：莊家不出現在 winners/losers/folders/ties/insolvent_winners 任何陣列中；其籌碼狀態僅透過 banker_remaining_chips 廣播（含 escrow 退回後的值）；Client 依 folders 陣列顯示所有棄牌閒家，依 banker_remaining_chips 更新莊家籌碼顯示。

8. Error Handling & Edge Cases

8.0 所有閒家Fold特殊場景

8.1 斷線 Mid-Game（來源 BRD §5.3）

8.2 Banker Insolvency（D13）

8.3 500-999 Chip Edge Case

8.4 Timer Expiry

8.5 Room Lifecycle Edge Cases

8.6 Graceful Degradation策略

9. Compliance Requirements（來源 BRD §9）

9.1 台灣賭博法規合規

9.1a 詐欺防制通報機制（《詐欺犯罪危害防制條例》）（屬REQ-017合規延伸，BDD S-017-fraud）

【F18 詐欺防制驗收標準AC】 (1) SOP文件由Legal書面確認通過（截止GA前2026-08-21）；(2) threshold.yaml配置實際可觸發Ops審核工作流（IT測試：模擬觸發事件→驗證Ops工作流啟動log）；(3) 帳號凍結API（/admin/account/freeze）可由Ops調用，IT-fraud-001測試通過。

9.2 防沉迷實作

9.3 年齡驗證流程

流程：
① 玩家填入出生年份（YYYY）
② Server 計算 currentYear - birthYear ≥ 18 → 通過
③ 通過後發送手機 OTP（6 碼，5 分鐘有效，SMS via Twilio / AWS SNS）
④ 玩家輸入 OTP → Server 驗證
⑤ 驗證成功：帳號 age_verified = true，解鎖正式對戰
⑥ 驗證失敗：最多 3 次錯誤後 OTP 失效，需重送（間隔 ≥ 60 秒）

升級觸發條件（F11）：
若法律意見書（2026-05-15）認定 OTP 方案不足，
須於 2026-08-13 前完成升級至第三方 KYC（TW 自然人憑證或等效方案）

未成年保護限制說明（Risk Log）： v1.0 年齡驗證僅依賴出生年份自填 + 手機 OTP，OTP 只驗證手機持有人，無法確認實際年齡。此方案存在被規避的風險（如：由成人代為填寫出生年份及接收OTP）。補充機制：REQ-015 AC-5 suspicious_underage_flag 於行為異常時觸發人工審查；最終是否強制 KYC 升級待法律意見書（2026-05-15）確認。此限制已知且接受，作為 v1.0 的技術債於法律意見書後評估。

9.4 Cookie 同意流程

Web 首次載入：
① 偵測 IP 國家（CloudFlare CF-IPCountry header 或 MaxMind GeoIP）
② 若歐盟 IP → GDPR opt-in 流程（非 pre-checked）
   若非歐盟（如台灣）→ 個資法告知橫幅（必要 Cookie 預設接受）
③ 玩家逐類選擇同意（必要 / 分析 / 行銷）
④ 記錄同意：時間戳 + IP hash + 版本號 + 各類選擇（保留 3 年）
⑤ 用戶可在帳號設定頁隨時撤回可選類 Cookie 同意

9.5 KYC 升級觸發條件

9.6 合規時程里程碑

9.7 GDPR 義務需求

適用條件：若判定本產品涉及歐盟居民個人資料處理，以下義務強制執行。

風險說明：本 §9.7 限制條件（是否需 DPO、是否高風險處理）依 DPIA 結果確定（截止 2026-06-01）；若 DPIA 要求重大產品修改，GA 時程可能延後，需 Exec Sponsor 決策。

10. Open Items

以下事項已知但未決，延後至指定截止日或後續 EDD / 設計階段處理：

REQ 編號說明： REQ-005（保留，好友系統 v1.x）；REQ-006（排行榜 Could Have）；REQ-007（聊天室 Could Have）；REQ-008（保留，多語系 v1.0 Won't Have）；REQ-009（保留，第二品類 v2.0）；REQ-017（反作弊 Must Have）；REQ-018（保留，Admin工具 v1.x）；REQ-019（個資刪除 Must Have）；各功能詳見§3 Feature Specifications及本章 Open Items。

PRD 文件結束。下一步：STEP-07 EDD（Engineering Design Document）。

Glossary

術語定義見 BRD §16 Glossary（docs/BRD.md）。PRD 不重複定義，請以 BRD §16 為準。

文件維護聲明： 本 PRD 由 /devsop-autodev STEP-03 自動生成，依據 BRD-SAM-GONG-GAME-20260421 v0.12-draft。所有財務預測數字（付費率、ARPPU、LTV、CAC 等）均為 AI 推斷假設，非來自可信第三方市場研究，不得作為投資決策或財務承諾依據。

變更追蹤

BUG-20260422-002：獎池（current_pot）語意錯誤 — 莊家下注不應入池

• 狀態：✅ DONE
• 分類：BUG / 工程
• 日期：2026-04-22
• 描述：三公規則中，「獎池」只應包含閒家跟注的錢；莊家下注屬莊家 escrow，不屬於桌面獎池。結算時：閒家贏 → 自己的 called_bet 從獎池退回 + 莊家另從口袋付 N× 賠率；閒家輸 → called_bet 從獎池流向莊家；平手 → called_bet 從獎池退回。當前 current_pot 錯把莊家下注加入，造成 UI 誤導。
• 影響範圍：§5.3 結算 UI 獎池顯示；EDD §3.2 current_pot 欄位語意（spec 已正確，實作不符）；結算動畫流向
• 修正/實作內容：src/rooms/SamGongRoom.ts 的 handleAutoMinBet 與 handleBankerBet 不再將莊家下注加入 current_pot（改純 escrow 扣款）；EDD §3.2 current_pot 註解改為「閒家跟注加總」；client/js/game.js 移除 banker→pot 金幣動畫（改播 coin drop 音效），triggerSettleAnimation 重寫為 5 階段依結果分流：輸家→莊家、平手/贏家→退回 called_bet、莊家→贏家付 N× 賠率、破產情境破碎動畫。256 server 測試 + 32 client 測試全通過。
• commit：d2b9465 docs + e69ecc3 server+client
• 完成日期：2026-04-22

BUG-20260422-001：房間開局後仍應允許加入 + 押注/跟注 checkbox 預設不勾選

• 狀態：✅ DONE
• 分類：BUG / 工程
• 日期：2026-04-22
• 描述：房間就算有位置, 一但開始遊戲, 就不能加入了, 應該開放加入；全部人不管怎麼加入房間, 預設不能打開押注或跟注, CHECKBOX DEFAULT 是不打勾
• 影響範圍：§5.0 莊家機制（第 3 點 — 中途加入）、§5.1 牌局流程（開局時房間不得鎖定）、押注/跟注介面自動押注 checkbox 預設值
• 修正/實作內容：PRD §5.0.3 改寫為「房間未滿即允許加入；中途加入者排隊等待下一局，本局不發牌 / 不下注 / 不跟注 / 不棄牌 / 不參與輪莊，resetForNextRound 後正式入局」；PDD §4 新增 CMP-012 Betting Panel 元件規格（auto-bet Toggle isChecked=false 預設 + phase 進入時強制重置）；EDD §3.1 onJoin 新增 mid-game join 判定邏輯並移除 this.lock() 呼叫；EDD §3.2 PlayerState 新增 is_waiting_next_round 欄位；EDD §3.6 resetForNextRound 清除此旗標。
• commit：7031a2b docs + 0c61349 server + 6cb702f client + 43ba640 tests
• 完成日期：2026-04-22