🎮 玩家端 H5 線稿圖 (Frontend Wireframes)

📱 互動功能

• 🔵 [☰] 開啟左側分類抽屜
• 🔵 [登入] / [註冊] 跳轉認證頁
• 🔵 主視覺輪播自動播 5s,點擊跳活動詳情或註冊
• 🔵 跑馬燈訊息可關閉,可點擊跳公告詳情
• 🔵 分類 Tab 切換刷新下方遊戲區塊
• 🔵 每張遊戲卡點擊 → 訪客身份直接進試玩(若白名單內)/ 已登入直接進真錢
• 🔵 客服懸浮鈕(右下浮動)展開即時客服
• 🔵 底部 4 鍵 Tab 列(已登入會出現)

🌐 API 端點

• GET /api/cms/banner/list?merchant=xxx&plat=0
• GET /api/cms/marquee/list
• GET /api/game/category/list
• GET /api/game/list?category=hot&page=1
• GET /api/system/branding 取 LOGO/主題色
• POST /api/guest/session/init 訪客 token 初始化

⚠️ 特殊邏輯

• 未登入時自動建立 guest_token 寫入 cookie + 設備指紋,以便試玩額度識別
• 已登入會員看到底部導航,訪客不見
• 分類順序、Banner、跑馬燈全部後台可調(白標核心)

📱 互動功能

• 🔵 顯示 FUN Coin 餘額(訪客專用試玩額度)
• 🔵 白名單內遊戲可點擊試玩,黑名單顯示 🔒 鎖頭
• 🔵 點 🔒 遊戲跳「升級會員解鎖」彈窗
• 🔵 [立即註冊解鎖] CTA 主按鈕
• 🔵 倒計時顯示額度重置時間

🌐 API 端點

• GET /api/guest/wallet/balance
• GET /api/guest/games/allowed 取得訪客可玩白名單
• GET /api/guest/demo-settings 取得試玩設定(額度/週期)

⚠️ 特殊邏輯

• 白名單由後台 demo_settings_by_level.allowed_game_ids 控制(level=0 訪客)
• 額度耗盡時所有遊戲變灰,顯示「明日重置 / 立即註冊」
• 重置週期:不重置 / 每日 / 每週 / 單次,由後台調控

📱 互動功能

• 🔵 額度歸零自動彈窗,無法繼續遊戲
• 🔵 [立即註冊] 跳轉 S04 註冊頁,並帶試玩 token 以繼承
• 🔵 [明日再來] 關閉彈窗回大廳

🌐 API 端點

• POST /api/guest/game/launch 啟動試玩
• POST /api/guest/bet/credit-spent 試玩扣額(由遊戲回調)

⚠️ 特殊邏輯

• 遊戲商透過 callback 回報試玩消耗,平台扣 FUN Coin
• 註冊轉換時帶 guest_token → 後端關聯 guest_sessions.bound_user_id → 自動繼承邀請鏈

📱 互動功能

• 🔵 三種註冊方式 Tab 切換(手機 / Email / 用戶名)
• 🔵 [發送驗證碼] 60 秒倒計時,防爆破限制每分鐘 1 次
• 🔵 密碼強度即時驗證(8+ 字 + 大小寫 + 數字)
• 🔵 邀請碼欄位若有 URL 參數 ?ref=XXX 自動帶入
• 🔵 兩個必勾條款不勾無法提交
• 🔵 第三方登入 → OAuth 流程或 Web3 簽名

🌐 API 端點

• POST /api/auth/sms/send
• POST /api/auth/email/send
• POST /api/auth/register
• GET /api/auth/check-username 用戶名重複檢查
• POST /api/auth/oauth/{provider}
• POST /api/auth/web3/nonce → /api/auth/web3/verify

⚠️ 特殊邏輯

• 註冊時自動繼承訪客身上的 guest_token / inviter_user_id / inviter_l5_id / utm
• 註冊成功立即發 $100 禮金到 activity 錢包(需流水達標方可提)
• 使用 one_time_tokens 表存簡訊/Email OTP,5 分鐘過期
• 註冊 IP 與設備指紋寫入 users 表,風控自動跑分

📱 互動功能

• 🔵 三種登入方式 Tab
• 🔵 異常登入(新設備/異地)觸發 Email/SMS 二次驗證
• 🔵 連續 5 次失敗 → 鎖 30 分鐘
• 🔵 啟用 2FA 帳號登入後跳 2FA 輸入頁

🌐 API 端點

• POST /api/auth/login
• POST /api/auth/2fa/verify
• POST /api/auth/refresh

⚠️ 特殊邏輯

• 每次登入寫入 user_login_attempts,失敗達閾值觸發 IP 風控
• 新設備登入發 Email 通知(若 user_security_settings 開啟)
• JWT + Refresh Token 雙 Token 機制,Access 1 小時,Refresh 30 天

📱 互動功能

• 🔵 手機 / Email 二選一
• 🔵 重設後所有 session 失效
• 🔵 必須通過 KYC 驗證(若有設定取款密碼則需另一驗證)

🌐 API 端點

• POST /api/auth/password/reset/request
• POST /api/auth/password/reset/confirm

⚠️ 特殊邏輯

• one_time_tokens 存重設 token,15 分鐘過期
• 重設成功 → 全部 user_sessions logout_reason = password_change

📱 互動功能

• 🔵 選擇錢包 → 觸發瀏覽器擴充或 WalletConnect QR
• 🔵 簽署訊息(無上鏈,無 gas)→ 後端驗簽 → 發 JWT
• 🔵 首次登入自動建立會員,綁定錢包地址

🌐 API 端點

• POST /api/auth/web3/nonce 取得 nonce
• POST /api/auth/web3/verify 驗證簽名

⚠️ 特殊邏輯

• 支援 EVM(ETH/BSC/Polygon)+ Solana
• 地址寫入 user_third_party_auths,可多錢包綁定
• nonce 防重放,5 分鐘過期

📱 互動功能

• 🔵 註冊成功一次性引導頁,可跳過
• 🔵 任務即時更新進度
• 🔵 點任務跳對應頁(儲值 / KYC / 遊戲)

🌐 API 端點

• GET /api/onboarding/tasks
• POST /api/onboarding/complete?task=xxx

📱 互動功能

• 🔵 頂部會員資訊條:用戶代號、VIP 徽章、即時餘額(可下拉切換錢包)、🔄 餘額重整
• 🔵 三快捷鍵:儲值 / 提款 / 轉帳
• 🔵 鈴鐺顯示未讀通知數
• 🔵 [我的收藏] 區塊只在收藏 ≥ 1 顯示
• 🔵 底部 5 鍵 Tab(首頁 / 遊戲 / 錢包 / 活動 / 我的)

🌐 API 端點

• GET /api/user/me 個人摘要
• GET /api/wallet/balance/all 各錢包餘額
• GET /api/notification/unread/count
• GET /api/game/favorites
• GET /api/game/recent

⚠️ 特殊邏輯

• VIP 徽章顏色與圖示由 vip_levels 表設定
• 餘額顯示幣別由 user_preferences.currency_display 決定

📱 互動功能

• 🔵 頂部頭像區顯示 VIP 等級徽章
• 🔵 4 個錢包概覽(主/活動禮金/返水/佣金),點擊跳錢包頁
• 🔵 安全設定列若未啟用 2FA 顯示紅色警告
• 🔵 訊息中心未讀數紅點
• 🔵 推廣中心若會員不是代理身份則隱藏

🌐 API 端點

• GET /api/user/profile
• GET /api/user/security/status
• GET /api/user/kyc/status
• GET /api/agent/summary (若是代理)

🌐 API 端點

• GET /api/user/profile
• PUT /api/user/profile
• POST /api/user/avatar/upload

⚠️ 特殊邏輯

• 已 KYC 通過的欄位(real_name / id_number)鎖定不可改
• 所有變更寫入 operation_logs + entity_versions

📱 互動功能

• 🔵 安全評分:依據 2FA / 取款密碼 / KYC / 設備數量等綜合計算
• 🔵 提款功能要求必設定取款密碼
• 🔵 高 VIP 強制 2FA(由商戶後台設定)

🌐 API 端點

• GET /api/user/security/overview
• PUT /api/user/security/notify

🌐 API 端點

• PUT /api/user/security/login-password
• PUT /api/user/security/withdraw-password

⚠️ 特殊邏輯

• 取款密碼必須與登入密碼不同(防 phishing 一網打盡)
• 提款 / 改提款帳戶 / 改 KYC 都需取款密碼

🌐 API 端點

• POST /api/user/2fa/setup 取得 secret + QR
• POST /api/user/2fa/enable 驗證並啟用
• POST /api/user/2fa/disable
• GET /api/user/2fa/backup-codes

⚠️ 特殊邏輯

• secret 用 AES 加密存 user_security_settings.2fa_secret_encrypted
• 備援碼一次性,使用後自動失效

🌐 API 端點

• GET /api/user/kyc/status
• POST /api/user/kyc/submit
• POST /api/user/kyc/document/upload

⚠️ 特殊邏輯

• 三級 KYC:L1 基本(註冊送)/ L2 證件 / L3 高額審查(住址證明等)
• 支援 AI 自動審核(Sumsub / Onfido)+ 人工覆核
• 所有文件加密上傳 S3,僅 KYC 審核員可解密

🌐 API 端點

• GET /api/user/devices
• PUT /api/user/devices/:id/trust
• DELETE /api/user/devices/:id
• POST /api/user/sessions/logout-others

🌐 API 端點

• GET /api/user/third-party-auths
• POST /api/user/third-party-auths/bind
• DELETE /api/user/third-party-auths/:id

⚠️ 特殊邏輯

• 至少保留一種登入方式(防全部解綁鎖死)
• Web3 解綁需簽名確認

🌐 API 端點

• GET /api/notification/list?type=all&page=1
• PUT /api/notification/:id/read
• PUT /api/notification/read-all

🌐 API 端點

• GET /api/user/preferences
• PUT /api/user/preferences
• PUT /api/user/responsible-gaming

⚠️ 特殊邏輯

• 責任博弈設定一旦提高(更嚴格)立即生效;放寬有 24~72h 冷靜期才生效(法規)
• 冷靜期 / 自我排除設定後直接登出,期間無法登入

🌐 API 端點

• GET /api/i18n/languages 取支援語言清單
• GET /api/i18n/texts?lang=zh-TW 取所有翻譯文案

⚠️ 特殊邏輯

• 語言由商戶後台 i18n_languages.is_active 控制可顯示
• 切換後本地存儲 + 重新請求所有 i18n 文案

📱 互動功能

• 🔵 總資產自動換算成顯示幣別(用 exchange_rates)
• 🔵 點任一錢包跳轉該錢包詳細交易記錄
• 🔵 活動禮金流水進度條
• 🔵 返水可一鍵領取到主錢包
• 🔵 佣金錢包僅代理身份顯示

🌐 API 端點

• GET /api/wallet/balance/all
• GET /api/wallet/total-value
• POST /api/wallet/rebate/claim

🌐 API 端點

• GET /api/payment/channels?direction=deposit&user=me

⚠️ 特殊邏輯

• 通道由 payment_channels.applicable_vip_levels + applicable_countries 過濾
• 各通道金額上下限即時顯示

🌐 API 端點

• POST /api/deposit/order/create
• GET /api/payment/account-info?channel=xxx

⚠️ 特殊邏輯

• 下一步顯示銀行收款帳號 + 訂單號(玩家轉帳備註)
• 15 分鐘倒計時等待付款
• 玩家確認付款後人工/自動對帳

🌐 API 端點

• GET /api/deposit/crypto/address?chain=tron¤cy=usdt 取得專屬地址
• GET /api/deposit/crypto/recent?address=xxx 最近鏈上交易

⚠️ 特殊邏輯

• 每用戶每幣種獨立地址(crypto_deposit_addresses)
• 後端鏈上監聽服務發現該地址收幣 → 自動建立 deposit_order + 入帳
• 達到所需 confirmations 才標記成功

🌐 API 端點

• GET /api/deposit/orders?status=xxx&from=date&to=date&page=1

🌐 API 端點

• GET /api/user/bank-accounts
• POST /api/user/bank-accounts
• DELETE /api/user/bank-accounts/:id
• PUT /api/user/bank-accounts/:id/default

🌐 API 端點

• GET /api/withdraw/limits
• GET /api/withdraw/bet-requirement
• POST /api/withdraw/order/create

⚠️ 特殊邏輯

• 必須通過取款密碼 + Email/SMS 驗證碼雙因子
• 未達流水鎖定提款
• 提交後立即從餘額凍結,進入 wallet_freeze_records
• 觸發後台多層審核流程

🌐 API 端點

• GET /api/withdraw/orders/:id/status
• POST /api/withdraw/orders/:id/cancel

⚠️ 特殊邏輯

• 每階段對應 withdraw_review_logs 一筆紀錄
• 未到「出款」階段可取消(退回餘額)
• 狀態變更即時 push 通知

🌐 API 端點

• POST /api/wallet/transfer
• GET /api/wallet/transfer/quote 取匯率 + 手續費試算

⚠️ 特殊邏輯

• 跨幣別需匯率(exchange_rates),記錄當時匯率永不修改
• 主錢包 ↔ 遊戲商錢包透過遊戲商 API 轉帳

🌐 API 端點

• GET /api/wallet/bet-requirements

🌐 API 端點

• GET /api/game/list?category=slot&provider=&sort=hot&page=1

⚠️ 特殊邏輯

• HOT/NEW/維護中 等標籤從遊戲表 hot_score / created_at / status 算
• 訪客白名單外遊戲顯示鎖頭(轉 S03)

📱 互動功能

• 🔵 點 [真錢] → 進入該遊戲(主大廳場景)
• 🔵 點 [試玩] → 用 FUN Coin 進入(若白名單內)
• 🔵 [場景切換] 影響歸因分潤,進入前主動告知
• 🔵 ⭐ 收藏 / 取消收藏

🌐 API 端點

• GET /api/game/:id/detail
• GET /api/game/:id/scenes 取可用場景
• POST /api/game/:id/launch?mode=real|demo&scene=xxx

⚠️ 特殊邏輯

• 場景對應 L5 活動代理,進入時掛上 scene_tag
• 後端先轉錢到該遊戲商子錢包再返回啟動 URL

🌐 API 端點

• GET /api/bet/:id/detail
• GET /api/bet/:id/attribution 取歸因明細

⚠️ 特殊邏輯

• 分潤透明化披露(可由商戶後台設定是否顯示)
• 歸因規則來自 attribution_rules 表

📱 互動功能

• 🔵 進入特殊場景前彈出歸因披露
• 🔵 由後台 disclosure_settings 控制各 VIP/角色是否顯示
• 🔵 [我知道了] 後 24h 不再彈(可由後台調整)

📱 互動功能

• 🔵 投注金額 ≥ user_preferences.confirm_bet_above 觸發
• 🔵 高 VIP 可關閉此功能

🌐 API: GET /api/game/providers?category=xxx

🌐 API: POST /api/game/launch 回傳遊戲 URL,iframe 載入

關閉時自動回收餘額(主錢包 ↔ 遊戲商錢包)

🌐 API: GET /api/game/favorites / GET /api/game/recent

儲存於 user_preferences.favorite_games / recent_games

🌐 API: GET /api/bet/list?type=real&from=date&to=date

🌐 API: GET /api/bet/statistics?period=week

🌐 API: GET /api/activity/list?status=active

🌐 API: GET /api/activity/:id/detail · POST /api/activity/:id/claim

🌐 API: GET /api/activity/sevenSign/info · POST /api/activity/sevenSign/claim

🌐 API: GET /api/vip/status · GET /api/vip/levels

🌐 API: GET /api/rebate/summary · POST /api/rebate/claim

🌐 API: GET /api/agent/dashboard

🌐 API: GET /api/agent/downline?level=all

🌐 API: GET /api/agent/promotion-kit

🌐 API: GET /api/agent/commission/wallet · POST /api/agent/commission/transfer

🌐 API: GET /api/user/upline-disclosure

由商戶後台 disclosure_settings 控制是否公開金額/比例

🌐 WebSocket: wss://chat.example.com/ws · API: GET /api/cs/sessions

🌐 API: GET /api/faq/list · GET /api/cs/tickets · POST /api/cs/tickets

⚠️ 觸發條件

• 由 system_environment_configs.maintenance_mode 開啟
• 後台可指定維護結束時間 + 公告訊息(多語系)
• 白名單 IP(如後台運維)可正常訪問