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

# C 端定格状态 packages 响应调整

## 背景与范围

目标接口在 [slot_console/app/api/controller/FreeCreditsController.php](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](slot_console/app/model/common/FreeCreditsPackageModel.php) 的 `listForClient()` 组装，经 `FreeCreditsLogic::clientPackagesForPlayer()` 注入响应：

```72:86:slot_console/app/model/common/FreeCreditsPackageModel.php
    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](slot_console/db/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 端展示层）：

```mermaid
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](slot_console/app/model/common/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](slot_console/app/api/logic/FreeCreditsLogic.php)：`clientPackagesForPlayer()` 的 `@return` 与注释。
- [FreeCreditsController.php](slot_console/app/api/controller/FreeCreditsController.php)：`status()` / `claim()` 中 `packages` 字段说明——去掉 `package_no`、`package_type`；`status` 改为 `0 locked ~ 3 completed（失败/拒绝对外亦为 3）`。

### 3. 单测

- [FreeCreditsClientStatusTest.php](slot_console/tests/Unit/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](slot_console/tests/Support/FreeCreditsLogicHarness.php)：更新 `injectClientPackages` 相关 PHPDoc 类型。

运行（Docker）：

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

## 数据流（变更后）

```mermaid
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](slot_console/tests/Unit/FreeCreditsClientStatusTest.php) 期望顶层含 `first_cash_amount`，但 [buildStatus](slot_console/app/api/logic/FreeCreditsLogic.php) 当前未返回该字段——与本次改动无关，不纳入本 PR，除非你希望一并补齐。