active

plans/status_返回_help_e344e40a.plan.md

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