229 lines
7.8 KiB
Markdown
229 lines
7.8 KiB
Markdown
---
|
||
name: 任务进度筛选对接
|
||
overview: 新增独立分页接口 `player-task/task-list`（筛选 task_type + status + page/page_size），供前端双下拉表格使用；保留现有 `player-task/task-progress` 全量快照不变。同步 slot_sdk 与 API 文档。
|
||
todos:
|
||
- id: wallet-model-paginate
|
||
content: WalletFundLotModel 新增 paginatePlayerTaskLots（按 lot_type/status 分页）
|
||
status: completed
|
||
- id: wallet-task-list-api
|
||
content: 新增 taskList 全链路（Validator/DTO/Logic/Service/Controller）
|
||
status: completed
|
||
- id: sdk-task-list
|
||
content: slot_sdk 新增 taskList 请求/响应实体与 WalletService 方法
|
||
status: completed
|
||
- id: api-doc-list
|
||
content: 新增 doc/player-task-list-api.md（含前端双下拉 + 分页说明）
|
||
status: completed
|
||
- id: feature-tests-list
|
||
content: Feature 测试：筛选、分页、参数校验；task-progress 回归不变
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# 玩家任务进度：新增分页列表接口
|
||
|
||
## 背景与目标
|
||
|
||
- **现有** [`player-task/task-progress`](doc/player-task-progress-api.md)：只读全量快照（`bonus_tasks` + `deposit_tasks` + `summary`），**不改契约**，继续给大厅/SDK 轻量查询用。
|
||
- **新增** `player-task/task-list`：面向 **前端操作页**（双下拉 + 表格），支持 **类型筛选、状态筛选、分页**。
|
||
|
||
前端操作区：
|
||
|
||
| 下拉框 | 选项 | 说明 |
|
||
|--------|------|------|
|
||
| 任务类型 | **Bonus** / **Deposit** | 必填，二选一 |
|
||
| 状态 | **全部** + Waiting / Active / PendingConversion / PlayedOut | `status=0` 或不传 = 全部可见态 |
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph keep [保持不变]
|
||
TP["POST task-progress"]
|
||
TP --> Full["bonus_tasks + deposit_tasks 全量"]
|
||
end
|
||
subgraph newApi [新增]
|
||
TL["POST task-list"]
|
||
TL --> Filter["task_type + status"]
|
||
TL --> Page["page + page_size"]
|
||
Page --> List["list + 分页元数据"]
|
||
end
|
||
UI[前端表格页] --> TL
|
||
Lobby[大厅轻量展示] --> TP
|
||
```
|
||
|
||
---
|
||
|
||
## 1. 新接口契约
|
||
|
||
### 1.1 路由
|
||
|
||
| 项 | 值 |
|
||
|----|-----|
|
||
| Method | `POST` |
|
||
| Path | `player-task/task-list` |
|
||
| Controller | [`PlayerTaskController::taskList`](app/api/controller/PlayerTaskController.php)（新增方法） |
|
||
|
||
### 1.2 请求参数
|
||
|
||
| 字段 | 类型 | 必填 | 说明 |
|
||
|------|------|------|------|
|
||
| `uid` | int | 是 | 用户 ID |
|
||
| `currency` | string | 是 | 币种，如 `TGO` |
|
||
| `task_type` | string | **是** | `bonus` \| `deposit` |
|
||
| `status` | int | 否 | `0` 或省略 = 全部玩家可见态；`1`/`2`/`3`/`5` = 单态 |
|
||
| `page` | int | 否 | 页码，默认 `1`，最小 `1` |
|
||
| `page_size` | int | 否 | 每页条数，默认 `20`，建议上限 `100` |
|
||
|
||
校验（[`PlayerTaskValidator`](app/validator/PlayerTaskValidator.php) 新 scene `list`）：
|
||
|
||
- `uid`：`require|integer`
|
||
- `currency`：`require`
|
||
- `task_type`：`require|in:bonus,deposit`
|
||
- `status`：`integer|in:0,1,2,3,5`（可空，默认 0）
|
||
- `page`：`integer|egt:1`（可空）
|
||
- `page_size`：`integer|between:1,100`（可空）
|
||
|
||
**前端映射**：
|
||
|
||
| UI | 请求 |
|
||
|----|------|
|
||
| Bonus | `"task_type": "bonus"` |
|
||
| Deposit | `"task_type": "deposit"` |
|
||
| 全部 | 不传 `status` 或 `"status": 0` |
|
||
| Waiting / Active / … | `status` = `1` / `2` / `3` / `5` |
|
||
| 翻页 | 修改 `page`（切换筛选时重置 `page=1`） |
|
||
|
||
### 1.3 成功响应 `data`
|
||
|
||
与仓库 [`SearchShardService`](app/service/search/shard/SearchShardService.php) 分页习惯对齐（`data` → `list`）：
|
||
|
||
```json
|
||
{
|
||
"task_type": "bonus",
|
||
"list": [ /* PlayerTaskItem，与 task-progress 任务项字段相同 */ ],
|
||
"total": 15,
|
||
"page": 1,
|
||
"page_size": 20,
|
||
"last_page": 1
|
||
}
|
||
```
|
||
|
||
- `list[]` 元素结构 **复用** [`PlayerTaskItemEntity::toApiArray()`](app/entity/wallet/PlayerTaskItemEntity.php)（与 `task-progress` 单条一致）。
|
||
- 排序：`consume_priority_at ASC`, `lot_id ASC`（与现 [`listPlayerTaskLots`](app/model/multi/WalletFundLotModel.php) 一致）。
|
||
- 状态范围：默认仍为 PRD §26.1 四态 `[1,2,3,5]`；**不含** Completed/Cancelled/Reversed（与 `task-progress` 一致）。
|
||
|
||
### 1.4 与 `task-progress` 的分工
|
||
|
||
| 接口 | 场景 | 返回 |
|
||
|------|------|------|
|
||
| `task-progress` | 一次拿全量两类任务 + 计数汇总 | `summary` + `bonus_tasks` + `deposit_tasks` |
|
||
| `task-list` | 表格页：选定类型 + 状态 + 翻页 | 单维 `list` + 分页字段 |
|
||
|
||
---
|
||
|
||
## 2. wallet 实现要点
|
||
|
||
### 2.1 Model
|
||
|
||
在 [`WalletFundLotModel`](app/model/multi/WalletFundLotModel.php) 新增：
|
||
|
||
```php
|
||
/**
|
||
* 分页查询玩家任务 Lot。
|
||
* @return array{list: array, total: int, page: int, page_size: int, last_page: int}
|
||
*/
|
||
public function paginatePlayerTaskLots(
|
||
string $currency,
|
||
int $lotType,
|
||
array $statuses,
|
||
int $page,
|
||
int $pageSize
|
||
): array
|
||
```
|
||
|
||
- `statuses` 为空时直接返回空分页（与 `listPlayerTaskLots` 一致）。
|
||
- 使用 ThinkORM `paginate($pageSize, false, ['page' => $page])`，再将 `data` 重命名为 `list`。
|
||
|
||
### 2.2 Service
|
||
|
||
在 [`PlayerTaskQueryService`](app/service/wallet/PlayerTaskQueryService.php) 新增 `queryTaskList(...)`：
|
||
|
||
- `task_type` 字符串 → `LOT_TYPE_BONUS` / `LOT_TYPE_DEPOSIT`
|
||
- `status` → `PLAYER_VISIBLE_STATUSES` 或单元素数组
|
||
- 调用 Model 分页后，`buildTaskItems()` 组装 `list`
|
||
|
||
### 2.3 分层文件（新增/扩展）
|
||
|
||
| 层级 | 文件 |
|
||
|------|------|
|
||
| DTO | `app/api/dto/request/PlayerTaskListRequestDTO.php`（新建） |
|
||
| Validator | `PlayerTaskValidator` 增加 `SCENE_LIST` |
|
||
| Logic | `PlayerTaskLogic::taskList()` |
|
||
| Controller | `PlayerTaskController::taskList()` |
|
||
|
||
**不修改** `PlayerTaskProgressRequestDTO` / `taskProgress` 逻辑。
|
||
|
||
---
|
||
|
||
## 3. slot_sdk
|
||
|
||
新增（与 wallet 字段 snake_case 一致）：
|
||
|
||
| 类型 | 文件 |
|
||
|------|------|
|
||
| 请求 | `PlayerTaskListRequestEntity.php` |
|
||
| 响应 | `PlayerTaskListResponseEntity.php`（含 `list`、`total`、`page`、`page_size`、`last_page`、`task_type`） |
|
||
|
||
[`WalletService`](slot_sdk/src/service/wallet/WalletService.php) 新增：
|
||
|
||
```php
|
||
public function taskList(PlayerTaskListRequestEntity $entity): ?PlayerTaskListResponseEntity
|
||
// POST api/player-task/task-list
|
||
```
|
||
|
||
`taskProgress` / `PlayerTaskProgressRequestEntity` **保持不变**。
|
||
|
||
发布：slot_sdk commit → push → slot-wallet `composer update`。
|
||
|
||
---
|
||
|
||
## 4. 文档
|
||
|
||
- **新建** [`doc/player-task-list-api.md`](doc/player-task-list-api.md)：路由、入参、响应、前端双下拉 + 翻页交互、与 `task-progress` 对比、curl 示例。
|
||
- [`doc/player-task-progress-api.md`](doc/player-task-progress-api.md) 顶部增加「列表分页请用 task-list」交叉引用。
|
||
- [`doc/wallet.md`](doc/wallet.md) §26.1 补充 `task-list` 一行说明。
|
||
|
||
---
|
||
|
||
## 5. 测试
|
||
|
||
新建 `tests/Feature/PlayerTaskListTest.php`（造数参考 [`WalletRegisterBetWinTest`](tests/Feature/WalletRegisterBetWinTest.php)）：
|
||
|
||
| 用例 | 断言 |
|
||
|------|------|
|
||
| `task_type=bonus` + 默认分页 | `list` 非空项字段完整；`total >= len(list)` |
|
||
| `status=2` | `list` 内 `status` 均为 2 |
|
||
| `page=2` + `page_size=1` | 第二页与总数一致 |
|
||
| 缺 `task_type` | `40003` |
|
||
| `page_size=101` | `40003` |
|
||
| `task-progress` 仍返回双数组 | 回归，不受新接口影响 |
|
||
|
||
容器内执行：`docker compose exec -T php82` + 项目 PHPUnit 命令。
|
||
|
||
---
|
||
|
||
## 6. 不在本次范围
|
||
|
||
- 修改 `task-progress` 入参或响应
|
||
- 任务类型「全部」合并在一个列表
|
||
- 运营后台终态（Completed 等）纳入筛选
|
||
- 前端页面实现（本仓库无前端）
|
||
|
||
---
|
||
|
||
## 7. 关键文件一览
|
||
|
||
| 仓库 | 变更 |
|
||
|------|------|
|
||
| slot-wallet | `PlayerTaskController`、`PlayerTaskLogic`、`PlayerTaskQueryService`、`WalletFundLotModel`、`PlayerTaskValidator`、新 DTO、`doc/player-task-list-api.md`、Feature 测试 |
|
||
| slot_sdk | 新 Entity ×2、`WalletService::taskList`、`readme.md` |
|