59 lines
4.8 KiB
Markdown
59 lines
4.8 KiB
Markdown
---
|
||
name: 玩家任务进度查询
|
||
overview: 新增一个面向玩家的只读接口，返回当前 Bonus/Deposit 任务及其打码进度与详情，数据口径以 PRD 定义的 `wallet_fund_lot` 为准。保持现有资金主流程不变，仅补充查询链路与文档说明。
|
||
todos:
|
||
- id: define-player-task-endpoint
|
||
content: 新建独立玩家任务查询 Controller（不改 WalletController），并完成入参校验与统一返回
|
||
status: pending
|
||
- id: add-lot-query-service
|
||
content: 在 wallet 域新增只读查询服务，按 PRD 聚合 bonus/deposit 当前任务视图并计算进度字段
|
||
status: pending
|
||
- id: extend-fund-lot-model
|
||
content: 在 WalletFundLotModel 增加面向玩家任务页的查询方法（按币种、lot_type、状态过滤与排序）
|
||
status: pending
|
||
- id: document-api-contract
|
||
content: 更新 doc/wallet.md，补充玩家任务进度查询接口契约与状态语义
|
||
status: pending
|
||
- id: verify-key-scenarios
|
||
content: 按基础与边界场景验证返回结构、进度计算和状态映射
|
||
status: pending
|
||
isProject: false
|
||
---
|
||
|
||
# 玩家查看Bonus/Deposit任务与打码进度计划
|
||
|
||
## 目标与口径
|
||
- 提供玩家侧查询能力：查看“当前仍在生命周期内”的 `Bonus` 与 `Deposit` 任务，以及每条任务的进度与关键详情。
|
||
- 数据源以 [`/Users/ray/Documents/project/www/ray/slot-wallet/app/model/multi/WalletFundLotModel.php`](/Users/ray/Documents/project/www/ray/slot-wallet/app/model/multi/WalletFundLotModel.php) 为准，不再使用旧 `wager_task` 作为玩家任务主视图。
|
||
- 任务状态遵循 PRD（`Waiting/Active/PendingConversion/PlayedOut` 等），并输出前端可直接消费的进度字段。
|
||
|
||
## 接口设计（新增）
|
||
- 新建独立 Controller 承载玩家查询接口（建议新增 [`/Users/ray/Documents/project/www/ray/slot-wallet/app/api/controller/PlayerTaskController.php`](/Users/ray/Documents/project/www/ray/slot-wallet/app/api/controller/PlayerTaskController.php) 并提供 `taskProgress` 方法），不在 [`/Users/ray/Documents/project/www/ray/slot-wallet/app/api/controller/WalletController.php`](/Users/ray/Documents/project/www/ray/slot-wallet/app/api/controller/WalletController.php) 增加行为。
|
||
- 入参：`uid`、`currency`（可复用 [`/Users/ray/Documents/project/www/ray/slot-wallet/app/validator/WalletValidator.php`](/Users/ray/Documents/project/www/ray/slot-wallet/app/validator/WalletValidator.php) 现有校验，或为新 Controller 补充专用 scene/validator）。
|
||
- 出参建议：
|
||
- `summary`：当前 `bonus_task_count`、`deposit_task_count`。
|
||
- `bonus_tasks[]` 与 `deposit_tasks[]`：每条含 `lot_id`、`lot_no`、`status`、`status_text`、`source_type`、`source_id`、`original_amount`、`remaining_amount`、`required_wager`、`current_wager`、`left_wager`、`progress_rate`、`created_at`、`completed_at`、`brief`。
|
||
- “当前任务”默认筛选为：`status in (Waiting, Active, PendingConversion, PlayedOut)`；不返回 `Completed/Cancelled/Reversed`（避免历史噪音）。
|
||
|
||
## 分层落地
|
||
- Logic/Service 层新增只读查询编排（建议放在 wallet 域 service，控制器不直接拼查询）：
|
||
- 查询指定用户指定币种的 Deposit/Bonus Lots；
|
||
- 按类型分组并按 `consume_priority_at, id` 排序；
|
||
- 统一计算衍生字段：
|
||
- `left_wager = max(required_wager - current_wager, 0)`
|
||
- `progress_rate = required_wager > 0 ? min(current_wager / required_wager, 1) : 1`
|
||
- 统一状态文案映射（与 PRD 对齐）。
|
||
- Model 层在 [`/Users/ray/Documents/project/www/ray/slot-wallet/app/model/multi/WalletFundLotModel.php`](/Users/ray/Documents/project/www/ray/slot-wallet/app/model/multi/WalletFundLotModel.php) 补充专用查询方法（如按币种+lot_type+status 列表查询），保持 Controller/Logic 不下沉 SQL 细节。
|
||
|
||
## 文档与兼容
|
||
- 在 [`/Users/ray/Documents/project/www/ray/slot-wallet/doc/wallet.md`](/Users/ray/Documents/project/www/ray/slot-wallet/doc/wallet.md) 的 API 建议章节补充“玩家任务进度查询”示例（字段说明与状态语义）。
|
||
- 明确该接口是玩家视图；旧 [`/Users/ray/Documents/project/www/ray/slot-wallet/app/api/controller/TaskController.php`](/Users/ray/Documents/project/www/ray/slot-wallet/app/api/controller/TaskController.php) 维持兼容，不做破坏式改造。
|
||
|
||
## 验证计划
|
||
- 基础场景：同时存在 Bonus/Deposit Active 任务，返回分组正确、进度计算正确。
|
||
- 边界场景：
|
||
- `required_wager=0`（进度应视为 100%）；
|
||
- `current_wager > required_wager`（进度封顶 100%）；
|
||
- 仅有 PlayedOut Bonus（仍应展示，方便玩家理解“已用完未转化”）；
|
||
- 无当前任务（返回空数组与计数 0）。
|
||
- 一致性检查：字段值与 `wallet_fund_lot` 原始记录一致，且状态解释符合 PRD。 |