---
name: status 返回 help
overview: 在 Free Credits C 端 status 接口（及 claim 同源 buildStatus）中增加 help 字段，读取活动配置表 recharge_gift_config.help，供问号说明弹窗等展示；status=-1 仍不返回 help。
todos:
  - id: build-status-help
    content: FreeCreditsLogic::buildStatus 增加 help 字段（读 config->help）
    status: completed
  - id: update-phpdoc
    content: FreeCreditsController::status PHPDoc 补充 help 说明
    status: completed
  - id: unit-test-help
    content: FreeCreditsClientStatusTest 白名单与透传断言
    status: completed
isProject: false
---

# status 接口增加 help 返回

## 目标

`GET /api/free-credits/status`（以及 `claim` 成功后的同源响应）在 `status !== -1` 时增加 **`help`（string）**，内容来自运营在后台活动编辑里填写的 **「帮助说明」**（[`recharge_gift_config.help`](slot_console/app/model/common/RechargeGiftConfigModel.php)）。

`status === -1` 时保持仅 `{ "status": -1 }`，不附带 help。

## 改动点

### 1. [`FreeCreditsLogic::buildStatus()`](slot_console/app/api/logic/FreeCreditsLogic.php)

在现有返回数组中增加：

```php
'help' => is_null($config) ? '' : strval($config->help ?? ''),
```

- `buildStatus` 已接收 `$config`（`activeConfig` 查出的 type=11 活动行），无需额外查库。
- 不做 §8 模板占位符替换（轻量方案）；C 端可用已有 `frozen_amount` / `recharge_unlock_amount` / `first_cash_amount` 自行替换，或原样展示运营配置的富文本/多行文案。

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

在 `status` 方法成功字段列表中补充：

- `help` (string) 活动规则说明，来自后台「帮助说明」

### 3. 单测 [`FreeCreditsClientStatusTest`](slot_console/tests/Unit/FreeCreditsClientStatusTest.php)

- `PLAYER_TOP_KEYS` 增加 `help`
- 用例：`FreeCreditsConfigStub` 设置 `help` 属性，`assertSame` 透传

## 数据流

```mermaid
flowchart LR
  admin[slot_admin 活动编辑 help 文本框]
  db[(recharge_gift_config.help)]
  logic[buildStatus]
  api["/api/free-credits/status"]
  admin --> db --> logic --> api
```

## 验收

- 后台 type=11 活动填写「帮助说明」并保存后，已参加用户 `status` 响应含相同 `help` 字符串
- `status=-1` 响应无 `help` 字段
- 单元测试通过；`claim` 返回结构同步含 `help`（复用 `buildStatus`）

## 不在本次范围

- `ext_config` 独立说明模板、动态金额替换服务端拼装
- `banner_image` 透出（如需可另开）
- 前端问号弹窗 UI