維護模式管理

最後更新：2026-04-07

---

功能說明

維護模式管理系統負責偵測並顯示各體育平台（FB/DB/UP）以及整個 APP 的維護狀態。當後端設定某平台進入維護時，前端會：

1. 阻止該平台的登入與資料請求
2. 在對應頁面覆蓋維護畫面（顯示維護時間、原因、客服入口）
3. 若為 APP 級別維護，則直接替換 rootViewController 為維護頁面
4. 額外處理 IP 限制情境（全域 IP 限制 & 遊戲 IP 限制）

維護資訊有兩個來源：API 主動查詢（App 啟動時）與 Socket 被動推送（即時變更）。

使用者流程

1. App 啟動 → 系統自動查詢維護狀態 API
2. 若某平台維護中 → 切換到其他未維護平台（自動）
3. 若 APP 級別維護 → 整個主畫面被維護頁取代（BBMaintainViewController）
4. 維護頁顯示：維護時間、維護原因、客服入口
5. 維護結束 → 恢復原主畫面（Socket 通知或重新查詢 API）

頁面跳轉

• APP 維護 → 主畫面被 BBMaintainViewController 取代（替換 rootVC）
• 維護結束 → 恢復原先的 rootViewController
• 維護頁客服按鈕 → CustomerChatManager.shared.openChat()

---

技術視角（開發看這裡）

相關檔案

類型	檔案路徑
維護管理器（核心）	/Users/user/Work/bbsport-new/BBSport/Tools/MaintenanceManager/GameMaintenanceManager.swift
維護狀態 Model	/Users/user/Work/bbsport-new/BBSport/Tools/MaintenanceManager/GameMaintenanceStatusModel.swift
維護頁面 View	/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Login_Register/登录注册/Maind/BBMaintain/BBMaintainView.swift
維護頁面 ViewController	/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/Login_Register/登录注册/Maind/BBMaintain/BBMaintainViewController.swift
體育狀態管理器	/Users/user/Work/bbsport-new/BBSport/Tab/体育/Sport/Common/GameStatusManager/GameStatusManager.swift
體育首頁維護適配器	/Users/user/Work/bbsport-new/BBSport/Tab/体育/Sport/HomePage/Adapter/SportMaintenanceAdapter.swift
SportStatusProvider 協定	/Users/user/Work/bbsport-new/BBSport/Tab/体育/Sport/Common/GameStatusManager/Provider/SportStatusProvider.swift
維護狀態 API 定義	/Users/user/Work/bbsport-new/BBSport/API/STAPI/STAPI+ProductConfigRequest.swift

API

功能說明	Namespace	Endpoint	Method	主要參數
取得平台維護資訊	STAPI	api/forehead/gamebet/product/productConfig	POST urlForm	isGame=true（遊戲維護）或 type=2（非遊戲）

資料模型

維護資料欄位（API Response）

欄位	說明
startDate	維護開始時間（timestamp）
endDate	維護結束時間（timestamp）
reason	維護原因
status	狀態，1 表示維護中
itemList	平台 channelId 列表（逗號分隔），空值視為 APP 級別維護

GameMaintenanceStatusModel

屬性	說明
isGameMaintenance	是否維護中（可 KVO 觀察，@objc dynamic）
isShowH5	是否顯示 H5 連結（APP 級別維護時為 true）
isShowBackBtn	是否顯示返回按鈕（遊戲 IP 限制時為 true）

各平台存取

GameMaintenanceManager.shared.app  // APP 級別
GameMaintenanceManager.shared.fb   // FB 體育（極速體育）
GameMaintenanceManager.shared.db   // DB 體育
GameMaintenanceManager.shared.up   // UP 體育

實作重點

1. 雙重資料來源：維護狀態同時透過 API 主動查詢和 Socket 被動推送更新，兩者共用同一套資料解析邏輯（setUpMaintainData + loadData）

2. 快取優先策略：checkStatus() 先用上次快取的狀態立即回調（isFromNetWork = false），再發 API 請求，避免畫面閃爍

3. 回調機制：maintenanceResultHandler 是覆蓋式閉包，回傳 (app, fb, db, up, isFromNetWork) 五個參數；最後一個設定者覆蓋前者

4. APP 維護替換 rootVC：APP 級別維護直接替換 window.rootViewController，維護結束後用 tempRootVC 恢復

5. 全部維護時：GameStatusManager.isAllSportMaintenance 為 true → 透過 STNotify.specifiedTab.post(object: 1) 自動切換到娛樂 Tab

6. channelId 為動態值：各平台的 sportChannelId 透過 IFCommonUtil.fbSportChannelID() 等取得，非固定常數

7. 維護中開啟客服：openCustomerService 旗標防止在 IP 限制畫面上重複疊加客服

8. 夜間模式支援：BBMaintainView 監聽 STNotify.nightPatternOpen，動態切換背景圖和 Logo

---

API 呼叫流程

維護狀態檢查

App 啟動 → MainViewController.setUpBusinessService()
  └─ GameMaintenanceManager.checkStatus()
     └─ [API] POST api/forehead/gamebet/product/productConfig
        → itemList 對應:
           0 = APP 整體維護
           1 = FB 體育維護
           3 = DB 體育維護
           4 = UP 體育維護
        → 各平台 isGameMaintenance, startTime, endTime

即時維護通知 (Socket)

Socket 推送維護狀態變更
  └─ GameMaintenanceManager.receiveSocketMaintenanceInfo()
     → 即時更新維護狀態 (不需額外 API)