--- 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。