---
name: status 配置与未充值
overview: 修复 slot_console FreeCreditsLogic::status：无玩家池时返回 status=0 及活动配置；C 端新增 win_threshold（不含 initial_amount、home_withdraw_unlocked）。Logic 已按需求变更实现，待对齐单测与 PHPDoc。
todos:
  - id: logic-pre-enrollment
    content: FreeCreditsLogic：buildPreEnrollmentStatus；status() 无 player 时返回配置态（已完成）
    status: completed
  - id: logic-build-status-fields
    content: buildStatus / buildConfigClientFields 仅透出 win_threshold（不含 initial_amount、home_withdraw_unlocked）（已完成）
    status: completed
  - id: align-phpdoc
    content: FreeCreditsController PHPDoc 与 buildConfigClientFields 注释：删除 initial_amount、home_withdraw_unlocked；移除无用 DEFAULT_INITIAL_AMOUNT
    status: completed
  - id: align-unit-tests
    content: FreeCreditsClientStatusTest / FreeCreditsEligibilityTest 白名单与断言与现实现一致
    status: completed
isProject: false
---

# Free Credits status 接口修复计划（需求变更版）

## 需求确认（2026-05-21）

**C 端 `GET /api/free-credits/status` 约定：**

- **包含**：`win_threshold`（来自 `ext_config.win_threshold_qf`）
- **不包含**：`initial_amount`、`home_withdraw_unlocked`
  - 注册赠送金额：仍由 `game_base.user_register_reward` 等其它接口提供
  - 首页 Withdraw 解锁：C 端用 `status`（如 `STATUS_HOME_UNLOCKED=1`）或钱包余额 + `win_threshold` 自行判断；库表 `home_withdraw_unlocked` 仍由 `syncHomeWithdrawUnlocked` 维护，仅不下发 API

后台 type=11 的 `initial_amount_qf` 配置保留（运营后台用），**不**经 status 透出。

## 问题根因

[`FreeCreditsLogic::status()`](slot_console/app/api/logic/FreeCreditsLogic.php) 原逻辑在无 `free_credits_player` 时返回 `{ status: -1 }`，导致首充前 C 端无法展示活动（`status !== -1` 为展示开关）。

## 目标行为

| 场景 | status | 返回顶层字段 |
| --- | --- | --- |
| 无资格 / 无 type=11 配置 | `-1` | 仅 `status` |
| 有资格 + 有配置 + **无 player** | `0` | `status`, `frozen_amount`, `first_cash_amount`, `win_threshold`, `recharge_unlock_amount`, `help`, `packages`（空数组） |
| 有资格 + 有配置 + **有 player** | 玩家真实值 | 同上 + 玩家 `frozen_amount` / `first_cash_amount` / `packages` |

```mermaid
flowchart TD
  statusReq[GET status] --> eligible{资格+活动配置?}
  eligible -->|否| notVisible["status=-1"]
  eligible -->|是| player{有 player 行?}
  player -->|无| preConfig["status=0 + win_threshold 等"]
  player -->|有| fullStatus["buildStatus 玩家态"]
```

## 已实现 Logic（当前代码，无需再改字段集）

[`FreeCreditsLogic.php`](slot_console/app/api/logic/FreeCreditsLogic.php) 已与上表一致：

- `status()`：无 player → `buildPreEnrollmentStatus($config)`
- `buildConfigClientFields()`：仅 `win_threshold`、`recharge_unlock_amount`、`help`
- `buildStatus()` / `buildPreEnrollmentStatus()`：**不**返回 `initial_amount`、`home_withdraw_unlocked`

## 待办：对齐文档与单测

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

- 删除 `initial_amount`、`home_withdraw_unlocked` 字段说明
- 明确 `status=0` 时仍返回 `win_threshold`、`recharge_unlock_amount`、`help`

### 2. 清理 Logic 注释/死代码 — [`FreeCreditsLogic.php`](slot_console/app/api/logic/FreeCreditsLogic.php)

- 删除未使用的 `DEFAULT_INITIAL_AMOUNT` 常量（若仍保留）
- `buildConfigClientFields` 的 `@return` 改为仅含 `win_threshold`、`recharge_unlock_amount`、`help`

### 3. 单测

| 文件 | 改动 |
| --- | --- |
| [`FreeCreditsClientStatusTest.php`](slot_console/tests/Unit/FreeCreditsClientStatusTest.php) | `PLAYER_TOP_KEYS` 改为：`status`, `frozen_amount`, `first_cash_amount`, `win_threshold`, `recharge_unlock_amount`, `help`, `packages`；移除 `initial_amount`、`home_withdraw_unlocked` 断言 |
| [`FreeCreditsEligibilityTest.php`](slot_console/tests/Unit/FreeCreditsEligibilityTest.php) | `testStatusReturnsPreEnrollmentConfigWhenNoPlayer`：断言 `win_threshold=50`，**不**断言 `initial_amount` / `home_withdraw_unlocked` |

运行：

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

## C 端约定（供联调）

- **展示开关**：`data.status !== -1`；首充前为 `status === 0`
- **进度条上限**：`win_threshold`
- **注册赠送**：**不要**从 status 取；走注册/大厅配置接口
- **Withdraw 解锁**：**不要**依赖 `home_withdraw_unlocked` 字段；用 `status` 或余额逻辑

## 不在本次范围

- status 返回 `initial_amount` / `home_withdraw_unlocked`
- 注册发奖改读 `ext_config.initial_amount_qf`
- slot_pwa / gateway 前端改动
- backend 后台 `initial_amount_qf` 编辑能力（已存在）

## 验收清单

1. 无 player：`status=0`，含 `win_threshold`、`recharge_unlock_amount`、`help`，`packages=[]`，**无** `initial_amount`、`home_withdraw_unlocked` 键
2. 有 player：含玩家态金额 + 同上配置字段
3. 无资格/无配置：`status=-1`
4. 单测全部通过