C9 Entertainment City — 產品規格書 (PM 版)

文件版本：v1.0 最後更新：2026-03-01 適用對象：Product Manager / Project Manager 語言：繁體中文

第 1 章：平台總覽
第 2 章：功能模組清單
第 3 章：前台功能規格 (c9-ec)
第 4 章：後台功能規格 (c9-ims)
第 5 章：業務流程圖
第 6 章：多站點架構
第 7 章：多語系支援
第 8 章：排程任務
第 9 章：API 端點總覽
第 10 章：資料庫概覽
第 11 章：錯誤碼體系
第 12 章：附錄

第 1 章：平台總覽

1.1 平台簡介

C9 Entertainment City 是一套完整的線上娛樂城白牌平台解決方案。平台採用前後端分離架構，包含三個獨立子專案：前台 (c9-ec)、後台管理系統 (c9-ims)、後端 API 伺服器 (c9-be)。

平台的核心設計理念為「白牌架構」(White-Label)，意味著同一套程式碼可以透過站點配置 (siteCode) 快速部署為多個不同品牌的娛樂城，每個站點擁有獨立的：

品牌視覺 (Logo、主題色、吉祥物)
遊戲配置 (遊戲商、遊戲分類)
VIP 等級與反水規則
金流通道
代理推廣體系
多語系支援

1.2 系統架構圖

                         +-----------------------+
                         |      使用者瀏覽器       |
                         +-----------+-----------+
                                     |
                    +----------------+----------------+
                    |                                  |
          +---------v----------+            +----------v---------+
          |     c9-ec (前台)     |            |    c9-ims (後台)    |
          |   Nuxt 4.2 / Vue 3  |            |  Next.js 16 / React|
          |   Port: 3010        |            |  Port: 3011        |
          +---------+-----------+            +----------+---------+
                    |                                   |
                    |     HTTP API (REST JSON)           |
                    +----------------+------------------+
                                     |
                          +----------v-----------+
                          |     c9-be (後端)       |
                          |   NestJS v11          |
                          |   Port: 8080          |
                          +----+-----+-----+-----+
                               |     |     |
                    +----------+  +--+--+  +----------+
                    |             |     |              |
              +-----v----+  +----v--+  +--v-----+ +---v---------+
              |  MySQL    |  | Redis |  |  R2    | | 外部服務     |
              |  資料庫    |  | 快取   |  | 儲存   | | (金流/遊戲)  |
              +----------+  +-------+  +--------+ +-------------+

1.3 技術棧總覽

前台 (c9-ec)

項目	技術	版本
框架	Nuxt	4.2
UI 框架	Vue	3.5
語言	TypeScript	-
UI 元件	Nuxt UI v4	(Tailwind CSS)
狀態管理	Pinia	-
多語系	@nuxtjs/i18n	(zh-TW, en-US, zh-CN, th-TH, vi-VN)
表單驗證	Zod v4	-
測試	Vitest + Playwright	-
裝置指紋	FingerprintJS	v5

後台 (c9-ims)

項目	技術	版本
框架	Next.js	16.1
UI 框架	React	19.2
語言	TypeScript	-
UI 元件	shadcn/ui	(Radix UI + Tailwind CSS v4)
狀態管理	TanStack React Query v5 + Zustand v5	-
多語系	next-intl	v4.8
認證	NextAuth	5 beta
表格	TanStack React Table	v8
表單	React Hook Form + Zod v4	-
圖表	Recharts	v3
富文本編輯器	Tiptap	v3

後端 (c9-be)

項目	技術	版本
框架	NestJS	v11
語言	TypeScript	5.7 (strict)
資料庫	MySQL	utf8mb4, TZ +08:00
ORM	TypeORM	0.3.28
快取	Redis	(@keyv/redis)
認證	JWT + Passport	/ AdminJWT
排程	@nestjs/schedule	(Cron)
API 文件	Swagger UI	-
Email	Resend API	-
SMS	Twilio	-
2FA	speakeasy	(TOTP/Google Auth)
匯率	tw-exchange	(台灣銀行即時匯率)
檔案儲存	Cloudflare R2	(S3-compatible)

1.4 專案規模統計

c9-ec (前台)

統計項目	數量
頁面 (Pages)	20
元件 (Components)	77+ (含 A1/A2 佈局變體共 121)
Composables	45
Stores	4 (appStore, gameStore, promoStore, userStore)
API 模組	12 (useAuthApi, useGameApi, useDepositApi, useWalletApi, useWithdrawalApi, useVipApi, usePromoApi, useAffiliateApi, useInboxApi, useMissionApi, useSiteConfigApi, useApi)
型別定義檔	13 (affiliate, auth, common, deposit, game, inbox, mission, promo, site-config, vip, wallet, withdrawal, index)

c9-ims (後台)

統計項目	數量
頁面 (Pages)	68
元件 (Components)	41 (layout 14 + shared 11 + ui 16)
Hooks	15 (useApi, useApiQuery, useMultiSiteTabs, useNotify, usePermissions, useDomainConfig, useInitEnums, useR2Url + 7 API hooks)
API Hooks	7 (useAdminApi, useAuthApi, useFinanceApi, useAffiliateApi, useVipApi, useGameApi, useContentApi)
Stores	3 (siteFilterStore, enumStore, uiStore)
型別定義檔	11

c9-be (後端)

統計項目	數量
API 端點	205+
資料表 (Tables)	49
模組 (Modules)	23
服務 (Services)	30+
DTO	53
Controller	25
Entity	48
Cron Jobs	5
i18n 檔案	85 (5 語系 x 17 檔案)
Seeds 腳本	19+

1.5 支援語系

語系代碼	語言名稱	幣別對應
zh-TW	繁體中文	TWD (新台幣)
en-US	English	USD (美元)
zh-CN	簡體中文	CNY (人民幣)
th-TH	ภาษาไทย (泰語)	THB (泰銖)
vi-VN	Tiếng Việt (越南語)	VND (越南盾)

1.6 服務端口

專案	開發端口	說明
c9-ec	3010	前台娛樂平台
c9-ims	3011	後台管理系統
c9-be	8080	後端 API (prefix: /api)

1.7 統一系統規範

幣別規範

系統內部所有金額一律使用 USD 儲存
資料庫欄位型別：decimal(18,6)，精確到小數點後 6 位
入金時由後端透過台灣銀行即時匯率轉換
USD 截斷規則：Math.floor(value * 1e6) / 1e6（無條件捨去）

資料精度

用途	資料庫型別	精度說明
金額	decimal(18,6)	小數 6 位
匯率	decimal(18,10)	小數 10 位
百分比	decimal(5,2)	小數 2 位
倍率	decimal(10,2)	小數 2 位

統一回應格式

成功回應：
  HTTP 200
  { code: 200, message: "ok", result: <資料>, timestamp: <時間戳>, path: <API路徑> }

業務錯誤：
  HTTP 200
  { code: <非200的錯誤碼>, message: <當前語系錯誤訊息>, timestamp: <時間戳>, path: <API路徑> }

未授權：
  HTTP 401
  { code: 401, message: "Unauthorized" }

認證機制

角色	認證方式	Token 過期	說明
前台用戶	JWT Bearer Token	7 天	支援帳密/Google/Telegram 登入
後台管理員	AdminJWT	-	獨立策略，payload 含 `role: 'admin'`
後台 IMS	NextAuth 5 beta	-	JWT 策略 + Credentials Provider

第 2 章：功能模組清單

2.1 模組總覽

以下為 C9 平台所有功能模組的完整清單，按分類整理。

2.1.1 認證系統 (Auth) — 17 個端點

功能	前台頁面	後端 API	狀態	多站點
帳號註冊	Modal (Register)	POST /auth/register	已完成	Y (siteCode)
帳號登入	Modal (Login)	POST /auth/login	已完成	Y (siteCode)
Google OAuth 登入	/redirect/[action]	POST /auth/google-login	已完成	Y (siteCode)
Telegram 登入	/redirect/[action]	POST /auth/telegram-login	已完成	Y (siteCode)
二步驟驗證 (2FA)	Modal (BindGoogleAuth)	POST /auth/google-auth/*	已完成	Y
發送 Email 驗證碼	/user/setting	POST /auth/send-email-verify	已完成	Y
驗證 Email	/user/setting	POST /auth/verify-email	已完成	Y
發送手機驗證碼	/user/setting	POST /auth/send-mobile-verify	已完成	Y
驗證手機號碼	/user/setting	POST /auth/verify-mobile	已完成	Y
設定密碼	Modal (SetPassword)	PATCH /auth/set-password	已完成	Y
修改密碼	Modal (EditPassword)	PATCH /auth/update-password	已完成	Y
上傳頭像	/user/setting	POST /auth/avatar	已完成	Y
取得用戶資料	多處使用	GET /auth/user-detail	已完成	Y
更新用戶資料	/user/setting	PATCH /auth/update-profile	已完成	Y
登出	Header	POST /auth/logout	已完成	Y
檢查帳號可用性	Modal (Register)	GET /auth/check-account	已完成	Y
取得 Google OAuth URL	Modal (Login)	GET /auth/google-auth-url	已完成	Y

2.1.2 遊戲系統 (Game) — 17 個端點

功能	前台頁面	後端 API	狀態	多站點
遊戲供應商列表	/game	GET /game/providers	已完成	Y (siteCode)
遊戲分類列表	/game	GET /game/type-configs	已完成	Y (siteCode)
啟動遊戲	/game/play	POST /game/launch	已完成	Y
試玩遊戲	/game/play	POST /game/demo	已完成	Y
近期遊玩	/game	GET /game/recent	已完成	Y
遊戲排行榜	/game	GET /ranking/list	已完成	Y
BetSolutions S2S 回調	-	POST /game/betsolutions/callback	已完成	Y
RSG S2S 回調	-	POST /game/rsg/callback	已完成	Y
[Admin] 遊戲商列表	/game/providers	GET /game/admin/providers	已完成	Y
[Admin] 新增遊戲商	/game/providers	POST /game/admin/providers	已完成	Y
[Admin] 更新遊戲商	/game/providers	PATCH /game/admin/providers/:id	已完成	Y
[Admin] 刪除遊戲商	/game/providers	DELETE /game/admin/providers/:id	已完成	Y
[Admin] 分類列表	/game/type-configs	GET /game/admin/type-configs	已完成	Y
[Admin] 新增分類	/game/type-configs	POST /game/admin/type-configs	已完成	Y
[Admin] 更新分類	/game/type-configs	PATCH /game/admin/type-configs/:id	已完成	Y
[Admin] 刪除分類	/game/type-configs	DELETE /game/admin/type-configs/:id	已完成	Y
[Admin] 跨站複製	/game/providers	POST /game/admin/copy-site-data	已完成	Y

2.1.3 金流管理 — 13 個端點

功能	前台頁面	後端 API	狀態	多站點
金流群組列表	-	GET /vendor/groups	已完成	Y
金流通道列表	/user/deposit	GET /vendor/channels	已完成	Y
萬通 ATM 入金	/user/deposit	POST /vendor/wantong/add-atm	已完成	Y
萬通信用卡入金	/user/deposit	POST /vendor/wantong/add-card	已完成	Y
萬通回調	-	POST /vendor/wantong/callback	已完成	Y
USDT 回調	-	POST /vendor/usdt/callback	已完成	Y
建立存款訂單	/user/deposit	POST /deposit	已完成	Y
存款訂單列表	/user/transaction	GET /deposit/orders	已完成	Y
取得匯率	/user/deposit	GET /deposit/exchange-rate	已完成	-
存款訂單詳情	/user/transaction	GET /deposit/orders/:id	已完成	Y
提領申請	/user/withdrawal	POST /withdrawal/request	已完成	Y
提領訂單列表	/user/transaction	GET /withdrawal/orders	已完成	Y
提領訂單詳情	/user/transaction	GET /withdrawal/orders/:id	已完成	Y

2.1.4 錢包管理 (Wallet) — 9 個端點

功能	前台頁面	後端 API	狀態	多站點
新增銀行卡	/user/wallet	POST /wallet/bank-card/add	已完成	Y
銀行卡列表	/user/wallet	GET /wallet/bank-card/list	已完成	Y
刪除銀行卡	/user/wallet	DELETE /wallet/bank-card/:id	已完成	Y
新增信用卡	/user/wallet	POST /wallet/credit-card/add	已完成	Y
信用卡列表	/user/wallet	GET /wallet/credit-card/list	已完成	Y
刪除信用卡	/user/wallet	DELETE /wallet/credit-card/:id	已完成	Y
新增加密錢包	/user/wallet	POST /wallet/crypto-address/add	已完成	Y
加密錢包列表	/user/wallet	GET /wallet/crypto-address/list	已完成	Y
刪除加密錢包	/user/wallet	DELETE /wallet/crypto-address/:id	已完成	Y

2.1.5 VIP 系統 — 13 個端點

功能	前台頁面	後端 API	狀態	多站點
VIP 等級列表	/user/vip	GET /vip/levels	已完成	Y (siteCode)
用戶 VIP 狀態	/user/vip	GET /vip/user-status	已完成	Y
我的返水紀錄	/user/vip	GET /vip/my-rebates	已完成	Y
返水規則列表	/user/vip	GET /vip/rebates	已完成	Y (siteCode)
[Admin] 等級列表	/vip/levels	GET /vip/admin/levels	已完成	Y
[Admin] 新增等級	/vip/levels	POST /vip/admin/levels	已完成	Y
[Admin] 更新等級	/vip/levels	PATCH /vip/admin/levels/:id	已完成	Y
[Admin] 刪除等級	/vip/levels	DELETE /vip/admin/levels/:id	已完成	Y
[Admin] 返水 Bulk Upsert	/vip/rebates	POST /vip/admin/rebates/bulk	已完成	Y
[Admin] 跨站複製	/vip/levels	POST /vip/admin/copy-site-data	已完成	Y
[Admin] 預覽模板	/vip/levels	GET /vip/admin/preview-template	已完成	Y
[Admin] 帶入模板	/vip/levels	POST /vip/admin/load-template	已完成	Y
[Admin] VIP 玩家列表	/vip/players	GET /admin/reports/vip-players	已完成	Y

功能	前台頁面	後端 API	狀態	多站點
活動列表	/promo	GET /promo/list	已完成	Y (siteCode)
活動詳情	/promo/[id]	GET /promo/:id	已完成	Y
領取活動	/promo/[id]	POST /promo/:id/claim	已完成	Y
活動標籤列表	/promo	GET /promo/tags	已完成	Y
[Admin] 新增活動	/activity/promos/new	POST /admin/promos/create	已完成	Y
[Admin] 更新活動	/activity/promos/[id]	PATCH /admin/promos/:id	已完成	Y
[Admin] 刪除活動	/activity/promos	DELETE /admin/promos/:id	已完成	Y

2.1.7 代理推廣系統 (Affiliate) — 39 個端點

功能	前台頁面	後端 API	狀態	多站點
追蹤點擊	-	POST /affiliate/track-click	已完成	Y
申請代理	/user/affiliate	POST /affiliate/apply-agent	已完成	Y
代理儀表板	/user/affiliate	GET /affiliate/dashboard	已完成	Y
佣金列表	/user/affiliate	GET /affiliate/commissions	已完成	Y
結算列表	/user/affiliate	GET /affiliate/settlements	已完成	Y
下線列表	/user/affiliate	GET /affiliate/downlines	已完成	Y
代理餘額	/user/affiliate	GET /affiliate/balance	已完成	Y
申請提款	/user/affiliate	POST /affiliate/request-withdrawal	已完成	Y
提款紀錄	/user/affiliate	GET /affiliate/withdrawals	已完成	Y
聯盟資訊	/alliance	GET /affiliate/alliance-info	已完成	Y
等級資訊	/alliance	GET /affiliate/tier-info	已完成	Y
VIP 里程碑	/alliance	GET /affiliate/vip-milestones	已完成	Y
推廣碼列表	/user/affiliate	GET /affiliate/referral-codes	已完成	Y
新增推廣碼	/user/affiliate	POST /affiliate/referral-codes	已完成	Y
刪除推廣碼	/user/affiliate	DELETE /affiliate/referral-codes/:id	已完成	Y
[Admin] 代理列表	/affiliate/agents	GET /affiliate/admin/agents	已完成	Y
[Admin] 新增代理	/affiliate/agents	POST /affiliate/admin/create-agent	已完成	Y
[Admin] 結算列表	/affiliate/settlements	GET /affiliate/admin/settlements	已完成	Y
[Admin] 結算審核	/affiliate/settlements	POST /affiliate/admin/settlements/:id/review	已完成	Y
[Admin] 風控紀錄	/affiliate/settlements	GET /affiliate/admin/settlements/:id/risk-logs	已完成	Y
[Admin] 代理提款列表	/affiliate/aff-withdrawals	GET /affiliate/admin/withdrawals	已完成	Y
[Admin] 提款審核	/affiliate/aff-withdrawals	POST /affiliate/admin/withdrawals/:id/review	已完成	Y
[Admin] 提款完成	/affiliate/aff-withdrawals	POST /affiliate/admin/withdrawals/:id/complete	已完成	Y
[Admin] 手動綁定	/affiliate/agents	POST /affiliate/admin/bind	已完成	Y
[Admin] 綁定紀錄	/affiliate/bind-logs	GET /affiliate/admin/bind-logs	已完成	Y
[Admin] 佣金費率列表	/affiliate/commission-rates	GET /affiliate/admin/commission-rates	已完成	Y
[Admin] 更新佣金費率	/affiliate/commission-rates	POST /affiliate/admin/commission-rates	已完成	Y
[Admin] 刪除佣金費率	/affiliate/commission-rates	DELETE /affiliate/admin/commission-rates	已完成	Y
[Admin] VIP 里程碑列表	/affiliate/vip-milestones	GET /affiliate/admin/vip-milestones	已完成	Y
[Admin] 更新 VIP 里程碑	/affiliate/vip-milestones	POST /affiliate/admin/vip-milestones	已完成	Y
[Admin] 刪除 VIP 里程碑	/affiliate/vip-milestones	DELETE /affiliate/admin/vip-milestones	已完成	Y
[Admin] 代理等級列表	/affiliate/agent-tiers	GET /affiliate/admin/agent-tiers	已完成	Y
[Admin] 更新代理等級	/affiliate/agent-tiers	POST /affiliate/admin/agent-tiers	已完成	Y
[Admin] 刪除代理等級	/affiliate/agent-tiers	DELETE /affiliate/admin/agent-tiers	已完成	Y
[Admin] 預覽模板	-	GET /affiliate/admin/preview-template	已完成	Y
[Admin] 帶入模板	-	POST /affiliate/admin/load-template	已完成	Y
[Admin] 設定代理等級	/affiliate/agents	POST /affiliate/admin/set-agent-tier	已完成	Y
[Admin] 觸發週結	/affiliate/settlements	POST /affiliate/admin/trigger-settlement	已完成	Y
[Admin] 觸發日結	/affiliate/settlements	POST /affiliate/admin/trigger-daily-settlement	已完成	Y

2.1.8 任務系統 (Mission) — 3 個端點

功能	前台頁面	後端 API	狀態	多站點
任務列表	/mission	GET /mission/list	已完成	Y
任務進度	/mission	GET /mission/progress	已完成	Y
領取獎勵	/mission	POST /mission/:id/claim	已完成	Y

2.1.9 站內信 (Inbox) — 7 個端點

功能	前台頁面	後端 API	狀態	多站點
通知列表	/user/inbox	GET /inbox/list	已完成	Y
通知詳情	/user/inbox	GET /inbox/:id	已完成	Y
標記已讀	/user/inbox	POST /inbox/:id/read	已完成	Y
刪除通知	/user/inbox	DELETE /inbox/:id	已完成	Y
未讀數量	Header	GET /inbox/unread-count	已完成	Y
[Admin] 發送通知	/mail/inbox	POST /admin/inbox/send	已完成	Y
[Admin] 通知設定	/mail/settings	GET /admin/inbox/settings	已完成	Y

2.1.10 站點設定 (Site Config) — 8+12 個端點

功能	前台頁面	後端 API	狀態	多站點
取得站點設定	全站	GET /site-config/public	已完成	Y
取得站點主題	全站	GET /site-config/theme	已完成	Y
[Admin] 站點列表	/system/site-config	GET /site-config/admin/list	已完成	-
[Admin] 新增站點	/system/site-config	POST /site-config/admin	已完成	-
[Admin] 更新站點	/system/site-config	PATCH /site-config/admin/:id	已完成	-
[Admin] 刪除站點	/system/site-config	DELETE /site-config/admin/:id	已完成	-
[Admin] 主題列表	/system/site-config	GET /site-config/admin/:siteConfigId/themes	已完成	-
[Admin] 新增主題	/system/site-config	POST /site-config/admin/:siteConfigId/themes	已完成	-
[Admin] 更新主題	/system/site-config	PATCH /site-config/admin/themes/:id	已完成	-
[Admin] 刪除主題	/system/site-config	DELETE /site-config/admin/themes/:id	已完成	-
[Admin] 上傳域名素材	/system/site-domains	POST /site-config/admin/:id/domain-asset	已完成	-
[Admin] 上傳客服圖示	/system/site-customer-service	POST /site-config/admin/:id/customer-service-icon	已完成	-
[Admin] 更新吉祥物	/system/site-config	PATCH /site-config/admin/:siteConfigId/mascots	已完成	-
[Admin] 取得客服設定	/system/site-customer-service	GET /site-config/admin/:siteCode/customer-service	已完成	-

2.1.11 風控管理 (Risk Control) — 11 個端點

功能	前台頁面	後端 API	狀態	多站點
[Admin] IP 規則列表	/risk-control/ip-rules	GET /admin/risk/ip-rules	已完成	Y
[Admin] 新增 IP 規則	/risk-control/ip-rules	POST /admin/risk/ip-rules	已完成	Y
[Admin] 更新 IP 規則	/risk-control/ip-rules	PATCH /admin/risk/ip-rules/:id	已完成	Y
[Admin] 刪除 IP 規則	/risk-control/ip-rules	DELETE /admin/risk/ip-rules/:id	已完成	Y
[Admin] IP/FP 查詢	/risk-control/ip-check	GET /admin/risk/lookup	已完成	Y
[Admin] 登入失敗紀錄	/players/login-failures	GET /admin/risk/login-failures	已完成	Y
[Admin] 遊戲黑名單列表	/risk-control/game-blacklist	GET /admin/risk/game-blacklist	已完成	Y
[Admin] 新增遊戲黑名單	/risk-control/game-blacklist	POST /admin/risk/game-blacklist	已完成	Y
[Admin] 更新遊戲黑名單	/risk-control/game-blacklist	PATCH /admin/risk/game-blacklist/:id	已完成	Y
[Admin] 刪除遊戲黑名單	/risk-control/game-blacklist	DELETE /admin/risk/game-blacklist/:id	已完成	Y
遊戲封鎖檢查	(遊戲啟動時)	內部呼叫 isUserBlockedFromGame()	已完成	Y

2.1.12 報表 (Reports) — 10 個端點

功能	前台頁面	後端 API	狀態	多站點
[Admin] 玩家報表	/reports/players	GET /admin/reports/players	已完成	Y
[Admin] VIP 玩家報表	/vip/players	GET /admin/reports/vip-players	已完成	Y
[Admin] 投注紀錄	/reports/bet-records	GET /admin/reports/bet-records	已完成	Y
[Admin] 總覽報表	/reports/overview	GET /admin/reports/overview	已完成	Y
[Admin] 損益報表	/reports/profit-loss	GET /admin/reports/profit-loss	已完成	Y
[Admin] 遊戲報表	/reports/games	GET /admin/reports/games	已完成	Y
[Admin] 活動報表	/reports/promos	GET /admin/reports/promos	已完成	N (待加入)
[Admin] 玩家摘要	/reports/player-summary	GET /admin/reports/player-summary	已完成	Y
[Admin] R2 日誌	/system/cloud-storage-logs	GET /admin/reports/r2-logs	已完成	Y
[Admin] 匯出	各報表頁面	GET /admin/reports/export	已完成	Y

2.1.13 系統管理 (Admin) — 18 個端點

功能	前台頁面	後端 API	狀態	多站點
[Admin] 管理員登入	/login	POST /admin/login	已完成	N (全站)
[Admin] 管理員註冊	-	POST /admin/register	已完成	N
[Admin] 發送驗證碼	/login	POST /admin/send-verify-code	已完成	N
[Admin] 驗證 Email	-	POST /admin/verify-email	已完成	N
[Admin] 管理員列表	/system/admins	GET /admin/list	已完成	N (全站)
[Admin] 新增管理員	/system/admins/new	POST /admin/create	已完成	N
[Admin] 取得管理員	/system/admins/[id]	GET /admin/:id	已完成	N
[Admin] 更新管理員	/system/admins/[id]	PATCH /admin/:id	已完成	N
[Admin] 刪除管理員	/system/admins	DELETE /admin/:id	已完成	N
[Admin] 群組列表	/system/groups	GET /admin/groups/list	已完成	N (全站)
[Admin] 新增群組	/system/groups/new	POST /admin/groups/create	已完成	N
[Admin] 取得群組	/system/groups/[id]	GET /admin/groups/:id	已完成	N
[Admin] 更新群組	/system/groups/[id]	PATCH /admin/groups/:id	已完成	N
[Admin] 刪除群組	/system/groups	DELETE /admin/groups/:id	已完成	N
[Admin] 所有權限	/system/groups	GET /admin/permissions/all	已完成	N
[Admin] 操作紀錄	/system/logs	GET /admin/logs/list	已完成	N (全站)
[Admin] R2 操作	/system/cloud-storage	GET/POST/DELETE /admin/r2/*	已完成	Y
[Admin] 個人資料	Header Profile	GET/PATCH /admin/profile	已完成	N

2.1.14 其他端點

功能	前台頁面	後端 API	狀態	多站點
共用列舉/錯誤碼	(前端初始化)	GET /common/enums	已完成	N
排行榜	/game	GET /ranking/list	已完成	Y
投注紀錄	/user/bet-record	GET /bet-record/list	已完成	Y
投注詳情	/user/bet-record	GET /bet-record/:id	已完成	Y
即時賽事	/ (首頁)	GET /live-sports/matches	已完成	N
健康檢查	-	GET /	已完成	N

第 3 章：前台功能規格 (c9-ec)

前台使用 Nuxt 4.2 (Vue 3.5 + TypeScript) 開發，面向終端用戶。前台目前使用 a1 佈局方案，所有頁面元件位於 components/A1/ 目錄下。另有 a2 佈局變體用於多品牌視覺切換。

3.1 首頁

路由：/
元件：pages/index.vue → A1/Home/index.vue
子元件：Banner.vue、LiveSports.vue、Promo.vue

用途說明

首頁是用戶進入平台後的第一個畫面，展示平台的核心內容，包括輪播橫幅、即時體育賽事、推薦活動，以及快速進入遊戲大廳的入口。

使用者故事

作為一個新訪客，我希望在首頁看到平台的核心特色與活動，以便快速了解平台提供的服務。
作為一個已登入用戶，我希望從首頁快速進入我想玩的遊戲，以便節省瀏覽時間。
作為一個體育迷，我希望在首頁看到即時賽事資訊，以便掌握最新賽況。

畫面元素說明

Banner 輪播區
- 動態橫幅，資料來自後端 API（活動圖片）
- 支援自動輪播與手動切換
- 點擊可跳轉至對應活動詳情頁
- 根據當前語系顯示對應語言的橫幅圖片
即時體育賽事區 (LiveSports)
- 顯示正在進行或即將開始的體育賽事
- 資料來源：API-Football，每 30 分鐘更新一次
- 顯示隊伍名稱、比分、開賽時間
- 支援多種體育項目
推薦活動區 (Promo)
- 展示平台當前的優惠活動
- 卡片式排列，每張含活動圖片、標題、簡介
- 點擊跳轉至活動詳情頁 /promo/[id]
快速遊戲入口
- 提供遊戲分類快捷按鈕（體育、老虎機、真人、彩票等）
- 點擊直接跳轉至遊戲大廳對應分類

API	方法	說明
/site-config/public	GET	取得站點設定（Banner、Logo 等）
/promo/list	GET	取得推薦活動列表
/live-sports/matches	GET	取得即時體育賽事

權限要求

無需登入即可瀏覽

多站點行為

根據當前域名自動載入對應站點的 Banner、Logo、主題色
透過 useConfig.ts 的 domainConfig[hostname] 進行域名設定映射

3.2 遊戲大廳

路由：/game
元件：pages/game/index.vue → A1/Game/index.vue
子元件：Lobby.vue、Provider.vue、Search.vue、ListBar.vue、LoadMore.vue、RankList.vue、Empty.vue

用途說明

遊戲大廳是平台的核心頁面，用戶可在此瀏覽、搜尋及啟動各類遊戲。頁面以 8 種遊戲分類進行組織，每個分類下展示遊戲供應商及其遊戲。

使用者故事

作為一個玩家，我希望按遊戲類型瀏覽遊戲，以便快速找到我感興趣的遊戲。
作為一個玩家，我希望搜尋特定遊戲名稱，以便直接找到目標遊戲。
作為一個回訪玩家，我希望看到最近遊玩的遊戲，以便快速回到之前的遊戲。
作為一個玩家，我希望看到遊戲排行榜，以便了解熱門遊戲。

畫面元素說明

遊戲分類標籤列 (ListBar)
- 8 種遊戲類型標籤：體育(1)、老虎機(2)、真人(3)、彩票(4)、棋牌(5)、電競(8)、加密(9)、捕魚(10)
- 水平捲動標籤列，當前選中分類高亮顯示
- 切換標籤自動載入對應分類的遊戲供應商
遊戲供應商卡片區 (Provider)
- 以供應商為單位展示遊戲
- 每張供應商卡片顯示供應商名稱、Logo、代表遊戲
- 展示邏輯：
  - 有子分類的類型：顯示第一款遊戲圖片
  - 無子分類的類型：顯示供應商封面圖
搜尋功能 (Search)
- 支援按遊戲名稱搜尋
- 即時搜尋結果顯示
- 無結果時顯示空狀態元件 (Empty)
近期遊玩區
- 顯示用戶最近遊玩的 10 款遊戲
- 需登入才顯示
- 資料來自 GET /game/recent
遊戲排行榜 (RankList)
- 顯示熱門遊戲排名
- 資料來自 GET /ranking/list
載入更多 (LoadMore)
- 分頁載入遊戲供應商
- 點擊「載入更多」顯示下一頁

API	方法	說明
/game/providers	GET	取得遊戲供應商列表（含 siteCode 篩選）
/game/type-configs	GET	取得遊戲分類列表（含 siteCode 篩選）
/game/recent	GET	取得最近遊玩遊戲（需登入）
/ranking/list	GET	取得遊戲排行榜

權限要求

瀏覽不需登入
「近期遊玩」區塊需登入

多站點行為

遊戲供應商與分類依站點 siteCode 獨立配置
不同站點可擁有不同的遊戲商與分類組合

3.3 遊戲啟動

路由：/game/play
元件：pages/game/play.vue → A1/Game/Play.vue

用途說明

遊戲啟動頁面負責透過 iframe 嵌入第三方遊戲供應商的遊戲畫面。使用者在遊戲大廳選擇遊戲後，會被導向此頁面。

使用者故事

作為一個玩家，我希望點擊遊戲後立即開始遊玩，以便享受無縫的遊戲體驗。
作為一個試玩用戶，我希望不需登入也能試玩遊戲，以便在註冊前體驗遊戲品質。

畫面元素說明

遊戲 Iframe 區域
- 全屏嵌入遊戲供應商提供的遊戲 URL
- 遊戲參數：gameCode + productId
- 載入中顯示 Loading 狀態
返回按鈕
- 提供返回遊戲大廳的導航

互動流程

使用者在遊戲大廳點擊遊戲
前端發送 POST /game/launch，帶入 gameCode 與 productId
後端執行風控檢查：
- 使用者是否已認證？
- 遊戲是否存在？
- 風控黑名單檢查 (isUserBlockedFromGame) → 若被封鎖返回錯誤碼 5010
後端呼叫遊戲供應商 API（BetSolutions 或 RSG），取得遊戲 URL
後端非同步記錄 UPSERT GamePlayLog
前端接收遊戲 URL，透過 iframe 載入遊戲
遊戲中下注/派彩透過 S2S 回調更新用戶餘額

API	方法	說明
/game/launch	POST	啟動遊戲（需登入）
/game/demo	POST	試玩遊戲（不需登入）

權限要求

正式遊戲需登入
試玩模式不需登入

多站點行為

遊戲啟動前依據用戶所屬站點進行風控檢查
遊戲供應商 API 金鑰依站點獨立配置

3.4 活動中心

路由：/promo
元件：pages/promo/index.vue → A1/Promo/Center.vue

用途說明

活動中心展示平台所有進行中的優惠活動，支援透過標籤進行分類篩選。

使用者故事

作為一個玩家，我希望瀏覽所有可用的優惠活動，以便找到適合自己的優惠。
作為一個玩家，我希望透過分類標籤篩選活動，以便快速找到特定類型的優惠。

畫面元素說明

活動標籤篩選列
- 顯示所有活動標籤（如：新手、VIP、每日、週末等）
- 支援點選篩選
- 「全部」選項顯示所有活動
活動卡片列表
- 每張卡片包含：
  - 活動圖片（根據裝置顯示 PC 版或行動版圖片）
  - 活動標題（多語系）
  - 活動簡介（多語系）
  - 活動期間
- 點擊跳轉至活動詳情頁

API	方法	說明
/promo/list	GET	取得活動列表
/promo/tags	GET	取得活動標籤列表

權限要求

無需登入即可瀏覽

3.5 活動詳情

路由：/promo/[id]
元件：pages/promo/[id].vue → A1/Promo/Detail.vue

用途說明

活動詳情頁展示單一活動的完整資訊，包括 HTML 格式的活動內容、領取條件及領取按鈕。

使用者故事

作為一個玩家，我希望查看活動的詳細規則與條件，以便了解如何參與及領取獎勵。
作為一個符合條件的玩家，我希望直接領取活動獎勵，以便快速獲得優惠。

畫面元素說明

活動圖片
- 頂部顯示活動的大圖橫幅
活動內容區
- HTML 富文本內容（後台使用 Tiptap 編輯器撰寫）
- 支援多語系內容切換
領取條件顯示
- 顯示活動的領取條件（如：存款門檻、VIP 等級、首次存款等）
領取按鈕
- 符合條件時可點擊領取
- 已領取時顯示「已領取」狀態
- 未登入時提示登入

API	方法	說明
/promo/:id	GET	取得活動詳情
/promo/:id/claim	POST	領取活動獎勵

權限要求

瀏覽不需登入
領取需登入且符合條件

3.6 聯盟推廣

路由：/alliance
元件：pages/alliance.vue → A1/Alliance/index.vue

用途說明

聯盟推廣頁面向潛在代理展示代理推廣計畫的資訊，包括代理等級體系、佣金費率、VIP 里程碑獎勵等。

使用者故事

作為一個有興趣成為代理的用戶，我希望了解代理計畫的獎勵機制，以便評估是否值得加入。
作為一個現有代理，我希望查看各等級的佣金費率，以便了解晉升目標。

畫面元素說明

代理計畫介紹
- 三層代理結構說明（上線 → 下線，最多 3 層）
- 佣金計算方式說明
代理等級資訊
- 4 個代理等級：Bronze / Silver / Gold / Platinum
- 各等級門檻與權益
佣金費率表
- 按代理等級 x 遊戲類型顯示佣金比例
VIP 里程碑獎勵
- 下線達到特定 VIP 等級時的額外獎勵

API	方法	說明
/affiliate/alliance-info	GET	取得聯盟計畫資訊
/affiliate/tier-info	GET	取得代理等級資訊
/affiliate/vip-milestones	GET	取得 VIP 里程碑獎勵

權限要求

無需登入即可瀏覽

3.7 任務系統

路由：/mission
元件：pages/mission.vue → A1/Mission/index.vue

用途說明

任務系統提供每日、每週、每月三種週期的任務，鼓勵用戶持續存款與投注。完成任務可領取額外獎勵。

使用者故事

作為一個活躍玩家，我希望透過完成任務獲得額外獎勵，以便提升遊戲體驗價值。
作為一個玩家，我希望清楚看到任務進度，以便知道還需要多少努力才能完成。

畫面元素說明

任務分類標籤
- 每日任務 (daily)
- 每週任務 (weekly)
- 每月任務 (monthly)
任務卡片
- 每張卡片顯示：
  - 任務名稱
  - 任務描述
  - 進度條（當前值 / 目標值）
  - 獎勵金額
  - 領取按鈕（達成後可領取）
任務類型
- 存款任務 (daily_deposit)：存入指定金額
- 投注任務 (weekly_bet)：累計投注達標
- 月度挑戰 (monthly_challenge)：綜合目標

互動流程

用戶查看任務列表與進度
用戶在平台上存款 → 系統自動更新存款任務進度
用戶在平台上投注 → 系統自動更新投注任務進度
進度達到目標 → 領取按鈕啟用
用戶點擊領取 → POST /mission/:id/claim → 獎勵入帳

API	方法	說明
/mission/list	GET	取得任務列表
/mission/progress	GET	取得任務進度
/mission/:id/claim	POST	領取任務獎勵

權限要求

需登入

3.8 幫助中心

路由：/help
元件：pages/help/index.vue → A1/Help/Center.vue

用途說明

幫助中心提供常見問題 (FAQ) 的手風琴式展示，協助用戶自助解決常見疑問。

使用者故事

作為一個新用戶，我希望查看常見問題解答，以便快速了解平台操作方式。

畫面元素說明

FAQ 手風琴列表
- 問題標題可展開/收合
- 答案支援 HTML 富文本
- 多語系內容

API	方法	說明
/site-config/public	GET	取得站點設定（含 learnMoreConfig FAQ 資料）

權限要求

無需登入

3.9 OAuth 回調

路由：/redirect/[action]
元件：pages/redirect/[action].vue

用途說明

OAuth 回調頁面處理第三方登入（Google / Telegram）的回調邏輯，接收授權碼後完成登入流程。

互動流程

用戶在登入彈窗選擇 Google 或 Telegram 登入
前端重導向至第三方授權頁面
用戶授權後被重導向回 /redirect/google 或 /redirect/telegram
前端擷取回調參數（authorization code 或 token）
前端呼叫後端 API 完成登入
成功後跳轉至首頁，失敗則顯示錯誤訊息

權限要求

不需登入（登入流程的一部分）

3.10 個人設定

路由：/user/setting
元件：pages/user/setting.vue → A1/User/Setting.vue
相關彈窗：EditPassword.vue、SetPassword.vue、BindGoogleAuth.vue、VerifyUserInfo.vue

用途說明

個人設定頁面讓用戶管理自己的帳號資訊，包括個人資料修改、頭像更換、密碼管理、二步驟驗證設定、語系同步等。

使用者故事

作為一個用戶，我希望修改我的個人資料（暱稱、Email、手機），以便保持資訊正確。
作為一個注重安全的用戶，我希望啟用 Google Authenticator 二步驟驗證，以便提升帳號安全性。
作為一個 OAuth 用戶，我希望設定密碼，以便日後也能用帳密登入。

畫面元素說明

頭像區域
- 顯示當前頭像
- 支援上傳新頭像
基本資料表單
- 帳號（唯讀）
- 暱稱（可修改）
- Email（需驗證碼驗證）
- 手機號碼（需驗證碼驗證）
- 生日
密碼管理
- 已設定密碼：顯示「修改密碼」按鈕 → EditPassword 彈窗
- 未設定密碼（OAuth 用戶）：顯示「設定密碼」按鈕 → SetPassword 彈窗
二步驟驗證 (2FA)
- Google Authenticator 綁定/解除
- 啟用流程：取得 QR Code + Secret → 掃描後輸入 6 位驗證碼確認
- 停用流程：輸入當前 TOTP 驗證碼確認身份後關閉
第三方帳號綁定狀態
- 顯示 Google / Telegram 綁定狀態
語系設定
- 語系切換（同步更新 cookie 與用戶偏好）

API	方法	說明
/auth/user-detail	GET	取得用戶資料
/auth/update-profile	PATCH	更新個人資料
/auth/avatar	POST	上傳頭像
/auth/set-password	PATCH	設定密碼
/auth/update-password	PATCH	修改密碼
/auth/send-email-verify	POST	發送 Email 驗證碼
/auth/verify-email	POST	驗證 Email
/auth/send-mobile-verify	POST	發送手機驗證碼
/auth/verify-mobile	POST	驗證手機
/auth/google-auth/*	POST	Google Auth 2FA 操作

權限要求

需登入

3.11 存款

路由：/user/deposit
元件：pages/user/deposit.vue → A1/User/Deposit/index.vue
子元件：Fiat.vue、Credit.vue、Crypto.vue

用途說明

存款頁面讓用戶選擇支付方式進行入金操作。支援法幣 ATM 轉帳、信用卡支付、加密貨幣 (USDT) 三種方式。

使用者故事

作為一個玩家，我希望使用我偏好的支付方式存入資金，以便在平台上進行遊戲。
作為一個加密貨幣用戶，我希望使用 USDT 存款，以便享受快速且低手續費的入金體驗。

畫面元素說明

支付方式標籤
- 法幣 ATM (Fiat)
- 信用卡 (Credit)
- 加密貨幣 (Crypto)
法幣 ATM 標籤頁 (Fiat.vue)
- 金流通道選擇（萬通金流）
- 金額輸入欄位
- 即時匯率顯示（台灣銀行匯率）
- 換算後的 USD 金額預覽
- 提交按鈕
信用卡標籤頁 (Credit.vue)
- 金流通道選擇
- 金額輸入
- 匯率顯示
- 提交按鈕
加密貨幣標籤頁 (Crypto.vue)
- USDT 入金資訊
- 支援網路選擇 (TRC-20 / ERC-20)
- 金額輸入
- 提交按鈕

互動流程

用戶選擇支付方式
選擇金流通道
輸入存款金額
系統顯示即時匯率與換算後 USD 金額
用戶確認提交 → POST /deposit
後端路由至對應金流商（萬通或 USDT）
金流商返回支付 URL 或加密地址
用戶在外部完成支付
金流商透過 S2S 回調通知後端
後端更新訂單狀態 → 入帳

API	方法	說明
/vendor/channels	GET	取得可用金流通道
/deposit/exchange-rate	GET	取得即時匯率
/deposit	POST	建立存款訂單

權限要求

需登入

3.12 提款

路由：/user/withdrawal
元件：pages/user/withdrawal.vue → A1/User/Withdrawal/index.vue

用途說明

提款頁面讓用戶申請將帳戶餘額提領至已綁定的銀行卡或加密錢包。

使用者故事

作為一個玩家，我希望將獲利提領至我的銀行帳戶，以便兌現我的遊戲收益。
作為一個加密貨幣用戶，我希望將獲利提領至我的加密錢包，以便快速收款。

畫面元素說明

可用餘額顯示
- 顯示當前可提領金額
提領目的地選擇
- 從已綁定的銀行卡中選擇
- 從已綁定的加密錢包中選擇
- 提示用戶尚未綁定任何錢包時前往綁定
金額輸入
- 輸入提領金額
- 最低/最高提領限制提示
提交按鈕
- 確認提領申請

互動流程

用戶選擇提領目的地（銀行卡或加密錢包）
輸入提領金額
確認提交 → POST /withdrawal/request
系統扣除餘額，加入凍結金額 (frozenBalance)
建立提領訂單（狀態：pending）
等待後台管理員審核
審核通過 → 管理員上傳匯款憑證 → 完成
審核拒絕 → 凍結金額退回可用餘額

API	方法	說明
/withdrawal/request	POST	提交提領申請
/wallet/bank-card/list	GET	取得銀行卡列表
/wallet/crypto-address/list	GET	取得加密錢包列表

權限要求

需登入

3.13 錢包管理

路由：/user/wallet
元件：pages/user/wallet.vue → A1/User/Wallet/index.vue
子元件：Fiat.vue、Credit.vue、Crypto.vue
相關彈窗：AddBankCard.vue、AddCreditCard.vue、AddCryptoAddress.vue、BankCardDetail.vue

用途說明

錢包管理頁面讓用戶管理三種類型的支付錢包：銀行卡、信用卡、加密錢包地址。

使用者故事

作為一個玩家，我希望新增我的銀行卡資訊，以便日後快速存款與提款。
作為一個玩家，我希望查看我所有錢包的審核狀態，以便了解是否可以使用。

畫面元素說明

錢包類型標籤
- 銀行卡 (Fiat)
- 信用卡 (Credit)
- 加密錢包 (Crypto)
錢包列表
- 每張卡片顯示：帳號/地址資訊、綁定狀態、審核狀態
- 支援刪除操作
新增按鈕
- 開啟對應的新增彈窗
新增銀行卡彈窗 (AddBankCard)
- 銀行名稱選擇
- 帳號輸入
- 持卡人姓名
新增信用卡彈窗 (AddCreditCard)
- 信用卡號
- 持卡人姓名
- 到期日
新增加密錢包彈窗 (AddCryptoAddress)
- 區塊鏈網路選擇 (TRC-20 / ERC-20)
- 錢包地址
- 幣種

API	方法	說明
/wallet/bank-card/list	GET	銀行卡列表
/wallet/bank-card/add	POST	新增銀行卡
/wallet/bank-card/:id	DELETE	刪除銀行卡
/wallet/credit-card/list	GET	信用卡列表
/wallet/credit-card/add	POST	新增信用卡
/wallet/credit-card/:id	DELETE	刪除信用卡
/wallet/crypto-address/list	GET	加密錢包列表
/wallet/crypto-address/add	POST	新增加密錢包
/wallet/crypto-address/:id	DELETE	刪除加密錢包

權限要求

需登入

3.14 交易紀錄

路由：/user/transaction
元件：pages/user/transaction.vue → A1/User/Transaction/index.vue
子元件：Deposit.vue、Withdrawal.vue、Dividend.vue、Promo.vue

用途說明

交易紀錄頁面展示用戶所有的資金變動紀錄，分為四個標籤頁。

使用者故事

作為一個玩家，我希望查看我的所有存款紀錄，以便核對入金情況。
作為一個玩家，我希望追蹤提款申請的處理進度，以便了解何時到帳。

畫面元素說明

標籤頁
- 存款紀錄 (Deposit)
- 提款紀錄 (Withdrawal)
- 分紅紀錄 (Dividend)
- 活動獎勵紀錄 (Promo)
紀錄列表
- 每筆紀錄顯示：時間、金額、狀態、類型
- 狀態標籤以顏色區分（待處理/已完成/已拒絕/失敗）
篩選功能
- 日期範圍篩選

API	方法	說明
/deposit/orders	GET	存款訂單列表
/withdrawal/orders	GET	提款訂單列表

權限要求

需登入

3.15 VIP

路由：/user/vip
元件：pages/user/vip.vue → A1/User/Vip/index.vue
子元件：StatusCard.vue、LevelList.vue、Benefits.vue、MyRebates.vue、RebateTable.vue

用途說明

VIP 頁面展示用戶的 VIP 等級狀態、升級進度、各等級權益，以及個人返水紀錄與返水規則表。

使用者故事

作為一個玩家，我希望查看我的 VIP 等級與升級進度，以便了解還需多少投注才能升級。
作為一個 VIP 玩家，我希望查看我的返水紀錄，以便確認返水金額正確。
作為一個玩家，我希望了解各 VIP 等級的權益差異，以便設定升級目標。

畫面元素說明

VIP 狀態卡片 (StatusCard)
- 當前 VIP 等級
- 等級名稱
- 累計有效投注
- 升級進度條（目前投注 / 下一等級門檻）
等級列表 (LevelList)
- 所有 VIP 等級的完整列表
- 每個等級顯示：等級名稱、升級門檻 (minChip)、保級門檻 (relegationChip)
- 當前等級高亮顯示
- 等級數量動態取得（不硬編碼，支援商戶自行擴充）
權益說明 (Benefits)
- 各等級專屬福利說明
我的返水 (MyRebates)
- 個人返水紀錄列表
- 顯示每日返水金額
返水規則表 (RebateTable)
- 按遊戲類型（8 種）顯示各 VIP 等級的返水比例
- 表格形式：行 = VIP 等級，列 = 遊戲類型

API	方法	說明
/vip/levels	GET	取得 VIP 等級列表
/vip/user-status	GET	取得用戶 VIP 狀態
/vip/my-rebates	GET	取得個人返水紀錄
/vip/rebates	GET	取得返水規則

權限要求

需登入

多站點行為

VIP 等級與返水規則依站點獨立配置
每站可擁有不同的等級數量與返水比例

3.16 代理中心

路由：/user/affiliate
元件：pages/user/affiliate.vue → A1/User/Affiliate/index.vue
子元件：Dashboard.vue、Commission.vue、Downline.vue、Settlement.vue、Withdrawal.vue、Alliance.vue

用途說明

代理中心是代理用戶的管理後台，提供佣金概覽、下線管理、結算紀錄、提款功能等。

使用者故事

作為一個代理，我希望查看我的佣金收益概覽，以便了解推廣成效。
作為一個代理，我希望管理我的推廣碼，以便追蹤不同推廣管道的效果。
作為一個代理，我希望查看下線名單與活躍狀態，以便管理我的推廣網路。
作為一個代理，我希望申請佣金提款，以便兌現我的推廣收益。

畫面元素說明

儀表板 (Dashboard)
- 總佣金收入
- 下線數量（各層級）
- 本週/本月收入
- 推廣碼管理（最多 10 個推廣碼）
佣金紀錄 (Commission)
- 佣金明細列表
- 篩選：日期範圍、遊戲類型
下線管理 (Downline)
- 三層下線樹狀結構
- 每個下線顯示：帳號（遮罩）、VIP 等級、累計投注
- 帳號遮罩：maskAccount() 隱藏中間字元
結算紀錄 (Settlement)
- 週結/日結結算紀錄
- 狀態：待審核/已核准/已拒絕
提款管理 (Withdrawal)
- 代理餘額顯示
- 提款申請
- 提款紀錄（三階段：待審核 → 已核准 → 已完成）
聯盟資訊 (Alliance)
- 代理等級與晉升條件
- 佣金費率表

API	方法	說明
/affiliate/dashboard	GET	代理儀表板數據
/affiliate/commissions	GET	佣金列表
/affiliate/downlines	GET	下線列表
/affiliate/settlements	GET	結算紀錄
/affiliate/balance	GET	代理餘額
/affiliate/request-withdrawal	POST	申請提款
/affiliate/withdrawals	GET	提款紀錄
/affiliate/referral-codes	GET/POST/DELETE	推廣碼管理
/affiliate/apply-agent	POST	申請成為代理

權限要求

需登入
部分功能需已成為代理

3.17 投注紀錄

路由：/user/bet-record
元件：pages/user/bet-record.vue → A1/User/BetRecord/index.vue

用途說明

投注紀錄頁面展示用戶的遊戲投注歷史記錄。

使用者故事

作為一個玩家，我希望查看我的投注紀錄，以便追蹤遊戲結果與收益。

畫面元素說明

篩選列
- 遊戲類型篩選
- 日期範圍篩選
- 投注狀態篩選 (valid / invalid / cancelled)
投注列表
- 每筆投注顯示：遊戲名稱、下注金額、派彩金額、有效投注、狀態、時間

API	方法	說明
/bet-record/list	GET	投注紀錄列表
/bet-record/:id	GET	投注詳情

權限要求

需登入

3.18 站內信

路由：/user/inbox
元件：pages/user/inbox.vue → A1/User/Inbox/index.vue

用途說明

站內信頁面展示系統通知與管理員發送的訊息。

使用者故事

作為一個用戶，我希望收到平台重要通知，以便及時了解活動資訊與系統公告。

畫面元素說明

通知列表
- 標題、摘要、時間
- 已讀/未讀狀態標記
- 點擊展開完整內容
操作
- 標記已讀
- 刪除通知

API	方法	說明
/inbox/list	GET	通知列表
/inbox/:id	GET	通知詳情
/inbox/:id/read	POST	標記已讀
/inbox/:id	DELETE	刪除通知
/inbox/unread-count	GET	未讀數量

權限要求

需登入

3.19 KYC 身份驗證

路由：/user/kyc
元件：pages/user/kyc.vue → A1/User/Kyc/index.vue
子元件：StatusCard.vue、StepBasicInfo.vue、StepDocUpload.vue、StepLiveness.vue、StepReview.vue

用途說明

KYC (Know Your Customer) 身份驗證流程，用於合規性要求的用戶身份確認。

使用者故事

作為一個需要提款的用戶，我希望完成身份驗證，以便順利提領我的資金。

畫面元素說明

進度指示器
- 4 步驟進度顯示
步驟一：基本資料 (StepBasicInfo)
- 姓名、出生日期、國籍
- 身份證件號碼
步驟二：文件上傳 (StepDocUpload)
- 上傳身份證件正反面
- 支援身份證、護照、駕照
步驟三：活體檢測 (StepLiveness)
- 自拍照驗證
- 確認為本人操作
步驟四：審核中 (StepReview)
- 顯示審核狀態
- 等待後台審核
狀態卡片 (StatusCard)
- 顯示當前 KYC 狀態（未驗證/審核中/已通過/已拒絕）

權限要求

需登入

3.20 挑戰

路由：/challenges
元件：pages/challenges.vue

用途說明

挑戰頁面為預留頁面，用於未來的挑戰活動功能。

畫面元素說明

目前為 Placeholder 頁面
預計未來加入各類挑戰任務

權限要求

視未來設計而定

3.21 前台共用元件

佈局元件 (Layout)

元件	說明
BottomBar.vue	行動版底部導航列（5 個圖示入口）
Footer.vue	頁尾區域（版權、連結）
LiveChat.vue	即時客服嵌入（LiveChat 腳本）
Sidebar.vue	側邊欄導航（行動版）
TitleBar.vue	頁面標題列（含返回按鈕）

元件	說明
Login.vue	登入彈窗（帳密/Google/Telegram）
Register.vue	註冊彈窗
Locale.vue	語系切換彈窗
Theme.vue	主題切換彈窗
ContactSupport.vue	聯繫客服彈窗（8 種管道）
AgentTour.vue	代理導覽彈窗
BuyCrypto.vue	購買加密貨幣引導彈窗
VerifyUserInfo.vue	用戶資訊驗證彈窗

共用元件 (Common)

元件	說明
ConfirmDialog.vue	通用確認對話框
SplashScreen.vue	啟動畫面
PromoLinkCard.vue	活動連結卡片

第 4 章：後台功能規格 (c9-ims)

後台管理系統使用 Next.js 16 (React 19 + TypeScript) 開發，面向平台管理員。後台採用 RBAC 權限控制，所有頁面需登入後方可存取。多數列表頁面已支援多站點 Tab 切換架構。

4.1 儀表板

4.1.1 Dashboard

路由：/dashboard
用途：平台營運數據概覽
權限：任何已認證管理員均可檢視
多站點：待實作

操作流程

管理員登入後自動導向此頁面
頁面顯示統計卡片（用戶總數、今日存款、今日提款等）
折線圖展示趨勢數據
長條圖展示分類統計

畫面元素

統計卡片（4-6 張）
折線圖（趨勢分析）
長條圖（分類比較）
時間範圍選擇器

4.2 系統管理

4.2.1 管理員列表

路由：/system/admins
用途：管理所有後台管理員帳號
權限：admin:read
多站點：否（全站共用，SiteSelector 自動隱藏）
API：GET /admin/list

操作流程

進入頁面顯示管理員列表
支援關鍵字搜尋（帳號、Email、名稱）
每列顯示：ID、帳號、Email、名稱、群組、狀態、建立時間
操作：編輯、刪除
右上角「新增管理員」按鈕

篩選條件

關鍵字搜尋

4.2.2 新增管理員

路由：/system/admins/new
用途：建立新的管理員帳號
權限：admin:write
多站點：否
API：POST /admin/create

操作流程

填寫管理員資訊（帳號、Email、密碼、名稱）
選擇所屬群組（決定權限範圍）
設定帳號狀態（啟用/停用）
提交後返回列表頁

4.2.3 編輯管理員

路由：/system/admins/[id]
用途：修改現有管理員資訊
權限：admin:write
多站點：否
API：GET /admin/:id、PATCH /admin/:id

操作流程

載入管理員現有資料
可修改：名稱、Email、密碼、群組、狀態
提交更新後返回列表頁

4.2.4 群組列表

路由：/system/groups
用途：管理權限群組
權限：admin-group:read
多站點：否（全站共用，SiteSelector 自動隱藏）
API：GET /admin/groups/list

操作流程

顯示群組列表
每列顯示：ID、群組名稱、群組類型、成員數量、建立時間
操作：編輯、刪除
右上角「新增群組」按鈕

群組類型

類型	說明
root	最高權限，略過所有權限檢查
super_admin	擁有除 site-config 外的所有權限
general_admin	僅有讀取權限
custom	自訂權限組合

4.2.5 新增群組

路由：/system/groups/new
用途：建立新的權限群組
權限：admin-group:write
多站點：否
API：POST /admin/groups/create、GET /admin/permissions/all

操作流程

輸入群組名稱
選擇群組類型
若為 custom 類型，勾選各權限模組的 read/write 權限
16 個權限模組的 checkbox 矩陣顯示
提交後返回列表頁

權限模組 (16 個)

模組	說明
admin	管理員管理
admin-group	群組管理
admin-log	操作紀錄
user	用戶管理
deposit	存款管理
withdrawal	提款管理
promo	活動管理
promo-tag	活動標籤
affiliate	代理管理
vip	VIP 管理
game	遊戲管理
risk	風控管理
report	報表
vendor	金流商管理
finance	財務管理
site-config	站點設定

4.2.6 編輯群組

路由：/system/groups/[id]
用途：修改現有群組的權限配置
權限：admin-group:write
多站點：否
API：GET /admin/groups/:id、PATCH /admin/groups/:id

4.2.7 操作紀錄

路由：/system/logs
用途：查詢後台管理員的操作紀錄
權限：admin-log:read
多站點：否（全站共用，SiteSelector 自動隱藏）
API：GET /admin/logs/list

操作流程

顯示操作紀錄列表
每列顯示：時間、管理員、動作、目標、IP、User-Agent

篩選條件

關鍵字搜尋
日期範圍

4.2.8 站點基本設定

路由：/system/site-config
用途：管理站點的基礎設定資訊
權限：site-config:read / site-config:write
多站點：否（本身就是站點管理）
API：GET /site-config/admin/list、POST /site-config/admin、PATCH /site-config/admin/:id、DELETE /site-config/admin/:id

操作流程

顯示所有站點列表
每個站點可編輯：站點名稱、站點代碼 (siteCode)、介紹（多語系）、支援語系列表
主題管理：每站可新增多組主題色，設定啟用主題
吉祥物管理：上傳/更新吉祥物圖片列表

主題色彩體系

色彩類別	說明
primary	主色調
accent	強調色
surface	表面色
text	文字色
border	邊框色

4.2.9 客服配置

路由：/system/site-customer-service
用途：管理各站點的客服管道配置
權限：site-config:read / site-config:write
多站點：是（模式 B — 設定頁）
API：GET /site-config/admin/:siteCode/customer-service、PATCH /site-config/admin/:id

操作流程

SiteTabs 切換站點
每個站點顯示 8 種客服管道設定
每個管道可設定：多語系標題 (label)、圖示 (icon)、連結 (link)、排序 (sortOrder)、啟用/停用 (enabled)
LiveChat 獨立開關：可嵌入 LiveChat 腳本
支援「同預設站點」一鍵複製

8 種客服管道

管道	說明
line	LINE
telegram	Telegram
wechat	微信
facebook	Facebook
instagram	Instagram
twitter	Twitter/X
discord	Discord
custom	自訂管道

4.2.10 域名設置

路由：/system/site-domains
用途：管理站點域名、Logo、Favicon 等品牌素材
權限：site-config:read / site-config:write
多站點：是（模式 B）
API：POST /site-config/admin/:id/domain-asset

操作流程

SiteTabs 切換站點
設定/更新域名 (hostname)
上傳品牌素材：
- 小 Logo (logoSmall)
- 大 Logo (logoBig)
- Favicon
設定該站點支援的語系列表 (supportedLocales)
支援「同預設站點」複製（保留 hostname + supportedLocales，同步其他欄位）

4.2.11 遊戲商配置

路由：/system/site-game-providers
用途：管理各站點的遊戲商 API 金鑰與配置
權限：site-config:read / site-config:write
多站點：是（模式 B）

操作流程

SiteTabs 切換站點
每個遊戲商的 API 金鑰與設定
支援「同預設站點」複製（前端狀態拷貝，需手動儲存）

4.2.12 三方登入配置

路由：/system/site-oauth
用途：管理各站點的 OAuth 登入提供者設定
權限：site-config:read / site-config:write
多站點：是（模式 B）

操作流程

SiteTabs 切換站點
設定 Google OAuth：Client ID、Client Secret、Redirect URI
設定 Telegram Login：Bot Token、Bot Username
啟用/停用各 OAuth 提供者
支援「同預設站點」複製

4.2.13 服務商配置

路由：/system/site-service-providers
用途：管理各站點的第三方服務提供商設定
權限：site-config:read / site-config:write
多站點：是（模式 B）

操作流程

SiteTabs 切換站點
設定 Resend (Email 服務)：API Key、寄件地址
設定 Twilio (SMS 服務)：Account SID、Auth Token、Verify Service SID
設定 Cloudflare R2 (儲存)：Bucket、Endpoint、Access Key
支援「同預設站點」複製

4.2.14 雲端儲存

路由：/system/cloud-storage
用途：Cloudflare R2 檔案瀏覽器
權限：admin:read / admin:write
多站點：是（模式 A）
API：GET /admin/r2/list、POST /admin/r2/upload、DELETE /admin/r2/delete、POST /admin/r2/move、POST /admin/r2/create-folder、DELETE /admin/r2/delete-folder

操作流程

以檔案瀏覽器形式展示 R2 儲存空間
支援目錄瀏覽、檔案上傳、檔案刪除、檔案移動
支援建立/刪除資料夾
每個檔案操作會記錄到 R2 操作日誌

4.2.15 雲端儲存日誌

路由：/system/cloud-storage-logs
用途：R2 檔案操作的稽核日誌
權限：admin:read
多站點：是（模式 A）
API：GET /admin/reports/r2-logs

操作流程

顯示 R2 操作紀錄列表
每列顯示：時間、操作者、動作、檔案路徑、MIME 類型
支援 OS/瀏覽器解析（User-Agent 解析）
支援 Detail Dialog 查看完整操作資訊

篩選條件

關鍵字搜尋
日期範圍

4.3 前台佈局配置

4.3.1 底部導航列配置

路由：/system/layout-bottom-bar
用途：管理前台行動版底部 Tab 項目
權限：site-config:read / site-config:write
多站點：是（模式 B）

操作流程

SiteTabs 切換站點
配置底部導航列的 Tab 項目
每個項目可設定：圖示、多語系標題、連結、排序、啟用/停用
支援「同預設站點」複製

4.3.2 頁尾配置

路由：/system/layout-footer
用途：管理前台頁尾區域的連結與版權資訊
權限：site-config:read / site-config:write
多站點：是（模式 B）

操作流程

SiteTabs 切換站點
配置頁尾連結分組
每組可設定：多語系標題、連結列表、排序
版權文字設定
支援「同預設站點」複製

4.3.3 了解更多配置

路由：/system/layout-learn-more
用途：管理前台「了解更多」區塊（FAQ）的內容
權限：site-config:read / site-config:write
多站點：是（模式 B）

操作流程

SiteTabs 切換站點
配置 FAQ 項目列表
每個項目含多語系標題與多語系內容（HTML）
支援「同預設站點」複製

4.4 玩家管理

4.4.1 全部玩家

路由：/players/all
用途：查詢與管理所有前台用戶
權限：user:read
多站點：是（模式 A）
API：GET /admin/finance/users/list

操作流程

SiteTabs 切換站點
FilterBar 篩選用戶
SimpleTable 顯示用戶列表
每列顯示：ID、帳號、暱稱、VIP 等級、餘額、狀態、註冊時間
點擊用戶可進入詳情頁

篩選條件

關鍵字搜尋（帳號、Email、手機）
VIP 等級篩選（動態下拉選單，不硬編碼等級數量）
日期範圍

4.4.2 玩家詳情

路由：/players/all/[id]
用途：查看單一玩家的完整資訊
權限：user:read / user:write
多站點：否（詳情頁）
API：GET /admin/finance/users/:id、PATCH /admin/finance/users/:id

操作流程

顯示玩家完整資料：
- 基本資料（帳號、Email、手機、暱稱、生日）
- VIP 資訊（等級、累計投注、升級進度）
- 餘額資訊（可用餘額、凍結金額）
- 登入紀錄（IP、裝置、時間）
- 錢包列表（銀行卡、信用卡、加密錢包）
可編輯用戶資訊
可調整用戶狀態（啟用/停用）

4.4.3 新註冊玩家

路由：/players/new-registrations
用途：查看近期新註冊的用戶
權限：user:read
多站點：是（模式 A）

操作流程

SiteTabs 切換站點
預設顯示近期註冊用戶
表格內容同「全部玩家」，但預設篩選為近期

篩選條件

關鍵字搜尋
VIP 等級篩選（動態）
日期範圍

4.4.4 線上玩家

路由：/players/online
用途：查看當前在線的用戶
權限：user:read
多站點：是（模式 A）

操作流程

SiteTabs 切換站點
顯示當前在線用戶列表
每列顯示：帳號、VIP 等級、最後活躍時間、IP

4.4.5 登入失敗紀錄

路由：/players/login-failures
用途：查看用戶登入失敗的紀錄，用於安全監控
權限：risk:read
多站點：是（模式 A）
API：GET /admin/risk/login-failures

操作流程

SiteTabs 切換站點
顯示登入失敗紀錄列表
每列顯示：時間、帳號、IP、裝置、失敗原因

篩選條件

關鍵字搜尋
日期範圍

4.4.6 玩家標籤

路由：/players/tags
用途：管理玩家分類標籤
權限：user:read / user:write
多站點：規劃中

操作流程

待實作

4.4.7 遊戲重新註冊

路由：/players/game-reregistration
用途：重新註冊用戶的遊戲帳號
權限：game:write
多站點：規劃中

操作流程

待實作

4.5 活動管理

4.5.1 優惠活動列表

路由：/activity/promos
用途：管理平台所有優惠活動
權限：promo:read
多站點：是（模式 A）
API：GET /admin/promos/list

操作流程

SiteTabs 切換站點
顯示活動列表
每列顯示：標題、標籤、狀態、開始日期、結束日期、領取人數
操作：編輯、刪除
右上角「新增活動」按鈕

篩選條件

關鍵字搜尋
狀態篩選
日期範圍

4.5.2 新增活動

路由：/activity/promos/new
用途：建立新的優惠活動
權限：promo:write
多站點：siteCode 從列表頁帶入
API：POST /admin/promos/create

操作流程

填寫活動基本資訊：
- 多語系標題
- 多語系簡介
- 活動標籤
- 開始/結束日期
- 狀態（啟用/停用）
上傳活動圖片：
- PC 版圖片（zh-TW / en-US）
- 行動版圖片（zh-TW / en-US）
設定領取條件：
- 存款門檻 (deposit_threshold)
- VIP 等級要求 (vip_level)
- 首次存款 (first_deposit)
使用 Tiptap 富文本編輯器撰寫活動內容（多語系）
設定打碼量倍率 (turnover multiplier)
提交建立

4.5.3 編輯活動

路由：/activity/promos/[id]
用途：修改現有活動內容
權限：promo:write
多站點：詳情頁，已由列表頁帶入 siteCode
API：GET /admin/promos/:id、PATCH /admin/promos/:id

4.5.4 活動標籤

路由：/activity/tags
用途：管理活動的分類標籤
權限：promo-tag:read / promo-tag:write
多站點：是（模式 A）
API：GET /admin/promo-tags/list、POST /admin/promo-tags、PATCH /admin/promo-tags/:id、DELETE /admin/promo-tags/:id

操作流程

SiteTabs 切換站點
顯示標籤列表
每個標籤含多語系名稱
支援新增、編輯、刪除

4.6 郵件管理

4.6.1 站內信管理

路由：/mail/inbox
用途：管理員發送站內信給前台用戶
權限：admin:read / admin:write
多站點：是（模式 A）
API：POST /admin/inbox/send

操作流程

SiteTabs 切換站點
顯示已發送的站內信列表
支援發送新站內信：
- 選擇收件對象（全體用戶 / 特定用戶 / VIP 等級）
- 多語系標題
- 多語系內容（HTML）
查看發送紀錄

4.6.2 郵件設定

路由：/mail/settings
用途：管理自動通知的觸發條件與模板
權限：admin:read / admin:write
多站點：是（模式 B）
API：GET /admin/inbox/settings

操作流程

SiteTabs 切換站點
設定各類自動通知的開關
設定通知模板
支援「同預設站點」複製

4.7 財務管理

4.7.1 人工調節金額

路由：/finance/adjust-balance
用途：手動調整用戶帳戶餘額
權限：finance:write
多站點：是（模式 A）
API：POST /admin/finance/adjust-balance

操作流程

SiteTabs 切換站點
搜尋目標用戶
輸入調整金額（正值增加，負值扣減）
輸入備註說明
確認操作（二次確認對話框）

篩選條件

關鍵字搜尋（帶 siteCode）

4.7.2 存款設置

路由：/finance/deposit-settings
用途：管理金流群組與金流通道的配置
權限：vendor:read / vendor:write
多站點：是（模式 A）

操作流程

SiteTabs 切換站點
管理金流群組（Vendor Groups）
管理金流通道（Vendor Channels）
配置群組與通道的關聯

4.7.3 存款訂單審核

路由：/finance/deposit-review
用途：審核存款訂單
權限：deposit:read / deposit:write
多站點：是（模式 A）
API：GET /admin/finance/deposit-review/list、POST /admin/finance/deposit-review/:id

操作流程

SiteTabs 切換站點
FilterBar 篩選訂單
SimpleTable 顯示訂單列表
每列顯示：訂單 ID、用戶、金額、支付方式、狀態、建立時間
操作：核准 / 拒絕

篩選條件

訂單 ID
用戶 ID
關鍵字
支付方式
訂單狀態
開始日期 / 結束日期

4.7.4 提款訂單管理

路由：/finance/withdrawals
用途：審核與管理提款訂單
權限：withdrawal:read / withdrawal:write
多站點：是（模式 A）
API：GET /admin/finance/withdrawals/list、POST /admin/finance/withdrawals/:id/review、POST /admin/finance/withdrawals/:id/complete

操作流程

SiteTabs 切換站點
FilterBar 篩選訂單
SimpleTable 顯示訂單列表
操作流程（三階段）：
- 待審核 → 核准 / 拒絕
- 已核准 → 上傳匯款憑證 → 標記完成
- 已拒絕 → 凍結金額自動退回

篩選條件

訂單 ID
訂單狀態
用戶 ID
關鍵字
區塊鏈網路 (network)
開始日期 / 結束日期

4.7.5 銀行卡管理

路由：/finance/bank-cards
用途：管理用戶綁定的銀行卡
權限：finance:read / finance:write
多站點：是（模式 A）
API：GET /admin/finance/bank-cards/list

操作流程

SiteTabs 切換站點
FilterBar 篩選
顯示銀行卡列表
操作：審核（核准/拒絕）、查看詳情

篩選條件

關鍵字
用戶 ID
審核狀態
銀行代碼
持卡人
開始日期 / 結束日期

4.7.6 信用卡管理

路由：/finance/credit-cards
用途：管理用戶綁定的信用卡
權限：finance:read / finance:write
多站點：是（模式 A）
API：GET /admin/finance/credit-cards/list

篩選條件

關鍵字
用戶 ID
審核狀態
持卡人
開始日期 / 結束日期

4.7.7 加密錢包管理

路由：/finance/crypto-addresses
用途：管理用戶綁定的加密錢包地址
權限：finance:read / finance:write
多站點：是（模式 A）
API：GET /admin/finance/crypto-addresses/list

篩選條件

關鍵字
用戶 ID
審核狀態
區塊鏈網路 (network)
幣種 (currency)
開始日期 / 結束日期

4.8 遊戲管理

4.8.1 遊戲供應商管理

路由：/game/providers
用途：管理各站點的遊戲供應商配置
權限：game:read / game:write
多站點：是（模式 A + 同預設站點 + 帶入模板）
API：GET /game/admin/providers、POST /game/admin/providers、PATCH /game/admin/providers/:id、DELETE /game/admin/providers/:id、POST /game/admin/copy-site-data、GET /game/admin/preview-template、POST /game/admin/load-template

操作流程

SiteTabs 切換站點
顯示該站點的遊戲供應商列表
每列顯示：ID、供應商名稱、供應商代碼 (providerCode)、遊戲類型、狀態、排序
操作：新增、編輯、刪除
特殊功能：
- 同預設站點：將預設站的遊戲商配置複製到目標站（後端 API，transaction 內先刪後插）
- 帶入模板：預覽預設模板 → 可編輯 → 確認帶入（只影響當前站點）

4.8.2 遊戲類型設定

路由：/game/type-configs
用途：管理各站點的遊戲分類配置
權限：game:read / game:write
多站點：是（模式 A + 同預設站點 + 帶入模板）
API：GET /game/admin/type-configs、POST /game/admin/type-configs、PATCH /game/admin/type-configs/:id、DELETE /game/admin/type-configs/:id

操作流程

SiteTabs 切換站點
顯示遊戲分類列表
每列顯示：遊戲類型、多語系名稱、圖示、排序、狀態
操作同遊戲供應商管理

4.9 VIP 管理

4.9.1 VIP 等級設定

路由：/vip/levels
用途：管理各站點的 VIP 等級配置
權限：vip:read / vip:write
多站點：是（模式 A + 同預設站點 + 帶入模板）
API：GET /vip/admin/levels、POST /vip/admin/levels、PATCH /vip/admin/levels/:id、DELETE /vip/admin/levels/:id、POST /vip/admin/copy-site-data

操作流程

SiteTabs 切換站點
顯示 VIP 等級列表
每列顯示：等級、多語系名稱、升級門檻 (minChip)、保級門檻 (relegationChip)、保級鎖定 (vipHold)、狀態
操作：新增、編輯、刪除
特殊功能：同預設站點、帶入模板

重要欄位

欄位	說明
level	VIP 等級數字
name	多語系等級名稱
minChip	升級所需最低有效投注（USD）
relegationChip	月度保級所需投注
vipHold	保級鎖定（VIP 5+ 可手動啟用）
enabled	啟用/停用

4.9.2 返水設定

路由：/vip/rebates
用途：管理 VIP 返水規則（按遊戲類型 x VIP 等級配置）
權限：vip:read / vip:write
多站點：是（模式 A + 同預設站點 + 帶入模板）
API：POST /vip/admin/rebates/bulk

操作流程

SiteTabs 切換站點
8 個遊戲類型標籤頁（Sports / Slot / Live / Lottery / Chess / Esports / Crypto / Fish）
每個標籤頁顯示 N 個 VIP 等級的返水比例
行內編輯（inline editing）：直接修改返水百分比
修改後的列以琥珀色 (amber) 高亮標記（dirty rows）
點擊「全部儲存」按鈕一次提交所有變更

互動特色

表格形式：行 = VIP 等級，列 = 返水比例
即時編輯，無需開啟彈窗
批量更新（Bulk Upsert），一次儲存所有變更
Unique key: (siteCode, level, gameType)

4.9.3 VIP 玩家列表

路由：/vip/players
用途：查看 VIP 玩家的統計資訊
權限：vip:read
多站點：是（模式 A）
API：GET /admin/reports/vip-players

操作流程

SiteTabs 切換站點
顯示 VIP 玩家列表
每列顯示：帳號、VIP 等級、累計投注、餘額

4.9.4 VIP 里程碑

路由：/vip/milestones
用途：管理 VIP 里程碑獎勵設定
權限：vip:read / vip:write
多站點：是（模式 A）

4.10 報表管理

4.10.1 總覽報表

路由：/reports/overview
用途：展示平台整體營運數據
權限：report:read
多站點：是（模式 A，使用 useMultiSiteTabs）
API：GET /admin/reports/overview

操作流程

SiteTabs 切換站點
頂部統計卡片：
- 新註冊人數
- 存款總額
- 提款總額
- 投注總額
- 毛利
每日摘要表格：
- 每列 = 一天的統計數據
- 欄位包含各項指標

篩選條件

開始日期
結束日期

4.10.2 玩家報表

路由：/reports/players
用途：按玩家維度的統計報表
權限：report:read
多站點：是（模式 A，使用 useMultiSiteTabs）
API：GET /admin/reports/players

篩選條件

關鍵字（帳號、暱稱）
VIP 等級（select 下拉，0-15）
開始日期 / 結束日期

4.10.3 玩家摘要

路由：/reports/player-summary
用途：玩家綜合摘要報表
權限：report:read
多站點：是（模式 A，使用 useMultiSiteTabs）
API：GET /admin/reports/player-summary

篩選條件

關鍵字
VIP 等級（select 下拉）
排序方式（select）
排序方向（asc / desc）
開始日期 / 結束日期

4.10.4 遊戲報表

路由：/reports/games
用途：按遊戲維度的統計報表
權限：report:read
多站點：是（模式 A，使用 useMultiSiteTabs）
API：GET /admin/reports/games

篩選條件

遊戲類型（select 下拉）
遊戲平台（select 下拉）
開始日期 / 結束日期

4.10.5 投注紀錄報表

路由：/reports/bet-records
用途：查詢所有用戶的投注紀錄
權限：report:read
多站點：是（模式 A，使用 useMultiSiteTabs）
API：GET /admin/reports/bet-records

篩選條件

關鍵字
遊戲類型
遊戲平台
投注狀態
開始日期 / 結束日期

4.10.6 損益報表

路由：/reports/profit-loss
用途：按時間維度的損益分析
權限：report:read
多站點：是（模式 A，使用 useMultiSiteTabs）
API：GET /admin/reports/profit-loss

篩選條件

分組方式（日 / 週 / 月）
遊戲類型
開始日期 / 結束日期

4.10.7 活動報表

路由：/reports/promos
用途：活動領取與成效統計
權限：report:read
多站點：否（待加入）
API：GET /admin/reports/promos

篩選條件

開始日期
結束日期

4.11 風控管理

4.11.1 IP 黑白名單

路由：/risk-control/ip-rules
用途：管理 IP 黑名單與白名單規則
權限：risk:read / risk:write
多站點：是（模式 A）
API：GET /admin/risk/ip-rules、POST /admin/risk/ip-rules、PATCH /admin/risk/ip-rules/:id、DELETE /admin/risk/ip-rules/:id

操作流程

SiteTabs 切換站點
FilterBar 篩選
顯示 IP 規則列表
每列顯示：IP、類型（黑名單/白名單）、備註、建立時間
操作：新增、編輯、刪除

篩選條件

類型（黑名單 / 白名單）
IP 關鍵字
開始日期 / 結束日期

4.11.2 IP/裝置指紋查詢

路由：/risk-control/ip-check
用途：透過 IP 或裝置指紋反查關聯用戶
權限：risk:read
多站點：是（模式 A）
API：GET /admin/risk/lookup

操作流程

SiteTabs 切換站點
輸入查詢關鍵字
系統回傳關聯用戶列表
可檢視同 IP / 同裝置的所有帳號

篩選條件

關鍵字（支援 IP / 裝置指紋 / 帳號 / 姓名 / Email / 手機）

4.11.3 遊戲黑名單

路由：/risk-control/game-blacklist
用途：封鎖特定用戶進入遊戲
權限：risk:read / risk:write
多站點：是（模式 A）
API：GET /admin/risk/game-blacklist、POST /admin/risk/game-blacklist、PATCH /admin/risk/game-blacklist/:id、DELETE /admin/risk/game-blacklist/:id

操作流程

SiteTabs 切換站點
顯示遊戲黑名單列表
新增封鎖規則：
- 選擇用戶
- 選擇封鎖範圍：
  - 全封鎖：gameType=null, productId=null
  - 類型封鎖：gameType='slot', productId=null
  - 特定遊戲封鎖：gameType='slot', productId=123

篩選條件

用戶 ID
用戶帳號
遊戲類型
開始日期 / 結束日期

4.12 代理中心

4.12.1 代理列表

路由：/affiliate/agents
用途：管理所有代理
權限：affiliate:read / affiliate:write
多站點：是（模式 A）
API：GET /affiliate/admin/agents、POST /affiliate/admin/create-agent、POST /affiliate/admin/bind

操作流程

SiteTabs 切換站點
顯示代理列表
每列顯示：帳號、代理碼、代理等級、下線數、累計佣金
操作：
- 新增代理（手動綁定用戶為代理）
- 手動綁定上下線關係
- 設定代理等級

4.12.2 佣金費率

路由：/affiliate/commission-rates
用途：管理代理佣金費率矩陣
權限：affiliate:read / affiliate:write
多站點：是（模式 A）
API：GET /affiliate/admin/commission-rates、POST /affiliate/admin/commission-rates、DELETE /affiliate/admin/commission-rates

操作流程

SiteTabs 切換站點
顯示佣金費率矩陣：代理等級 (4) x 代理層級 (3) x 遊戲類型 (8)
模板預設：4 等級 x 3 級別 x 8 遊戲類型 = 96 筆費率

4.12.3 佣金結算

路由：/affiliate/settlements
用途：管理佣金結算紀錄與審核
權限：affiliate:read / affiliate:write
多站點：是（模式 A）
API：GET /affiliate/admin/settlements、POST /affiliate/admin/settlements/:id/review、GET /affiliate/admin/settlements/:id/risk-logs

操作流程

SiteTabs 切換站點
顯示結算紀錄列表
每列顯示：代理帳號、結算期間、佣金金額、風控狀態、審核狀態
操作：
- 審核（核准 / 拒絕）
- 查看風控紀錄（該結算的風控檢測結果）
手動觸發結算：
- 觸發週結：POST /affiliate/admin/trigger-settlement
- 觸發日結：POST /affiliate/admin/trigger-daily-settlement

4.12.4 代理提款

路由：/affiliate/aff-withdrawals
用途：管理代理的提款申請
權限：affiliate:read / affiliate:write
多站點：是（模式 A）
API：GET /affiliate/admin/withdrawals、POST /affiliate/admin/withdrawals/:id/review、POST /affiliate/admin/withdrawals/:id/complete

操作流程

SiteTabs 切換站點
顯示代理提款列表
三階段審核流程：
- 待審核 → 核准 / 拒絕
- 已核准 → 標記完成
每列顯示：代理帳號、提款金額、提款方式、狀態、申請時間

4.12.5 綁定紀錄

路由：/affiliate/bind-logs
用途：查看代理與下線的綁定/解綁歷史紀錄
權限：affiliate:read
多站點：是（模式 A）
API：GET /affiliate/admin/bind-logs

篩選條件

動作類型（綁定/解綁）
推廣碼
日期範圍

4.12.6 代理等級

路由：/affiliate/agent-tiers
用途：管理代理等級配置
權限：affiliate:read / affiliate:write
多站點：是（模式 A）
API：GET /affiliate/admin/agent-tiers、POST /affiliate/admin/agent-tiers、DELETE /affiliate/admin/agent-tiers

代理等級列表

等級代碼	名稱
bronze	銅牌
silver	銀牌
gold	金牌
platinum	白金

4.12.7 VIP 里程碑

路由：/affiliate/vip-milestones
用途：管理下線 VIP 等級達標時的獎勵規則
權限：affiliate:read / affiliate:write
多站點：是（模式 A）
API：GET /affiliate/admin/vip-milestones、POST /affiliate/admin/vip-milestones、DELETE /affiliate/admin/vip-milestones

操作流程

SiteTabs 切換站點
設定各 VIP 等級的獎勵金額
當下線用戶達到指定 VIP 等級時，自動發放獎勵給代理

4.12.8 代理導覽

路由：/affiliate/agent-tour
用途：管理代理新手導覽內容
權限：affiliate:read / affiliate:write
多站點：是（模式 B — 設定頁）

操作流程

SiteTabs 切換站點
編輯導覽步驟的多語系內容
設定導覽流程圖片與說明

4.13 用戶管理

4.13.1 用戶列表

路由：/users
用途：前台用戶管理（與玩家管理部分重疊）
權限：user:read

4.13.2 新增用戶

路由：/users/new
用途：手動建立前台用戶帳號
權限：user:write

4.13.3 編輯用戶

路由：/users/[id]
用途：編輯前台用戶資訊
權限：user:write

4.13.4 角色管理

路由：/roles
用途：重導向至 /system/groups
說明：此為轉址頁面，不含獨立功能

4.14 後台共用元件

佈局元件 (Layout)

元件	說明
sidebar	側邊欄導航（14+ 群組、50+ 項目，含 Feature Flag + RBAC 檢查）
header	頂部導航列（含 SiteSelector 站點切換下拉選單）
providers	Context Providers（SessionProvider / QueryClientProvider / ThemeProvider 等）
AdminContentWrapper	包裹管理頁面，`key={selectedSiteCode}` 強制 remount 以刷新資料
SiteFilterInitializer	啟動時拉取站點列表，填入 siteFilterStore
SiteSelector	Header 站點切換下拉選單（「全部站點」或選擇單站）
localeGuard	檢查當前語系是否在站點 supportedLocales 內
scrollToTop	路由變更時自動捲至頂部
google-auth-dialog	Google Authenticator 2FA 設定對話框
themeInjector	注入站點主題 CSS 變數

共用元件 (Shared)

元件	說明
SiteTabs	多站點 Tab 切換元件
FilterBar	篩選列（支援 text / date / select 欄位）
SimpleTable	資料表格（含分頁、排序、自訂欄位）
pagination	通用分頁元件
StatusBadge	狀態標籤（搭配 colorMap）
confirmDialog	確認對話框（useConfirm hook）
htmlEditor	Tiptap HTML 編輯器
exportButton	CSV 匯出按鈕
loadingSpinner	載入中動畫
accessDenied	無權限提示頁面
templatePreviewDialog	模板預覽對話框

第 5 章：業務流程圖

5.1 用戶註冊/登入流程

5.1.1 帳號註冊流程

+------------------+
|   用戶開啟前台    |
+--------+---------+
         |
         v
+------------------+
|  點擊「註冊」按鈕  |
+--------+---------+
         |
         v
+------------------+
| 顯示註冊彈窗      |
| (Register Modal) |
+--------+---------+
         |
         v
+------------------+
| 填寫註冊資訊：     |
| - 帳號 (account)  |
| - 密碼 (password) |
| - 推廣碼 (選填)   |
| - 裝置指紋        |
+--------+---------+
         |
         v
+------------------+      +------------------+
| POST /auth/      |      | 驗證失敗：        |
| register          +----->| - 帳號已存在      |
+--------+---------+      | - 推廣碼無效      |
         |                 +------------------+
         | 驗證成功
         v
+------------------+
| 後端處理：         |
| 1. 檢查帳號唯一性  |
| 2. 密碼 bcrypt 雜湊|
| 3. 建立用戶記錄    |
| 4. 依語系分配      |
|    金流群組        |
| 5. 處理推廣碼綁定  |
+--------+---------+
         |
         v
+------------------+
| 推廣碼處理：       |
| resolveRefCode() |
| 1. 查詢推廣碼     |
| 2. 找到對應代理    |
| 3. 綁定 3 層上下線 |
|    level1/2/3     |
| 4. 記錄綁定日誌    |
+--------+---------+
         |
         v
+------------------+
| 簽發 JWT Token    |
| payload:          |
| - sub: userId     |
| - account         |
| - tokenVersion    |
| 有效期: 7 天       |
+--------+---------+
         |
         v
+------------------+
| 回傳 token +      |
| 用戶資訊          |
| → 登入成功        |
+------------------+

詳細步驟說明：

帳號驗證：系統檢查同站點 (siteCode) 下帳號是否已存在。帳號唯一約束為 (siteCode, account)，不同站點可有相同帳號。
密碼處理：使用 bcryptjs 進行密碼雜湊，salt rounds 依配置決定。
用戶建立：在 auth-user 表建立新記錄，自動由 SiteCodeSubscriber 填入 siteCode。
金流群組分配：根據用戶註冊時的語系自動分配金流群組：
- zh-TW → TWD 群組
- en-US → USD 群組
- zh-CN → CNY 群組
- th-TH → THB 群組
- vi-VN → VND 群組
推廣碼綁定：若用戶註冊時帶有推廣碼 (refCode)，系統會：
- 查詢推廣碼對應的代理用戶
- 支援聯盟推廣碼的雙重查找（聯盟碼 → 主代理碼）
- 綁定三層代理結構：level1 (直屬上線)、level2 (上線的上線)、level3 (最上層)
- 記錄綁定日誌到 affiliate-bind-log
裝置指紋：前端透過 FingerprintJS v5 生成 visitorId，隨註冊請求一同送出，記錄於登入日誌。

5.1.2 帳號登入流程

用戶輸入帳號密碼
    |
    v
POST /auth/login (含 device 指紋)
    |
    v
查詢用戶 (siteCode + account)
    |
    +-- 帳號不存在 → 錯誤 2001
    |
    v
驗證密碼 (bcrypt.compare)
    |
    +-- 密碼錯誤 → 錯誤 2001，記錄登入失敗 (LOGIN_FAIL)
    |
    v
檢查帳號狀態
    |
    +-- 帳號停用 → 錯誤 2002
    |
    v
檢查 2FA (Google Authenticator)
    |
    +-- 已啟用 2FA → 要求輸入 TOTP 驗證碼
    |                  |
    |                  +-- 驗證碼錯誤 → 錯誤
    |                  |
    |                  +-- 驗證成功 ↓
    |
    v
簽發 JWT Token
    |
    v
記錄登入日誌 (auth-user-login-log)
  - IP 位址
  - 裝置指紋 / User-Agent
  - 登入時間
  - 動作: LOGIN
    |
    v
更新 lastActivityAt
    |
    v
回傳 { token, user }

5.1.3 Google OAuth 登入流程

用戶點擊「Google 登入」
    |
    v
GET /auth/google-auth-url
    → 回傳 Google OAuth 授權 URL
    |
    v
重導向至 Google 授權頁面
    |
    v
用戶授權
    |
    v
Google 回調至 /redirect/google (含 authorization code)
    |
    v
前端擷取 code
    |
    v
POST /auth/google-login { code, device }
    |
    v
後端處理：
  1. 使用 google-auth-library 驗證 code
  2. 取得 Google 用戶資訊 (email, sub, name)
  3. 查詢用戶 (siteCode + google = sub)
     |
     +-- 用戶存在 → 直接登入
     |
     +-- 用戶不存在 → 自動建立帳號
         - account: 自動生成
         - google: payload.sub
         - email: payload.email
    |
    v
若舊用戶 google 欄位為空 → 自動補綁 google
    |
    v
簽發 JWT Token → 登入成功

5.1.4 Telegram 登入流程

用戶點擊「Telegram 登入」
    |
    v
Telegram Login Widget 彈出
    |
    v
用戶授權
    |
    v
Telegram 回調至 /redirect/telegram
    |
    v
POST /auth/telegram-login { telegramId, hash, ... }
    |
    v
後端處理：
  1. 驗證 Telegram hash (HMAC-SHA256)
  2. 查詢用戶 (siteCode + telegram = telegramId)
     |
     +-- 用戶存在 → 直接登入
     +-- 用戶不存在 → 自動建立帳號
    |
    v
簽發 JWT Token → 登入成功

5.1.5 2FA (Google Authenticator) 設定流程

用戶進入個人設定
    |
    v
點擊「啟用 Google Authenticator」
    |
    v
POST /auth/google-auth/generate
    → 後端使用 speakeasy 生成 secret
    → 產生 QR Code (使用 qrcode 套件)
    → 回傳 { qrCode, secret }
    |
    v
用戶使用 Google Authenticator App 掃描 QR Code
    |
    v
用戶輸入 6 位 TOTP 驗證碼
    |
    v
POST /auth/google-auth/verify { token: '123456' }
    → 後端使用 speakeasy.totp.verify() 驗證
    |
    +-- 驗證失敗 → 提示重試
    |
    +-- 驗證成功 → 啟用 2FA，儲存 secret 到用戶記錄
    |
    v
後續登入時需輸入 TOTP 驗證碼

5.2 存款流程

用戶進入存款頁面
    |
    v
選擇支付方式：
  +-- 法幣 ATM (Fiat)
  +-- 信用卡 (Credit)
  +-- 加密貨幣 (Crypto/USDT)
    |
    v
選擇金流通道 (Vendor Channel)
    |
    v
輸入存款金額 (當地幣別)
    |
    v
GET /deposit/exchange-rate
    → 取得台灣銀行即時匯率
    → 顯示換算後 USD 金額
    |
    v
用戶確認金額
    |
    v
POST /deposit
  body: { channelId, amount, paymentMethod }
    |
    v
後端處理：
  1. 驗證用戶身份
  2. 查詢金流通道
  3. 計算 USD 金額：
     amount(本幣) / exchangeRate = USD
     truncateUsd() → 無條件捨去至 6 位小數
  4. 建立 deposit-order (status: 'pending')
  5. 路由至對應金流商：
     |
     +-- 萬通金流 (ATM)
     |   POST /vendor/wantong/add-atm
     |   → 萬通 API 回傳付款資訊 (銀行帳號等)
     |
     +-- 萬通金流 (信用卡)
     |   POST /vendor/wantong/add-card
     |   → 萬通 API 回傳信用卡付款頁 URL
     |
     +-- USDT
         → 回傳加密貨幣收款地址 + QR Code
    |
    v
前端顯示付款資訊
    |
    v
用戶在外部完成支付
    |
    v
金流商透過 S2S 回調通知後端：
  +-- POST /vendor/wantong/callback
  +-- POST /vendor/usdt/callback
    |
    v
後端處理回調：
  1. 驗證回調合法性
  2. 更新 deposit-order 狀態
     +-- 成功: status → 'paid'
     +-- 失敗: status → 'failed'
  3. 若成功：
     - 增加用戶 balance
     - 觸發 MissionService.updateDepositProgress()
     - 記錄交易日誌
    |
    v
管理員可在後台審核（若需要）
  /finance/deposit-review
  → 核准 / 拒絕
    |
    v
存款完成

幣別轉換規則：

系統內部一律使用 USD
入金時透過 tw-exchange 取得台灣銀行即時匯率
轉換公式：USD = localAmount / exchangeRate
截斷規則：Math.floor(value * 1e6) / 1e6（無條件捨去至小數 6 位）

5.3 提款流程

用戶進入提款頁面
    |
    v
系統顯示可用餘額 (balance)
    |
    v
選擇提領目的地：
  +-- 已綁定的銀行卡
  +-- 已綁定的加密錢包
    |
    v
輸入提領金額
    |
    v
POST /withdrawal/request
  body: { amount, walletType, walletId }
    |
    v
後端處理：
  1. 驗證餘額是否足夠
  2. 扣除用戶 balance
  3. 增加 frozenBalance (凍結金額)
  4. 建立 withdrawal-order (status: 'pending')
    |
    v
等待後台管理員審核
  /finance/withdrawals
    |
    +-- 拒絕 (reject)
    |   → frozenBalance 退回 balance
    |   → status: 'rejected'
    |
    +-- 核准 (approve)
        → status: 'approved'
        |
        v
    管理員匯款
        |
        v
    上傳匯款憑證
        |
        v
    標記完成 (complete)
        → frozenBalance 扣減
        → status: 'completed'
    |
    v
提款完成，用戶收到款項

三階段審核流程：

階段	狀態	操作	金額變動
1. 申請	pending	用戶提交	balance(-) → frozenBalance(+)
2. 審核	approved / rejected	管理員審核	rejected: frozenBalance(-) → balance(+)
3. 完成	completed	管理員標記	frozenBalance(-)

5.4 遊戲啟動流程

用戶在遊戲大廳點擊遊戲
    |
    v
前端發送 POST /game/launch
  body: { gameCode, productId }
    |
    v
後端處理：
  1. 驗證用戶已登入 (JwtAuthGuard)
    |
    +-- 未登入 → HTTP 401
    |
    v
  2. 查詢遊戲配置 (game-provider + game-type-config)
    |
    +-- 遊戲不存在 → 錯誤
    |
    v
  3. 風控檢查：
     AdminRiskService.isUserBlockedFromGame(userId, gameCode, productId, siteCode)
     - 查詢 risk-game-blacklist：
       a. 全封鎖：gameType=null, productId=null
       b. 類型封鎖：gameType 匹配
       c. 特定遊戲封鎖：productId 匹配
    |
    +-- 被封鎖 → 錯誤碼 5010
    |
    v
  4. 呼叫遊戲供應商 API：
    |
    +-- BetSolutions:
    |   POST BS_AUTH_URL/auth
    |   → 取得遊戲 URL
    |
    +-- RSG:
        DES 加密請求 → POST RSG_API_URL
        → DES 解密回應 → 取得遊戲 URL
    |
    v
  5. 非同步記錄遊玩紀錄：
     UPSERT game-play-log (userId, gameCode, productId, siteCode)
     → .catch(() => {}) 不阻塞主流程
    |
    v
  6. 回傳遊戲 URL
    |
    v
前端以 iframe 載入遊戲
    |
    v
用戶在遊戲中下注 / 派彩
    |
    v
遊戲供應商透過 S2S 回調通知：
  +-- POST /game/betsolutions/callback
  +-- POST /game/rsg/callback
    |
    v
後端處理 S2S 回調：
  1. 驗證回調合法性
  2. 記錄 game-transaction
  3. 更新用戶 balance (下注扣款 / 派彩加款)
  4. 記錄 bet-order / bet-detail
    |
    v
投注結算後連鎖觸發（同步）：
  a. VipService.recalculateUserVip(userId)
     → 檢查 totalEffectiveBet 是否達到下一等級 minChip
     → 若達標：自動升級（只升不降）
  b. PromoService.updatePromoTurnover(userId, betAmount, gameType)
     → 扣減活動打碼量
  c. MissionService.updateBetProgress(userId, betAmount, gameType)
     → 更新任務投注進度

5.5 VIP 升級/保級/降級流程

5.5.1 VIP 升級（即時觸發）

用戶投注結算完成
    |
    v
VipService.recalculateUserVip(userId)
    |
    v
查詢用戶累計有效投注 (totalEffectiveBet)
    |
    v
查詢用戶當前 VIP 等級 (currentLevel)
    |
    v
查詢下一等級的升級門檻 (nextLevel.minChip)
    |
    v
totalEffectiveBet >= nextLevel.minChip ?
    |
    +-- 否 → 不做任何操作
    |
    +-- 是 → 自動升級：
        1. 更新用戶 vipLevel
        2. 檢查是否可再往上升（遞迴檢查）
        3. 觸發 VIP 里程碑檢查：
           → 通知代理上線獲得里程碑獎勵
           → 記錄 alliance-vip-milestone-log

重要規則：

VIP 等級只升不降（投注觸發的升級是單向的）
降級只會透過月度保級檢查觸發
每站 VIP 等級獨立配置，等級數量可自由擴充

5.5.2 每日反水結算（Cron: 每日 00:05）

Cron 觸發 (0 5 0 * * *)
    |
    v
遍歷所有站點 (siteCode)
    |
    v
遍歷所有有效用戶
    |
    v
對每個用戶：
  1. 查詢前一天的有效投注（按 8 種遊戲類型分類）
     - Sports (1)
     - Slot (2)
     - Live (3)
     - Lottery (4)
     - Chess (5)
     - Esports (8)
     - Crypto (9)
     - Fish (10)
    |
    v
  2. 查詢用戶 VIP 等級
    |
    v
  3. 查詢該等級各遊戲類型的返水比例
     vip-rebate: unique(siteCode, level, gameType)
    |
    v
  4. 計算返水金額：
     rebateAmount = effectiveBet * rebateRate / 100
     truncateUsd(rebateAmount)
    |
    v
  5. 發放反水：
     - 增加用戶 balance
     - 記錄 vip-rebate-log
    |
    v
結算完成

5.5.3 月度保級檢查（Cron: 每月 1 號 01:00）

Cron 觸發 (0 0 1 1 * *)
    |
    v
遍歷所有站點
    |
    v
遍歷所有 VIP 等級 >= 1 的用戶
    |
    v
對每個用戶：
  1. 查詢當月有效投注 (monthlyEffectiveBet)
  2. 查詢當前 VIP 等級的保級門檻 (relegationChip)
    |
    v
  monthlyEffectiveBet >= relegationChip ?
    |
    +-- 是 (達標)：
    |   → relegationMissCount = 0
    |   → 保級成功
    |
    +-- 否 (未達標)：
        → relegationMissCount++
        |
        v
    relegationMissCount >= 2 ?
        |
        +-- 否 → 警告，下月繼續觀察
        |
        +-- 是 → 檢查保級鎖定
            |
            v
        vipHold = 1 ?
            |
            +-- 是 → 跳過降級（VIP 5+ 手動鎖定）
            |
            +-- 否 → 降一級
                → vipLevel--
                → relegationMissCount = 0

5.6 代理推廣流程

5.6.1 代理申請與推廣

用戶申請成為代理
    |
    v
POST /affiliate/apply-agent
    |
    v
系統為用戶生成代理碼 (agentCode)
    |
    v
代理可建立推廣碼（最多 10 個）
  POST /affiliate/referral-codes
  → 建立 alliance-referral-code 記錄
  → 支援聯盟碼到主代理碼的雙重查找
    |
    v
代理分享推廣連結
  https://example.com?ref=ABC123
    |
    v
潛在用戶點擊連結
  → POST /affiliate/track-click
  → 記錄 affiliate-click (IP, refCode, timestamp)
    |
    v
用戶註冊時帶入 refCode
  → resolveRefCode()
  → 綁定 3 層代理關係 (level1/2/3)
  → 記錄 affiliate-bind-log

5.6.2 佣金結算流程

每週一 03:00 觸發週結 (Cron: 0 0 3 * * 1)
  或
每日 03:30 觸發日結 (Cron: 0 30 3 * * *)
    |
    v
遍歷所有站點
    |
    v
遍歷所有代理
    |
    v
對每個代理：
  1. 查詢結算期間內下線的有效投注
  2. 按 3 層級別分別計算佣金：
     - level1 (直屬下線)
     - level2 (下線的下線)
     - level3 (第三層下線)
  3. 根據代理等級 (tier) 查詢佣金費率
     alliance-commission-rate: (agentTier, agentLevel, gameType)
  4. 計算佣金 = effectiveBet * commissionRate
    |
    v
風控檢測 (AffiliateRiskService)
  → 檢查異常下線行為
  → 記錄 affiliate-risk-log
    |
    v
建立結算記錄 (affiliate-settlement)
  unique(siteCode, agentId, weekStart)
  status: 'pending'
    |
    v
等待管理員審核
  /affiliate/settlements
    |
    +-- 核准 (approve)
    |   → 佣金入帳 affiliate-balance
    |   → status: 'approved'
    |
    +-- 拒絕 (reject)
        → status: 'rejected'

5.6.3 代理提款流程

代理查看佣金餘額
  GET /affiliate/balance
    |
    v
申請提款
  POST /affiliate/request-withdrawal
  body: { amount, method }
    |
    v
建立 affiliate-withdrawal (status: 'pending')
  → 扣減 affiliate-balance
    |
    v
等待管理員審核
  /affiliate/aff-withdrawals
    |
    +-- 拒絕 → 退回餘額, status: 'rejected'
    |
    +-- 核准 → status: 'approved'
        |
        v
    管理員匯款並標記完成
        → status: 'completed'

5.7 任務系統流程

管理員建立任務 (mission)
  - category: daily_deposit / weekly_bet / monthly_challenge
  - periodType: daily / weekly / monthly
  - tier: 任務層級
  - target: 目標值
  - reward: 獎勵金額
  - unique(siteCode, category, periodType, tier)
    |
    v
用戶在平台進行操作：
    |
    +-- 存款確認 → MissionService.updateDepositProgress()
    |   → 更新 mission-progress 的 currentValue
    |   → unique(siteCode, userId, periodType, periodKey)
    |
    +-- 投注結算 → MissionService.updateBetProgress()
        → 更新 mission-progress 的 currentValue
    |
    v
用戶查看任務列表
  GET /mission/list + GET /mission/progress
    |
    v
任務進度 currentValue >= target ?
    |
    +-- 否 → 顯示進度條
    |
    +-- 是 → 領取按鈕啟用
        |
        v
    用戶點擊領取
      POST /mission/:id/claim
        |
        v
    後端處理：
      1. 驗證任務進度達標
      2. 檢查是否已領取 (mission-claim unique)
      3. 發放獎勵至用戶 balance
      4. 建立 mission-claim 記錄
         unique(siteCode, missionId, userId, periodKey)

5.8 活動領取流程

管理員建立活動 (promo)
  - 多語系標題、內容
  - 條件：deposit_threshold / vip_level / first_deposit
  - 打碼量倍率 (turnoverMultiplier)
  - 獎勵金額
  - 有效期間
    |
    v
用戶瀏覽活動列表
  GET /promo/list
    |
    v
用戶進入活動詳情
  GET /promo/:id
    |
    v
用戶點擊「領取」
  POST /promo/:id/claim
    |
    v
後端處理：
  1. 檢查活動是否在有效期間內
  2. 檢查活動狀態是否為啟用
  3. 檢查用戶是否已領取
     promo-claim unique(siteCode, promoId, userId)
  4. 檢查領取條件：
     +-- deposit_threshold: 用戶累計存款是否達標
     +-- vip_level: 用戶 VIP 等級是否達標
     +-- first_deposit: 是否為首次存款
    |
    +-- 條件不符 → 錯誤訊息
    |
    +-- 條件符合：
        1. 建立 promo-claim 記錄
        2. 發放獎勵至用戶 balance
        3. 設定打碼量要求：
           remainingTurnover = reward * turnoverMultiplier
        4. 後續投注會扣減 remainingTurnover
           (PromoService.updatePromoTurnover)

第 6 章：多站點架構

6.1 白牌架構概念

C9 平台採用白牌 (White-Label) 架構設計，核心理念是：一套程式碼，多個品牌。

每個「站點」(Site) 代表一個獨立的娛樂城品牌，擁有：

獨立的品牌視覺（Logo、主題色、吉祥物）
獨立的遊戲配置（可選擇啟用哪些遊戲商與遊戲分類）
獨立的 VIP 體系（等級數量、升級門檻、返水比例皆可不同）
獨立的金流通道
獨立的代理推廣體系
獨立的用戶帳號系統（同帳號可在不同站點各自註冊）
獨立的風控規則
獨立的客服配置

6.2 站點隔離機制

siteCode 欄位

站點隔離的核心是 siteCode 欄位。在 49 張資料表中，有 37 張包含 siteCode 欄位，確保資料按站點隔離。

@Column({ type: 'varchar', length: 30, default: 'C9', comment: '所屬站點代碼' })
@Index()
siteCode: string;

SiteCodeSubscriber

TypeORM Entity Subscriber，在 Entity 插入 (beforeInsert) 時自動填入 siteCode：

檢查 Entity metadata 是否有 siteCode 欄位
若有且未手動設定，自動填入環境變數 SITE_CODE（預設 'C9'）
若已手動設定（例如透過 @AdminSiteCode() 帶入），則不覆寫

不含 siteCode 的資料表 (12 張)

以下資料表為全站共用，不區分站點：

資料表	原因
admin-user	管理員帳號全站共用
admin-group	權限群組全站共用
admin-operation-log	操作紀錄全站共用
r2-operation-log	R2 操作紀錄全站共用
vendor-group-channel	群組-通道關聯（中間表）
alliance-commission-rate	佣金費率全站共用
alliance-agent-tier	代理等級全站共用
alliance-vip-milestone	VIP 里程碑全站共用
site-config	站點設定表（自身就是站點定義）
site-theme	站點主題（透過 siteConfigId 關聯）

6.3 前端站點解析

前台 (c9-ec)

前台透過 useConfig.ts 中的 domainConfig 物件，根據當前瀏覽器的 hostname 判斷站點：

hostname → domainConfig[hostname] → { siteId, siteCode, apiBaseUrl, siteName }

前端自動在 HTTP 請求中注入 site-name header，供後端識別站點。

後台 (c9-ims)

後台的站點切換透過 Header 的 SiteSelector 下拉選單操作：

SiteFilterInitializer：App 啟動時拉取 /site-config/admin/list，取得所有站點列表，填入 siteFilterStore
SiteSelector：Header 中的站點切換下拉選單，提供「全部站點」或選擇單一站點
AdminContentWrapper：以 key={selectedSiteCode} 包裹管理頁面，站點切換時強制 remount，確保所有子頁面重新載入資料
TanStack Query Cache 清除：切換站點時自動清除 TanStack Query 快取

6.4 siteCode 傳遞機制

前台 API

場景	Header	說明
前台用戶操作	`site-name: C9`	自動由 domainConfig 設定

後端透過 @SiteName() decorator 讀取。

後台 Admin API

場景	Header 選擇	API Client 行為	前端處理
全部站點 + Tab	selectedSiteCode = null	不帶 x-site-code	手動傳 siteCode query param
獨立站點	selectedSiteCode = "C9"	自動帶 x-site-code: C9	Tab 僅顯示一個站

後端透過 @AdminSiteCode() decorator 讀取：

優先讀 x-site-code header
其次讀 siteCode query param
都沒有則回傳 null（代表全站）

6.5 SiteTabs 元件

SiteTabs 是多站點列表頁面的核心元件，提供站點 Tab 切換功能。

使用 useMultiSiteTabs hook（推薦）

const { visibleSites, activeSiteId, activeSiteCode, handleSiteChange }
  = useMultiSiteTabs({ onSiteChange: () => setPage(1) });

自動處理：

根據 Header SiteSelector 的選擇過濾可見站點
追蹤當前選中的 Tab
推導 activeSiteCode 用於 API 查詢
站點切換時重置分頁

已完成多站點支援的模組 (47 個頁面)

分類	頁面數	模式
財務管理	7	模式 A
遊戲管理	2	模式 A + 同預設站點 + 帶入模板
VIP 管理	4	模式 A + 同預設站點 + 帶入模板
玩家管理	4	模式 A
活動管理	2	模式 A
報表	6	模式 A
風控管理	3	模式 A
代理中心	8	模式 A / 模式 B
站內信	2	模式 A / 模式 B
系統管理	2	模式 A
站點設定	5	模式 B
佈局配置	3	模式 B

6.6 「同預設站點」功能

提供兩種「從預設站點複製」的模式：

模式 1：前端狀態拷貝

適用 5 個站點設定頁面（三方登入、遊戲商配置、服務商配置、客服配置、域名設置）。

深拷貝預設站的表單資料到目標站
用戶需手動確認並儲存
不直接寫入資料庫

模式 2：後端 API 直接複製

適用遊戲管理、VIP 等 CRUD 列表頁面。

呼叫後端 API：POST /xxx/admin/copy-site-data
參數：{ sourceSiteCode, targetSiteCode, type }
後端在 transaction 內先刪後插
立即生效，自動刷新頁面資料

6.7 模板系統

遊戲管理與 VIP 管理支援「帶入模板」功能：

預覽：GET /xxx/admin/preview-template → 回傳預設模板資料
編輯：前端顯示 templatePreviewDialog，用戶可修改模板內容
確認：POST /xxx/admin/load-template → atomic transaction 寫入資料庫
模板只影響當前站點（由 @AdminSiteCode() 決定寫入站點）

第 7 章：多語系支援

7.1 支援語系總覽

語系代碼	語言	前台 (c9-ec)	後台 (c9-ims)	後端 (c9-be)	幣別映射
zh-TW	繁體中文	Y	Y	Y	TWD (新台幣)
en-US	English	Y	Y	Y	USD (美元)
zh-CN	簡體中文	Y	Y	Y	CNY (人民幣)
th-TH	ภาษาไทย	Y	Y	Y	THB (泰銖)
vi-VN	Tiếng Việt	Y	Y	Y	VND (越南盾)

7.2 各專案多語系策略

前台 (c9-ec)

項目	說明
框架	@nuxtjs/i18n
策略	no_prefix (cookie 儲存語系偏好)
URL 行為	URL 中不顯示語系前綴
切換方式	語系切換彈窗 (Locale Modal)
儲存位置	Cookie
同步	切換語系時同步更新用戶偏好到後端

後台 (c9-ims)

項目	說明
框架	next-intl v4.8
策略	no_prefix (cookie 儲存，NEXT_LOCALE)
URL 行為	URL 中不顯示語系前綴
檔案格式	扁平 key-value JSON
檔案路徑	src/messages/{locale}.json
使用方式	`const t = useTranslations("namespace")` → `t("key")`

i18n key 格式範例：

"system.admins.title": "管理員管理"
"common.save": "儲存"
"common.cancel": "取消"
"nav.dashboard": "儀表板"

後端 (c9-be)

項目	說明
框架	nestjs-i18n v10.6
預設語系	zh-TW (fallback)
解析器	HeaderResolver(['locales']) → AcceptLanguageResolver()
前端傳遞	HTTP header `locales: zh-TW`
檔案數量	5 語系 x 17 JSON 檔案 = 85 個
檔案路徑	src/i18n/{locale}/*.json

7.3 後端 i18n 檔案清單 (每語系 17 個)

檔案名稱	用途
adminError.json	後台管理錯誤碼
affiliateError.json	代理推廣錯誤碼
authError.json	認證錯誤碼
betRecordError.json	投注紀錄錯誤碼
depositError.json	存款錯誤碼
game.json	遊戲相關文字
gameError.json	遊戲錯誤碼
inboxError.json	站內信錯誤碼
liveSports.json	即時體育文字
missionError.json	任務錯誤碼
promoError.json	活動錯誤碼
ranking.json	排行榜文字
siteConfigError.json	站點設定錯誤碼
vendorError.json	金流錯誤碼
vipError.json	VIP 錯誤碼
walletError.json	錢包錯誤碼
withdrawalError.json	提領錯誤碼

7.4 多語系內容儲存

資料庫多語系欄位

資料庫中的多語系內容使用 JSON 格式儲存，欄位型別為 json：

json

{
  "zh-TW": "繁體中文內容",
  "en-US": "English content",
  "zh-CN": "简体中文内容",
  "th-TH": "เนื้อหาภาษาไทย",
  "vi-VN": "Nội dung tiếng Việt"
}

使用此格式的欄位包括：

VIP 等級名稱 (vip-level.name)
活動標題/簡介/內容 (promo.title, promo.description, promo.content)
活動標籤名稱 (promo-tag.name)
通知標題/內容 (notification.title, notification.content)
任務名稱/描述 (mission.name, mission.description)
站點名稱/介紹 (site-config.name, site-config.description)
客服管道標題 (customerServiceConfig[].label)
了解更多 FAQ (learnMoreConfig[].title, learnMoreConfig[].content)

後端解析方法

後端使用 resolveText(json) 工具函式解析多語系 JSON：

優先使用當前請求語系的文字
Fallback 到 zh-TW
再 Fallback 到 JSON 中的第一個值
最終 Fallback 到空字串

7.5 翻譯工作流程

新增翻譯 key 的規範

後台 (c9-ims)：

在 src/messages/zh-TW.json 新增 key
必須同步更新全部 5 個語系檔案：zh-TW, en-US, zh-CN, th-TH, vi-VN
使用扁平 key 格式（dot notation）："module.section.key": "翻譯內容"

後端 (c9-be)：

在 src/i18n/zh-TW/xxxError.json 新增錯誤碼
必須同步更新全部 5 個語系目錄下的對應檔案
錯誤碼 JSON 結構：{ "section": { "code": "錯誤訊息" } }

ICU 格式注意事項

後台使用 next-intl，其內部使用 ICU 訊息格式。大括號 {} 會被解析為變數佔位符：

正確："格式為 '{'變數名'}'" → 顯示 格式為 {變數名}
錯誤："格式為 {變數名}" → 會導致 IntlError: FORMATTING_ERROR

7.6 語系同步機制

前台切換語系
    |
    v
更新 Cookie (no_prefix 策略)
    |
    v
API 請求自動帶入 locales header
    |
    v
後端根據 locales header 回傳對應語系內容
    |
    v
前端更新頁面顯示

第 8 章：排程任務

8.1 排程任務總覽

#	排程名稱	Cron 表達式	執行時間	模組	服務
1	每日 VIP 反水結算	`0 5 0 * * *`	每日 00:05	VIP	VipService
2	月度 VIP 保級檢查	`0 0 1 1 * *`	每月 1 號 01:00	VIP	VipService
3	代理佣金週結	`0 0 3 * * 1`	每週一 03:00	Affiliate	AffiliateSettlementService
4	代理佣金日結	`0 30 3 * * *`	每日 03:30	Affiliate	AffiliateSettlementService
5	即時賽事快取更新	`0 /30 * * *`	每 30 分鐘	LiveSports	LiveSportsService

8.2 每日 VIP 反水結算

基本資訊

項目	說明
Cron	`0 5 0 * * *`
執行時間	每日 00:05
服務	VipService
影響資料表	vip-rebate-log, auth-user

詳細流程

遍歷所有站點：逐一處理每個站點的反水結算
查詢前日有效投注：
- 時間範圍：前一天 00:00:00 ~ 23:59:59
- 按用戶 x 遊戲類型 (8 種) 彙總有效投注金額
查詢返水規則：
- 根據用戶 VIP 等級查詢 vip-rebate 表
- unique key: (siteCode, level, gameType)
- 每個等級的每種遊戲類型可有不同的返水比例

計算返水金額：

rebateAmount = effectiveBet * rebateRate / 100
rebateAmount = truncateUsd(rebateAmount)  // 無條件捨去至 6 位小數

發放反水：
- 增加用戶 balance
- 建立 vip-rebate-log 記錄

注意事項

每站獨立計算，VIP 等級與返水規則按站點配置
8 種遊戲類型各自計算：Sports, Slot, Live, Lottery, Chess, Esports, Crypto, Fish
返水金額使用 USD 無條件捨去規則

8.3 月度 VIP 保級檢查

基本資訊

項目	說明
Cron	`0 0 1 1 * *`
執行時間	每月 1 號 01:00
服務	VipService
影響資料表	auth-user

詳細流程

遍歷所有站點
遍歷所有 VIP >= 1 的用戶
查詢當月有效投注：
- 彙總用戶當月所有有效投注 (totalEffectiveBet)
與保級門檻比較：
- 查詢用戶當前 VIP 等級的 relegationChip
判定結果：
- 達標：relegationMissCount = 0
- 未達標：relegationMissCount++
- 連續 2 月未達標：relegationMissCount >= 2 → 降一級
- 保級鎖定：vipHold = 1 → 跳過降級（VIP 5+ 手動鎖定功能）

保級規則表

條件	動作
月投注 >= relegationChip	保級成功，missCount 歸零
月投注 < relegationChip，missCount < 2	警告，missCount+1
月投注 < relegationChip，missCount >= 2，vipHold=0	降一級
月投注 < relegationChip，missCount >= 2，vipHold=1	跳過降級

8.4 代理佣金週結

基本資訊

項目	說明
Cron	`0 0 3 * * 1`
執行時間	每週一 03:00
服務	AffiliateSettlementService
影響資料表	affiliate-settlement, affiliate-balance, affiliate-commission, affiliate-risk-log

詳細流程

遍歷所有站點
計算結算期間：上週一 00:00 ~ 上週日 23:59
遍歷所有代理
彙總下線有效投注：
- 按 3 層級別 (level1/2/3) 分別計算
- 按 8 種遊戲類型分類
查詢佣金費率：
- 根據代理等級 (tier) 查詢 alliance-commission-rate
- unique: (agentTier, agentLevel, gameType)

計算佣金：

commission = effectiveBet * commissionRate

風控檢測：
- AffiliateRiskService 檢查異常行為
- 記錄 affiliate-risk-log
建立結算記錄：
- affiliate-settlement (status: 'pending')
- unique: (siteCode, agentId, weekStart)
等待管理員審核

佣金費率矩陣

維度	選項
代理等級 (tier)	bronze / silver / gold / platinum (4 級)
代理層級 (level)	level1 / level2 / level3 (3 層)
遊戲類型 (gameType)	8 種
合計	4 x 3 x 8 = 96 筆費率

8.5 代理佣金日結

基本資訊

項目	說明
Cron	`0 30 3 * * *`
執行時間	每日 03:30
服務	AffiliateSettlementService
影響資料表	同週結

說明

日結為週結的替代結算方式，流程與週結相同，但結算期間為前一天。管理員可在後台手動觸發結算。

8.6 即時賽事快取更新

基本資訊

項目	說明
Cron	`0 /30 * * *`
執行時間	每 30 分鐘
服務	LiveSportsService
快取	Redis

詳細流程

呼叫 API-Football 外部 API 取得最新賽事資料
解析回應資料（比賽隊伍、比分、狀態、開賽時間等）
將結果存入 Redis 快取
前台透過 GET /live-sports/matches 從快取讀取
快取 TTL 隨 Cron 週期自動更新

第 9 章：API 端點總覽

9.1 端點統計

模組	端點數	路徑前綴
Auth (認證)	17	/api/auth
Game (遊戲)	17	/api/game
Wallet (錢包)	9	/api/wallet
Vendor (金流)	9	/api/vendor
Deposit (存款)	4	/api/deposit
Withdrawal (提領)	7	/api/withdrawal
Promo (活動)	7	/api/promo
VIP	13	/api/vip
Affiliate (代理)	39	/api/affiliate
Inbox (站內信)	7	/api/inbox
Mission (任務)	3	/api/mission
SiteConfig (站點設定)	8	/api/site-config
Ranking (排行榜)	1	/api/ranking
BetRecord (投注紀錄)	2	/api/bet-record
LiveSports (即時賽事)	1	/api/live-sports
Common (共用)	1	/api/common
Admin (後台管理)	90+	/api/admin
合計	205+

9.2 認證模組 (Auth) — 17 個端點

#	方法	路由	認證	說明
1	POST	/auth/register	無	帳號註冊
2	POST	/auth/login	無	帳號登入
3	GET	/auth/google-auth-url	無	取得 Google OAuth URL
4	POST	/auth/google-login	無	Google OAuth 登入
5	POST	/auth/telegram-login	無	Telegram 登入
6	GET	/auth/check-account	無	檢查帳號可用性
7	GET	/auth/user-detail	JWT	取得用戶資料
8	PATCH	/auth/update-profile	JWT	更新個人資料
9	POST	/auth/avatar	JWT	上傳頭像
10	PATCH	/auth/set-password	JWT	設定密碼（OAuth 用戶首次設定）
11	PATCH	/auth/update-password	JWT	修改密碼
12	POST	/auth/send-email-verify	JWT	發送 Email 驗證碼
13	POST	/auth/verify-email	JWT	驗證 Email
14	POST	/auth/send-mobile-verify	JWT	發送手機驗證碼
15	POST	/auth/verify-mobile	JWT	驗證手機
16	POST	/auth/google-auth/*	JWT	Google Auth 2FA 操作 (generate/verify/disable)
17	POST	/auth/logout	JWT	登出

9.3 遊戲模組 (Game) — 17 個端點

#	方法	路由	認證	說明
1	GET	/game/providers	可選JWT	遊戲供應商列表
2	GET	/game/type-configs	可選JWT	遊戲分類列表
3	POST	/game/launch	JWT	啟動遊戲
4	POST	/game/demo	無	試玩遊戲
5	GET	/game/recent	JWT	近期遊玩遊戲
6	POST	/game/betsolutions/callback	無	BetSolutions S2S 回調
7	POST	/game/rsg/callback	無	RSG S2S 回調
8	GET	/game/admin/providers	AdminJWT	[Admin] 遊戲商列表
9	POST	/game/admin/providers	AdminJWT	[Admin] 新增遊戲商
10	PATCH	/game/admin/providers/:id	AdminJWT	[Admin] 更新遊戲商
11	DELETE	/game/admin/providers/:id	AdminJWT	[Admin] 刪除遊戲商
12	GET	/game/admin/type-configs	AdminJWT	[Admin] 分類列表
13	POST	/game/admin/type-configs	AdminJWT	[Admin] 新增分類
14	PATCH	/game/admin/type-configs/:id	AdminJWT	[Admin] 更新分類
15	DELETE	/game/admin/type-configs/:id	AdminJWT	[Admin] 刪除分類
16	GET	/game/admin/preview-template	AdminJWT	[Admin] 預覽模板
17	POST	/game/admin/load-template	AdminJWT	[Admin] 帶入模板

9.4 錢包模組 (Wallet) — 9 個端點

#	方法	路由	認證	說明
1	POST	/wallet/bank-card/add	JWT	新增銀行卡
2	GET	/wallet/bank-card/list	JWT	銀行卡列表
3	DELETE	/wallet/bank-card/:id	JWT	刪除銀行卡
4	POST	/wallet/credit-card/add	JWT	新增信用卡
5	GET	/wallet/credit-card/list	JWT	信用卡列表
6	DELETE	/wallet/credit-card/:id	JWT	刪除信用卡
7	POST	/wallet/crypto-address/add	JWT	新增加密錢包
8	GET	/wallet/crypto-address/list	JWT	加密錢包列表
9	DELETE	/wallet/crypto-address/:id	JWT	刪除加密錢包

9.5 金流模組 (Vendor) — 9 個端點

#	方法	路由	認證	說明
1	GET	/vendor/groups	JWT	金流群組列表
2	GET	/vendor/channels	JWT	金流通道列表
3	POST	/vendor/wantong/add-atm	JWT	萬通 ATM 入金
4	POST	/vendor/wantong/add-card	JWT	萬通信用卡入金
5	POST	/vendor/wantong/callback	無	萬通 S2S 回調
6	POST	/vendor/usdt/callback	無	USDT S2S 回調
7	GET	/vendor/admin/groups	AdminJWT	[Admin] 群組列表
8	GET	/vendor/admin/channels	AdminJWT	[Admin] 通道列表
9	POST	/vendor/admin/groups	AdminJWT	[Admin] 管理群組

9.6 存款模組 (Deposit) — 4 個端點

#	方法	路由	認證	說明
1	POST	/deposit	JWT	建立存款訂單
2	GET	/deposit/orders	JWT	存款訂單列表
3	GET	/deposit/orders/:id	JWT	存款訂單詳情
4	GET	/deposit/exchange-rate	JWT	取得即時匯率

9.7 提領模組 (Withdrawal) — 7 個端點

#	方法	路由	認證	說明
1	POST	/withdrawal/request	JWT	提領申請
2	GET	/withdrawal/orders	JWT	提領訂單列表
3	GET	/withdrawal/orders/:id	JWT	提領訂單詳情
4	GET	/withdrawal/admin/list	AdminJWT	[Admin] 提領列表
5	POST	/withdrawal/admin/:id/review	AdminJWT	[Admin] 審核
6	POST	/withdrawal/admin/:id/upload-proof	AdminJWT	[Admin] 上傳憑證
7	POST	/withdrawal/admin/:id/complete	AdminJWT	[Admin] 標記完成

#	方法	路由	認證	說明
1	GET	/promo/list	可選JWT	活動列表
2	GET	/promo/tags	無	活動標籤列表
3	GET	/promo/:id	可選JWT	活動詳情
4	POST	/promo/:id/claim	JWT	領取活動
5	POST	/admin/promos/create	AdminJWT	[Admin] 新增活動
6	PATCH	/admin/promos/:id	AdminJWT	[Admin] 更新活動
7	DELETE	/admin/promos/:id	AdminJWT	[Admin] 刪除活動

9.9 VIP 模組 — 13 個端點

#	方法	路由	認證	說明
1	GET	/vip/levels	可選JWT	VIP 等級列表
2	GET	/vip/user-status	JWT	用戶 VIP 狀態
3	GET	/vip/my-rebates	JWT	我的返水紀錄
4	GET	/vip/rebates	可選JWT	返水規則列表
5	GET	/vip/admin/levels	AdminJWT	[Admin] 等級列表
6	POST	/vip/admin/levels	AdminJWT	[Admin] 新增等級
7	PATCH	/vip/admin/levels/:id	AdminJWT	[Admin] 更新等級
8	DELETE	/vip/admin/levels/:id	AdminJWT	[Admin] 刪除等級
9	POST	/vip/admin/rebates/bulk	AdminJWT	[Admin] 返水批量更新
10	POST	/vip/admin/copy-site-data	AdminJWT	[Admin] 跨站複製
11	GET	/vip/admin/preview-template	AdminJWT	[Admin] 預覽模板
12	POST	/vip/admin/load-template	AdminJWT	[Admin] 帶入模板
13	GET	/admin/reports/vip-players	AdminJWT	[Admin] VIP 玩家報表

9.10 代理模組 (Affiliate) — 39 個端點

前台端點 (15 個)

#	方法	路由	認證	說明
1	POST	/affiliate/track-click	無	追蹤推廣點擊
2	POST	/affiliate/apply-agent	JWT	申請成為代理
3	GET	/affiliate/dashboard	JWT	代理儀表板
4	GET	/affiliate/commissions	JWT	佣金列表
5	GET	/affiliate/settlements	JWT	結算紀錄
6	GET	/affiliate/downlines	JWT	下線列表
7	GET	/affiliate/balance	JWT	代理餘額
8	POST	/affiliate/request-withdrawal	JWT	申請提款
9	GET	/affiliate/withdrawals	JWT	提款紀錄

聯盟公開端點 (6 個)

#	方法	路由	認證	說明
10	GET	/affiliate/alliance-info	無	聯盟資訊
11	GET	/affiliate/tier-info	無	代理等級資訊
12	GET	/affiliate/vip-milestones	無	VIP 里程碑
13	GET	/affiliate/referral-codes	JWT	推廣碼列表
14	POST	/affiliate/referral-codes	JWT	新增推廣碼
15	DELETE	/affiliate/referral-codes/:id	JWT	刪除推廣碼

Admin 端點 (24 個)

#	方法	路由	認證	說明
16	GET	/affiliate/admin/agents	AdminJWT	代理列表
17	POST	/affiliate/admin/create-agent	AdminJWT	新增代理
18	GET	/affiliate/admin/settlements	AdminJWT	結算列表
19	POST	/affiliate/admin/settlements/:id/review	AdminJWT	結算審核
20	GET	/affiliate/admin/settlements/:id/risk-logs	AdminJWT	風控紀錄
21	GET	/affiliate/admin/withdrawals	AdminJWT	代理提款列表
22	POST	/affiliate/admin/withdrawals/:id/review	AdminJWT	提款審核
23	POST	/affiliate/admin/withdrawals/:id/complete	AdminJWT	提款完成
24	POST	/affiliate/admin/bind	AdminJWT	手動綁定
25	GET	/affiliate/admin/bind-logs	AdminJWT	綁定紀錄
26	GET	/affiliate/admin/commission-rates	AdminJWT	佣金費率列表
27	POST	/affiliate/admin/commission-rates	AdminJWT	更新佣金費率
28	DELETE	/affiliate/admin/commission-rates	AdminJWT	刪除佣金費率
29	GET	/affiliate/admin/vip-milestones	AdminJWT	VIP 里程碑列表
30	POST	/affiliate/admin/vip-milestones	AdminJWT	更新 VIP 里程碑
31	DELETE	/affiliate/admin/vip-milestones	AdminJWT	刪除 VIP 里程碑
32	GET	/affiliate/admin/agent-tiers	AdminJWT	代理等級列表
33	POST	/affiliate/admin/agent-tiers	AdminJWT	更新代理等級
34	DELETE	/affiliate/admin/agent-tiers	AdminJWT	刪除代理等級
35	GET	/affiliate/admin/preview-template	AdminJWT	預覽模板
36	POST	/affiliate/admin/load-template	AdminJWT	帶入模板
37	POST	/affiliate/admin/set-agent-tier	AdminJWT	設定代理等級
38	POST	/affiliate/admin/trigger-settlement	AdminJWT	觸發週結
39	POST	/affiliate/admin/trigger-daily-settlement	AdminJWT	觸發日結

9.11 站內信模組 (Inbox) — 7 個端點

#	方法	路由	認證	說明
1	GET	/inbox/list	JWT	通知列表
2	GET	/inbox/:id	JWT	通知詳情
3	POST	/inbox/:id/read	JWT	標記已讀
4	DELETE	/inbox/:id	JWT	刪除通知
5	GET	/inbox/unread-count	JWT	未讀數量
6	POST	/admin/inbox/send	AdminJWT	[Admin] 發送通知
7	GET	/admin/inbox/settings	AdminJWT	[Admin] 通知設定

9.12 站點設定模組 (Site Config) — 8+12 個端點

公開端點 (2 個)

#	方法	路由	認證	說明
1	GET	/site-config/public	無	取得站點公開設定
2	GET	/site-config/theme	無	取得站點主題

Admin 端點 (12 個)

#	方法	路由	認證	說明
3	GET	/site-config/admin/list	AdminJWT	站點列表
4	POST	/site-config/admin	AdminJWT	新增站點
5	PATCH	/site-config/admin/:id	AdminJWT	更新站點
6	DELETE	/site-config/admin/:id	AdminJWT	刪除站點
7	GET	/site-config/admin/:siteConfigId/themes	AdminJWT	主題列表
8	POST	/site-config/admin/:siteConfigId/themes	AdminJWT	新增主題
9	PATCH	/site-config/admin/themes/:id	AdminJWT	更新主題
10	DELETE	/site-config/admin/themes/:id	AdminJWT	刪除主題
11	POST	/site-config/admin/:id/domain-asset	AdminJWT	上傳域名素材
12	POST	/site-config/admin/:id/customer-service-icon	AdminJWT	上傳客服圖示
13	PATCH	/site-config/admin/:siteConfigId/mascots	AdminJWT	更新吉祥物
14	GET	/site-config/admin/:siteCode/customer-service	AdminJWT	取得客服設定

9.13 其他模組

Mission (任務) — 3 個端點

#	方法	路由	認證	說明
1	GET	/mission/list	JWT	任務列表
2	GET	/mission/progress	JWT	任務進度
3	POST	/mission/:id/claim	JWT	領取任務獎勵

Ranking (排行榜) — 1 個端點

#	方法	路由	認證	說明
1	GET	/ranking/list	可選JWT	排行榜列表

BetRecord (投注紀錄) — 2 個端點

#	方法	路由	認證	說明
1	GET	/bet-record/list	JWT	投注紀錄列表
2	GET	/bet-record/:id	JWT	投注詳情

LiveSports (即時賽事) — 1 個端點

#	方法	路由	認證	說明
1	GET	/live-sports/matches	無	即時賽事列表

Common (共用) — 1 個端點

#	方法	路由	認證	說明
1	GET	/common/enums	無	共用列舉 + ERROR_CODES

9.14 後台管理模組 (Admin) — 90+ 個端點

認證管理 (4 個)

#	方法	路由	說明
1	POST	/admin/login	管理員登入
2	POST	/admin/register	管理員註冊
3	POST	/admin/send-verify-code	發送驗證碼
4	POST	/admin/verify-email	驗證 Email

個人資料 (4 個)

#	方法	路由	說明
5	GET	/admin/profile	取得個人資料
6	PATCH	/admin/profile	更新個人資料
7	POST	/admin/google-auth/generate	生成 2FA QR Code
8	POST	/admin/google-auth/verify	驗證 2FA

管理員 CRUD (5 個)

#	方法	路由	權限	說明
9	GET	/admin/list	admin:read	管理員列表
10	POST	/admin/create	admin:write	新增管理員
11	GET	/admin/:id	admin:read	取得管理員
12	PATCH	/admin/:id	admin:write	更新管理員
13	DELETE	/admin/:id	admin:write	刪除管理員

群組 CRUD (5 個)

#	方法	路由	權限	說明
14	GET	/admin/groups/list	admin-group:read	群組列表
15	POST	/admin/groups/create	admin-group:write	新增群組
16	GET	/admin/groups/:id	admin-group:read	取得群組
17	PATCH	/admin/groups/:id	admin-group:write	更新群組
18	DELETE	/admin/groups/:id	admin-group:write	刪除群組

權限 (1 個)

#	方法	路由	說明
19	GET	/admin/permissions/all	取得所有權限列表

操作紀錄 (1 個)

#	方法	路由	權限	說明
20	GET	/admin/logs/list	admin-log:read	查詢操作紀錄

財務管理 (16 個)

#	方法	路由	權限	說明
21	GET	/admin/finance/users/list	user:read	前台用戶列表
22	GET	/admin/finance/users/:id	user:read	用戶詳情
23	PATCH	/admin/finance/users/:id	user:write	更新用戶
24	POST	/admin/finance/adjust-balance	finance:write	手動調帳
25	GET	/admin/finance/deposit-review/list	deposit:read	存款訂單列表
26	POST	/admin/finance/deposit-review/:id	deposit:write	存款審核
27	GET	/admin/finance/withdrawals/list	withdrawal:read	提款列表
28	POST	/admin/finance/withdrawals/:id/review	withdrawal:write	提款審核
29	POST	/admin/finance/withdrawals/:id/complete	withdrawal:write	提款完成
30	GET	/admin/finance/bank-cards/list	finance:read	銀行卡列表
31-35	CRUD	/admin/finance/bank-cards/*	finance:write	銀行卡管理
36-40	CRUD	/admin/finance/credit-cards/*	finance:write	信用卡管理
41-45	CRUD	/admin/finance/crypto-addresses/*	finance:write	加密地址管理

風控管理 (10 個)

#	方法	路由	權限	說明
46-49	CRUD	/admin/risk/ip-rules/*	risk:read/write	IP 黑白名單
50	GET	/admin/risk/lookup	risk:read	IP/FP 反查
51	GET	/admin/risk/login-failures	risk:read	登入失敗紀錄
52-55	CRUD	/admin/risk/game-blacklist/*	risk:read/write	遊戲黑名單

報表 (10 個)

#	方法	路由	權限	說明
56	GET	/admin/reports/players	report:read	玩家報表
57	GET	/admin/reports/vip-players	report:read	VIP 玩家報表
58	GET	/admin/reports/bet-records	report:read	投注紀錄
59	GET	/admin/reports/overview	report:read	總覽報表
60	GET	/admin/reports/profit-loss	report:read	損益報表
61	GET	/admin/reports/games	report:read	遊戲報表
62	GET	/admin/reports/promos	report:read	活動報表
63	GET	/admin/reports/player-summary	report:read	玩家摘要
64	GET	/admin/reports/r2-logs	report:read	R2 日誌
65	GET	/admin/reports/export	report:read	CSV 匯出

活動管理 (8 個)

#	方法	路由	權限	說明
66	GET	/admin/promos/list	promo:read	活動列表
67	POST	/admin/promos/create	promo:write	新增活動
68	PATCH	/admin/promos/:id	promo:write	更新活動
69	DELETE	/admin/promos/:id	promo:write	刪除活動
70-73	CRUD	/admin/promo-tags/*	promo-tag:read/write	活動標籤管理

R2 檔案操作 (6 個)

#	方法	路由	說明
74	GET	/admin/r2/list	列出檔案
75	POST	/admin/r2/upload	上傳檔案
76	DELETE	/admin/r2/delete	刪除檔案
77	POST	/admin/r2/move	移動檔案
78	POST	/admin/r2/create-folder	建立資料夾
79	DELETE	/admin/r2/delete-folder	刪除資料夾

金流商管理 (9 個)

#	方法	路由	權限	說明
80-84	CRUD	/admin/vendor-groups/*	vendor:read/write	金流群組管理
85-88	CRUD	/admin/vendor-channels/*	vendor:read/write	金流通道管理
89	GET/POST	/admin/users/:userId/vendor-group	user:write	用戶金流群組分配

第 10 章：資料庫概覽

10.1 資料庫基本設定

項目	設定值
資料庫類型	MySQL
字元集	utf8mb4
時區	+08:00 (UTC+8)
ORM	TypeORM 0.3.28
自動同步	僅開發環境 (synchronize: isDev)
資料表總數	49 張
含 siteCode	37 張
不含 siteCode	12 張

10.2 資料表分類總覽

分類	資料表數	資料表列表
用戶認證	2	auth-user, auth-user-login-log
金流	3	vendor-group, vendor-channel, vendor-group-channel
存提款	2	deposit-order, withdrawal-order
錢包	3	bank-card, credit-card, crypto-address
遊戲	6	game-provider, game-type-config, game-transaction, game-play-log, bet-order, bet-detail
VIP	3	vip-level, vip-rebate, vip-rebate-log
活動	3	promo, promo-claim, promo-tag
排行	1	rank-list
代理	7	affiliate-commission, affiliate-settlement, affiliate-balance, affiliate-withdrawal, affiliate-click, affiliate-bind-log, affiliate-risk-log
聯盟	5	alliance-commission-rate, alliance-agent-tier, alliance-vip-milestone, alliance-vip-milestone-log, alliance-referral-code
站內信	2	notification, notification-read
站點	2	site-config, site-theme
任務	3	mission, mission-progress, mission-claim
風控	2	risk-ip-rule, risk-game-blacklist
後台	3	admin-user, admin-group, admin-operation-log
儲存	1	r2-operation-log

10.3 用戶認證 (2 張)

auth-user

項目	說明
用途	前台用戶帳號
siteCode	Y
主要欄位	id, siteCode, account, password, email, mobile, nickname, birthday, balance, frozenBalance, vipLevel, totalEffectiveBet, relegationMissCount, vipHold, vendorGroupId, agentCode, level1AgentId, level2AgentId, level3AgentId, google, telegram, googleAuthSecret, googleAuthEnabled, avatar, status, tokenVersion, locale, lastActivityAt, device
唯一約束	(siteCode, account), (siteCode, email), (siteCode, mobile), (siteCode, telegram), (siteCode, google), (siteCode, agentCode)

項目	說明
用途	用戶登入紀錄（含登入成功、失敗、登出）
siteCode	Y
主要欄位	id, siteCode, userId, action, ip, device, lastUse
索引	(userId, lastUse), (ip)

10.4 金流 (3 張)

vendor-group

項目	說明
用途	金流群組（按幣別/語系分組）
siteCode	Y
主要欄位	id, siteCode, name, currency, status

vendor-channel

項目	說明
用途	金流通道（具體的支付方式）
siteCode	Y
主要欄位	id, siteCode, name, providerCode, paymentMethod, minAmount, maxAmount, fee, status

vendor-group-channel

項目	說明
用途	金流群組與通道的多對多關聯表
siteCode	N（透過 groupId/channelId 關聯）
主要欄位	id, groupId, channelId
唯一約束	(groupId, channelId)

10.5 存提款 (2 張)

deposit-order

項目	說明
用途	存款訂單
siteCode	Y
主要欄位	id, siteCode, userId, channelId, amount, amountUsd, exchangeRate, paymentMethod, vendorOrderId, status, callbackData
狀態值	pending, created, paid, failed, cancelled

withdrawal-order

項目	說明
用途	提領訂單
siteCode	Y
主要欄位	id, siteCode, userId, amount, walletType, walletId, status, reviewNote, proofUrl
狀態值	pending, approved, rejected, completed

10.6 錢包 (3 張)

bank-card

項目	說明
用途	用戶綁定的銀行卡
siteCode	Y
主要欄位	id, siteCode, userId, bankCode, bankName, accountNumber, cardHolder, status

credit-card

項目	說明
用途	用戶綁定的信用卡
siteCode	Y
主要欄位	id, siteCode, userId, cardNumber, cardHolder, expiryDate, status

crypto-address

項目	說明
用途	用戶綁定的加密錢包地址
siteCode	Y
主要欄位	id, siteCode, userId, network, currency, address, status

10.7 遊戲 (6 張)

game-provider

項目	說明
用途	遊戲供應商配置
siteCode	Y
主要欄位	id, siteCode, gameCode, providerCode, name, gameType, coverImage, status, sortOrder
唯一約束	(siteCode, gameCode)

game-type-config

項目	說明
用途	遊戲分類配置
siteCode	Y
主要欄位	id, siteCode, gameType, name, icon, status, sortOrder
唯一約束	(siteCode, gameType)

game-transaction

項目	說明
用途	遊戲交易記錄（下注/派彩）
siteCode	Y
主要欄位	id, siteCode, userId, gameCode, productId, transactionType, amount, balanceBefore, balanceAfter

game-play-log

項目	說明
用途	用戶遊玩紀錄（用於「近期遊玩」功能）
siteCode	Y
主要欄位	id, siteCode, userId, gameCode, productId, lastPlayedAt
唯一約束	(siteCode, userId, gameCode, productId)

bet-order

項目	說明
用途	投注注單
siteCode	Y
主要欄位	id, siteCode, userId, gameCode, productId, gameType, betAmount, betEffective, payoutAmount, status
狀態值	valid, invalid, cancelled

bet-detail

項目	說明
用途	注單明細（投注的詳細記錄）
siteCode	Y
主要欄位	id, siteCode, betOrderId, roundId, betAmount, payoutAmount

10.8 VIP (3 張)

vip-level

項目	說明
用途	VIP 等級配置（每站獨立）
siteCode	Y
主要欄位	id, siteCode, level, name(JSON), minChip, relegationChip, upgradeBonus, monthlyBonus, birthdayBonus, vipHold, enabled, sortOrder
唯一約束	(siteCode, level)

vip-rebate

項目	說明
用途	VIP 返水規則（每站 x 每級 x 每遊戲類型）
siteCode	Y
主要欄位	id, siteCode, level, gameType, rebateRate
唯一約束	(siteCode, level, gameType)

vip-rebate-log

項目	說明
用途	VIP 反水發放紀錄
siteCode	Y
主要欄位	id, siteCode, userId, level, gameType, effectiveBet, rebateRate, rebateAmount, settleDate

10.9 活動 (3 張)

項目	說明
用途	優惠活動
siteCode	Y
主要欄位	id, siteCode, title(JSON), description(JSON), content(JSON), imgPc(JSON), imgMobile(JSON), tagId, conditions(JSON), turnoverMultiplier, reward, startDate, endDate, status

項目	說明
用途	活動領取記錄
siteCode	Y
主要欄位	id, siteCode, promoId, userId, rewardAmount, remainingTurnover
唯一約束	(siteCode, promoId, userId)

項目	說明
用途	活動分類標籤
siteCode	Y
主要欄位	id, siteCode, name(JSON), sortOrder
唯一約束	(siteCode, name)

10.10 排行 (1 張)

rank-list

項目	說明
用途	遊戲排行榜
siteCode	Y
主要欄位	id, siteCode, userId, gameCode, score, rank

10.11 代理 (7 張)

affiliate-commission

項目	說明
用途	代理佣金記錄
siteCode	Y
主要欄位	id, siteCode, agentId, memberId, level, gameType, betAmount, commissionRate, commissionAmount

affiliate-settlement

項目	說明
用途	佣金結算記錄
siteCode	Y
主要欄位	id, siteCode, agentId, weekStart, totalCommission, status, reviewNote
唯一約束	(siteCode, agentId, weekStart)
狀態值	pending, approved, rejected

affiliate-balance

項目	說明
用途	代理佣金餘額
siteCode	Y
主要欄位	id, siteCode, userId, balance, totalEarned, totalWithdrawn

affiliate-withdrawal

項目	說明
用途	代理提款記錄
siteCode	Y
主要欄位	id, siteCode, agentId, amount, method, status
狀態值	pending, approved, rejected, completed

affiliate-click

項目	說明
用途	推廣連結點擊追蹤
siteCode	Y
主要欄位	id, siteCode, refCode, ip, userAgent

affiliate-bind-log

項目	說明
用途	代理綁定/解綁紀錄
siteCode	Y
主要欄位	id, siteCode, agentId, memberId, action, refCode

affiliate-risk-log

項目	說明
用途	代理結算風控檢測紀錄
siteCode	Y
主要欄位	id, siteCode, settlementId, riskType, detail, result

10.12 聯盟 (5 張)

alliance-commission-rate

項目	說明
用途	聯盟佣金費率配置
siteCode	N（全站共用）
主要欄位	id, agentTier, agentLevel, gameType, commissionRate
唯一約束	(agentTier, agentLevel, gameType)

alliance-agent-tier

項目	說明
用途	代理等級配置
siteCode	N（全站共用）
主要欄位	id, tierCode, name(JSON), minDownlines, minMonthlyBet
唯一約束	(tierCode)

alliance-vip-milestone

項目	說明
用途	VIP 里程碑獎勵規則
siteCode	N（全站共用）
主要欄位	id, vipLevel, rewardAmount
唯一約束	(vipLevel)

alliance-vip-milestone-log

項目	說明
用途	VIP 里程碑獎勵發放紀錄
siteCode	Y
主要欄位	id, siteCode, agentId, memberId, vipLevel, rewardAmount
唯一約束	(siteCode, agentId, memberId, vipLevel)

alliance-referral-code

項目	說明
用途	聯盟推廣碼
siteCode	Y
主要欄位	id, siteCode, userId, code, parentAgentCode
唯一約束	(siteCode, code)
限制	每人最多 10 個推廣碼

10.13 站內信 (2 張)

notification

項目	說明
用途	站內信/通知
siteCode	Y
主要欄位	id, siteCode, title(JSON), content(JSON), targetType, targetId, senderId

notification-read

項目	說明
用途	通知已讀記錄
siteCode	Y
主要欄位	id, siteCode, userId, notificationId
唯一約束	(siteCode, userId, notificationId)

10.14 站點 (2 張)

site-config

項目	說明
用途	站點基本設定（站點定義表）
siteCode	N（自身就是站點定義）
主要欄位	id, siteCode, name(JSON), description(JSON), supportedLocales, activeThemeId, features(JSON), logoSmall, logoBig, favicon, customerServiceConfig(JSON), learnMoreConfig(JSON), mascots(JSON), hostname

site-theme

項目	說明
用途	站點主題色彩配置
siteCode	N（透過 siteConfigId 關聯）
主要欄位	id, siteConfigId, name, primary, accent, surface, text, border

10.15 任務 (3 張)

mission

項目	說明
用途	任務定義
siteCode	Y
主要欄位	id, siteCode, category, periodType, tier, name(JSON), description(JSON), target, reward, enabled
唯一約束	(siteCode, category, periodType, tier)

mission-progress

項目	說明
用途	用戶任務進度
siteCode	Y
主要欄位	id, siteCode, userId, periodType, periodKey, currentValue
唯一約束	(siteCode, userId, periodType, periodKey)

mission-claim

項目	說明
用途	任務獎勵領取記錄
siteCode	Y
主要欄位	id, siteCode, missionId, userId, periodKey, rewardAmount
唯一約束	(siteCode, missionId, userId, periodKey)

10.16 風控 (2 張)

risk-ip-rule

項目	說明
用途	IP 黑白名單規則
siteCode	Y
主要欄位	id, siteCode, ip, type, note
type 值	blacklist, whitelist

risk-game-blacklist

項目	說明
用途	遊戲封鎖名單
siteCode	Y
主要欄位	id, siteCode, userId, gameType, productId, note
封鎖範圍	gameType=null+productId=null (全封鎖)、gameType+productId=null (類型封鎖)、gameType+productId (特定遊戲)

10.17 後台 (3 張)

admin-user

項目	說明
用途	後台管理員帳號
siteCode	N（全站共用）
主要欄位	id, email, password, name, groupId, status, tokenVersion, googleAuthSecret, googleAuthEnabled

admin-group

項目	說明
用途	管理員權限群組
siteCode	N（全站共用）
主要欄位	id, name, groupType, permissions(JSON)
groupType 值	root, super_admin, general_admin, custom

admin-operation-log

項目	說明
用途	管理員操作紀錄
siteCode	N（全站共用）
主要欄位	id, adminId, action, target, detail, ip, userAgent

10.18 儲存 (1 張)

r2-operation-log

項目	說明
用途	Cloudflare R2 檔案操作紀錄
siteCode	N（全站共用）
主要欄位	id, adminId, action, filePath, fileSize, mimeType, ip, userAgent

第 11 章：錯誤碼體系

11.1 統一回應格式

所有 API 回應遵循統一的 JSON 格式：

成功回應

json

{
  "code": 200,
  "message": "ok",
  "result": { ... },
  "timestamp": "2026-03-01T12:00:00.000Z",
  "path": "/api/auth/login"
}

業務錯誤回應

json

{
  "code": 2001,
  "message": "帳號或密碼錯誤",
  "timestamp": "2026-03-01T12:00:00.000Z",
  "path": "/api/auth/login"
}

HTTP Status 一律為 200（僅 401 Unauthorized 例外）
code 為 200 表示成功，非 200 為業務錯誤
message 為當前語系的錯誤訊息（由後端 i18n 翻譯）

未授權回應

json

{
  "code": 401,
  "message": "Unauthorized"
}

11.2 錯誤碼組織方式

後端 i18n JSON 結構

錯誤碼定義在後端 i18n JSON 檔案中，結構如下：

json

// src/i18n/zh-TW/authError.json
{
  "register": {
    "2001": "帳號已存在",
    "2002": "推廣碼不存在",
    "2003": "Email 已存在"
  },
  "login": {
    "2001": "帳號或密碼錯誤",
    "2002": "帳號已停用"
  }
}

i18n key 格式：{featureFile}.{section}.{code} 例如：authError.register.2001 → "帳號已存在"

後端拋出錯誤方式

typescript

throw new HttpException(
  { code: 2001, message: this.i18n.t('authError.register.2001') },
  HttpStatus.BAD_REQUEST
);

規則：

錯誤碼從 2001 起遞增
各功能模組獨立編號
一律透過 this.i18n.t() 翻譯，禁止硬寫錯誤文字
HTTP Status 被 AllExceptionsFilter 正規化為 200

11.3 前端錯誤碼查表機制

ERROR_CODES API

前端啟動時呼叫 GET /common/enums，取得完整的錯誤碼對照表。

後端 CommonService.onModuleInit() 會遞迴掃描 i18n/zh-TW/*.json，找出所有數字 key，建構 code map。呼叫 getEnums() 時翻譯為當前語系回傳。

I18N_PATH_MAP

錯誤碼以 API 路徑為索引，透過 I18N_PATH_MAP 映射：

i18n Prefix	API Path
authError.register	/api/auth/register
authError.login	/api/auth/login
walletError.bankCard.add	/api/wallet/bank-card/add
vendorError.wantong	/api/vendor/wantong/add-atm, /api/vendor/wantong/add-card
promoError	/api/promo/:id, /api/admin/promos/create, /api/admin/promos/:id
vipError.levels	/api/vip/levels, /api/vip/levels/:id
gameError.launch	/api/game/launch
affiliateError.trackClick	/api/affiliate/track-click
adminError.login	/api/admin/login
depositError	/api/deposit
withdrawalError	/api/withdrawal/request
inboxError	/api/inbox/*
missionError	/api/mission/*
siteConfigError	/api/site-config/*

共 32+ 條映射，支援萬用 :id 參數匹配。

前端三層錯誤處理

前端 API 呼叫時的錯誤處理層級：

第一層：Store 查表
- errorCodes[path][code]（來自 /common/enums，支援 :id 萬用）
- 自動匹配 API 路徑並查找對應錯誤訊息
第二層：呼叫端覆寫
- API 呼叫時可傳入 errorMessage: string | Record<code, msg>
- 覆寫特定錯誤碼的顯示訊息
第三層：自動 Toast
- toast.error(message)
- 可用 errorToast: false 停用自動 Toast

11.4 錯誤碼分類

認證相關 (authError)

Section	Code	說明
register	2001	帳號已存在
register	2002	推廣碼不存在
register	2003	Email 已存在
login	2001	帳號或密碼錯誤
login	2002	帳號已停用
login	2003	需要 2FA 驗證

後台管理 (adminError)

Section	Code	說明
login	2001	Email 或密碼錯誤
login	2002	帳號已停用
register	2001	Email 已存在
register	2002	驗證碼錯誤

遊戲相關 (gameError)

Section	Code	說明
launch	5010	用戶被風控封鎖

錢包相關 (walletError)

Section	Code	說明
bankCard.add	2001	銀行卡已存在
creditCard.add	2001	信用卡已存在
cryptoAddress.add	2001	地址已存在

存款相關 (depositError)

Section	Code	說明
deposit	2001	金流通道不存在
deposit	2002	金額超出範圍

提領相關 (withdrawalError)

Section	Code	說明
request	2001	餘額不足
request	2002	錢包不存在

第 12 章：附錄

12.1 術語表

術語 (中文)	術語 (English)	說明
白牌	White-Label	同一套系統可部署為不同品牌
站點	Site	一個獨立的娛樂城品牌
站點代碼	siteCode	站點唯一識別碼 (如 C9)
前台	Frontend (EC)	面向終端用戶的娛樂平台
後台	Admin Panel (IMS)	內部管理系統
多站點	Multi-Site / Multi-Tenant	一套系統支援多個站點
遊戲商	Game Provider	遊戲內容供應商
遊戲分類	Game Type Config	遊戲類型設定
金流商	Vendor	金流服務提供商
金流通道	Vendor Channel	具體的支付方式
金流群組	Vendor Group	金流通道的分組（按幣別）
存款	Deposit	入金操作
提款 / 提領	Withdrawal	出金操作
凍結金額	Frozen Balance	提款申請中被凍結的金額
返水	Rebate	VIP 玩家的投注回饋
保級	Retention / Relegation	VIP 等級維持機制
打碼量	Turnover	活動獎勵的投注要求
有效投注	Effective Bet	計入統計的有效投注金額
佣金	Commission	代理推廣的獎勵金額
結算	Settlement	佣金的定期結算
週結	Weekly Settlement	每週結算一次佣金
日結	Daily Settlement	每日結算一次佣金
代理碼	Agent Code	代理的唯一識別碼
推廣碼	Referral Code	代理的推廣連結代碼
上線	Upline	代理推廣的上級
下線	Downline	代理推廣的下級
三層代理	3-level Affiliate	最多 3 層的代理結構
聯盟	Alliance	代理推廣聯盟體系
代理等級	Agent Tier	代理的等級分類
VIP 里程碑	VIP Milestone	下線達 VIP 等級時的額外獎勵
站內信	Notification / Inbox	系統內部通知訊息
活動	Promo / Promotion	優惠活動
活動標籤	Promo Tag	活動的分類標籤
風控	Risk Control	風險控制管理
黑名單	Blacklist	封鎖名單
白名單	Whitelist	允許名單
裝置指紋	Device Fingerprint	裝置唯一識別 (FingerprintJS)
S2S 回調	Server-to-Server Callback	伺服器間的通知回調
轉帳錢包	Transfer Wallet	遊戲使用的轉帳錢包模式
RBAC	Role-Based Access Control	基於角色的存取控制
2FA	Two-Factor Authentication	二步驟驗證
TOTP	Time-based One-Time Password	基於時間的一次性密碼
JWT	JSON Web Token	JSON 網路令牌
OAuth	Open Authorization	開放授權標準
ORM	Object-Relational Mapping	物件關聯映射
DTO	Data Transfer Object	資料傳輸物件
CRUD	Create, Read, Update, Delete	增刪改查
R2	Cloudflare R2	Cloudflare 物件儲存服務
i18n	Internationalization	國際化（多語系）
ICU	International Components for Unicode	Unicode 國際化元件
OKLCH	OK Lightness Chroma Hue	色彩空間模型
Cron	Cron Expression	排程時間表達式
seed	Seed Data	種子資料（測試用初始資料）

12.2 縮寫對照表

縮寫	全稱	中文
EC	Entertainment City	娛樂城
IMS	Internal Management System	內部管理系統
BE	Backend	後端
PM	Product/Project Manager	產品/專案經理
API	Application Programming Interface	應用程式介面
UI	User Interface	使用者介面
UX	User Experience	使用者體驗
DB	Database	資料庫
KYC	Know Your Customer	認識你的客戶
VIP	Very Important Person	貴賓
ATM	Automated Teller Machine	自動櫃員機
USDT	Tether (USD Tether)	泰達幣
TRC-20	TRON Token Standard	波場代幣標準
ERC-20	Ethereum Token Standard	以太坊代幣標準
TWD	New Taiwan Dollar	新台幣
USD	United States Dollar	美元
CNY	Chinese Yuan	人民幣
THB	Thai Baht	泰銖
VND	Vietnamese Dong	越南盾
QR	Quick Response	快速回應碼
FAQ	Frequently Asked Questions	常見問題
CSS	Cascading Style Sheets	層疊樣式表
HTML	HyperText Markup Language	超文本標記語言
JSON	JavaScript Object Notation	JavaScript 物件表示法
CSV	Comma-Separated Values	逗號分隔值
TTL	Time To Live	存活時間
HMAC	Hash-based Message Authentication Code	雜湊訊息認證碼
DES	Data Encryption Standard	資料加密標準
SHA	Secure Hash Algorithm	安全雜湊演算法
IP	Internet Protocol	網際網路協定
FP	Fingerprint	指紋
UA	User Agent	使用者代理

12.3 遊戲類型對照表

遊戲類型 ID	英文名稱	中文名稱	說明
1	SPORTS	體育	體育賽事投注
2	SLOT	老虎機	電子老虎機遊戲
3	LIVE	真人	真人荷官遊戲
4	LOTTERY	彩票	彩票類遊戲
5	CHESS	棋牌	棋牌類遊戲
8	ESPORTS	電競	電子競技投注
9	CRYPTO	加密	加密貨幣相關遊戲
10	FISH	捕魚	捕魚類遊戲

打碼量權重 (TURNOVER_WEIGHT)：

遊戲類型	權重
Sports (1)	1.0
Slot (2)	1.0
Live (3)	1.0
Lottery (4)	1.0
Chess (5)	1.0
Esports (8)	1.0
Crypto (9)	0.5
Fish (10)	0.5

12.4 權限模組對照表

模組代碼	模組名稱	說明	read 權限	write 權限
admin	管理員管理	管理後台管理員帳號	admin:read	admin:write
admin-group	群組管理	管理權限群組	admin-group:read	admin-group:write
admin-log	操作紀錄	查看管理員操作日誌	admin-log:read	admin-log:write
user	用戶管理	管理前台用戶	user:read	user:write
deposit	存款管理	存款訂單審核	deposit:read	deposit:write
withdrawal	提款管理	提款訂單審核	withdrawal:read	withdrawal:write
promo	活動管理	優惠活動 CRUD	promo:read	promo:write
promo-tag	活動標籤	活動標籤 CRUD	promo-tag:read	promo-tag:write
affiliate	代理管理	代理推廣管理	affiliate:read	affiliate:write
vip	VIP 管理	VIP 等級/返水管理	vip:read	vip:write
game	遊戲管理	遊戲商/分類管理	game:read	game:write
risk	風控管理	風控規則管理	risk:read	risk:write
report	報表	各類報表查看	report:read	report:write
vendor	金流商管理	金流群組/通道管理	vendor:read	vendor:write
finance	財務管理	錢包審核/調帳	finance:read	finance:write
site-config	站點設定	站點基本設定管理	site-config:read	site-config:write

權限總數：16 模組 x 2 操作 (read/write) = 32 個權限 key

12.5 群組類型對照表

群組類型 (groupType)	名稱	權限範圍	說明
root	最高管理員	全部權限	略過所有權限檢查，擁有最高權限
super_admin	超級管理員	全部（除 site-config）	擁有除站點設定外的所有權限
general_admin	一般管理員	僅讀取	所有模組的 read 權限，無 write 權限
custom	自訂群組	依 permissions 設定	根據 permissions JSON 陣列中的權限 key 決定

12.6 幣別對照表

幣別代碼	名稱	語系映射	說明
TWD	新台幣	zh-TW	台灣法幣
USD	美元	en-US	系統內部統一幣別
CNY	人民幣	zh-CN	中國法幣
THB	泰銖	th-TH	泰國法幣
VND	越南盾	vi-VN	越南法幣

12.7 訂單狀態對照表

存款訂單 (deposit-order)

狀態	說明
pending	待處理（訂單已建立，等待付款）
created	已建立（金流商已回應）
paid	已付款（金流商回調確認）
failed	失敗
cancelled	已取消

提款訂單 (withdrawal-order)

狀態	說明
pending	待審核
approved	已核准（等待匯款）
rejected	已拒絕（凍結金額退回）
completed	已完成（匯款完成）

投注注單 (bet-order)

狀態	說明
valid	有效投注
invalid	無效投注
cancelled	已取消

代理結算 (affiliate-settlement)

狀態	說明
pending	待審核
approved	已核准（佣金入帳）
rejected	已拒絕

代理提款 (affiliate-withdrawal)

狀態	說明
pending	待審核
approved	已核准
rejected	已拒絕
completed	已完成

12.8 登入動作類型

動作	說明
LOGIN	登入成功
LOGOUT	登出
LOGIN_FAIL	登入失敗
DEL	移除紀錄
UNCAPTURED	未補獲

12.9 任務類別與週期

任務類別 (category)

類別	說明
daily_deposit	每日存款任務
weekly_bet	每週投注任務
monthly_challenge	每月綜合挑戰

任務週期 (periodType)

週期	說明	periodKey 格式
daily	每日	YYYY-MM-DD
weekly	每週	YYYY-WW
monthly	每月	YYYY-MM

12.10 客服管道類型

管道代碼	名稱	說明
line	LINE	LINE 即時通訊
telegram	Telegram	Telegram 通訊
wechat	微信	微信通訊
facebook	Facebook	Facebook Messenger
instagram	Instagram	Instagram DM
twitter	Twitter/X	Twitter/X 私訊
discord	Discord	Discord 伺服器
custom	自訂	自訂客服管道

12.11 代理等級

等級代碼	名稱	說明
bronze	銅牌	基礎代理等級
silver	銀牌	中級代理等級
gold	金牌	高級代理等級
platinum	白金	最高代理等級

12.12 風控封鎖範圍

遊戲黑名單封鎖範圍

gameType	productId	封鎖範圍
null	null	封鎖用戶所有遊戲
'slot'	null	封鎖用戶該類型所有遊戲
'slot'	123	封鎖用戶特定遊戲

IP 規則類型

類型	說明
blacklist	黑名單（封鎖該 IP）
whitelist	白名單（允許該 IP）

12.13 資料庫唯一約束完整清單

以下為所有資料表中的複合唯一約束 (Unique Constraints)，這些約束確保資料的一致性與正確性。

#	Entity (資料表)	唯一欄位組合	業務說明
1	auth-user	(siteCode, account)	同站帳號唯一
2	auth-user	(siteCode, email)	同站 Email 唯一
3	auth-user	(siteCode, mobile)	同站手機唯一
4	auth-user	(siteCode, telegram)	同站 Telegram 唯一
5	auth-user	(siteCode, google)	同站 Google 唯一
6	auth-user	(siteCode, agentCode)	同站代理碼唯一
7	vip-level	(siteCode, level)	同站 VIP 等級唯一
8	vip-rebate	(siteCode, level, gameType)	同站等級+遊戲類型唯一
9	game-provider	(siteCode, gameCode)	同站遊戲碼唯一
10	game-type-config	(siteCode, gameType)	同站遊戲類型唯一
11	game-play-log	(siteCode, userId, gameCode, productId)	同站用戶+遊戲唯一
12	promo-claim	(siteCode, promoId, userId)	同站活動+用戶唯一
13	promo-tag	(siteCode, name)	同站標籤名唯一
14	notification-read	(siteCode, userId, notificationId)	同站用戶+通知唯一
15	affiliate-settlement	(siteCode, agentId, weekStart)	同站代理+週起始唯一
16	alliance-commission-rate	(agentTier, agentLevel, gameType)	等級+層級+遊戲類型唯一
17	alliance-agent-tier	(tierCode)	等級代碼唯一
18	alliance-vip-milestone	(vipLevel)	VIP 等級唯一
19	alliance-vip-milestone-log	(siteCode, agentId, memberId, vipLevel)	同站代理+會員+VIP 唯一
20	alliance-referral-code	(siteCode, code)	同站推廣碼唯一
21	vendor-group-channel	(groupId, channelId)	群組+通道唯一
22	mission	(siteCode, category, periodType, tier)	同站類別+週期+層級唯一
23	mission-progress	(siteCode, userId, periodType, periodKey)	同站用戶+週期唯一
24	mission-claim	(siteCode, missionId, userId, periodKey)	同站任務+用戶+週期唯一

12.14 投注後連鎖觸發詳細說明

每筆遊戲投注結算完成後，系統會自動觸發以下連鎖操作。這些操作是同步執行的，確保資料一致性。

觸發條件

當遊戲供應商透過 S2S 回調通知後端一筆投注已結算時：

連鎖操作一：VIP 等級重算

VipService.recalculateUserVip(userId)
  |
  v
1. 查詢用戶所有有效投注的累計金額
   SELECT COALESCE(SUM(betEffective), 0) FROM bet-order WHERE userId = ? AND status = 'valid'
  |
  v
2. 查詢用戶當前 VIP 等級
  |
  v
3. 查詢所有比當前等級高的 VIP 等級
   按 minChip 排序
  |
  v
4. 逐一比較：totalEffectiveBet >= level.minChip ?
   找到最高可達到的等級
  |
  v
5. 若新等級 > 當前等級：
   - 更新 auth-user.vipLevel
   - 觸發 VIP 里程碑檢查（通知代理上線）

重要規則：

只升不降：投注觸發的等級變動永遠是向上的
降級只發生在月度保級檢查（Cron Job）
每站 VIP 等級獨立配置

連鎖操作二：活動打碼量更新

PromoService.updatePromoTurnover(userId, betAmount, gameType)
  |
  v
1. 查詢用戶所有未完成打碼量的活動領取記錄 (promo-claim)
   WHERE remainingTurnover > 0
  |
  v
2. 計算打碼量扣減：
   weightedBet = betAmount * TURNOVER_WEIGHT[gameType]
   (CRYPTO 和 FISH 類型權重為 0.5，其他為 1.0)
  |
  v
3. 更新 remainingTurnover：
   remainingTurnover = MAX(0, remainingTurnover - weightedBet)
  |
  v
4. 當 remainingTurnover = 0 時，標記打碼量已完成

連鎖操作三：任務投注進度更新

MissionService.updateBetProgress(userId, betAmount, gameType)
  |
  v
1. 查詢用戶當前週期的投注任務進度 (mission-progress)
   WHERE periodType = 'weekly' AND periodKey = 當前週
  |
  v
2. 更新 currentValue += betAmount
  |
  v
3. 用戶可在任務頁面查看進度並領取獎勵

非同步操作：遊戲遊玩記錄

GameService.recordGamePlay(userId, gameCode, productId)
  → UPSERT game-play-log (更新 lastPlayedAt)
  → .catch(() => {})  // 不阻塞主流程

12.15 金流群組自動分配規則

用戶註冊時，系統根據用戶的語系自動分配金流群組。分配對照如下：

用戶語系	對應幣別	分配的金流群組	說明
zh-TW	TWD	TWD 群組	台灣用戶使用新台幣通道
en-US	USD	USD 群組	英語用戶使用美元通道
zh-CN	CNY	CNY 群組	中國用戶使用人民幣通道
th-TH	THB	THB 群組	泰國用戶使用泰銖通道
vi-VN	VND	VND 群組	越南用戶使用越南盾通道

分配邏輯位於 AuthService.register() 中，透過 LOCALE_CURRENCY_MAP 查找對應幣別，再查找該幣別的金流群組。

12.16 Cache Key 命名慣例

後端使用 Redis 快取，key 命名遵循以下格式：

cache:{module}:{type}:{id}

Cache Key	TTL	說明
cache:auth📺	60s	用戶 token version（驗證 JWT 時使用）
cache:admin📺	60s	管理員 token version
cache:admin-group:perms:	60s	群組權限列表（RBAC 檢查時使用）
cache:vip:levels	1 小時	VIP 等級列表
cache:common:enums:	1 小時	錯誤碼查詢表（依語系快取）
cache:online:	60s	用戶在線狀態（節流 lastActivityAt 更新）
cache:live-sports:matches	30 分鐘	即時體育賽事資料

12.17 前台 Composable 完整清單

Composable	用途	說明
useApi	API 統一入口	Facade pattern，合併所有 API 模組
useHttp	HTTP 請求封裝	Axios 攔截器、錯誤處理、site-name 注入
useAuth	認證狀態管理	登入/登出/用戶資訊
useConfig	站點配置	domainConfig 域名映射
useDevice	裝置偵測	行動版/桌面版判斷
useFingerprint	裝置指紋	FingerprintJS v5 整合
useGame	遊戲邏輯	遊戲啟動、遊戲列表
useLayout	佈局管理	佈局切換 (a1/a2)
useTheme	主題管理	主題色切換、CSS 變數注入
useExchangeRate	匯率	即時匯率查詢
useCash	金額格式化	USD 金額顯示處理
usePaymentChannels	支付通道	金流通道選擇邏輯
useRefCode	推廣碼	推廣碼解析與綁定
useAffiliate	代理功能	代理推廣相關邏輯
useAgentTour	代理導覽	新手代理導覽流程
useInbox	站內信	站內信讀取與管理
useKyc	KYC 驗證	身份驗證流程
usePreventZoom	防止縮放	行動版防止手勢縮放
useR2Url	R2 URL	Cloudflare R2 圖片 URL 產生
useApiTypes	API 型別	API 回應型別定義

API Composables (12 個)

Composable	模組	主要方法
useAuthApi	認證	register, login, googleLogin, telegramLogin, getUserDetail, updateProfile, setPassword, updatePassword, uploadAvatar, sendEmailVerify, verifyEmail
useGameApi	遊戲	getProviders, getTypeConfigs, launchGame, demoGame, getRecentGames
useDepositApi	存款	createDeposit, getDepositOrders, getExchangeRate
useWalletApi	錢包	addBankCard, getBankCards, deleteBankCard, addCreditCard, getCreditCards, deleteCreditCard, addCryptoAddress, getCryptoAddresses, deleteCryptoAddress
useWithdrawalApi	提領	requestWithdrawal, getWithdrawalOrders
useVipApi	VIP	getLevels, getUserStatus, getMyRebates, getRebates
usePromoApi	活動	getPromoList, getPromoDetail, claimPromo, getPromoTags
useAffiliateApi	代理	getDashboard, getCommissions, getSettlements, getDownlines, getBalance, requestWithdrawal, getWithdrawals, getReferralCodes, createReferralCode, deleteReferralCode, applyAgent, getAllianceInfo, getTierInfo, getVipMilestones
useInboxApi	站內信	getNotifications, getNotification, markAsRead, deleteNotification, getUnreadCount
useMissionApi	任務	getMissionList, getMissionProgress, claimMission
useSiteConfigApi	站點設定	getPublicConfig, getTheme

12.18 後台 API Hook 方法清單

useAdminApi

方法	說明
login	管理員登入
register	管理員註冊
getAdminList	管理員列表
createAdmin	新增管理員
getAdmin	取得管理員
updateAdmin	更新管理員
deleteAdmin	刪除管理員
getGroupList	群組列表
createGroup	新增群組
getGroup	取得群組
updateGroup	更新群組
deleteGroup	刪除群組
getAllPermissions	取得所有權限
getOperationLogs	查詢操作紀錄
getR2Files	R2 檔案列表
uploadR2File	上傳 R2 檔案
deleteR2File	刪除 R2 檔案
moveR2File	移動 R2 檔案
createR2Folder	建立 R2 資料夾
deleteR2Folder	刪除 R2 資料夾
getR2Logs	R2 操作日誌

useFinanceApi

方法	說明
getUserList	前台用戶列表
getUserDetail	用戶詳情
updateUser	更新用戶
adjustBalance	手動調帳
getDepositReviewList	存款訂單列表
reviewDeposit	存款審核
getWithdrawalList	提款列表
reviewWithdrawal	提款審核
completeWithdrawal	提款完成
uploadWithdrawalProof	上傳匯款憑證
getBankCardList	銀行卡列表
reviewBankCard	銀行卡審核
getCreditCardList	信用卡列表
reviewCreditCard	信用卡審核
getCryptoAddressList	加密地址列表
reviewCryptoAddress	加密地址審核
assignVendorGroup	用戶金流群組分配

useContentApi

方法	說明
getPromoList	活動列表
createPromo	新增活動
updatePromo	更新活動
deletePromo	刪除活動
getPromoTagList	活動標籤列表
createPromoTag	新增活動標籤
updatePromoTag	更新活動標籤
deletePromoTag	刪除活動標籤
getSiteConfigs	站點列表
createSiteConfig	新增站點
updateSiteConfig	更新站點
deleteSiteConfig	刪除站點
getSiteThemes	主題列表
createSiteTheme	新增主題
updateSiteTheme	更新主題
deleteSiteTheme	刪除主題
uploadDomainAsset	上傳域名素材
uploadCustomerServiceIcon	上傳客服圖示
updateMascots	更新吉祥物
getCustomerService	取得客服設定
sendNotification	發送站內信
getNotificationSettings	通知設定
getIpRules	IP 規則列表
createIpRule	新增 IP 規則
updateIpRule	更新 IP 規則
deleteIpRule	刪除 IP 規則
lookupRisk	IP/FP 查詢
getLoginFailures	登入失敗紀錄
getGameBlacklist	遊戲黑名單列表
createGameBlacklist	新增遊戲黑名單
updateGameBlacklist	更新遊戲黑名單
deleteGameBlacklist	刪除遊戲黑名單
getReportPlayers	玩家報表
getReportVipPlayers	VIP 玩家報表
getReportBetRecords	投注紀錄報表
getReportOverview	總覽報表
getReportProfitLoss	損益報表
getReportGames	遊戲報表
getReportPromos	活動報表
getReportPlayerSummary	玩家摘要報表
exportReport	匯出報表 (CSV)

useGameApi (後台)

方法	說明
getGameProviders	遊戲商列表
createGameProvider	新增遊戲商
updateGameProvider	更新遊戲商
deleteGameProvider	刪除遊戲商
getGameTypeConfigs	遊戲分類列表
createGameTypeConfig	新增遊戲分類
updateGameTypeConfig	更新遊戲分類
deleteGameTypeConfig	刪除遊戲分類
previewGameTemplate	預覽遊戲模板
loadGameTemplate	帶入遊戲模板
copyGameSiteData	跨站複製遊戲資料

useVipApi (後台)

方法	說明
getVipLevels	VIP 等級列表
createVipLevel	新增 VIP 等級
updateVipLevel	更新 VIP 等級
deleteVipLevel	刪除 VIP 等級
bulkUpsertRebates	批量更新返水規則
copyVipSiteData	跨站複製 VIP 資料
previewVipTemplate	預覽 VIP 模板
loadVipTemplate	帶入 VIP 模板

useAffiliateApi (後台)

方法	說明
getAgents	代理列表
createAgent	新增代理
getSettlements	結算列表
reviewSettlement	結算審核
getSettlementRiskLogs	結算風控紀錄
getAffWithdrawals	代理提款列表
reviewAffWithdrawal	代理提款審核
completeAffWithdrawal	代理提款完成
adminBind	手動綁定
getBindLogs	綁定紀錄
getCommissionRates	佣金費率列表
upsertCommissionRates	更新佣金費率
deleteCommissionRates	刪除佣金費率
getVipMilestones	VIP 里程碑列表
upsertVipMilestones	更新 VIP 里程碑
deleteVipMilestones	刪除 VIP 里程碑
getAgentTiers	代理等級列表
upsertAgentTiers	更新代理等級
deleteAgentTiers	刪除代理等級
previewAffTemplate	預覽代理模板
loadAffTemplate	帶入代理模板
setAgentTier	設定代理等級
triggerSettlement	觸發週結
triggerDailySettlement	觸發日結

12.19 Seed 資料腳本清單

後端提供 19+ 個 seed 腳本用於建立測試資料：

#	腳本名稱	用途	執行方式
1	seed-all.ts	全資料表假資料（主入口）	`npx ts-node scripts/seed-all.ts`
2	seed-site-config.ts	站點設定種子資料	由 seed-all 呼叫
3	seed-vendor.ts	金流群組/通道種子資料	由 seed-all 呼叫
4	seed-deposit.ts	存款訂單種子資料	由 seed-all 呼叫
5	seed-deposit-order.ts	存款訂單（獨立版本）	獨立執行
6	seed-vip.ts	VIP 等級/反水種子資料	由 seed-all 呼叫
7	seed-bet-record.ts	投注紀錄種子資料	由 seed-all 呼叫
8	seed-ranking.ts	排行榜種子資料	由 seed-all 呼叫
9	seed-ranking-users.ts	排行榜用戶種子資料	由 seed-all 呼叫
10	seed-inbox.ts	站內信種子資料	由 seed-all 呼叫
11	seed-mission.ts	任務系統種子資料	由 seed-all 呼叫
12	seed-withdrawal.ts	提領訂單種子資料	由 seed-all 呼叫
13	seed-learn-more.ts	了解更多 FAQ 種子資料	由 seed-all 呼叫
14	seed-layout-defaults.ts	前台佈局預設配置	由 seed-all 呼叫
15	seed-agent-promo.ts	代理活動種子資料	由 seed-all 呼叫
16	assign-all-channels.ts	分配所有金流通道	獨立執行
17	clear-deposit.ts	清除存款資料	獨立執行
18	generate-promo-images.ts	活動橫幅圖片生成 + R2 上傳	獨立執行
19	generate-mascot-avatars.ts	吉祥物頭像生成 + R2 上傳	獨立執行

seed-all.ts 執行後會建立：

5 個站點配置
每站 30 個測試用戶
完整的金流群組與通道
VIP 等級與返水規則
測試用的投注紀錄、存款/提領訂單
站內信、任務、活動等資料

12.20 環境變數清單

必要環境變數

變數名稱	說明	範例值
DB_HOST	資料庫主機	localhost
DB_PORT	資料庫端口	3306
DB_USER	資料庫使用者	root
DB_PASSWORD	資料庫密碼	password
DB_DATABASE	資料庫名稱	c9
REDIS_URL	Redis 連線 URL	redis://localhost:6379
JWT_SECRET	前台 JWT 密鑰	your-jwt-secret
SITE_CODE	預設站點代碼	C9
R2_BUCKET_NAME	R2 儲存桶名稱	c9-storage
R2_ENDPOINT	R2 API 端點	https://xxxx.r2.cloudflarestorage.com
R2_ACCESS_KEY_ID	R2 存取金鑰 ID	your-access-key
R2_SECRET_ACCESS_KEY	R2 存取密鑰	your-secret-key
R2_PUBLIC_URL	R2 公開 URL	https://cdn.example.com

應用程式變數

變數名稱	說明	預設值
PORT	伺服器端口	8080
NODE_ENV	執行環境	development
APP_NAME	應用名稱（2FA issuer 用）	C9
API_DOMAIN	API 域名（金流回調用）	http://localhost:8080
FRONTEND_URL	前台 URL（代理分享連結用）	http://localhost:3000
TZ	時區	Asia/Seoul

Admin 變數

變數名稱	說明	預設值
ADMIN_JWT_SECRET	後台 JWT 密鑰	fallback JWT_SECRET
ADMIN_DEFAULT_PASSWORD	預設管理員密碼	root
ADMIN_DEFAULT_EMAIL	預設管理員 Email	root
ADMIN_DEFAULT_NAME	預設管理員名稱	Root

OAuth 變數 (選填)

變數名稱	說明
GOOGLE_CLIENT_ID	Google OAuth Client ID
GOOGLE_CLIENT_SECRET	Google OAuth Client Secret
GOOGLE_REDIRECT_URI	Google OAuth Redirect URI
TELEGRAM_BOT_TOKEN	Telegram Bot Token
TELEGRAM_BOT_USERNAME	Telegram Bot Username

服務提供商變數 (選填)

變數名稱	說明
RESEND_API_KEY	Resend (Email) API Key
RESEND_FROM	Resend 寄件地址
TWILIO_ACCOUNT_SID	Twilio Account SID
TWILIO_AUTH_TOKEN	Twilio Auth Token
TWILIO_VERIFY_SERVICE_SID	Twilio Verify Service SID

遊戲商變數 (選填)

變數名稱	說明
BS_API_URL	BetSolutions API URL
BS_AUTH_URL	BetSolutions Auth URL
BS_MERCHANT_ID	BetSolutions Merchant ID
BS_PRIVATE_KEY	BetSolutions Private Key
RSG_API_URL	RSG API URL
RSG_CLIENT_ID	RSG Client ID
RSG_CLIENT_SECRET	RSG Client Secret
RSG_DES_KEY	RSG DES 加密金鑰
RSG_DES_IV	RSG DES 初始向量
RSG_SYSTEM_CODE	RSG System Code
RSG_WEB_ID	RSG Web ID

其他變數 (選填)

變數名稱	說明
LIVE_SPORTS_API_KEY	API-Football 即時賽事 API Key

12.21 後台側邊欄導航結構

後台側邊欄包含 14+ 個導航群組，50+ 個導航項目。每個項目都有對應的 RBAC 權限檢查：

群組	項目	路由	所需權限
儀表板	儀表板	/dashboard	(任何認證用戶)
系統管理	管理員管理	/system/admins	admin:read
	群組管理	/system/groups	admin-group:read
	操作紀錄	/system/logs	admin-log:read
	站點設定	/system/site-config	site-config:read
	客服配置	/system/site-customer-service	site-config:read
	域名設置	/system/site-domains	site-config:read
	遊戲商配置	/system/site-game-providers	site-config:read
	三方登入	/system/site-oauth	site-config:read
	服務商配置	/system/site-service-providers	site-config:read
	雲端儲存	/system/cloud-storage	admin:read
	雲端儲存日誌	/system/cloud-storage-logs	admin:read
前台佈局	底部導航列	/system/layout-bottom-bar	site-config:read
	頁尾	/system/layout-footer	site-config:read
	了解更多	/system/layout-learn-more	site-config:read
玩家管理	全部玩家	/players/all	user:read
	新註冊	/players/new-registrations	user:read
	線上玩家	/players/online	user:read
	登入失敗	/players/login-failures	risk:read
	玩家標籤	/players/tags	user:read
	遊戲重新註冊	/players/game-reregistration	game:write
活動管理	優惠活動	/activity/promos	promo:read
	活動標籤	/activity/tags	promo-tag:read
郵件	站內信	/mail/inbox	admin:read
	郵件設定	/mail/settings	admin:read
財務管理	人工調帳	/finance/adjust-balance	finance:write
	存款設置	/finance/deposit-settings	vendor:read
	存款審核	/finance/deposit-review	deposit:read
	提款管理	/finance/withdrawals	withdrawal:read
	銀行卡	/finance/bank-cards	finance:read
	信用卡	/finance/credit-cards	finance:read
	加密錢包	/finance/crypto-addresses	finance:read
遊戲管理	遊戲供應商	/game/providers	game:read
	遊戲類型	/game/type-configs	game:read
VIP 管理	VIP 等級	/vip/levels	vip:read
	返水設定	/vip/rebates	vip:read
	VIP 玩家	/vip/players	vip:read
	VIP 里程碑	/vip/milestones	vip:read
報表	總覽	/reports/overview	report:read
	玩家報表	/reports/players	report:read
	玩家摘要	/reports/player-summary	report:read
	遊戲報表	/reports/games	report:read
	投注紀錄	/reports/bet-records	report:read
	損益報表	/reports/profit-loss	report:read
	活動報表	/reports/promos	report:read
風控管理	IP 規則	/risk-control/ip-rules	risk:read
	IP/FP 查詢	/risk-control/ip-check	risk:read
	遊戲黑名單	/risk-control/game-blacklist	risk:read
代理中心	代理列表	/affiliate/agents	affiliate:read
	佣金費率	/affiliate/commission-rates	affiliate:read
	佣金結算	/affiliate/settlements	affiliate:read
	代理提款	/affiliate/aff-withdrawals	affiliate:read
	綁定紀錄	/affiliate/bind-logs	affiliate:read
	代理等級	/affiliate/agent-tiers	affiliate:read
	VIP 里程碑	/affiliate/vip-milestones	affiliate:read
	代理導覽	/affiliate/agent-tour	affiliate:read

12.22 前台 Store 結構

Store	用途	持久化	主要狀態
appStore	全域應用狀態	-	siteConfig, theme, locale, isLoading
userStore	用戶狀態	-	user, token, isLoggedIn, balance
gameStore	遊戲狀態	-	providers, typeConfigs, currentGame, recentGames
promoStore	活動狀態	-	promos, tags, currentPromo

12.23 後台 Store 結構

Store	用途	持久化	主要狀態
siteFilterStore	Header 站點選擇	sessionStorage	selectedSiteCode, sites
enumStore	後端枚舉快取	-	errorCodes, gameTypes
uiStore	UI 狀態	-	sidebarExpanded, currentTheme

12.24 專案啟動指令

一鍵啟動

指令	說明
`yarn dev`	同時啟動三個專案（concurrently）
`yarn dev:ec`	只啟動前台 (http://localhost:3010)
`yarn dev:ims`	只啟動後台 (http://localhost:3011)
`yarn dev:be`	只啟動後端 (http://localhost:8080/api)

一鍵 Commit

指令	說明
`yarn commit`	統一 commit 三個專案（互動式 git-cz）
`yarn push`	依序 commit + push 三個專案
`yarn push:all`	只推送未 push 的 commit
`yarn push:ec`	只推送 c9-ec
`yarn push:ims`	只推送 c9-ims
`yarn push:be`	只推送 c9-be

首次安裝

# 根目錄
cd c9 && yarn install

# 各子專案
cd c9-ec && yarn install
cd c9-ims && pnpm install
cd c9-be && yarn install

各子專案指令

c9-ec (前台)

指令	說明
yarn dev	開發模式
yarn build	正式建置
yarn preview	預覽正式版
yarn test	單元測試 (Vitest)
yarn test:unit	只跑單元測試
yarn test:nuxt	只跑元件測試
yarn test:e2e	E2E 測試 (Playwright)
yarn lint	程式碼檢查
yarn format	格式化

c9-ims (後台)

指令	說明
yarn dev:a1	開發模式 a1 站點 (Turbopack)
yarn build:a1	建置 a1 站點
yarn start:a1	啟動正式版
yarn typecheck	TypeScript 類型檢查
yarn lint	程式碼檢查
yarn format	格式化

c9-be (後端)

指令	說明
yarn dev	開發模式
yarn build	正式建置
yarn start:prod	正式啟動
yarn test	單元測試 (Jest)
yarn test:e2e	E2E 測試
yarn lint	程式碼檢查
yarn format	格式化 (Prettier)
npx ts-node scripts/seed-all.ts	資料庫假資料

12.25 資料表欄位完整規格

以下為核心資料表的欄位完整規格，包含欄位名稱、DB 型別、是否為空、預設值、說明。

auth-user（前台用戶帳號）

#	欄位名稱	DB 型別	可空	預設值	說明
1	id	int (PK, AI)	N	-	主鍵
2	account	varchar(50)	N	-	帳號
3	password	varchar(255)	N	-	密碼 (bcrypt hash)
4	name	varchar(50)	N	-	用戶暱稱
5	email	varchar(50)	Y	null	電子信箱
6	emailVerifyCode	varchar(6)	Y	null	信箱驗證碼
7	mobile	varchar(30)	Y	null	手機號碼
8	mobileVerifyCode	varchar(40)	Y	null	手機驗證碼 (E.164 格式)
9	telegram	varchar(50)	Y	null	Telegram ID
10	google	varchar(50)	Y	null	Google OAuth ID
11	vipLevel	varchar(4)	N	'1'	VIP 等級
12	vipProgress	varchar(3)	Y	'0'	VIP 進度 (百分比)
13	totalEffectiveBet	decimal(18,6)	N	0	累計有效投注流水 (USD)
14	relegationMissCount	tinyint(1)	N	0	連續未達保級月數
15	vipHold	tinyint(1)	N	0	VIP 保級鎖定 (1=手動保持等級)
16	googleAuthSecret	varchar(32)	Y	null	Google Authenticator Secret
17	googleAuthEnabled	tinyint(1)	N	0	Google 2FA 啟用狀態
18	tokenVersion	int	N	0	Token 版本號 (遞增可強制登出)
19	balance	decimal(18,6)	N	0	USD 餘額
20	frozenBalance	decimal(18,6)	N	0	凍結中金額 (提領審核中)
21	withdrawalVerifyCode	varchar(6)	Y	null	提領用郵箱驗證碼
22	locale	varchar(10)	N	'zh-TW'	使用者語系偏好
23	avatar	varchar(255)	Y	null	用戶頭像 URL (吉祥物)
24	vendorGroupId	int	Y	null	所屬金流群組 ID
25	agentCode	varchar(20)	Y	null	代理推廣碼 (null=非代理)
26	level1AgentId	int	Y	null	一級代理 (直屬上線) user ID
27	level2AgentId	int	Y	null	二級代理 user ID
28	level3AgentId	int	Y	null	三級代理 user ID
29	agentTourCompletedAt	datetime	Y	null	代理導覽完成時間
30	agentTourDismissedAt	datetime	Y	null	代理導覽跳過時間
31	lastActivityAt	datetime	Y	null	最後活動時間
32	siteCode	varchar(30)	N	'C9'	所屬站點代碼
33	createdAt	datetime	N	CURRENT_TIMESTAMP	建立時間

索引列表：

索引名稱	索引欄位	類型
IDX_site_account	(siteCode, account)	UNIQUE
IDX_site_email	(siteCode, email)	UNIQUE
IDX_site_mobile	(siteCode, mobile)	UNIQUE
IDX_site_telegram	(siteCode, telegram)	UNIQUE
IDX_site_google	(siteCode, google)	UNIQUE
IDX_site_agentCode	(siteCode, agentCode)	UNIQUE
IDX_level1AgentId	(level1AgentId)	INDEX
IDX_vendorGroupId	(vendorGroupId)	INDEX
IDX_lastActivityAt	(lastActivityAt)	INDEX
IDX_siteCode	(siteCode)	INDEX

deposit-order（存款訂單）

#	欄位名稱	DB 型別	可空	預設值	說明
1	id	int (PK, AI)	N	-	主鍵
2	userId	int	N	-	用戶 ID
3	channelId	int	N	-	金流通道 ID
4	channelName	varchar(30)	N	-	金流通道名稱 (e.g. wantong)
5	currency	varchar(10)	N	'TWD'	幣別
6	subOrder	varchar(24)	N	-	商家訂單編號 (UNIQUE)
7	orderAmount	decimal(18,6)	N	0	用戶輸入金額 (USDT)
8	vendorAmount	int	N	0	送出給金流商的金額 (原幣整數)
9	paymentMethod	varchar(10)	N	-	支付方式 fiat/credit/crypto
10	status	varchar(20)	N	'pending'	訂單狀態
11	payAmount	int	N	0	實際繳款金額 (原幣)
12	payTime	varchar(50)	Y	null	繳款時間
13	usdAmount	decimal(18,6)	N	0	入帳 USD 金額
14	exchangeRate	decimal(18,10)	N	0	使用的匯率
15	resultUrl	text	Y	null	金流商付款頁面 URL
16	vendorRequest	json	Y	null	送出給金流商的請求與回應
17	callbackData	json	Y	null	回調原始資料
18	proofImage	varchar(500)	Y	null	繳費證明圖片 URL
19	rejectReason	varchar(200)	Y	null	拒絕原因
20	reviewedBy	varchar(50)	Y	null	審核人
21	siteCode	varchar(30)	N	'C9'	所屬站點代碼
22	createdAt	datetime	N	CURRENT_TIMESTAMP	建立時間
23	updatedAt	datetime	N	CURRENT_TIMESTAMP	更新時間

索引列表：

索引名稱	索引欄位	類型
IDX_userId_status	(userId, status)	INDEX
IDX_subOrder	(subOrder)	UNIQUE
IDX_siteCode	(siteCode)	INDEX

withdrawal-order（提領訂單）

#	欄位名稱	DB 型別	可空	預設值	說明
1	id	int (PK, AI)	N	-	主鍵
2	userId	int	N	-	用戶 ID
3	amount	decimal(18,6)	N	-	提領金額 (USD)
4	cryptoAddressId	int	N	-	提領目標錢包 ID
5	address	varchar(255)	N	-	快照：錢包地址
6	network	varchar(20)	N	-	快照：鏈路 (TRC-20)
7	status	varchar(20)	N	'pending'	狀態
8	rejectReason	varchar(255)	Y	null	拒絕原因
9	reviewedBy	varchar(50)	Y	null	審核人帳號
10	reviewedAt	datetime	Y	null	審核時間
11	proofKey	varchar(500)	Y	null	代付證明 R2 key
12	proofOriginalName	varchar(255)	Y	null	代付證明原始檔名
13	completedBy	varchar(50)	Y	null	完成出款操作員帳號
14	completedAt	datetime	Y	null	完成時間
15	siteCode	varchar(30)	N	'C9'	所屬站點代碼
16	createdAt	datetime	N	CURRENT_TIMESTAMP	建立時間
17	updatedAt	datetime	N	CURRENT_TIMESTAMP	更新時間

提領三階段流程：

pending (待審核)
  → approved (已核准)     ← reviewWithdrawal(approve)
  → rejected (已拒絕)     ← reviewWithdrawal(reject) → 退回 frozenBalance
approved (已核准)
  → completed (已完成)    ← completeWithdrawal → 上傳匯款憑證

vip-level（VIP 等級配置）

#	欄位名稱	DB 型別	可空	預設值	說明
1	id	int (PK, AI)	N	-	主鍵
2	level	int	N	-	VIP 等級編號
3	siteCode	varchar(30)	N	'C9'	所屬站點代碼
4	name	json	N	-	等級名稱 (多語系 JSON)
5	tier	varchar(20)	N	-	階級：bronze/gold/platinum/diamond
6	minChip	decimal(18,6)	N	0	升級所需最低累計籌碼 (USD)
7	relegationChip	decimal(18,6)	N	0	保級所需月投注額 (USD)
8	sortOrder	int	N	1	排序權重
9	enabled	tinyint(1)	N	1	是否啟用
10	createdAt	datetime	N	CURRENT_TIMESTAMP	建立時間
11	updatedAt	datetime	N	CURRENT_TIMESTAMP	更新時間

name JSON 格式範例：

json

{
  "zh-TW": "青銅 I",
  "en-US": "Bronze I",
  "zh-CN": "青铜 I",
  "th-TH": "บรอนซ์ I",
  "vi-VN": "Đồng I"
}

affiliate-settlement（代理佣金結算）

#	欄位名稱	DB 型別	可空	預設值	說明
1	id	int (PK, AI)	N	-	主鍵
2	agentId	int	N	-	代理 user ID
3	weekStart	date	N	-	週結算開始日 (Monday)
4	weekEnd	date	N	-	週結算結束日 (Sunday)
5	activeMemberCount	int	N	0	本週活躍下線人數
6	totalNetLoss	decimal(18,6)	N	0	下線總淨輸 (USD)
7	level1Commission	decimal(18,6)	N	0	一級佣金 (USD)
8	level2Commission	decimal(18,6)	N	0	二級佣金 (USD)
9	level3Commission	decimal(18,6)	N	0	三級佣金 (USD)
10	totalCommission	decimal(18,6)	N	0	佣金總額 (USD)
11	gameTypeBreakdown	json	Y	null	各遊戲類型佣金分解
12	periodType	varchar(10)	N	'weekly'	結算週期：weekly/daily
13	status	varchar(20)	N	'pending'	結算狀態
14	riskFlagged	tinyint(1)	N	0	是否有風控標記
15	riskReasons	text	Y	null	風控原因 (JSON array)
16	reviewedBy	varchar(50)	Y	null	審核人帳號
17	reviewedAt	datetime	Y	null	審核時間
18	siteCode	varchar(30)	N	'C9'	所屬站點代碼
19	createdAt	datetime	N	CURRENT_TIMESTAMP	建立時間
20	updatedAt	datetime	N	CURRENT_TIMESTAMP	更新時間

結算狀態流程：

Cron 觸發 → pending (待審核)
  → 風控檢測 → riskFlagged = 1 → pendingReview (需人工審核)
  → 無異常 → approved (自動核准) → 佣金入 affiliate-balance
  → 人工審核 → approved / rejected

site-config（站點基本設定）

#	欄位名稱	DB 型別	可空	預設值	說明
1	id	int (PK, AI)	N	-	主鍵
2	siteCode	varchar(30)	N	-	站點代碼 (UNIQUE)
3	prefix	varchar(30)	N	-	白牌前綴 (UNIQUE)，對應 R2 路徑
4	layout	varchar(30)	N	'a1'	前台模板代碼
5	siteName	json	N	-	站點名稱 (多語系)
6	siteDescription	json	N	-	站點介紹 (多語系)
7	supportedLocales	json	N	-	支援語系陣列
8	activeThemeId	int	Y	null	當前使用的主題 ID
9	mascots	json	Y	null	吉祥物清單
10	agentTourEnabled	tinyint(1)	N	1	代理導覽功能開關
11	agentTourIntervalSec	int	N	604800	代理導覽重新提醒間隔（秒）
12	depositMethods	json	Y	null	存款通路開關
13	bottomBarEnabled	tinyint(1)	N	1	下導列功能開關
14	bottomBarConfig	json	Y	null	下導列配置
15	footerConfig	json	Y	null	頁腳配置
16	learnMoreConfig	json	Y	null	站點介紹 FAQ 配置
17	customerServiceConfig	json	Y	null	客服設置
18	domains	json	Y	null	域名設置
19	oauthProviders	json	Y	null	三方登入設定
20	gameProviders	json	Y	null	遊戲商 API 設定
21	serviceProviders	json	Y	null	服務商設定
22	templateVariables	json	Y	null	模板變數
23	notificationConfig	json	Y	null	自動通知設定
24	enabled	tinyint(1)	N	1	是否啟用
25	createdAt	datetime	N	CURRENT_TIMESTAMP	建立時間
26	updatedAt	datetime	N	CURRENT_TIMESTAMP	更新時間

JSON 欄位結構詳細說明：

depositMethods 結構

json

{
  "fiat": true,
  "credit": true,
  "crypto": true
}

customerServiceConfig 結構

json

{
  "channels": [
    {
      "type": "line",
      "label": { "zh-TW": "LINE 客服", "en-US": "LINE Support" },
      "icon": "line-icon-url",
      "link": "https://line.me/...",
      "sortOrder": 1,
      "enabled": true
    }
  ],
  "liveChatScript": "<script>...</script>",
  "liveChatEnabled": false
}

domains 結構

json

[
  {
    "hostname": "www.c9.com",
    "browserTitle": "C9 Entertainment",
    "browserDescription": "Best online entertainment platform",
    "logoSmall": "https://cdn.example.com/logo-small.png",
    "logoBig": "https://cdn.example.com/logo-big.png",
    "favicon": "https://cdn.example.com/favicon.ico",
    "supportedLocales": ["zh-TW", "en-US"]
  }
]

oauthProviders 結構

json

{
  "google": {
    "clientId": "xxx.apps.googleusercontent.com",
    "clientSecret": "xxx",
    "redirectUri": "https://www.c9.com/redirect/google-callback"
  },
  "telegram": {
    "botToken": "xxx:xxx",
    "botUsername": "C9Bot"
  },
  "domainWhitelist": ["www.c9.com", "m.c9.com"]
}

gameProviders 結構

json

{
  "rsg": {
    "apiUrl": "https://api.rsg.com",
    "clientId": "xxx",
    "clientSecret": "xxx",
    "desKey": "xxx",
    "desIv": "xxx",
    "systemCode": "xxx",
    "webId": "xxx"
  },
  "betsolutions": {
    "apiUrl": "https://api.betsolutions.com",
    "authUrl": "https://auth.betsolutions.com",
    "merchantId": "12345",
    "privateKey": "xxx"
  },
  "liveSports": {
    "apiKey": "xxx"
  }
}

serviceProviders 結構

json

{
  "resend": {
    "apiKey": "re_xxx",
    "from": "noreply@c9.com"
  },
  "twilio": {
    "accountSid": "ACxxx",
    "authToken": "xxx",
    "verifyServiceSid": "VAxxx"
  },
  "r2": {
    "bucketName": "c9-storage",
    "endpoint": "https://xxx.r2.cloudflarestorage.com",
    "accessKeyId": "xxx",
    "secretAccessKey": "xxx",
    "publicUrl": "https://cdn.c9.com"
  }
}

notificationConfig 結構

json

{
  "welcomeRegistration": true,
  "depositSuccess": true,
  "withdrawalApproved": true,
  "withdrawalRejected": true,
  "withdrawalCompleted": true
}

bottomBarConfig 結構

json

{
  "mobile": [
    {
      "icon": "home",
      "label": { "zh-TW": "首頁", "en-US": "Home" },
      "link": "/",
      "sortOrder": 1,
      "enabled": true
    },
    {
      "icon": "game",
      "label": { "zh-TW": "遊戲", "en-US": "Games" },
      "link": "/game",
      "sortOrder": 2,
      "enabled": true
    }
  ],
  "desktop": []
}

footerConfig 結構

json

[
  {
    "title": { "zh-TW": "關於我們", "en-US": "About Us" },
    "icon": "info",
    "sortOrder": 1,
    "enabled": true,
    "links": [
      {
        "label": { "zh-TW": "隱私政策", "en-US": "Privacy Policy" },
        "link": "/help",
        "icon": "shield",
        "sortOrder": 1
      }
    ]
  }
]

learnMoreConfig 結構

json

[
  {
    "question": { "zh-TW": "如何註冊帳號？", "en-US": "How to register?" },
    "answer": { "zh-TW": "點擊右上角註冊按鈕...", "en-US": "Click the register button..." },
    "sortOrder": 1,
    "enabled": true
  }
]

game-provider（遊戲供應商）

#	欄位名稱	DB 型別	可空	預設值	說明
1	id	int (PK, AI)	N	-	主鍵
2	gameCode	varchar(255)	N	-	遊戲代碼
3	siteCode	varchar(30)	N	'C9'	所屬站點代碼
4	providerCode	varchar(20)	N	''	對接遊戲商 API：rsg / betsolutions
5	gameType	int	N	-	遊戲類型 (1-10)
6	areaBlock	tinyint(1)	N	0	地區封鎖
7	maintain	tinyint(1)	N	0	維護中
8	enable	tinyint(1)	N	1	是否啟用
9	label	json	Y	null	多語系顯示名稱
10	sortOrder	int	N	0	排序權重 (越小越前)
11	isHot	tinyint(1)	N	0	是否為熱門遊戲
12	createdAt	datetime	N	CURRENT_TIMESTAMP	建立時間

12.26 後台列表頁面欄位規格

以下列出各後台列表頁面的表格欄位，供開發及設計參考。

管理員列表 (/system/admins)

欄位	說明	排序
#	序號	-
帳號	管理員 Email	-
名稱	管理員名稱	-
群組	所屬權限群組	-
狀態	啟用/停用 (StatusBadge)	-
2FA	Google Auth 啟用狀態	-
建立時間	createdAt	-
操作	編輯、刪除	-

群組列表 (/system/groups)

欄位	說明	排序
#	序號	-
群組名稱	name	-
群組類型	groupType (StatusBadge)	-
成員數	該群組的管理員數量	-
權限數	permissions 陣列長度	-
建立時間	createdAt	-
操作	編輯、刪除	-

操作紀錄 (/system/logs)

欄位	說明	排序
#	序號	-
時間	createdAt	Y (desc)
管理員	操作者帳號	-
動作	action 描述	-
目標	操作對象	-
IP	來源 IP 地址	-
詳情	展開查看完整 detail	-

存款訂單 (/finance/deposit-review)

欄位	說明	排序
#	序號	-
訂單編號	subOrder	-
用戶 ID	userId	-
用戶帳號	account (join auth-user)	-
支付方式	paymentMethod (fiat/credit/crypto)	-
申請金額	orderAmount (USD)	-
入帳金額	usdAmount (USD)	-
匯率	exchangeRate	-
狀態	status (StatusBadge)	-
申請時間	createdAt	Y (desc)
操作	審核 (approve/reject)	-

提款訂單 (/finance/withdrawals)

欄位	說明	排序
#	序號	-
用戶 ID	userId	-
用戶帳號	account (join auth-user)	-
提領金額	amount (USD)	-
目標地址	address (快照)	-
鏈路	network (TRC-20 等)	-
狀態	status (StatusBadge)	-
審核人	reviewedBy	-
申請時間	createdAt	Y (desc)
操作	審核/上傳憑證/完成	-

銀行卡列表 (/finance/bank-cards)

欄位	說明	排序
#	序號	-
用戶 ID	userId	-
用戶帳號	account	-
銀行代碼	bankCode	-
銀行名稱	bankName	-
帳號	accountNumber (部分遮罩)	-
持卡人	cardHolder	-
狀態	status (StatusBadge)	-
建立時間	createdAt	Y (desc)
操作	審核 (approve/reject)	-

信用卡列表 (/finance/credit-cards)

欄位	說明	排序
#	序號	-
用戶 ID	userId	-
用戶帳號	account	-
卡號	cardNumber (部分遮罩)	-
持卡人	cardHolder	-
到期日	expiryDate	-
狀態	status (StatusBadge)	-
建立時間	createdAt	Y (desc)
操作	審核 (approve/reject)	-

加密地址列表 (/finance/crypto-addresses)

欄位	說明	排序
#	序號	-
用戶 ID	userId	-
用戶帳號	account	-
鏈路	network (TRC-20/ERC-20)	-
幣種	currency (USDT)	-
地址	address (部分遮罩)	-
狀態	status (StatusBadge)	-
建立時間	createdAt	Y (desc)
操作	審核 (approve/reject)	-

活動列表 (/activity/promos)

欄位	說明	排序
#	序號	-
縮圖	imgPc 預覽	-
標題	title (當前語系)	-
標籤	tagId → tag name	-
類型	conditions.type	-
獎勵	reward (USD)	-
打碼倍率	turnoverMultiplier	-
狀態	status (StatusBadge)	-
開始日期	startDate	-
結束日期	endDate	-
操作	編輯、刪除	-

活動標籤 (/activity/tags)

欄位	說明	排序
#	序號	-
名稱	name (多語系，顯示當前語系)	-
排序	sortOrder	-
建立時間	createdAt	-
操作	編輯、刪除	-

VIP 等級列表 (/vip/levels)

欄位	說明	排序
#	序號	-
等級	level 編號	Y (asc)
名稱	name (當前語系)	-
階級	tier (bronze/gold/platinum/diamond)	-
升級門檻	minChip (USD)	-
保級門檻	relegationChip (USD)	-
排序	sortOrder	-
狀態	enabled (StatusBadge)	-
操作	編輯、刪除	-

VIP 返水設定 (/vip/rebates)

欄位	說明	排序
VIP 等級	level (行標題)	Y (asc)
Sports	rebateRate for gameType=1	-
Slot	rebateRate for gameType=2	-
Live	rebateRate for gameType=3	-
Lottery	rebateRate for gameType=4	-
Chess	rebateRate for gameType=5	-
Esports	rebateRate for gameType=8	-
Crypto	rebateRate for gameType=9	-
Fish	rebateRate for gameType=10	-

返水設定以矩陣表格呈現（等級 x 遊戲類型），每格為 decimal(5,2) 百分比值。

遊戲供應商列表 (/game/providers)

欄位	說明	排序
#	序號	-
遊戲代碼	gameCode	-
名稱	label (當前語系)	-
對接商	providerCode (rsg/betsolutions)	-
遊戲類型	gameType (中文名稱)	-
排序	sortOrder	Y (asc)
熱門	isHot (icon)	-
維護	maintain (icon)	-
狀態	enable (StatusBadge)	-
操作	編輯、刪除	-

遊戲分類列表 (/game/type-configs)

欄位	說明	排序
#	序號	-
遊戲類型	gameType ID + 名稱	-
名稱	name (當前語系)	-
圖示	icon URL 預覽	-
排序	sortOrder	Y (asc)
狀態	enable (StatusBadge)	-
操作	編輯、刪除	-

代理列表 (/affiliate/agents)

欄位	說明	排序
#	序號	-
用戶 ID	userId	-
帳號	account	-
代理碼	agentCode	-
代理等級	agentTier	-
直屬下線數	level1DownlineCount	-
總下線數	totalDownlineCount	-
累計佣金	totalEarned (USD)	-
建立時間	createdAt	Y (desc)
操作	查看詳情	-

佣金結算列表 (/affiliate/settlements)

欄位	說明	排序
#	序號	-
代理 ID	agentId	-
代理帳號	agentAccount	-
結算週期	weekStart ~ weekEnd	-
類型	periodType (weekly/daily)	-
活躍下線	activeMemberCount	-
下線淨輸	totalNetLoss (USD)	-
佣金總額	totalCommission (USD)	-
風控	riskFlagged (icon)	-
狀態	status (StatusBadge)	-
操作	審核、查看風控紀錄	-

IP 黑白名單 (/risk-control/ip-rules)

欄位	說明	排序
#	序號	-
IP 地址	ip	-
類型	type (blacklist/whitelist)	-
備註	note	-
建立時間	createdAt	Y (desc)
操作	編輯、刪除	-

遊戲黑名單 (/risk-control/game-blacklist)

欄位	說明	排序
#	序號	-
用戶 ID	userId	-
用戶帳號	account	-
遊戲類型	gameType (名稱或 "全部")	-
遊戲 ID	productId (名稱或 "全部")	-
備註	note	-
建立時間	createdAt	Y (desc)
操作	編輯、刪除	-

投注紀錄報表 (/reports/bet-records)

欄位	說明	排序
#	序號	-
用戶 ID	userId	-
用戶帳號	account	-
遊戲代碼	gameCode	-
遊戲類型	gameType (名稱)	-
遊戲平台	providerCode	-
投注金額	betAmount (USD)	-
有效投注	betEffective (USD)	-
派彩金額	payoutAmount (USD)	-
狀態	status (StatusBadge)	-
時間	createdAt	Y (desc)

玩家報表 (/reports/players)

欄位	說明	排序
#	序號	-
用戶 ID	userId	-
帳號	account	-
VIP 等級	vipLevel	-
餘額	balance (USD)	-
總投注	totalBet (USD)	-
總派彩	totalPayout (USD)	-
總存款	totalDeposit (USD)	-
總提款	totalWithdrawal (USD)	-
註冊時間	createdAt	Y (desc)

損益報表 (/reports/profit-loss)

欄位	說明	排序
日期/週/月	分組維度	Y (desc)
存款金額	totalDeposit (USD)	-
提款金額	totalWithdrawal (USD)	-
投注金額	totalBet (USD)	-
派彩金額	totalPayout (USD)	-
反水金額	totalRebate (USD)	-
活動獎勵	totalPromo (USD)	-
淨利潤	netProfit (USD)	-

遊戲報表 (/reports/games)

欄位	說明	排序
遊戲代碼	gameCode	-
遊戲名稱	gameName (當前語系)	-
遊戲類型	gameType (名稱)	-
遊戲平台	providerCode	-
總投注	totalBet (USD)	-
總派彩	totalPayout (USD)	-
投注人次	betCount	-
RTP	returnToPlayer (%)	-

總覽報表 (/reports/overview)

統計卡片 (Summary Cards)：

卡片	說明
總用戶數	平台註冊用戶總數
今日新增	今日新註冊用戶數
今日存款	今日存款總額 (USD)
今日提款	今日提款總額 (USD)
今日投注	今日投注總額 (USD)
今日派彩	今日派彩總額 (USD)

每日摘要表格 (Daily Summary)：

欄位	說明
日期	date
新增用戶	newUsers
活躍用戶	activeUsers
存款金額	deposits (USD)
提款金額	withdrawals (USD)
投注金額	bets (USD)
派彩金額	payouts (USD)
淨利潤	netProfit (USD)

12.27 前台元件樹狀結構

以下為前台 (c9-ec) A1 佈局的元件樹狀結構，展示各頁面的主要元件組成。

A1/
├── Layout/
│   ├── BottomBar.vue           # 行動版底部導航列
│   ├── Footer.vue              # 頁尾（含連結群組、版權資訊）
│   ├── LiveChat.vue            # LiveChat 嵌入腳本元件
│   ├── Sidebar.vue             # 左側側邊欄（行動版抽屜）
│   └── TitleBar.vue            # 頂部標題列
│
├── Home/
│   ├── index.vue               # 首頁主元件
│   ├── Banner.vue              # 輪播橫幅
│   ├── Promo.vue               # 活動快捷入口
│   └── LiveSports.vue          # 即時賽事比分
│
├── Game/
│   ├── index.vue               # 遊戲大廳主元件
│   ├── Lobby.vue               # 遊戲大廳（遊戲列表 + 類型篩選）
│   ├── Provider.vue            # 遊戲商標籤切換
│   ├── ListBar.vue             # 遊戲列表工具列
│   ├── Search.vue              # 遊戲搜尋
│   ├── RankList.vue            # 遊戲排行榜
│   ├── LoadMore.vue            # 載入更多按鈕
│   ├── Empty.vue               # 無遊戲提示
│   └── Play.vue                # 遊戲進行頁面（iframe 嵌入）
│
├── Promo/
│   ├── Center.vue              # 活動中心列表
│   └── Detail.vue              # 活動詳情頁
│
├── Mission/
│   └── index.vue               # 任務系統（日/週/月任務列表 + 進度條）
│
├── Help/
│   └── Center.vue              # 幫助中心（手風琴 FAQ）
│
├── Alliance/
│   └── index.vue               # 聯盟資訊頁面
│
├── User/
│   ├── Setting.vue             # 個人設定（帳號資訊、密碼修改、2FA、語系、Avatar）
│   │
│   ├── Deposit/
│   │   ├── index.vue           # 存款主頁（支付方式選擇）
│   │   ├── Fiat.vue            # 法幣存款（ATM/銀行轉帳）
│   │   ├── Credit.vue          # 信用卡存款
│   │   └── Crypto.vue          # 加密貨幣存款
│   │
│   ├── Withdrawal/
│   │   └── index.vue           # 提領主頁（錢包選擇 + 金額輸入 + 驗證）
│   │
│   ├── Wallet/
│   │   ├── index.vue           # 錢包管理主頁
│   │   ├── Fiat.vue            # 銀行卡管理
│   │   ├── Credit.vue          # 信用卡管理
│   │   └── Crypto.vue          # 加密地址管理
│   │
│   ├── Vip/
│   │   ├── index.vue           # VIP 主頁
│   │   ├── StatusCard.vue      # VIP 狀態卡片（等級、進度條）
│   │   ├── Benefits.vue        # VIP 權益展示
│   │   ├── LevelList.vue       # VIP 等級列表
│   │   ├── RebateTable.vue     # 返水費率表
│   │   └── MyRebates.vue       # 我的返水紀錄
│   │
│   ├── Affiliate/
│   │   ├── index.vue           # 代理推廣主頁
│   │   ├── Dashboard.vue       # 代理儀表板（概覽數據）
│   │   ├── Commission.vue      # 佣金紀錄
│   │   ├── Settlement.vue      # 結算紀錄
│   │   ├── Downline.vue        # 下線管理
│   │   ├── Withdrawal.vue      # 代理提款
│   │   └── Alliance.vue        # 聯盟資訊
│   │
│   ├── Transaction/
│   │   ├── index.vue           # 交易紀錄主頁
│   │   ├── Deposit.vue         # 存款紀錄
│   │   ├── Withdrawal.vue      # 提款紀錄
│   │   ├── Dividend.vue        # 分紅紀錄
│   │   └── Promo.vue           # 活動獎勵紀錄
│   │
│   ├── BetRecord/
│   │   └── index.vue           # 投注紀錄
│   │
│   ├── Inbox/
│   │   └── index.vue           # 站內信
│   │
│   └── Kyc/
│       ├── index.vue           # KYC 身份驗證主頁
│       ├── StatusCard.vue      # KYC 狀態卡片
│       ├── StepBasicInfo.vue   # 步驟一：基本資料
│       ├── StepDocUpload.vue   # 步驟二：文件上傳
│       ├── StepLiveness.vue    # 步驟三：活體驗證
│       └── StepReview.vue      # 步驟四：審核中
│
├── Modal/
│   ├── Login.vue               # 登入彈窗（帳密 + Google + Telegram）
│   ├── Register.vue            # 註冊彈窗
│   ├── Locale.vue              # 語系切換彈窗
│   ├── Theme.vue               # 主題切換彈窗
│   ├── ContactSupport.vue      # 聯繫客服彈窗（8 種管道列表）
│   ├── AgentTour.vue           # 代理導覽彈窗（新手引導）
│   ├── BuyCrypto.vue           # 購買加密貨幣引導彈窗
│   ├── VerifyUserInfo.vue      # 用戶資訊驗證彈窗
│   ├── EditPassword.vue        # 修改密碼彈窗
│   ├── SetPassword.vue         # 設定密碼彈窗（OAuth 用戶首次設定）
│   ├── BindGoogleAuth.vue      # 綁定 Google Authenticator 彈窗
│   ├── AddBankCard.vue         # 新增銀行卡彈窗
│   ├── AddCreditCard.vue       # 新增信用卡彈窗
│   ├── AddCryptoAddress.vue    # 新增加密地址彈窗
│   └── BankCardDetail.vue      # 銀行卡詳情彈窗
│
└── PromoLinkCard.vue           # 活動連結卡片（共用）

12.28 前台 Store 完整清單

Store 檔案	Store 名稱	持久化	主要狀態
auth.ts	useAuthStore	localStorage (token)	user, token, isAuthenticated, loginType
config.ts	useConfigStore	-	siteConfig, theme, domainConfig
game.ts	useGameStore	-	providers, typeConfigs, searchKeyword, activeType
modal.ts	useModalStore	-	loginVisible, registerVisible, localeVisible, themeVisible, supportVisible, agentTourVisible
deposit.ts	useDepositStore	-	selectedChannel, amount, currency, exchangeRate

useAuthStore 方法列表

方法	說明
setToken(token)	設定 JWT Token（寫入 localStorage）
clearToken()	清除 Token
setUser(user)	設定用戶資訊
logout()	登出（清除 token + user）
refreshUserDetail()	重新取得用戶資訊

useModalStore 方法列表

方法	說明
openLogin()	開啟登入彈窗
openRegister()	開啟註冊彈窗
openLocale()	開啟語系選擇彈窗
openTheme()	開啟主題選擇彈窗
openSupport()	開啟客服彈窗
openAgentTour()	開啟代理導覽彈窗
closeAll()	關閉所有彈窗

useConfigStore 方法列表

方法	說明
fetchPublicConfig()	取得站點公開設定
fetchTheme()	取得站點主題
applyTheme(theme)	套用主題 CSS 變數
getSiteName()	取得站點名稱（當前語系）

以下為後台 sidebar 的完整導航結構，包含群組、項目、路由、權限、圖示。

群組	項目	路由	權限	圖示
儀表板	儀表板	/dashboard	-	LayoutDashboard
系統管理	管理員管理	/system/admins	admin:read	Users
系統管理	群組管理	/system/groups	admin-group:read	Shield
系統管理	操作紀錄	/system/logs	admin-log:read	FileText
系統管理	站點基本設定	/system/site-config	site-config:read	Settings
系統管理	三方登入	/system/site-oauth	site-config:read	Key
系統管理	遊戲商配置	/system/site-game-providers	site-config:read	Gamepad2
系統管理	服務商配置	/system/site-service-providers	site-config:read	Server
系統管理	客服配置	/system/site-customer-service	site-config:read	Headphones
系統管理	域名設置	/system/site-domains	site-config:read	Globe
系統管理	雲端儲存	/system/cloud-storage	admin:read	Cloud
系統管理	雲端儲存日誌	/system/cloud-storage-logs	admin:read	History
前台佈局	底部導航列	/system/layout-bottom-bar	site-config:read	Dock
前台佈局	頁尾	/system/layout-footer	site-config:read	PanelBottom
前台佈局	了解更多	/system/layout-learn-more	site-config:read	HelpCircle
玩家管理	全部玩家	/players/all	user:read	Users
玩家管理	新註冊玩家	/players/new-registrations	user:read	UserPlus
玩家管理	線上玩家	/players/online	user:read	Activity
玩家管理	登入失敗紀錄	/players/login-failures	user:read	AlertTriangle
玩家管理	玩家標籤	/players/tags	user:read	Tag
玩家管理	遊戲重新註冊	/players/game-reregistration	user:read	RefreshCw
遊戲管理	遊戲供應商	/game/providers	game:read	Gamepad
遊戲管理	遊戲類型設定	/game/type-configs	game:read	Layers
VIP	VIP 等級	/vip/levels	vip:read	Crown
VIP	返水設定	/vip/rebates	vip:read	Percent
VIP	VIP 玩家	/vip/players	vip:read	Star
VIP	VIP 里程碑	/vip/milestones	vip:read	Flag
活動管理	優惠活動	/activity/promos	promo:read	Gift
活動管理	活動標籤	/activity/tags	promo-tag:read	Tags
郵件管理	站內信	/mail/inbox	admin:read	Mail
郵件管理	郵件設定	/mail/settings	admin:read	MailCog
財務管理	人工調節金額	/finance/adjust-balance	finance:write	Calculator
財務管理	存款設置	/finance/deposit-settings	vendor:read	Settings2
財務管理	存款訂單	/finance/deposit-review	deposit:read	FileInput
財務管理	提款訂單	/finance/withdrawals	withdrawal:read	FileOutput
財務管理	銀行卡列表	/finance/bank-cards	finance:read	CreditCard
財務管理	信用卡列表	/finance/credit-cards	finance:read	CreditCard
財務管理	虛擬錢包地址	/finance/crypto-addresses	finance:read	Wallet
代理中心	代理列表	/affiliate/agents	affiliate:read	Network
代理中心	佣金費率	/affiliate/commission-rates	affiliate:read	Percent
代理中心	佣金結算	/affiliate/settlements	affiliate:read	Receipt
代理中心	代理提領	/affiliate/aff-withdrawals	affiliate:read	ArrowDownCircle
代理中心	綁定紀錄	/affiliate/bind-logs	affiliate:read	Link
代理中心	代理等級	/affiliate/agent-tiers	affiliate:read	Layers
代理中心	VIP 里程碑	/affiliate/vip-milestones	affiliate:read	Flag
代理中心	代理導覽	/affiliate/agent-tour	affiliate:read	Compass
風控管理	IP 黑白名單	/risk-control/ip-rules	risk:read	Shield
風控管理	IP/FP 檢查	/risk-control/ip-check	risk:read	Search
風控管理	遊戲黑名單	/risk-control/game-blacklist	risk:read	Ban
報表	總覽	/reports/overview	report:read	BarChart3
報表	玩家報表	/reports/players	report:read	Users
報表	玩家摘要	/reports/player-summary	report:read	FileBarChart
報表	投注紀錄	/reports/bet-records	report:read	Dices
報表	損益報表	/reports/profit-loss	report:read	TrendingUp
報表	遊戲報表	/reports/games	report:read	Gamepad2
報表	活動報表	/reports/promos	report:read	Gift

總計：14 個群組、55+ 個導航項目

12.30 主題色彩系統

主題色 CSS 變數（OKLCH 色彩空間）

後台使用 OKLCH 色彩空間定義主題色。每個站點可建立多組主題，透過 activeThemeId 切換。

CSS 變數	用途	範例值
--color-primary	主色	oklch(0.7 0.2 250)
--color-primary-light	主色淺	oklch(0.85 0.15 250)
--color-primary-dark	主色深	oklch(0.55 0.25 250)
--color-accent	強調色	oklch(0.75 0.18 130)
--color-accent-light	強調色淺	oklch(0.88 0.12 130)
--color-accent-dark	強調色深	oklch(0.6 0.22 130)
--color-surface	表面色	oklch(0.98 0.01 250)
--color-surface-alt	替代表面色	oklch(0.95 0.02 250)
--color-text	文字色	oklch(0.2 0.02 250)
--color-text-muted	次要文字色	oklch(0.55 0.02 250)
--color-border	邊框色	oklch(0.85 0.01 250)
--color-border-light	淺邊框色	oklch(0.92 0.01 250)

前台內建主題預設

前台 (c9-ec) 內建 6 組主題預設，各站點可透過後台自訂或使用預設：

主題名稱	主色調	風格說明
經典深藍	深藍色	穩重專業的經典娛樂城風格
炫金奢華	金色	高端奢華的 VIP 風格
科技紫	紫色	現代科技感風格
極光綠	綠色	清新自然的環保風格
烈焰紅	紅色	熱情活力的刺激風格
霓虹粉	粉紅	年輕時尚的潮流風格

site-theme 資料表

欄位	DB 型別	說明
id	int (PK)	主鍵
siteConfigId	int (FK)	關聯站點 ID
name	varchar(50)	主題名稱
primary	varchar(100)	主色
primaryLight	varchar(100)	主色淺
primaryDark	varchar(100)	主色深
accent	varchar(100)	強調色
accentLight	varchar(100)	強調色淺
accentDark	varchar(100)	強調色深
surface	varchar(100)	表面色
surfaceAlt	varchar(100)	替代表面色
text	varchar(100)	文字色
textMuted	varchar(100)	次要文字色
border	varchar(100)	邊框色
borderLight	varchar(100)	淺邊框色
createdAt	datetime	建立時間
updatedAt	datetime	更新時間

12.31 API 請求/回應範例

以下為核心 API 的請求與回應範例，供前後端對接參考。

用戶註冊

Request:

POST /api/auth/register
Headers:
  Content-Type: application/json
  site-name: C9
  locales: zh-TW

Body:
{
  "account": "user001",
  "password": "P@ssw0rd123",
  "name": "測試用戶",
  "refCode": "AGT123",
  "device": "fp_abc123def456"
}

Response (Success):

json

{
  "code": 200,
  "message": "ok",
  "result": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 42,
      "account": "user001",
      "name": "測試用戶",
      "email": null,
      "vipLevel": "1",
      "balance": "0.000000",
      "locale": "zh-TW",
      "avatar": null,
      "agentCode": null
    }
  },
  "timestamp": "2026-03-01T12:00:00.000Z",
  "path": "/api/auth/register"
}

Response (Error):

json

{
  "code": 2001,
  "message": "帳號已存在",
  "timestamp": "2026-03-01T12:00:00.000Z",
  "path": "/api/auth/register"
}

用戶登入

Request:

POST /api/auth/login
Headers:
  Content-Type: application/json
  site-name: C9
  locales: zh-TW

Body:
{
  "account": "user001",
  "password": "P@ssw0rd123",
  "device": "fp_abc123def456"
}

Response (Success):

json

{
  "code": 200,
  "message": "ok",
  "result": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "user": {
      "id": 42,
      "account": "user001",
      "name": "測試用戶",
      "email": "user001@test.com",
      "vipLevel": "3",
      "balance": "1250.500000",
      "frozenBalance": "100.000000",
      "locale": "zh-TW",
      "avatar": "https://cdn.c9.com/mascots/01.png",
      "agentCode": "AGT042",
      "googleAuthEnabled": 0
    }
  },
  "timestamp": "2026-03-01T12:00:00.000Z",
  "path": "/api/auth/login"
}

建立存款訂單

Request:

POST /api/deposit
Headers:
  Content-Type: application/json
  Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
  site-name: C9
  locales: zh-TW

Body:
{
  "channelId": 1,
  "paymentMethod": "fiat",
  "amount": 100
}

Response (Success):

json

{
  "code": 200,
  "message": "ok",
  "result": {
    "orderId": 156,
    "subOrder": "DEP20260301120000001",
    "orderAmount": "100.000000",
    "vendorAmount": 3080,
    "currency": "TWD",
    "exchangeRate": "30.800000000",
    "paymentUrl": "https://pay.vendor.com/order?id=xxx",
    "status": "created"
  },
  "timestamp": "2026-03-01T12:00:00.000Z",
  "path": "/api/deposit"
}

後台管理員登入

Request:

POST /api/admin/login
Headers:
  Content-Type: application/json
  locales: zh-TW

Body:
{
  "email": "admin@c9.com",
  "password": "admin123",
  "totpCode": "123456"
}

Response (Success):

json

{
  "code": 200,
  "message": "ok",
  "result": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "admin": {
      "id": 1,
      "email": "admin@c9.com",
      "name": "Root Admin",
      "groupId": 1,
      "groupType": "root",
      "googleAuthEnabled": 1
    }
  },
  "timestamp": "2026-03-01T12:00:00.000Z",
  "path": "/api/admin/login"
}

後台列表查詢 (分頁)

Request:

GET /api/admin/finance/deposit-review/list?page=1&pageSize=20&status=pending&siteCode=C9
Headers:
  Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
  x-site-code: C9
  locales: zh-TW

Response (Success):

json

{
  "code": 200,
  "message": "ok",
  "result": {
    "items": [
      {
        "id": 156,
        "userId": 42,
        "account": "user001",
        "subOrder": "DEP20260301120000001",
        "paymentMethod": "fiat",
        "orderAmount": "100.000000",
        "usdAmount": "0.000000",
        "exchangeRate": "30.800000000",
        "status": "pending",
        "siteCode": "C9",
        "createdAt": "2026-03-01T12:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 20,
      "total": 1,
      "totalPages": 1
    }
  },
  "timestamp": "2026-03-01T12:00:00.000Z",
  "path": "/api/admin/finance/deposit-review/list"
}

取得錯誤碼 (共用列舉)

Request:

GET /api/common/enums
Headers:
  locales: zh-TW

Response:

json

{
  "code": 200,
  "message": "ok",
  "result": {
    "ERROR_CODES": {
      "/api/auth/register": {
        "2001": "帳號已存在",
        "2002": "推廣碼不存在",
        "2003": "Email 已存在"
      },
      "/api/auth/login": {
        "2001": "帳號或密碼錯誤",
        "2002": "帳號已停用"
      },
      "/api/game/launch": {
        "5010": "您已被限制進入此遊戲"
      }
    }
  }
}

12.32 資料精度計算範例

USD 截斷規則

所有 USD 金額使用 decimal(18,6) 儲存，計算後使用無條件捨去 (Math.floor)：

truncateUsd(value) = Math.floor(value * 1e6) / 1e6

計算範例：

原始值	截斷後	說明
100.1234567	100.123456	保留 6 位小數
50.9999999	50.999999	無條件捨去，非四捨五入
0.000001	0.000001	最小有效金額
0.0000001	0.000000	低於精度被捨去

匯率換算範例

以 TWD → USD 為例：

用戶存入 TWD 30,000
當前匯率 1 USD = 30.80 TWD (decimal(18,10))

usdAmount = 30000 / 30.80 = 974.025974025...
truncateUsd(974.025974025...) = 974.025974

入帳金額 = USD 974.025974

返水計算範例

以 VIP 3 等級、Slot 遊戲為例：

用戶 VIP 等級 = 3
遊戲類型 = Slot (2)
返水費率 = 0.50% (decimal(5,2))
昨日有效投注 = USD 10,000.000000

反水金額 = 10000.000000 * 0.50 / 100
         = 50.000000

truncateUsd(50.000000) = USD 50.000000

發放：auth-user.balance += 50.000000
記錄：vip-rebate-log 新增一筆

活動打碼量計算範例

以首存活動為例：

活動：首存送 50%，打碼倍率 = 15x
用戶存款 = USD 100.000000
活動獎勵 = 100.000000 * 50% = USD 50.000000

所需打碼量 = 50.000000 * 15 = USD 750.000000

用戶投注：
  Slot 投注 500 (權重 1.0) → 打碼扣減 500
  剩餘打碼量 = 750 - 500 = 250

  Crypto 投注 200 (權重 0.5) → 打碼扣減 100
  剩餘打碼量 = 250 - 100 = 150

  Live 投注 200 (權重 1.0) → 打碼扣減 200
  剩餘打碼量 = max(0, 150 - 200) = 0 → 打碼完成

12.33 多語系 JSON 欄位慣例

欄位儲存格式

系統中所有需要多語系的欄位統一使用 JSON 格式儲存，key 為語系代碼，value 為對應語言文字：

json

{
  "zh-TW": "繁體中文文字",
  "en-US": "English Text",
  "zh-CN": "简体中文文字",
  "th-TH": "ข้อความภาษาไทย",
  "vi-VN": "Văn bản tiếng Việt"
}

使用此格式的資料表欄位

資料表	欄位名稱	用途
site-config	siteName	站點名稱
site-config	siteDescription	站點介紹
vip-level	name	VIP 等級名稱
game-provider	label	遊戲商顯示名稱
game-type-config	name	遊戲分類名稱
promo	title	活動標題
promo	description	活動描述
promo	content	活動內容 (HTML)
promo	imgPc	PC 版橫幅圖片 URL
promo	imgMobile	手機版橫幅圖片 URL
promo-tag	name	活動標籤名稱
notification	title	站內信標題
notification	content	站內信內容 (HTML)
mission	name	任務名稱
mission	description	任務描述
alliance-agent-tier	name	代理等級名稱

後端 resolveText() 函數

resolveText(jsonField, locale?)

解析順序：
1. jsonField[currentLocale]     → 當前語系
2. jsonField['zh-TW']           → zh-TW fallback
3. Object.values(jsonField)[0]  → 第一個有值的語系
4. ''                           → 空字串 fallback

12.34 系統安全機制

密碼安全

項目	規格
雜湊演算法	bcrypt (bcryptjs)
雜湊輪數	10 rounds (預設)
密碼儲存	只儲存 hash，永不儲存明文
密碼驗證	bcrypt.compare()

JWT Token 安全

項目	前台用戶	後台管理員
Secret	JWT_SECRET	ADMIN_JWT_SECRET (fallback JWT_SECRET)
過期時間	7 天	7 天
Payload	sub, account, tokenVersion	sub, email, tokenVersion, role, groupId, groupType
Token Version	支援（強制登出機制）	支援（強制登出機制）
Cache TTL	60 秒 (token version 快取)	60 秒 (token version 快取)

Token Version 強制登出機制

1. 正常登入：生成 JWT，寫入 tokenVersion (例如 5)
2. JWT 驗證：
   a. 取 cache:auth:tv:{userId}
   b. cache miss → 查 DB → 寫入 cache (60s TTL)
   c. 比對 JWT.payload.tokenVersion === DB.tokenVersion
   d. 不一致 → 401 Unauthorized

3. 強制登出：
   a. DB: auth-user.tokenVersion++ (從 5 → 6)
   b. Cache 過期 (最多 60s)
   c. 下次 JWT 驗證時 5 !== 6 → 401

效果：更改密碼後最多 60 秒內所有舊 token 失效

2FA (Google Authenticator)

項目	說明
演算法	TOTP (Time-based One-Time Password)
庫	speakeasy
Secret 儲存	auth-user.googleAuthSecret / admin-user.googleAuthSecret
啟用標記	googleAuthEnabled (0/1)
驗證碼	6 位數字，30 秒有效期
QR Code	使用 qrcode 庫生成

CORS 設定

origin: true          → 允許所有來源（開發環境）
credentials: true     → 允許攜帶 cookie

Request Validation

ValidationPipe:
  whitelist: true     → 自動移除 DTO 未定義的欄位
  transform: true     → 自動型別轉換 (query string → number)

12.35 開發環境 Port 分配

服務	Port	URL
c9-ec (前台)	3010	http://localhost:3010
c9-ims (後台)	3011	http://localhost:3011
c9-be (後端)	8080	http://localhost:8080/api
Swagger UI	8080	http://localhost:8080/api/docs
MySQL	3306	localhost:3306
Redis	6379	localhost:6379

12.36 業務規則邊界條件

以下列出各模組的業務規則邊界條件與特殊情境處理，供開發及 QA 測試參考。

用戶註冊相關

規則	說明
帳號唯一性	同一 siteCode 下帳號不可重複
Email 唯一性	同一 siteCode 下 email 不可重複（null 除外）
手機唯一性	同一 siteCode 下手機不可重複（null 除外）
推廣碼綁定	註冊時若帶 refCode，自動綁定上線代理（最多 3 層）
推廣碼不存在	推廣碼無效時回傳錯誤碼 2002，不建立帳號
金流群組分配	註冊時根據語系自動分配金流群組
OAuth 自動綁定	Google/Telegram 登入時，新用戶自動建立帳號
OAuth 補綁	既有用戶 Google 欄位為空時，登入後自動補綁
裝置指紋	若前端傳入 device，記錄於 login-log；否則 fallback UA
初始 VIP	新用戶預設 VIP 等級 = 1
初始餘額	新用戶預設 balance = 0.000000

存款相關

規則	說明
金額限制	受金流通道 minAmount / maxAmount 限制
匯率快照	建立訂單時快照當前匯率，不隨後續變動
重複入金防護	同一 subOrder 不可重複建立 (UNIQUE 約束)
回調冪等性	金流商可能多次回調，需檢查訂單狀態避免重複入帳
USD 截斷	入帳金額使用 truncateUsd() 無條件捨去
任務進度	存款確認後自動更新存款任務進度
通路開關	受 site-config.depositMethods 控制（fiat/credit/crypto）

提領相關

規則	說明
餘額檢查	提領金額 + 凍結金額 <= 餘額
凍結機制	提領申請時立即凍結金額 (balance -= amount, frozenBalance += amount)
審核拒絕	拒絕時退回凍結金額 (balance += amount, frozenBalance -= amount)
審核通過	核准後凍結金額不變，等待操作員匯款
完成出款	匯款後上傳憑證，標記完成 (frozenBalance -= amount)
錢包驗證	提領目標錢包需已通過審核 (status = 'approved')
地址快照	提領時快照錢包地址，即使後續更改也不影響

VIP 相關

規則	說明
只升不降	投注觸發的等級變動永遠只向上
月度保級	每月 1 號 01:00 檢查，未達保級門檻 relegationMissCount++
降級門檻	連續 2 個月未達保級 → 降一級 (relegationMissCount >= 2)
保級鎖定	vipHold = 1 時不降級（VIP 5+ 手動鎖定）
等級不限	每站 VIP 等級數量不限（不硬編碼 15 級）
反水計算	每日 00:05 結算，按用戶當前 VIP 等級 x 8 種遊戲類型計算
反水精度	rebateAmount = truncateUsd(effectiveBet * rebateRate / 100)
跨站獨立	VIP 等級和反水規則每站獨立配置

代理推廣相關

規則	說明
三層限制	代理綁定最多 3 層 (level1, level2, level3)
推廣碼上限	每人最多 10 個推廣碼
帳號遮罩	代理視角下線帳號使用 maskAccount() 遮罩中間字元
佣金計算	基於下線淨輸 (net loss) 按各遊戲類型 x 代理等級費率計算
風控標記	結算時自動檢測異常下線（新帳號大量投注、IP 重複等）
審核流程	有風控標記的結算需人工審核，無標記的自動核准
日結/週結	週結每週一 03:00，日結每日 03:30
提款三階段	pending → approved → completed

遊戲相關

規則	說明
風控檢查	啟動遊戲前檢查 risk-game-blacklist（錯誤碼 5010）
封鎖優先序	全封鎖 > 類型封鎖 > 特定遊戲封鎖
投注連鎖	投注結算後同步觸發：VIP 重算、打碼量更新、任務進度
遊玩記錄	遊戲啟動後非同步 UPSERT game-play-log（不阻塞主流程）
轉帳錢包	遊戲內下注/派彩透過 S2S 回調更新用戶餘額
試玩模式	部分遊戲支援未登入試玩（使用 OptionalJwtAuthGuard）

活動相關

規則	說明
領取唯一性	同一用戶同一活動只能領取一次 (UNIQUE 約束)
打碼量	領取獎勵後需完成 reward * turnoverMultiplier 的投注才可提領
打碼權重	Crypto 和 Fish 類型投注權重為 0.5，其他為 1.0
多語系內容	title, description, content 均為多語系 JSON
圖片	imgPc 和 imgMobile 分別為 PC 版和手機版橫幅
時間限制	活動有 startDate / endDate，過期無法領取
條件觸發	conditions.type 支援 any / first_deposit / deposit_amount

站內信相關

規則	說明
發送對象	支援全體用戶 / 特定用戶 / VIP 等級群組
已讀記錄	notification-read 表記錄每個用戶的已讀狀態
未讀計數	前端定期拉取未讀數量（badge 顯示）
多語系	標題和內容均為多語系 JSON
刪除行為	用戶端刪除為軟刪除（標記已讀），不刪除原始通知
自動通知	支援 5 種自動通知（受 notificationConfig 控制）

任務系統相關

規則	說明
進度更新	存款後自動更新存款任務進度，投注後自動更新投注任務進度
週期重置	每日/每週/每月任務各自獨立的 periodKey
領取條件	進度 >= 目標值才可領取獎勵
領取唯一性	同一任務同一週期只能領取一次 (UNIQUE 約束)
層級機制	同類任務可設定多個 tier（低階到高階，獎勵遞增）

12.37 QA 測試重點清單

以下為各模組的 QA 測試重點，供測試團隊參考。

認證測試

[ ] 帳號註冊（正常流程 + 重複帳號 + 無效推廣碼）
[ ] 帳號登入（正常 + 錯誤密碼 + 停用帳號）
[ ] Google OAuth 登入（新用戶自動建立 + 舊用戶補綁）
[ ] Telegram 登入（新用戶自動建立）
[ ] 2FA 啟用/停用（QR Code → 驗證碼確認）
[ ] JWT Token 過期測試（7 天後失效）
[ ] Token Version 強制登出（修改密碼後驗證）
[ ] 多站點帳號隔離（不同 siteCode 相同帳號可共存）

存款測試

[ ] 法幣存款（ATM 流程完整測試）
[ ] 信用卡存款（建立訂單 + 回調確認）
[ ] 加密貨幣存款（USDT 流程）
[ ] 匯率快照正確性（訂單建立時固定）
[ ] 金額精度（decimal(18,6) 截斷驗證）
[ ] 重複回調冪等性測試
[ ] 金額範圍限制（min/max）
[ ] 任務進度自動更新驗證

提領測試

[ ] 正常提領流程（申請 → 審核 → 完成）
[ ] 餘額不足被拒絕
[ ] 凍結金額正確性（申請時凍結，拒絕時退回）
[ ] 錢包未審核不可提領
[ ] 地址快照驗證（提領後修改錢包不影響）
[ ] 匯款憑證上傳
[ ] 並行提領金額凍結一致性

VIP 測試

[ ] 投注累積自動升級
[ ] 只升不降規則驗證
[ ] 月度保級（未達標 + 連續 2 月降級）
[ ] VIP Hold 保級鎖定
[ ] 每日反水結算正確性
[ ] 反水精度（truncateUsd 驗證）
[ ] 跨站 VIP 獨立性
[ ] 模板帶入測試

多站點測試

[ ] Header 選「全部站點」時 Tab 正確顯示
[ ] Header 選獨立站點時 Tab 僅顯示該站
[ ] 站點切換時資料正確刷新
[ ] siteCode 篩選正確性（API level）
[ ] 「同預設站點」複製功能
[ ] 模板帶入僅影響當前站
[ ] AdminContentWrapper key remount 機制
[ ] x-site-code header 傳遞正確性

權限測試

[ ] root 群組全權限通過
[ ] super_admin 除 site-config 外全通過
[ ] general_admin 只有 read 權限
[ ] custom 群組依 permissions 設定
[ ] 未授權操作返回 403
[ ] 權限快取 60s TTL 測試

12.38 後端模組間依賴關係

以下列出後端各模組之間的依賴關係，幫助理解系統架構。

模組依賴圖

AppModule
├── AuthModule ← → AffiliateModule (forwardRef 循環依賴)
│   └── 依賴：JwtModule, CacheModule, SiteConfigModule
│
├── GameModule
│   ├── 子模組：BetSolutionsModule, RsgModule
│   ├── 依賴：AuthModule (用戶查詢), VipModule (等級重算), PromoModule (打碼量), MissionModule (任務進度)
│   └── 匯入：AdminModule (export AdminRiskService 用於遊戲封鎖檢查)
│
├── DepositModule ← → VendorModule (forwardRef 循環依賴)
│   └── 依賴：AuthModule (用戶餘額), MissionModule (存款任務進度)
│
├── VendorModule
│   ├── 子模組：WantongModule, UsdtModule
│   └── 依賴：DepositModule (訂單更新)
│
├── VipModule
│   ├── 依賴：AuthModule (用戶 VIP 等級更新), AffiliateModule (VIP 里程碑通知)
│   └── Cron：每日反水結算、月度保級檢查
│
├── AffiliateModule
│   ├── 5 個 Service：core, settlement, risk, withdrawal, alliance
│   ├── 依賴：AuthModule (用戶查詢)
│   └── Cron：週結、日結
│
├── PromoModule
│   └── 依賴：AuthModule (用戶餘額增減)
│
├── AdminModule
│   ├── 3 個 Service：admin, admin-report, admin-risk
│   ├── 依賴：幾乎所有其他模組（作為管理入口）
│   └── OnModuleInit：ensureDefaultAdmin()
│
├── SiteConfigModule
│   └── 被大多數模組依賴（站點設定查詢）
│
├── R2Module (@Global)
│   └── 被 AdminModule, SiteConfigModule 依賴（檔案上傳）
│
├── TimeModule (@Global)
│   └── 被所有使用時間的模組依賴
│
├── CommonModule
│   └── OnModuleInit：掃描 i18n 建構 ERROR_CODES
│
├── WalletModule
│   └── 聚合：BankCardModule, CreditCardModule, CryptoAddressModule
│
├── InboxModule
│   └── 依賴：AuthModule (用戶查詢)
│
├── WithdrawalModule
│   └── 依賴：AuthModule (餘額凍結/解凍), WalletModule (錢包驗證)
│
├── MissionModule
│   └── 依賴：AuthModule (用戶餘額增減)
│
├── LiveSportsModule
│   └── Cron：每 30 分鐘快取 API-Football 資料
│
├── RankingModule
│   └── 依賴：BetRecordModule (投注資料)
│
└── BetRecordModule
    └── 獨立模組（僅查詢）

循環依賴解決方式

循環依賴	解決方式	說明
AuthModule ↔ AffiliateModule	`forwardRef(() => AffiliateModule)`	用戶註冊時需綁定代理，代理功能需查詢用戶
DepositModule ↔ VendorModule	`forwardRef(() => VendorModule)`	存款建立需路由至金流商，金流商回調需更新存款訂單

全域模組

模組	裝飾器	說明
R2Module	@Global()	Cloudflare R2 檔案上傳，所有模組可直接注入 R2Service
TimeModule	@Global()	moment-timezone wrapper，所有模組可直接注入 TimeService
CacheModule	isGlobal: true	Redis/in-memory 快取，所有模組可直接注入 CACHE_MANAGER
ConfigModule	isGlobal: true	環境變數，所有模組可直接注入 ConfigService
I18nModule	-	多語系，透過 I18nService 注入

12.39 API 分頁慣例

分頁參數

所有列表 API 統一使用以下分頁參數：

參數	類型	預設值	說明
page	number	1	頁碼（從 1 開始）
pageSize / limit	number	20	每頁筆數

分頁回應格式

json

{
  "items": [...],
  "pagination": {
    "page": 1,
    "pageSize": 20,
    "total": 156,
    "totalPages": 8
  }
}

parsePagination() 工具函數

後端使用 parsePagination(query) 正規化分頁參數：

Input:  { page: '2', pageSize: '30' }
Output: { skip: 30, take: 30, page: 2, pageSize: 30 }

Input:  { page: undefined, pageSize: undefined }
Output: { skip: 0, take: 20, page: 1, pageSize: 20 }

Input:  { page: '-1', pageSize: '0' }
Output: { skip: 0, take: 20, page: 1, pageSize: 20 }  (自動修正)

日期範圍篩選

後端使用 applyDateRange(qb, column, startDate, endDate) 工具函數：

applyDateRange(qb, 'order.createdAt', '2026-01-01', '2026-03-01')

生成 SQL：
  order.createdAt >= '2026-01-01 00:00:00'
  AND order.createdAt <= '2026-03-01 23:59:59'

12.40 R2 檔案儲存路徑慣例

R2 路徑結構

Cloudflare R2 的檔案路徑遵循以下慣例：

{sitePrefix}/
├── promos/                    # 活動橫幅圖片
│   ├── {promoId}/
│   │   ├── pc.jpg             # PC 版橫幅
│   │   └── mobile.jpg         # 手機版橫幅
├── avatars/                   # 用戶頭像/吉祥物
│   ├── mascot-01.png
│   ├── mascot-02.png
│   └── ...
├── domains/                   # 域名相關素材
│   ├── {hostname}/
│   │   ├── logo-small.png     # 小 Logo
│   │   ├── logo-big.png       # 大 Logo
│   │   └── favicon.ico        # Favicon
├── customer-service/          # 客服管道圖示
│   ├── line.png
│   ├── telegram.png
│   └── ...
├── withdrawals/               # 提領匯款憑證
│   ├── {orderId}/
│   │   └── proof.jpg
└── uploads/                   # 管理員上傳的其他檔案
    └── ...

R2 URL 產生

前端使用 useR2Url() composable / hook 產生完整的 R2 公開 URL：

R2_PUBLIC_URL + '/' + filePath
例如：https://cdn.c9.com/c9/promos/1/pc.jpg

檔案操作限制

操作	限制	說明
上傳大小	10MB	單檔最大上傳大小
允許格式	jpg, jpeg, png, gif, webp, svg, ico	圖片檔案
命名規則	自動重新命名（避免衝突）	使用 UUID 或 timestamp
日誌記錄	所有操作記錄到 r2-operation-log	含操作者、IP、UA

12.41 版本歷程

版本	日期	變更說明
v1.0	2026-03-01	初版，涵蓋完整平台規格

文件結束
本文件涵蓋 C9 Entertainment City 平台的完整產品規格，包含 3 個子專案、205+ 個 API 端點、49 張資料表、68 個後台頁面、20 個前台頁面的詳細規格說明。全文共 12 章、41 個附錄小節。
如需更新，請同步修改本文件與相關子專案的 CLAUDE.md。

C9 Entertainment City — 產品規格書 (PM 版) ​

目錄 ​

第 1 章：平台總覽 ​

1.1 平台簡介 ​

1.2 系統架構圖 ​

1.3 技術棧總覽 ​

前台 (c9-ec) ​

後台 (c9-ims) ​

後端 (c9-be) ​

1.4 專案規模統計 ​

c9-ec (前台) ​

c9-ims (後台) ​

c9-be (後端) ​

1.5 支援語系 ​

1.6 服務端口 ​

1.7 統一系統規範 ​

幣別規範 ​

資料精度 ​

統一回應格式 ​

認證機制 ​

第 2 章：功能模組清單 ​

2.1 模組總覽 ​

2.1.1 認證系統 (Auth) — 17 個端點 ​

2.1.2 遊戲系統 (Game) — 17 個端點 ​

2.1.3 金流管理 — 13 個端點 ​

2.1.4 錢包管理 (Wallet) — 9 個端點 ​

2.1.5 VIP 系統 — 13 個端點 ​

2.1.6 活動系統 (Promo) — 7 個端點 ​

2.1.7 代理推廣系統 (Affiliate) — 39 個端點 ​

2.1.8 任務系統 (Mission) — 3 個端點 ​

2.1.9 站內信 (Inbox) — 7 個端點 ​

2.1.10 站點設定 (Site Config) — 8+12 個端點 ​

2.1.11 風控管理 (Risk Control) — 11 個端點 ​

2.1.12 報表 (Reports) — 10 個端點 ​

2.1.13 系統管理 (Admin) — 18 個端點 ​

2.1.14 其他端點 ​

第 3 章：前台功能規格 (c9-ec) ​

3.1 首頁 ​

用途說明 ​

使用者故事 ​

畫面元素說明 ​

相關 API ​

權限要求 ​

多站點行為 ​

3.2 遊戲大廳 ​

用途說明 ​

使用者故事 ​

畫面元素說明 ​

相關 API ​

權限要求 ​

多站點行為 ​

3.3 遊戲啟動 ​

用途說明 ​

使用者故事 ​

畫面元素說明 ​

互動流程 ​

相關 API ​

權限要求 ​

多站點行為 ​

3.4 活動中心 ​

用途說明 ​

使用者故事 ​

畫面元素說明 ​

相關 API ​

權限要求 ​

3.5 活動詳情 ​

用途說明 ​

使用者故事 ​

畫面元素說明 ​

相關 API ​

權限要求 ​

3.6 聯盟推廣 ​

用途說明 ​

使用者故事 ​

畫面元素說明 ​

相關 API ​

權限要求 ​

3.7 任務系統 ​

用途說明 ​

使用者故事 ​

C9 Entertainment City — 產品規格書 (PM 版)

目錄

第 1 章：平台總覽

1.1 平台簡介

1.2 系統架構圖

1.3 技術棧總覽

前台 (c9-ec)

後台 (c9-ims)

後端 (c9-be)

1.4 專案規模統計

c9-ec (前台)

c9-ims (後台)

c9-be (後端)

1.5 支援語系

1.6 服務端口

1.7 統一系統規範

幣別規範

資料精度

統一回應格式

認證機制

第 2 章：功能模組清單

2.1 模組總覽

2.1.1 認證系統 (Auth) — 17 個端點

2.1.2 遊戲系統 (Game) — 17 個端點

2.1.3 金流管理 — 13 個端點

2.1.4 錢包管理 (Wallet) — 9 個端點

2.1.5 VIP 系統 — 13 個端點

2.1.6 活動系統 (Promo) — 7 個端點

2.1.7 代理推廣系統 (Affiliate) — 39 個端點

2.1.8 任務系統 (Mission) — 3 個端點

2.1.9 站內信 (Inbox) — 7 個端點

2.1.10 站點設定 (Site Config) — 8+12 個端點

2.1.11 風控管理 (Risk Control) — 11 個端點

2.1.12 報表 (Reports) — 10 個端點

2.1.13 系統管理 (Admin) — 18 個端點

2.1.14 其他端點

第 3 章：前台功能規格 (c9-ec)

3.1 首頁

用途說明

使用者故事

畫面元素說明

相關 API

權限要求

多站點行為

3.2 遊戲大廳

用途說明

使用者故事

畫面元素說明

相關 API

權限要求

多站點行為

3.3 遊戲啟動

用途說明

使用者故事

畫面元素說明

互動流程

相關 API

權限要求

多站點行為

3.4 活動中心

用途說明

使用者故事

畫面元素說明

相關 API

權限要求

3.5 活動詳情

用途說明

使用者故事

畫面元素說明

相關 API

權限要求

3.6 聯盟推廣

用途說明

使用者故事

畫面元素說明

相關 API

權限要求

3.7 任務系統

用途說明

使用者故事