投注功能（開發文檔）

最後更新：2026-04-10

📖 功能說明請參考投注功能

架構

相關檔案

ViewController（7 個）

檔案	說明
`.../NewBet/BetViewController.swift`	投注面板
`.../Bets/FB/SingleBet/FBSingleBetViewController.swift`	FB 單關
`.../Bets/UP/SingleBet/UPSingleBetViewController.swift`	UP 單關
`.../Bets/DB/SingleBet/DBSingleBetViewController.swift`	DB 單關
`.../Bets/FB/SeriesBet/FBSeriesPassBetViewController.swift`	FB 串關
`.../Bets/UP/SeriesBet/UPSeriesPassBetViewController.swift`	UP 串關
`.../Bets/DB/SeriesBet/DBSeriesPassBetViewController.swift`	DB 串關

基礎路徑：BBSport/Tab/体育/Sport/

ViewModel / Manager（5 個）

檔案	說明
`.../NewBet/BetViewModel/BetViewModel.swift`	投注面板 VM
`.../NewBet/BetViewModel/BetViewModel+LiveGame.swift`	LiveGame 擴展
`.../NewBet/BetManager.swift`	投注管理
`.../Bets/Base/Controller/BaseBetViewController.swift`	投注基底 VC
`.../Common/GameBalanceManager/GameBalanceManager.swift`	遊戲餘額管理

基礎路徑：BBSport/Tab/体育/Sport/

Service（3 個）

檔案	說明
`.../Bets/FB/Service/FBBetsService.swift`	FB 投注
`.../Bets/DB/service/DBBetsService.swift`	DB 投注
`.../Bets/UP/Service/UPBetsService.swift`	UP 投注

基礎路徑：BBSport/Tab/体育/Sport/

View（20 個）

檔案	說明
`.../Base/View/BetResultView/SingleBetResultView.swift`	投注結果
`.../Base/View/BetResultView/SingleBetConfirmView.swift`	單關確認
`.../Base/View/BetResultView/SingleBetNotEnoughMoney.swift`	餘額不足
`.../Base/View/BetResultView/SeriesPassConfirmView.swift`	串關確認
`.../Base/View/BetResultView/SeriesPassSuccessBetView.swift`	串關成功
`.../Base/View/BetResultView/SeriePassSuccessTable.swift`	串關成功 Table
`.../Base/View/BetResultView/SerieSuccessOddCell.swift`	串關成功賠率 Cell
`.../Base/View/AppointmentBet/STAppointmentAdjustOddView.swift`	賠率調整提示
`.../Base/View/BetKeyboardView.swift`	投注鍵盤
`.../Base/View/BetMatchInfoCell.swift`	投注賽事資訊 Cell
`.../Base/View/BetMoneyInfoCell.swift`	投注金額資訊 Cell
`.../Base/View/BetTableFooter.swift`	Table Footer
`.../Base/View/BetTableHeader.swift`	Table Header
`.../Base/View/CartView.swift`	購物車
`.../Base/View/BalanceLabel.swift`	餘額標籤
`.../Base/View/CustomTextFieldFroBeyKeyboard.swift`	自訂輸入框
`.../Base/View/BetContentView/PreBetCommonTableView.swift`	預投注 TableView
`.../Base/View/BetContentView/PreBetDownCell.swift`	預投注下方 Cell
`.../Base/View/BetContentView/PreBetTopCell.swift`	預投注上方 Cell
`.../NewBet/View/NewPreBetCommonTableView.swift`	新預投注 TableView

基礎路徑：BBSport/Tab/体育/Sport/Bets/（除 NewBet）

Model（22 個）

檔案	說明
`.../FB/FBBetCommonDatas.swift`	FB 共用資料
`.../FB/FBStartBetModel.swift`	FB 開始投注
`.../FB/Service/SingleBetModel/FBCalculateBetsModel.swift`	FB 預投注
`.../FB/Service/SingleBetModel/FBSingleBetResultModel.swift`	FB 投注結果
`.../FB/Service/SingleBetModel/UBCalculateBetsModel.swift`	UB 預投注
`.../FB/Service/CheckOrderModel/FBOrderStatusModel.swift`	FB 訂單狀態
`.../FB/Service/SeriesPassBetModel/FBSeriesPassBetResultModel.swift`	FB 串關結果
`.../FB/Service/SeriesPassBetModel/FBSeriesPassCalculateBetsModel.swift`	FB 串關計算
`.../FB/Service/AppointmentBetModel/FBAppointmentBetCommModel.swift`	FB 預約共用
`.../FB/Service/AppointmentBetModel/FBAppointmentResultModel.swift`	FB 預約結果
`.../FB/Service/AppointmentBetModel/FBAskAppointmentBetResultModel.swift`	FB 預約結果查詢
`.../FB/Service/AppointmentBetModel/FBAskAppointmentCashResultModel.swift`	FB 預約提前結算查詢
`.../FB/Service/AppointmentBetModel/FBCalculateAppointmentBetModel.swift`	FB 預約限額
`.../FB/FBMerchantConfig/FBMerchantDetailModel.swift`	FB 商戶設定 Model
`.../FB/FBMerchantConfig/FBMerchantDetailService.swift`	FB 商戶設定 Service
`.../DB/DBBetCommonDatas.swift`	DB 共用資料
`.../DB/DBStartBetModel.swift`	DB 開始投注
`.../DB/service/DBBetResultModel.swift`	DB 投注結果
`.../DB/service/DBCheckOrderModel/DBOrderStatusModel.swift`	DB 訂單狀態
`.../DB/service/DBQueryLatestMarketInfoModel/DBQueryLatestMarketInfoModel.swift`	DB 最新盤口
`.../DB/service/DBQueryMarketMaxMinBetMondyModel/DBOrderMaxBetMoney.swift`	DB 投注限額
`.../UP/UPBetCommonDatas.swift`	UP 共用資料

基礎路徑：BBSport/Tab/体育/Sport/Bets/

Tools / Adapter（6 個）

檔案	說明
`.../Base/Tools/RiskFreeBetting.swift`	包賠投注
`.../Base/Tools/BetCommonFuncs.swift`	投注共用函式
`.../Base/Tools/BetCommonModel.swift`	投注共用 Model
`.../Base/Tools/TimerProxy.swift`	計時器代理
`.../Base/Adapter/BetAdapter.swift`	投注 Adapter
`.../Base/Adapter/SeriesPassMatchAdapter.swift`	串關賽事 Adapter

基礎路徑：BBSport/Tab/体育/Sport/Bets/

API Request（30 個）

檔案	說明
`BBSport/API/FBSportAPI/Bet/FBSportAPI+CalculateBetsRequest.swift`	FB 預投注計算
`BBSport/API/FBSportAPI/Bet/FBSportAPI+SingleBetsRequest.swift`	FB 單關下注
`BBSport/API/FBSportAPI/Bet/FBSportAPI+SeriesBetsRequest.swift`	FB 串關下注
`BBSport/API/FBSportAPI/Bet/FBSportAPI+CheckOrderStatusRequest.swift`	FB 訂單狀態
`BBSport/API/FBSportAPI/Bet/FBSportAPI+AppointmentBetsRequest.swift`	FB 預約投注
`BBSport/API/FBSportAPI/Bet/FBSportAPI+CancleAppointmentBetsRequest.swift`	FB 取消預約
`BBSport/API/FBSportAPI/Bet/FBSportAPI+ModifyAppointmentBetsRequest.swift`	FB 修改預約
`BBSport/API/FBSportAPI/Bet/FBSportAPI+ReserveBetParameterRequest.swift`	FB 預約限額
`BBSport/API/FBSportAPI/Bet/FBSportAPI+CheckAppointmentBetsResultRequest.swift`	FB 預約結果
`BBSport/API/FBSportAPI/Bet/FBSportAPI+CheckAppointmentCashOutResultRequest.swift`	FB 預約提前結算
`BBSport/API/UPSportAPI/Bet/UPSportAPI+CalculateBetsRequest.swift`	UP 預投注計算
`BBSport/API/UPSportAPI/Bet/UPSportAPI+SingleBetsRequest.swift`	UP 單關下注
`BBSport/API/UPSportAPI/Bet/UPSportAPI+SeriesBetsRequest.swift`	UP 串關下注
`BBSport/API/UPSportAPI/Bet/UPSportAPI+CheckOrderStatusRequest.swift`	UP 訂單狀態
`BBSport/API/UPSportAPI/Bet/UPSportAPI+AppointmentBetsRequest.swift`	UP 預約投注
`BBSport/API/UPSportAPI/Bet/UPSportAPI+CancleAppointmentBetsRequest.swift`	UP 取消預約
`BBSport/API/UPSportAPI/Bet/UPSportAPI+ModifyAppointmentBetsRequest.swift`	UP 修改預約
`BBSport/API/UPSportAPI/Bet/UPSportAPI+ReserveBetParameterRequest.swift`	UP 預約限額
`BBSport/API/UPSportAPI/Bet/UPSportAPI+CheckAppointmentBetsResultRequest.swift`	UP 預約結果
`BBSport/API/UPSportAPI/Bet/UPSportAPI+CheckAppointmentCashOutResultRequest.swift`	UP 預約提前結算
`BBSport/API/DBSportAPI/Bet/DBSportAPI+BetRequest.swift`	DB 投注
`BBSport/API/DBSportAPI/Bet/DBSportAPI+LatestMarketInfoRequest.swift`	DB 最新盤口
`BBSport/API/DBSportAPI/Bet/DBSportAPI+MarketMaxMinBetMoneyRequest.swift`	DB 投注限額
`BBSport/API/DBSportAPI/Bet/DBSportAPI+OrderStatusRequest.swift`	DB 訂單狀態
`BBSport/API/DBSportAPI/Bet/DBSportAPI+RecordUserPreferenceRequest.swift`	DB 使用者偏好
`BBSport/API/STAPI/Bet/STAPI+LiveGameBet.swift`	直播投注
`BBSport/API/STAPI/Bet/STAPI+LiveGamePreBetInfo.swift`	直播預投注
`BBSport/API/STAPI/Bet/STAPI+RiskFreeBetBetConfirmationRequest.swift`	包賠確認
`BBSport/API/STAPI/Bet/STAPI+RiskFreeBetConfigurationRequest.swift`	包賠設定
`BBSport/API/STAPI/Bet/STAPI+GameBetListRequest.swift`	投注列表

API

單關投注

FB/UP 預投注計算

POST v1/order/batchBetMatchMarketOfJumpLine — JSON — 來源：FBSportAPI / UPSportAPI

TIP

單關與串關共用此 endpoint。單關回傳 FBCalculateBetsDataModel，串關回傳 FBSeriesPassCalculateBetsDataModel。

Request：

參數	型別	必填	說明
（body dict）	[String: Any]	✅	含 `languageType`、`betMatchMarketList`（含 `type`、`matchId`、`marketId`）

Response（單關）：（success=true 時 data，型別 FBCalculateBetsDataModel）

欄位	型別	說明
bms	[FBCalculateBetsBmsModel]	投注項列表

FBCalculateBetsBmsModel 主要欄位：

欄位	型別	說明
mid	Int	盤口 ID
odds	String	當前最新賠率（UI 展示）
real_odds	Decimal	真實賠率（計算可贏額）
real_smin	Decimal	最小投注額
real_smax	Decimal	最大投注額
ss	Int	銷售狀態（1=開售、-1=未開售、0=暫停）
isClosed	Bool	是否封盤
isBetChange	Bool	賠率有變動
isCanSerise	Bool	支持串關
op	FBCalculateBetsDataOPModel?	投注項詳情

Response（串關）：

欄位	型別	說明
bms	[FBSeriesPassEventInfoModel]	賽事資訊列表
sos	[FBSeriesPassBetInfoModel]	串關投注方式（含 `sn`=串幾、`_in`=注數、`smin`/`smax`=限額）

FB/UP 單關下注

POST v1/order/bet/singlePass — JSON — 來源：FBSportAPI / UPSportAPI

參數	型別	必填	說明
（body dict）	[String: Any]	✅	含 `singleBetList`（含 `oddsChange`、`unitStake`、`betOptionList`）

Response：（JSON String → FBSingleBetResultModel）

欄位	型別	說明
code	Int	狀態碼
success	Bool	是否成功
data	[FBSingleBetResultDataModel]	投注結果列表

FB/UP 串關下注

POST v1/order/betMultiple — JSON — 來源：FBSportAPI / UPSportAPI

參數	型別	必填	說明
（body dict）	[String: Any]	✅	含 `multipleType`、`singleBetList`、`betName`、`betCount`、`betOdds`

Response： 同 FB/UP 單關下注結果。

FB/UP 查詢訂單狀態

POST v1/order/getStakeOrderStatus — JSON — 來源：FBSportAPI / UPSportAPI

參數	型別	必填	說明
orderIds	[string]	✅	訂單 ID 陣列
languageType	string	✅	固定 `"CMN"`

Response：（JSON String → FBOrderStatusDataModel）

欄位	型別	說明
data	[FBOrderStatusModel]	訂單狀態列表（含 `oid`、`st`、`orderStatus`）

預約投注（僅 FB/UP）

取得預約投注限額

POST v1/order/reserve/getBetParameter — JSON — 來源：FBSportAPI / UPSportAPI

參數	型別	必填	說明
（body dict）	[String: Any]	✅	含 `type`、`marketId`、`matchId`

Response：（success=true 時 data，型別 FBCalculateAppointmentBetModel）

欄位	型別	說明
mid	Int?	盤口 ID
mis	Int?	最小可投注額
mly	Int	最大可賠率額

預約下注

POST v1/order/reserve/bet — JSON — 來源：FBSportAPI / UPSportAPI

參數	型別	必填	說明
（body dict）	[String: Any]	✅	含 `unitStake`、`odds`、`type`、`marketId`

Response： JSON String，含預約投注結果狀態。

取消預約

POST v1/order/reserve/cancel — JSON

參數	型別	必填	說明
（body dict）	[String: Any]	✅	含 `reserveId`

Response： JSON String。

修改預約

POST v1/order/reserve/update — JSON

參數	型別	必填	說明
（body dict）	[String: Any]	✅	含 `reserveId`、`unitStake`、`odds`

Response： JSON String。

查詢預約投注結果

POST v1/order/reserve/statusInfoByIds — JSON

參數	型別	必填	說明
reserveIds	[string]	✅	預約投注 ID 陣列
languageType	string	✅	固定 `"CMN"`

Response： JSON String → FBAskAppointmentBetResultModel。

查詢預約提前結算結果

POST v1/order/reserve/cashOut/statusInfoByIds — JSON

參數	型別	必填	說明
reserveCashOutIds	[string]	✅	預約提前結算 ID 陣列
languageType	string	✅	固定 `"CMN"`

Response： JSON String → FBAskAppointmentCashResultModel。

DB 投注

DB 取得最新盤口資料

POST yewu13/v1/betOrder/client/queryLatestMarketInfo — JSON — 來源：DBSportAPI

參數	型別	必填	說明
（body dict）	[String: Any]	✅	含 `matchIdList`、`playOptionIdList`

Response：（code="0000000" 時 data，型別 [DBQueryLatestMarketInfoModel]?）

欄位	型別	說明
id	String	盤口 ID
matchInfoId	String	賽事 ID
marketValue	String	盤口值
status	Int	盤口狀態（0=開盤、1=封盤、2=關盤、11=鎖盤）
playId	Int	玩法 ID
marketOddsList	[DBQueryMarketOddsListItemModel]	投注項集合

DB 查詢投注限額

POST yewu13/v1/betOrder/client/queryMarketMaxMinBetMoney — JSON — 來源：DBSportAPI

參數	型別	必填	說明
（body dict）	[String: Any]	✅	含 `marketIdList`

Response：（code="0000000" 時 data，型別 [DBOrderMaxBetMoneyModel]?）

欄位	型別	說明
minBet	String	最小可投注金額
orderMaxPay	String	最大可投注金額
seriesOdds	String	串關賠率
type	String	串關類型
betCount	Int	投注數量
betName	String	幾串幾（如 `"3串1"`）

DB 投注（單關/串關共用）

POST yewu13/v1/betOrder/client/bet — JSON — 來源：DBSportAPI

參數	型別	必填	說明
（body dict）	[String: Any]	✅	含 `orderDetailRespList`（含 `matchId`、`playOptionId`、`oddsValues`、`unitStake`）

Response：（JSON String → DBBetResultModel）

欄位	型別	說明
code	String	狀態碼（`"0000000"`=成功）
data	DBBetResultDataModel?	投注結果

DBBetResultDataModel：

欄位	型別	說明
orderType	DBBetResultType?	0=餘額不足、1=確認中、2=已確認、3=失敗
betMoneyTotal	String?	總投注金額
maxWinMoneyTotal	String?	最高可盈金額
orderDetailRespList	[DBBetResultDetailRespListModel]	單關訂單明細
seriesOrderRespList	[DBBetResultDetailRespListModel]	串關訂單明細

WARNING

DB 金額精度：betMoneyTotal 和 maxWinMoneyTotal 需除以 100 才是實際金額（分轉元）。

DB 餘額不足錯誤碼：0400454 / 0400455 / 0402035。

DB 查詢訂單狀態

GET yewu13/v1/betOrder/queryOrderStatus — JSON — 來源：DBSportAPI

參數	型別	必填	說明
orderNos	string	✅	訂單號，逗號隔開

Response：（code="0000000" 時 data，型別 [DBOrderStatusModel]?）

欄位	型別	說明
orderNo	String	訂單號
status	Int	0=已確認、1=已處理、2=已拒絕、3=待確認、4=失敗

DB 設定使用者投注偏好

POST yewu12/v1/betOrder/client/recordUserPreference — JSON — 來源：DBSportAPI

參數	型別	必填	說明
userBetPrefer	int		1=更好賠率、2=任意賠率、3=固定賠率
userMarketPrefer	string		`"EU"`=歐賠、`"HK"`=港賠

Response： 無 data（STEmptyResponse）。

WARNING

DB 不支援預約投注、骰寶、包賠。DB host 為 DBSportAPI.Host.sport，與 FB/UP 體系不同。

骰寶（LiveGame 投注）

骰寶為聊天室內的即時對局遊戲（Sicbo），使用 STAPI LiveGame 系列 API，僅 FB/UP 支持。

骰寶預投注資訊

POST api/forehead/live-bet-game/sicbo/preBetInfo — JSON — 來源：STAPI

Request：

參數	型別	必填	說明
betOption	Int	✅	投注選項
roundId	Int	✅	對局 ID
gameId	Int	✅	遊戲 ID
liveRoomId	Int	✅	直播間 ID

Response： 型別 LiveGameBetInfoModel，含投注選項限額資訊。

骰寶投注

POST api/forehead/live-bet-game/sicbo/bet — JSON — 來源：STAPI

Request：

參數	型別	必填	說明
roundId	Int	✅	對局 ID
roundNumber	Int	✅	對局輪次
liveRoomId	Int	✅	直播間 ID
betAmount	String	✅	投注金額
betOption	Int	✅	投注選項
betRemark	BetRemark	✅	投注備註（含 `type`、`chatRoomId`、`liveHostType`、`hostId`）

Response：（型別 LiveGameBetResponse）

欄位	型別	說明
errorCode	String	錯誤碼
message	String	錯誤訊息
success	Bool	是否成功

包賠

包賠投注配置

包賠投注（Risk-Free Bet）：平台活動型投注方式，使用者在符合活動條件的賽事中投注，若投注失敗可獲得部分或全額賠償返還，降低首次投注風險。

POST api/forehead/activity/compensation/info — urlForm — 來源：STAPI

無參數，靠 Header token/uid 認證。

Response：（code=1 時 data，型別 RiskFreeBetConfigurationRequest.Response）

欄位	型別	說明
actId	Int	活動 ID
actName	String	活動名稱
status	Int	是否有包賠
template	String	活動模板
gameRuleConfig	[GameRuleConfig]	盤口設置
amountSettingConfig	[AmountSettingConfig]	條件設定
introduction	[String]	活動說明

錯誤碼速查

錯誤碼	平台	處理
`3001`	FB/UP	餘額不足
`0400454` / `0400455` / `0402035`	DB	餘額不足
`0000000`	DB	成功

串關限制規則

規則	說明
最少場數	2 場（2串1）
最多場數	10 場
同場限制	同一 `matchId` 只能選 1 個投注項，新加入自動覆蓋
組合類型	N串1（不包號）、N串M（包號），如 3串4、5串26、10串1013 等

實作重點

BetViewController：繼承 STBaseViewController<BetViewModel>，使用 Combine @Published 驅動 UI
弱網訂單確認：下注回傳 confirming → 延遲 0.5s 輪詢 checkOrderStatus；仍確認中 → 記入 BetCommonDatas.betsIDs 後台定期輪詢
可贏額計算：FB/UP 公式 投注金額 * (賠率 - 1)；DB 串關：計算 C(n,k) 組合乘積
防重複投注：isBetWaitingResponse 為 true 時禁止關閉面板，5 秒後自動恢復

關鍵數字

FB/UP 投注面板賠率輪詢：每 2 秒
DB 投注面板賠率輪詢：每 5 秒
弱網輪詢延遲：0.5 秒
防重複投注超時：5 秒
串關最多場數：10 場

投注功能（開發文檔） ​

架構 ​

相關檔案 ​

API ​

單關投注 ​

FB/UP 預投注計算 ​

FB/UP 單關下注 ​

FB/UP 串關下注 ​

FB/UP 查詢訂單狀態 ​

預約投注（僅 FB/UP） ​

取得預約投注限額 ​

預約下注 ​

取消預約 ​

修改預約 ​

查詢預約投注結果 ​

查詢預約提前結算結果 ​

DB 投注 ​

DB 取得最新盤口資料 ​

DB 查詢投注限額 ​

DB 投注（單關/串關共用） ​

DB 查詢訂單狀態 ​

DB 設定使用者投注偏好 ​

骰寶（LiveGame 投注） ​

骰寶預投注資訊 ​

骰寶投注 ​

包賠 ​

包賠投注配置 ​

錯誤碼速查 ​

串關限制規則 ​

實作重點 ​

投注功能（開發文檔）

架構

相關檔案

API

單關投注

FB/UP 預投注計算

FB/UP 單關下注

FB/UP 串關下注

FB/UP 查詢訂單狀態

預約投注（僅 FB/UP）

取得預約投注限額

預約下注

取消預約

修改預約

查詢預約投注結果

查詢預約提前結算結果

DB 投注

DB 取得最新盤口資料

DB 查詢投注限額

DB 投注（單關/串關共用）

DB 查詢訂單狀態

DB 設定使用者投注偏好

骰寶（LiveGame 投注）

骰寶預投注資訊

骰寶投注

包賠

包賠投注配置

錯誤碼速查

串關限制規則

實作重點