cursor/plans/status_返回_help_e344e40a.plan.md

name, overview, todos, isProject

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

status 接口增加 help 返回

目标

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

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

改动点

1. FreeCreditsLogic::buildStatus()

在现有返回数组中增加：

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

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

2. FreeCreditsController PHPDoc

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

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

3. 单测 FreeCreditsClientStatusTest

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

数据流

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