客服系統（開發文檔）

最後更新：2026-04-10

📖 功能說明請參考客服系統

架構

相關檔案

Manager / 核心（4 個）

檔案	說明
`.../Manager/CustomerChatManager.swift`	核心管理器 + 訂單浮層
`.../Login_Register/ModuleApi.m`	路由註冊
`BBSport/Tools/RouterComponent/Classes/Service/IFLoginRegisterConfig.h`	路由常數 Header
`BBSport/Tools/RouterComponent/Classes/Service/IFLoginRegisterConfig.m`	路由常數實作

基礎路徑（前兩項）：BBSport/Tab/我的/Mine/Login_Register/登录注册/CustomerChatManager 放在登入註冊目錄下，是因為客服入口最初與登入流程綁定（登入失敗提供客服入口），後續擴展為全域客服管理器但路徑未遷移。

ViewController / View（6 個）

檔案	說明
`.../Home/C/ContactBenefitMemberViewController.swift`	福利專員頁
`.../Home/V/BenefitMemberTableViewCell.swift`	福利專員 Cell
`.../Home/V/BBMineCustomerServiceButton.swift`	「我的」客服按鈕
`.../Recharge/V/ChatView/RechargeChatView.swift`	充值客服聊天 View
`.../Recharge/V/ChatView/RechargeChatViewModel.swift`	充值客服 ViewModel
`.../Recharge/V/CustomerService/KefuRechargeView.swift`	充值碼顯示

基礎路徑：BBSport/Tab/我的/（Home 或 Mine）

API（2 個）

檔案	說明
`BBSport/API/STAPI/Feedback/STAPI+FeedbackProblemsRequest.swift`	問題列表
`BBSport/API/STAPI/Feedback/STAPI+SendFeedbackRequest.swift`	送出反饋

各頁面客服入口（12 個）

檔案	說明
`BBSport/Tab/体育/Sport/Banner/V/HomeNavView.swift`	體育首頁
`.../EventDetail/Views/ChatView/ChatCustomService/EventDetailCustomServiceView.swift`	賽事詳情
`BBSport/STUIKit/.../STSpecialCustomerView.swift`	懸浮泡泡
`BBSport/AppDelegate/AppDelegate+JPPush.swift`	推送入口
`BBSport/AppDelegate/AppDelegate.swift`	SDK 初始化
`.../Home/M/BenefitMembersModel.swift`	福利專員 Model
其他充值/提現/注單/資金明細頁面...	透過路由呼叫

API

福利專員與反饋

取得福利專員聯繫方式

POST api/forehead/system/proxy/config/contacts — urlForm — STAPI.UserContactBenefitMemberRequest

無參數（需 Authorization）。

Response： [BenefitMembersModel]

欄位	型別	說明
contact	String	聯繫方式
icon	String	平台圖示 URL
name	String	軟體名稱（Telegram、微信等）
proxyName	String	代理帳號
proxyId	Int	代理 ID

問題列表

POST api/forehead/user/feedback/type/list — urlForm — STAPI.FeedbackProblemsRequest

無參數。

Response：

欄位	型別	說明
id	Int	問題 ID
name	String	問題類型
describes	String	問題描述

送出反饋

POST api/forehead/user/feedback/add — urlForm — STAPI.SendFeedbackRequest

參數	型別	必填	說明
typeId	Int	✅	問題類型 ID
typeName	String	✅	問題類型名稱
title	String	✅	反饋標題
content	String	✅	反饋內容
images	String		圖片 URL

Response： 無 data，僅 code + message。

DD SDK 客服

DD SDK 的通訊由 DDConfigManager（DDClientComponent）處理，不經過 STAPI 層，無可暴露的 Endpoint。

客服線路判斷

主線/次線概念

「主線」和「次線」是後台配置的兩組客服線路，對應域名列表中的 UrlTypeServiceMainLine（type=15）和 UrlTypeServiceMinorLine（type=16）。值存於 BBUrlListModel 並透過 IFMainSwitch.getUrlStr(with:) 讀取。

後台可為每條線路配置不同客服類型（SDK / LiveChat / 智齒 URL）
使用者點擊客服時，若兩條線路都有值，會彈出「主線客服」/「次線客服」選擇彈窗
若只有一條線路有值，直接走該線路
來源 API：域名列表 API（/system/url/list），App 啟動時拉取

線路設定值對應

設定值	客服類型
`"SDK"`	DD SDK 客服
`"LiveChat"`	LiveChat SDK
其他非空字串	智齒 H5 客服（該字串即為智齒域名）
主線次線都空	預設走 DD SDK

場景類型

場景	說明
normal (0)	普通客服
customerRecharge (1)	代客充值
recharge (2)	充值
withdraw (3)	提現
game (4)	遊戲
custom(Int)	專屬場景（後台定義）
cancelRecharge	撤銷充值觸發
createFailRecharge	建單失敗觸發

實作重點

SDK 初始化順序：configLocalDomain → configHost → registerServices → requestDownloadPages
DD SDK 參數：appId:"sport", productId:"bb", mainColor:"blue", languageType:"zh_CN", cusType: 1=會員/3=遊客
LiveChat SDK：透過 CocoaPods 引入（LiveChat 2.0.20），AppDelegate+SDK.swift 中以 licenseId 初始化 LiveChat.licenseId，開啟時透過 LiveChat.presentChat() 呈現。會帶入會員帳號、手機型號、設備號、登入 IP、APP 版本等 setVariable 參數
智齒客服：AppID c7e9a12ad95d4fccb3c8450141ea8e5e，普通渠道 "3"，充值渠道 "5"
智齒 H5 URL 來源：從 IFMainSwitch.getZhiChiKefuUrl() 取得基底域名（來自域名列表 type=9 的 zhiChiUrlArray），再拼接 ?sysNum={AppID}&color=1A1C2A&uname={encodedUserName} 組成完整 URL，以 WebView 開啟

關鍵數字

充值建單連續失敗 5 次 → 自動觸發客服
充值訂單連續撤銷 3 次 → 自動觸發客服
泡泡氣泡每個使用者每天只顯示 1 次

福利客服輪詢：DDConfigManager.checkHaveBoon 在體育首頁、我的頁、注單頁、遊戲首頁、廣場頁等多處呼叫（非定時器，而是每次進入頁面時觸發）。先使用本地快取判斷是否顯示泡泡，再非同步請求 /api/cusCustomer/scenes 更新資料，透過 BehaviorSubject 廣播 (showBubbles, haveNewMessage) 狀態
充值碼顯示：KefuRechargeView 固定 4 格，碼為空則隱藏
充值嵌入聊天：RechargeChatView 需 eventId、hostId、liveRoomId；這三個參數來自 RechargeViewController.currentStreamer（當前正在觀看的主播資訊），若無主播則傳空字串/0。覆寫 hitTest 不攔截點擊

客服系統（開發文檔） ​

架構 ​

相關檔案 ​

API ​

福利專員與反饋 ​

取得福利專員聯繫方式 ​

問題列表 ​

送出反饋 ​

客服線路判斷 ​

主線/次線概念 ​

線路設定值對應 ​

場景類型 ​

實作重點 ​