first commit

plans/status_返回_help_e344e40a.plan.md

@@ -0,0 +1,70 @@
+---
+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