cursor/plans/c端_packages_响应精简_b2ac407a.plan.md

name, overview, todos, isProject

name	overview	todos	isProject
C端 packages 响应精简	在 slot_console 的 Free Credits 定格状态接口（`/api/free-credits/status` 与 `claim` 共用 `buildStatus`）中，精简 `packages[]` 每项字段，并将档位 status 4/5 映射为 3，使 C 端仅见 0–3。后台 innerapi 与库表语义不变。	id content status model-list-for-client 在 FreeCreditsPackageModel 实现 mapStatusForClient，并精简 listForClient 返回字段 in_progress id content status update-phpdoc 更新 FreeCreditsLogic、FreeCreditsController 的 packages/status PHPDoc pending id content status update-unit-tests 调整 FreeCreditsClientStatusTest / Harness，并补充 status 4/5→3 用例 pending id content status run-phpunit 在 php82 容器内跑 FreeCreditsClientStatusTest 验证 pending	false

C 端定格状态 packages 响应调整

背景与范围

目标接口在 slot_console/app/api/controller/FreeCreditsController.php：

• POST /api/free-credits/status → FreeCreditsLogic::status() → buildStatus()
• POST /api/free-credits/claim 成功后的 data 结构相同

packages[] 当前由 slot_console/app/model/common/FreeCreditsPackageModel.php 的 listForClient() 组装，经 FreeCreditsLogic::clientPackagesForPlayer() 注入响应：

    public static function listForClient(int $playerId, callable $formatAmount): array
    {
        // ...
            $packages[] = [
                'id' => intval($row->id),
                'package_no' => intval($row->package_no),
                'package_type' => intval($row->package_type),
                'amount' => $formatAmount(intval($row->amount_qf)),
                'status' => intval($row->status),
            ];

库表档位 status（install.sql）：0 锁定、1 可操作、2 处理中、3 已完成、4 失败、5 风控拒绝。

不在本次范围：innerapi/free-credits/*（后台仍用 package_no / package_type 聚合）、库表与 Logic 内按 package_no / package_type 的业务判断。

目标契约

packages[] 每项仅保留：

字段	类型	说明
id	int	档位主键；claim / 第一档提现仍传 package_id
amount	float	展示大单位，逻辑不变
status	int	仅可能为 0、1、2、3；DB 为 4 或 5 时对外返回 3

列表仍按 package_no 升序（查询不变，仅响应不暴露 package_no）。C 端可用数组下标区分第一档（[0]）与后续档。

Status 映射（仅 C 端展示层）：

flowchart LR
  db0[DB 0 locked] --> c0[C 0]
  db1[DB 1 ready] --> c1[C 1]
  db2[DB 2 processing] --> c2[C 2]
  db3[DB 3 completed] --> c3[C 3]
  db4[DB 4 failed] --> c3
  db5[DB 5 rejected] --> c3

实现步骤

1. 修改 FreeCreditsPackageModel::listForClient()

文件：FreeCreditsPackageModel.php

• 新增私有/公有静态方法（建议 mapStatusForClient(int $status): int），将 STATUS_FAILED(4)、STATUS_REJECTED(5) 转为 STATUS_COMPLETED(3)，其余原样返回。
• listForClient() 返回项改为 { id, amount, status }，status 走映射方法。
• 更新 @return PHPDoc：list<array{id:int,amount:float,status:int}>，并注明 C 端 status 取值 0–3。

2. 同步 Logic / Controller 文档

• FreeCreditsLogic.php：clientPackagesForPlayer() 的 @return 与注释。
• FreeCreditsController.php：status() / claim() 中 packages 字段说明——去掉 package_no、package_type；status 改为 0 locked ~ 3 completed（失败/拒绝对外亦为 3）。

3. 单测

• FreeCreditsClientStatusTest.php：PACKAGE_KEYS 改为 ['id','amount','status']；注入样例去掉 package_no / package_type。
• 新增用例（二选一或都做）：
  • 对 mapStatusForClient：断言 4→3、5→3、0–3 不变；
  • 或在 harness 注入 status=4/5 的 package，断言 buildStatus 输出为 3。
• FreeCreditsLogicHarness.php：更新 injectClientPackages 相关 PHPDoc 类型。

运行（Docker）：

docker exec -w /app/www/slot/slot_console php82 ./vendor/bin/phpunit tests/Unit/FreeCreditsClientStatusTest.php

数据流（变更后）

sequenceDiagram
  participant C as C端
  participant API as FreeCreditsController
  participant Logic as FreeCreditsLogic
  participant Model as FreeCreditsPackageModel

  C->>API: status / claim
  API->>Logic: buildStatus
  Logic->>Model: listForClient
  Model->>Model: mapStatusForClient
  Model-->>Logic: id, amount, status
  Logic-->>C: packages[]

风险与说明

• C 端若已依赖 package_no / package_type 或区分 4/5：需同步改 UI；服务端 claim 仍用 package_id，顺序校验仍在 Logic/DB，不依赖响应里的 package_no。
• 失败/拒绝与成功完成在 UI 上同为 status=3：符合当前需求；若以后要区分展示，需另加字段或改映射规则。
• 单测 FreeCreditsClientStatusTest 期望顶层含 first_cash_amount，但 buildStatus 当前未返回该字段——与本次改动无关，不纳入本 PR，除非你希望一并补齐。