---
name: status 透出后续最小充值
overview: 在 slot_console 的 Free Credits `GET /api/free-credits/status`（及 claim 共用 `buildStatus`）中，将后台 ext_config 的 `subsequent_min_recharge_qf` 以 C 端约定字段 `subsequent_min_recharge`（float 大单位）透出，与 `recharge_unlock_amount` 一致。
todos:
  - id: logic-expose-field
    content: FreeCreditsLogic：buildConfigClientFields / buildStatus / buildPreEnrollmentStatus 透出 subsequent_min_recharge
    status: completed
  - id: controller-phpdoc
    content: FreeCreditsController::status PHPDoc 补充 subsequent_min_recharge 说明
    status: completed
  - id: unit-tests
    content: 更新 FreeCreditsClientStatusTest、FreeCreditsEligibilityTest 白名单与断言
    status: completed
  - id: run-phpunit
    content: php82 容器跑相关单测验证
    status: completed
isProject: false
---

# status 透出 subsequent_min_recharge

## 背景

后台 type=11 活动 [`ext_config`](backend/slot_admin_vue/src/views/game/activity/edit.vue) 已保存 **`subsequent_min_recharge_qf`**（后续解锁最小单笔充值，千分位）。

[`FreeCreditsLogic::advanceByRecharge()`](slot_console/app/api/logic/FreeCreditsLogic.php) 充值推进逻辑**已读取**该配置：

```627:628:slot_console/app/api/logic/FreeCreditsLogic.php
        $minRecharge = $this->configAmount($config, 'subsequent_min_recharge', self::DEFAULT_SUBSEQUENT_MIN_RECHARGE);
        if ($rechargeAmount < $minRecharge || !is_null(FreeCreditsPackageModel::nextReadyReleasePackage($player->id))) {
```

[`configAmount()`](slot_console/app/api/logic/FreeCreditsLogic.php) 会优先读 `key_qf`（即 `subsequent_min_recharge_qf`），再 fallback 旧键 `subsequent_min_recharge`。

但 C 端 [`buildConfigClientFields()`](slot_console/app/api/logic/FreeCreditsLogic.php) / [`buildStatus()`](slot_console/app/api/logic/FreeCreditsLogic.php) 目前只透出 `win_threshold`、`recharge_unlock_amount`、`help`、`banner_image`，**缺少**后续档解锁门槛，前端无法展示「单笔充值满 $X 解锁下一档」类文案。

```mermaid
flowchart LR
  extConfig["ext_config.subsequent_min_recharge_qf"]
  configAmount["configAmount(subsequent_min_recharge)"]
  buildFields["buildConfigClientFields"]
  statusAPI["status / claim data"]
  advanceByRecharge["advanceByRecharge 已有"]
  extConfig --> configAmount
  configAmount --> advanceByRecharge
  configAmount --> buildFields --> statusAPI
```

## 目标契约

| 项 | 约定 |
| --- | --- |
| 接口 | `GET /api/free-credits/status`；`POST /api/free-credits/claim` 成功后的 `data` 结构相同 |
| 字段名 | **`subsequent_min_recharge`**（与 `recharge_unlock_amount` 命名一致，**不**在 C 端响应中带 `_qf`） |
| 类型 | `float`，展示大单位（`formatClientAmount` + `CommonFn::getNumberFormat`） |
| 配置来源 | `ext_config.subsequent_min_recharge_qf`（经现有 `configAmount`） |
| 默认值 | `DEFAULT_SUBSEQUENT_MIN_RECHARGE = 10`（千分位 → 展示 `10.0`） |
| `status=-1` | 仍仅 `{ status: -1 }`，不含本字段 |
| `status=0` 与有 player | 均返回（与 `recharge_unlock_amount` 同级） |

响应片段示例（`status≥0`）：

```json
{
  "status": 2,
  "win_threshold": 50.0,
  "recharge_unlock_amount": 50.0,
  "subsequent_min_recharge": 10.0,
  "help": "...",
  "packages": []
}
```

## 实现步骤（仅 slot_console）

### 1. Logic — [`FreeCreditsLogic.php`](slot_console/app/api/logic/FreeCreditsLogic.php)

在 **`buildConfigClientFields()`** 增加：

```php
'subsequent_min_recharge' => $this->formatClientAmount(
    $this->configAmount($config, 'subsequent_min_recharge', self::DEFAULT_SUBSEQUENT_MIN_RECHARGE)
),
```

- `config === null` 时占位 `0.0`（与 `recharge_unlock_amount` 一致）
- 更新方法 `@return` 数组 shape

在 **`buildStatus()`**、**`buildPreEnrollmentStatus()`** 顶层增加：

```php
'subsequent_min_recharge' => $configFields['subsequent_min_recharge'],
```

无需改 Model / Service；不新增中转 Service。

### 2. PHPDoc — [`FreeCreditsController.php`](slot_console/app/api/controller/FreeCreditsController.php)

在 `status()` 的 `data` 字段说明中，于 `recharge_unlock_amount` 后补充：

- `subsequent_min_recharge (float)` 解锁下一后续释放档所需**单笔**充值下限（来自 `ext_config.subsequent_min_recharge_qf`）

### 3. 单测

| 文件 | 改动 |
| --- | --- |
| [`FreeCreditsClientStatusTest.php`](slot_console/tests/Unit/FreeCreditsClientStatusTest.php) | `PLAYER_TOP_KEYS` 增加 `subsequent_min_recharge`；stub 配置加 `subsequent_min_recharge_qf`（如 `10000` → 展示 `10.0`）并断言 |
| [`FreeCreditsEligibilityTest.php`](slot_console/tests/Unit/FreeCreditsEligibilityTest.php) | `testStatusReturnsPreEnrollmentConfigWhenNoPlayer`：stub 加 `subsequent_min_recharge_qf`，断言 `subsequent_min_recharge` |

### 4. 验证

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

## 不在本次范围

- C 端 / slot_pwa 消费字段与 UI 文案（仅后端补字段）
- 透出 `first_cash_amount`、`package_amount`、`max_unlock_per_recharge` 等其它 ext 配置
- 修改 `advanceByRecharge` 业务规则（已正确读配置）

## 验收

1. 有资格且 `status≥0`：`data` 含 `subsequent_min_recharge`，值与后台配置的 `subsequent_min_recharge_qf` 一致（大单位）
2. `status=-1`：无该键
3. `claim` 成功返回的 `data` 同样含该字段
4. 上述单测通过