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

name, overview, todos, isProject

name	overview	todos	isProject
玩家任务进度查询	新增一个面向玩家的只读接口，返回当前 Bonus/Deposit 任务及其打码进度与详情，数据口径以 PRD 定义的 `wallet_fund_lot` 为准。保持现有资金主流程不变，仅补充查询链路与文档说明。	id content status define-player-task-endpoint 新建独立玩家任务查询 Controller（不改 WalletController），并完成入参校验与统一返回 pending id content status add-lot-query-service 在 wallet 域新增只读查询服务，按 PRD 聚合 bonus/deposit 当前任务视图并计算进度字段 pending id content status extend-fund-lot-model 在 WalletFundLotModel 增加面向玩家任务页的查询方法（按币种、lot_type、状态过滤与排序） pending id content status document-api-contract 更新 doc/wallet.md，补充玩家任务进度查询接口契约与状态语义 pending id content status verify-key-scenarios 按基础与边界场景验证返回结构、进度计算和状态映射 pending	false

玩家查看Bonus/Deposit任务与打码进度计划

目标与口径

• 提供玩家侧查询能力：查看“当前仍在生命周期内”的 Bonus 与 Deposit 任务，以及每条任务的进度与关键详情。
• 数据源以 /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 并提供 taskProgress 方法），不在 /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 现有校验，或为新 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 补充专用查询方法（如按币种+lot_type+status 列表查询），保持 Controller/Logic 不下沉 SQL 细节。

文档与兼容

• 在 /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 维持兼容，不做破坏式改造。

验证计划

• 基础场景：同时存在 Bonus/Deposit Active 任务，返回分组正确、进度计算正确。
• 边界场景：
  • required_wager=0（进度应视为 100%）；
  • current_wager > required_wager（进度封顶 100%）；
  • 仅有 PlayedOut Bonus（仍应展示，方便玩家理解“已用完未转化”）；
  • 无当前任务（返回空数组与计数 0）。
• 一致性检查：字段值与 wallet_fund_lot 原始记录一致，且状态解释符合 PRD。