🏗️ Wolves Play Game — 三層架構說明

💡 一句話

玩家在大廳點一張卡，背後自動完成「建帳號 → 把餘額轉進那款遊戲 → 取一次性進場券 → 開遊戲」； 按返回時再自動把餘額全部轉回來。整個過程玩家不需要知道有幾個系統。

🗺️ 三層圖

                        ┌──────────────────────────────┐
   玩家瀏覽器 ─────────▶ │  wolves_game_town            │  商戶門面（這個網站）
                        │  玩家帳號 · 主錢包 · 遊戲牆    │  對外開放
                        │  iframe · 商戶後台            │
                        └───────────┬──────────────────┘
                                    │  MIS  x-merchant-key（後端對後端）
                                    ▼
                        ┌──────────────────────────────┐
                        │  wolves_game_hub             │  聚合層
                        │  商戶 · 帳號命名空間 · 幣別    │  🔒 不對外
                        │  轉帳流水 · 對帳 · 遊戲目錄    │
                        └───────────┬──────────────────┘
                                    │  GIS  x-api-key（只有 hub 持有）
              ┌─────────────────────┼─────────────────────┐
              ▼                     ▼                     ▼
      wolves_fortune_lotto      SLOT 平台            魚機 / 百人 / 棋牌…
      （彩票，已接）             （規劃中）              （規劃中）
              ▲
              └──── iframe + 玩家的下注、開獎都直接連遊戲，不經過上面兩層

📋 誰負責什麼

🎬 一次進場的全程

玩家點一張遊戲卡
   │
   │  town → hub → game
   ├─ ①  建帳號（冪等，已經有就用既有的）
   ├─ ②  把玩家主錢包的餘額全額轉入那款遊戲所屬的平台
   ├─ ③  取一次性進場券（5 分鐘、用一次即失效）
   └─▶ 在站內 iframe 打開遊戲，玩家開始玩
          │
          │  ← 這段時間 town 與 hub 完全沒有參與
          │
玩家按「返回大廳」
   ├─ ④  查玩家在那個平台還剩多少
   ├─ ⑤  全額轉回主錢包
   └─▶ 回到大廳，餘額同步

玩家直接關掉瀏覽器怎麼辦？

錢會暫時留在遊戲那邊。後端有一個回收工作會定期把「太久沒動靜」的場次撈出來， 把餘額收回主錢包 —— 所以玩家的錢不會不見，下次登入就看得到。

🧩 為什麼要有中間這層

只有一個商戶、一款遊戲的時候，hub 看起來像多餘的一層。它存在有三個具體理由：

順帶的好處

• 吸收各平台的差異：每個自研平台的 API 長得不一樣（有的走 POST + JSON、有的走 GET + 簽章）， 差異全部關在 hub 的轉接器裡，商戶只看到一組介面。
• 商戶不用懂遊戲：接一組 API 就有全部遊戲；之後平台加新遊戲，商戶零改動。
• 新增一個商戶＝在 hub 開一組憑證，遊戲那邊完全不用動。

💱 幣別怎麼換（不是匯率）

設計目標很明確：讓幣別對遊戲的影響是零。遊戲那邊永遠只看到一種東西（遊戲幣）， 不需要幣別欄位、不需要為了不同幣別多開機器或多套資料庫。換算全部發生在 hub。

比 MMK 更小的幣別（IDR / VND）沒辦法用 1:1，所以改用「最小帶入單位」處理： 一次至少要帶 10 元進遊戲。這樣比把比例硬湊成 1 誠實得多 —— 後者會讓這些幣別憑空貴十倍。

要接一個新幣別，就是在 hub 加一列設定，不用改任何程式碼。

🧾 注單為什麼不存在 hub

分界線是「帳同構、單不同構」：

• 帳（錢的移動）跨平台長得一模一樣，只有金額與方向 → hub 存得起、也對得起帳。
• 單（注單 / 局 / 開獎明細）每款結構完全不同 —— 彩票是門與賠率、拉霸是盤面與線、魚機是砲台與魚種。hub 要存就得為每款做一套資料表， 等於把遊戲邏輯搬進中間層。

所以細單一律用單號回遊戲現拉，不在中間層留副本 —— 遊戲那邊本來就有自己的稽核機制，再存一份只會製造「兩份可能不一致的真相」。

🔐 關於錢的三條紅線

1. 帳本只增不改：每一筆加減都留一列，永不修改、永不刪除。 隨時可以驗「餘額 = 帳本總和」。
2. 重送不會重複記帳：每筆轉帳有唯一流水號，網路超時重送同一筆， 結果只會記一次。
3. 🔴 結果未知時不猜：呼叫遊戲逾時而不知道成功與否， 系統會把它標成「待查明」而不是自動回沖，交由對帳查明。 寧可卡住一筆，也不要猜錯方向。

📈 容量與部署

因為玩家的遊戲流量不經過前兩層，會被人數壓垮的永遠是遊戲平台本身。 商戶門面與聚合層都很輕，可以跟其中一台遊戲共處。