BBSport Knowledge Base

Appearance

福利中心（Welfare Center） ​

最後更新：2026-04-07

功能說明 ​

福利中心集中展示使用者所有可領取的獎勵，包含：現金、現金券、存送券、流水券、實物、VIP 成長值、禮品券、稱號、體驗金等多種獎勵類型。分為「進行中」（可領取）和「已失效」兩個狀態頁籤，支援按獎勵類型篩選。

使用者流程 ​

  1. 進入「我的」→ 找到「福利中心」入口 → WelfareCentreViewModel 驅動頁面
  2. 頁面頂部兩個 Tab：「進行中」/ 「已失效」
  3. 各 Tab 下方有類型篩選按鈕（全部 / 現金 / 現金券 / 存送券 / 流水券 / 實物 / VIP / 禮品券 / 體驗金 / 稱號）
  4. 清單顯示福利項目，每項顯示獎勵名稱、金額、截止時間、狀態
  5. 點擊「領取」→ 呼叫 WelfareCenterClaimRequest
  6. 部分實物獎品需填寫收貨地址（addressId）

頁面跳轉 ​

  • 「我的」首頁 → 福利中心 → WelfareCentreViewController
  • 實物獎品領取 → 填寫收貨地址頁

技術視角（開發看這裡） ​

相關檔案 ​

類型檔案路徑
ViewController/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/MiddleMenu/WalfareCentre/C/WelfareCentreViewController.swift
ViewModel/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/MiddleMenu/WalfareCentre/M/WelfareCentreViewModel.swift
Model/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/MiddleMenu/WalfareCentre/M/WelfareCentreModel.swift
View（Cell）/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/MiddleMenu/WalfareCentre/V/WelfareCentreCellTableViewCell.swift
View（篩選）/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/MiddleMenu/WalfareCentre/V/WelfareCentreFilterView.swift
View（Header）/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/MiddleMenu/WalfareCentre/V/WelfareCentreHeaderView.swift
View（TableView）/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/MiddleMenu/WalfareCentre/V/WelfareCentreTableView.swift
View（Footer）/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/MiddleMenu/WalfareCentre/V/WelfareCenterFooterView.swift
Extension（UIButton）/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/MiddleMenu/WalfareCentre/V/ExtensionUIButton.swift
View（多選按鈕）/Users/user/Work/bbsport-new/BBSport/Tab/我的/Mine/MiddleMenu/WalfareCentre/V/SelectMultipleButtons.swift
API（活動列表）/Users/user/Work/bbsport-new/BBSport/API/STAPI/Activity/STAPI+ActivityListRequest.swift
API（彩蛋資訊）/Users/user/Work/bbsport-new/BBSport/API/STAPI/Activity/STAPI+EggInfoRequest.swift
API（金幣商城餘額）/Users/user/Work/bbsport-new/BBSport/API/STAPI/Activity/STAPI+GoldMallBalanceRequest.swift
API（福利中心領取）/Users/user/Work/bbsport-new/BBSport/API/STAPI/WelfareCenter/STAPI+WelfareCenterClaimRequest.swift
API（福利中心列表）/Users/user/Work/bbsport-new/BBSport/API/STAPI/WelfareCenter/STAPI+WelfareCenterListRequest.swift
API（福利未領取數量）/Users/user/Work/bbsport-new/BBSport/API/STAPI/WelfareCenter/STAPI+WelfareCenterUnclaimCountRequest.swift
API（福利各類型數量）/Users/user/Work/bbsport-new/BBSport/API/STAPI/WelfareCenter/STAPI+WelfareCountByAwardTypeRequest.swift

API ​

功能說明NamespaceEndpointMethod主要參數
福利列表（進行中/已失效）STAPIapi/forehead/activity/welfare/listPOST無
各類型數量統計STAPIapi/forehead/activity/welfare/countByAwardTypePOST無
領取福利STAPIapi/forehead/activity/welfare/claimPOSTidStr、addressId（實物必填）
未領取數量STAPIapi/forehead/activity/welfare/unClaimCountPOST無

資料模型 ​

StatusType（福利狀態） ​

值說明
-1不可領取
0已達標未領取（可領取）
1已領取
2已過期
3已發貨
4已拒絕
5已刪除
6未使用

FilterButtonType（篩選類型） ​

all、cash（現金）、cashTicket（現金券）、saveTicket（存送券）、waterTicket（流水券）、goods（實物）、vip、giftTicket（禮品券）、title（稱號）、experienceTicket（體驗金）

實作重點 ​

  1. 雙重狀態管理：enable（進行中）/ disable（已失效）有各自的分頁計數器，切換 Tab 時獨立分頁

  2. 本地篩選：類型篩選（getData）在本地資料上做 filter，不重新請求 API，避免過多網路請求

  3. 數量統計：getListCount 呼叫 WelfareCountByAwardTypeRequest 取得各類型的數量，篩選按鈕旁顯示數量 badge

  4. 分頁加載：currentEnablePage / currentDisablePage 管理各狀態的分頁

  5. 狀態對應：進行中對應 status == 0 或 6；已失效對應其餘狀態（-1, 1, 2, 3, 4, 5）

API 呼叫流程 ​

進入福利中心 (WelfareCentreViewController) ​

viewDidLoad → getData()
  ├─ [並行 1] POST api/forehead/activity/welfare/list
  │  {status:"0,6", page:0, size:200}
  │  → 可用福利 (進行中)
  │
  ├─ [並行 2] POST api/forehead/activity/welfare/list
  │  {status:"-1,1,2,3,4,5", page:0, size:200}
  │  → 已失效福利
  │
  └─ [並行 3] POST api/forehead/activity/welfare/countByAwardType
     → 各類型未領取/已失效數量
        (現金、現金券、存款券、流水券、實物、VIP、禮品券、稱號、經驗券)

領取福利 ​

用戶點擊領取
  └─ [API] POST api/forehead/activity/welfare/claim {idStr, addressId?}
     → 成功後重新載入列表

分頁 ​

上拉載入更多 → page += 1 → 重新請求對應狀態列表