Appearance
福利中心（開發文檔）
最後更新：2026-04-10
📖 功能說明請參考 福利中心
架構
相關檔案
ViewController / ViewModel（2 個）
| 檔案 | 說明 |
|---|---|
.../WalfareCentre/C/WelfareCentreViewController.swift | 福利中心主頁 |
.../WalfareCentre/M/WelfareCentreViewModel.swift | ViewModel |
基礎路徑：
BBSport/Tab/我的/Mine/MiddleMenu/
View（6 個）
| 檔案 | 說明 |
|---|---|
.../WalfareCentre/V/WelfareCentreCellTableViewCell.swift | 福利 Cell |
.../WalfareCentre/V/WelfareCentreFilterView.swift | 篩選視圖 |
.../WalfareCentre/V/WelfareCentreHeaderView.swift | Header |
.../WalfareCentre/V/WelfareCentreTableView.swift | TableView |
.../WalfareCentre/V/WelfareCenterFooterView.swift | Footer |
.../WalfareCentre/V/SelectMultipleButtons.swift | 多選按鈕 |
基礎路徑：
BBSport/Tab/我的/Mine/MiddleMenu/
Model（1 個）
| 檔案 | 說明 |
|---|---|
.../WalfareCentre/M/WelfareCentreModel.swift | 福利 Model |
基礎路徑：
BBSport/Tab/我的/Mine/MiddleMenu/
API（4 個）
| 檔案 | 說明 |
|---|---|
.../WelfareCenter/STAPI+WelfareCenterListRequest.swift | 福利列表 |
.../WelfareCenter/STAPI+WelfareCenterClaimRequest.swift | 領取 |
.../WelfareCenter/STAPI+WelfareCenterUnclaimCountRequest.swift | 未領取數 |
.../WelfareCenter/STAPI+WelfareCountByAwardTypeRequest.swift | 各類型數量 |
基礎路徑：
BBSport/API/STAPI/
API
進入福利中心
福利列表
POST api/forehead/activity/welfare/list — urlForm — STAPI.WelfareCenterListRequest
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| status | String | 進行中: "0,6"，已失效: "-1,1,2,3,4,5" | |
| page | Int | ✅ | 頁碼（從 0 開始） |
| size | Int | ✅ | 固定 200 |
Response：
| 欄位 | 型別 | 說明 |
|---|---|---|
| pageNum | Int | 當前頁碼 |
| total | Int | 總筆數 |
| list | [WelfareCentreDetailModel] | 福利項目列表 |
WelfareCentreDetailModel 欄位
actId(Int), actName(String), awardType(Int), claimTime(Int), createTime(Int), expireTime(Int), imgUrl(String), idStr(String), price(Double), prizeId(Int), prizeName(String), status(Int) 等
各類型數量統計
POST api/forehead/activity/welfare/countByAwardType — urlForm — STAPI.WelfareCountByAwardTypeRequest
無參數，靠 Header token/uid 認證。
Response： [WelfareCountModel]
| 欄位 | 型別 | 說明 |
|---|---|---|
| typeName | WelfareCoupon | 福利券類型（見下方枚舉值） |
| awardTypes | [Int] | 對應後端 awardType 值 |
| unClaimCount | Int | 未領取數量 |
| invalidCount | Int | 已失效數量 |
WelfareCoupon 枚舉值（用於分類篩選）：
| rawValue（String） | 說明 |
|---|---|
"现金" | 現金 |
"现金券" | 現金券 |
"存送券" | 存送券 |
"流水券" | 流水券 |
"实物" | 實物 |
"VIP成长值" | VIP 成長值 |
"礼品券" | 禮品券 |
"称号" | 稱號 |
"体验金" | 體驗金 |
"" | 空值（預設） |
awardType 對照表（WelfareCouponType 枚舉）：
| rawValue（Int） | 枚舉名 | 說明 |
|---|---|---|
| -10 | cashNegativeTen | — |
| -9 | cashNegativeNine | 現金 |
| -6 | experienceTicket | 體驗金 |
| 0 | cashZero | 金幣 |
| 1 | cashOne | — |
| 2 | cashTwo | — |
| 3 | goods | 實物 |
| 4 | cashFour | — |
| 5 | cashFive | — |
| 6 | cashSix | — |
| 7 | cashSeven | — |
| 8 | cash | 現金券/免費彩金 |
| 10 | cashTen | — |
| 11 | vip | VIP 經驗值 |
| 12 | saveTicket | 存送券 |
| 13 | waterTicket | 流水券 |
| 14 | cashFourteen | — |
| 15 | coin | 金幣 |
| 16 | giftTicket | 禮品券 |
| 17 | title | 稱號 |
完整的後端 awardType 含義也可參考 每日任務與簽到-dev 的獎勵類型對照表。
領取福利
POST api/forehead/activity/welfare/claim — urlForm — STAPI.WelfareCenterClaimRequest
| 參數 | 型別 | 必填 | 說明 |
|---|---|---|---|
| idStr | String | ✅ | 福利項目 ID |
| addressId | String | 收貨地址 ID（實物必填） |
Response： 無 data，僅 code + message。
未領取數量
POST api/forehead/activity/welfare/unClaimCount — urlForm — STAPI.WelfareCenterUnclaimCountRequest
無參數（需 Authorization）。Response： data: Int。
狀態碼
| 值 | 說明 |
|---|---|
-1 | 不可領取 |
0 | 可領取（已達標未領） |
1 | 已領取 |
2 | 已過期 |
3 | 已發貨 |
4 | 已拒絕 |
5 | 已刪除 |
6 | 未使用 |
實作重點
- 雙重狀態管理：進行中 / 已失效各有獨立分頁計數器
- 本地篩選：類型篩選在本地 filter，不重新請求 API
- 數量 badge：
WelfareCountByAwardTypeRequest取得各類型數量，篩選按鈕旁顯示 - 分頁加載：
currentEnablePage/currentDisablePage管理各狀態分頁，透過MJRefreshAutoNormalFooter觸發上拉加載更多。呼叫viewModel.loadMoreData()時根據當前 Tab（進行中/已失效）對對應的 page 計數器 +1 並請求下一頁。每頁固定size=200 - 分頁觸發條件：TableView 底部的
MJRefreshAutoNormalFooter，上拉到底自動觸發 - 狀態對應：進行中 =
status 0, 6；已失效 = 其餘 - 收貨地址：實物獎勵需填收貨地址。跳轉到
BBPersonalInfoEntryAddressController（位於BBSport/Tab/我的/Mine/UserInfo/C/），是個人資訊模組的共用元件，非本模組獨有 - WalfareCentre vs WelfareCenter 拼寫差異：目錄和部分檔案名使用
WalfareCentre（如WalfareCentre/C/WelfareCentreViewController.swift），而 API Request 檔案使用WelfareCenter（如STAPI+WelfareCenterListRequest.swift）。這是歷史拼寫差異，Walfare為早期 typo，後續 API 層修正為Welfare但 UI 層未統一重命名