ok

plans/玩家任务进度查询_bf651c60.plan.md

@@ -0,0 +1,59 @@
+---
+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。