cursor/plans/status_透出后续最小充值_47cf9e62.plan.md

name, overview, todos, isProject

name	overview	todos	isProject
status 透出后续最小充值	在 slot_console 的 Free Credits `GET /api/free-credits/status`（及 claim 共用 `buildStatus`）中，将后台 ext_config 的 `subsequent_min_recharge_qf` 以 C 端约定字段 `subsequent_min_recharge`（float 大单位）透出，与 `recharge_unlock_amount` 一致。	id content status logic-expose-field FreeCreditsLogic：buildConfigClientFields / buildStatus / buildPreEnrollmentStatus 透出 subsequent_min_recharge completed id content status controller-phpdoc FreeCreditsController::status PHPDoc 补充 subsequent_min_recharge 说明 completed id content status unit-tests 更新 FreeCreditsClientStatusTest、FreeCreditsEligibilityTest 白名单与断言 completed id content status run-phpunit php82 容器跑相关单测验证 completed	false

status 透出 subsequent_min_recharge

背景

后台 type=11 活动 ext_config 已保存 subsequent_min_recharge_qf（后续解锁最小单笔充值，千分位）。

FreeCreditsLogic::advanceByRecharge() 充值推进逻辑已读取该配置：

        $minRecharge = $this->configAmount($config, 'subsequent_min_recharge', self::DEFAULT_SUBSEQUENT_MIN_RECHARGE);
        if ($rechargeAmount < $minRecharge || !is_null(FreeCreditsPackageModel::nextReadyReleasePackage($player->id))) {

configAmount() 会优先读 key_qf（即 subsequent_min_recharge_qf），再 fallback 旧键 subsequent_min_recharge。

但 C 端 buildConfigClientFields() / buildStatus() 目前只透出 win_threshold、recharge_unlock_amount、help、banner_image，缺少后续档解锁门槛，前端无法展示「单笔充值满 $X 解锁下一档」类文案。

flowchart LR
  extConfig["ext_config.subsequent_min_recharge_qf"]
  configAmount["configAmount(subsequent_min_recharge)"]
  buildFields["buildConfigClientFields"]
  statusAPI["status / claim data"]
  advanceByRecharge["advanceByRecharge 已有"]
  extConfig --> configAmount
  configAmount --> advanceByRecharge
  configAmount --> buildFields --> statusAPI

目标契约

项	约定
接口	GET /api/free-credits/status；POST /api/free-credits/claim 成功后的 data 结构相同
字段名	subsequent_min_recharge（与 recharge_unlock_amount 命名一致，不在 C 端响应中带 _qf）
类型	float，展示大单位（formatClientAmount + CommonFn::getNumberFormat）
配置来源	ext_config.subsequent_min_recharge_qf（经现有 configAmount）
默认值	DEFAULT_SUBSEQUENT_MIN_RECHARGE = 10（千分位 → 展示 10.0）
status=-1	仍仅 { status: -1 }，不含本字段
status=0 与有 player	均返回（与 recharge_unlock_amount 同级）

响应片段示例（status≥0）：

{
  "status": 2,
  "win_threshold": 50.0,
  "recharge_unlock_amount": 50.0,
  "subsequent_min_recharge": 10.0,
  "help": "...",
  "packages": []
}

实现步骤（仅 slot_console）

1. Logic — FreeCreditsLogic.php

在 buildConfigClientFields() 增加：

'subsequent_min_recharge' => $this->formatClientAmount(
    $this->configAmount($config, 'subsequent_min_recharge', self::DEFAULT_SUBSEQUENT_MIN_RECHARGE)
),

• config === null 时占位 0.0（与 recharge_unlock_amount 一致）
• 更新方法 @return 数组 shape

在 buildStatus()、buildPreEnrollmentStatus() 顶层增加：

'subsequent_min_recharge' => $configFields['subsequent_min_recharge'],

无需改 Model / Service；不新增中转 Service。

2. PHPDoc — FreeCreditsController.php

在 status() 的 data 字段说明中，于 recharge_unlock_amount 后补充：

• subsequent_min_recharge (float) 解锁下一后续释放档所需单笔充值下限（来自 ext_config.subsequent_min_recharge_qf）

3. 单测

文件	改动
FreeCreditsClientStatusTest.php	PLAYER_TOP_KEYS 增加 subsequent_min_recharge；stub 配置加 subsequent_min_recharge_qf（如 10000 → 展示 10.0）并断言
FreeCreditsEligibilityTest.php	testStatusReturnsPreEnrollmentConfigWhenNoPlayer：stub 加 subsequent_min_recharge_qf，断言 subsequent_min_recharge

4. 验证

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

不在本次范围

• C 端 / slot_pwa 消费字段与 UI 文案（仅后端补字段）
• 透出 first_cash_amount、package_amount、max_unlock_per_recharge 等其它 ext 配置
• 修改 advanceByRecharge 业务规则（已正确读配置）

验收

1. 有资格且 status≥0：data 含 subsequent_min_recharge，值与后台配置的 subsequent_min_recharge_qf 一致（大单位）
2. status=-1：无该键
3. claim 成功返回的 data 同样含该字段
4. 上述单测通过