ray604638018/cursor

Fork 0

Files

ray zhou f71a5c59af ok

2026-05-29 11:21:40 +08:00

7.8 KiB

Raw Permalink Blame History

name, overview, todos, isProject

name

overview

todos

isProject

任务进度筛选对接

新增独立分页接口 `player-task/task-list`（筛选 task_type + status + page/page_size），供前端双下拉表格使用；保留现有 `player-task/task-progress` 全量快照不变。同步 slot_sdk 与 API 文档。

id	content	status
wallet-model-paginate	WalletFundLotModel 新增 paginatePlayerTaskLots（按 lot_type/status 分页）	completed

id	content	status
wallet-task-list-api	新增 taskList 全链路（Validator/DTO/Logic/Service/Controller）	completed

id	content	status
sdk-task-list	slot_sdk 新增 taskList 请求/响应实体与 WalletService 方法	completed

id	content	status
api-doc-list	新增 doc/player-task-list-api.md（含前端双下拉 + 分页说明）	completed

id	content	status
feature-tests-list	Feature 测试：筛选、分页、参数校验；task-progress 回归不变	completed

false

玩家任务进度：新增分页列表接口

背景与目标

现有 player-task/task-progress：只读全量快照（bonus_tasks + deposit_tasks + summary），不改契约，继续给大厅/SDK 轻量查询用。
新增 player-task/task-list：面向 前端操作页（双下拉 + 表格），支持 类型筛选、状态筛选、分页。

前端操作区：

下拉框	选项	说明
任务类型	Bonus / Deposit	必填，二选一
状态	全部 + Waiting / Active / PendingConversion / PlayedOut	`status=0` 或不传 = 全部可见态

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`（新增方法）

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 新 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 分页习惯对齐（data → list）：

{
  "task_type": "bonus",
  "list": [ /* PlayerTaskItem，与 task-progress 任务项字段相同 */ ],
  "total": 15,
  "page": 1,
  "page_size": 20,
  "last_page": 1
}

list[] 元素结构复用 PlayerTaskItemEntity::toApiArray()（与 task-progress 单条一致）。
排序：consume_priority_at ASC, lot_id ASC（与现 listPlayerTaskLots 一致）。
状态范围：默认仍为 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 新增：

/**
 * 分页查询玩家任务 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 新增 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 新增：

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：路由、入参、响应、前端双下拉 + 翻页交互、与 task-progress 对比、curl 示例。
doc/player-task-progress-api.md 顶部增加「列表分页请用 task-list」交叉引用。
doc/wallet.md §26.1 补充 task-list 一行说明。

5. 测试

新建 tests/Feature/PlayerTaskListTest.php（造数参考 WalletRegisterBetWinTest）：

用例	断言
`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`

7.8 KiB Raw Permalink Blame History Unescape Escape