130 lines
5.5 KiB
Markdown
130 lines
5.5 KiB
Markdown
---
|
||
name: status 透出后续最小充值
|
||
overview: 在 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` 一致。
|
||
todos:
|
||
- id: logic-expose-field
|
||
content: FreeCreditsLogic：buildConfigClientFields / buildStatus / buildPreEnrollmentStatus 透出 subsequent_min_recharge
|
||
status: completed
|
||
- id: controller-phpdoc
|
||
content: FreeCreditsController::status PHPDoc 补充 subsequent_min_recharge 说明
|
||
status: completed
|
||
- id: unit-tests
|
||
content: 更新 FreeCreditsClientStatusTest、FreeCreditsEligibilityTest 白名单与断言
|
||
status: completed
|
||
- id: run-phpunit
|
||
content: php82 容器跑相关单测验证
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# status 透出 subsequent_min_recharge
|
||
|
||
## 背景
|
||
|
||
后台 type=11 活动 [`ext_config`](backend/slot_admin_vue/src/views/game/activity/edit.vue) 已保存 **`subsequent_min_recharge_qf`**（后续解锁最小单笔充值，千分位）。
|
||
|
||
[`FreeCreditsLogic::advanceByRecharge()`](slot_console/app/api/logic/FreeCreditsLogic.php) 充值推进逻辑**已读取**该配置：
|
||
|
||
```627:628:slot_console/app/api/logic/FreeCreditsLogic.php
|
||
$minRecharge = $this->configAmount($config, 'subsequent_min_recharge', self::DEFAULT_SUBSEQUENT_MIN_RECHARGE);
|
||
if ($rechargeAmount < $minRecharge || !is_null(FreeCreditsPackageModel::nextReadyReleasePackage($player->id))) {
|
||
```
|
||
|
||
[`configAmount()`](slot_console/app/api/logic/FreeCreditsLogic.php) 会优先读 `key_qf`（即 `subsequent_min_recharge_qf`），再 fallback 旧键 `subsequent_min_recharge`。
|
||
|
||
但 C 端 [`buildConfigClientFields()`](slot_console/app/api/logic/FreeCreditsLogic.php) / [`buildStatus()`](slot_console/app/api/logic/FreeCreditsLogic.php) 目前只透出 `win_threshold`、`recharge_unlock_amount`、`help`、`banner_image`，**缺少**后续档解锁门槛，前端无法展示「单笔充值满 $X 解锁下一档」类文案。
|
||
|
||
```mermaid
|
||
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`）：
|
||
|
||
```json
|
||
{
|
||
"status": 2,
|
||
"win_threshold": 50.0,
|
||
"recharge_unlock_amount": 50.0,
|
||
"subsequent_min_recharge": 10.0,
|
||
"help": "...",
|
||
"packages": []
|
||
}
|
||
```
|
||
|
||
## 实现步骤（仅 slot_console）
|
||
|
||
### 1. Logic — [`FreeCreditsLogic.php`](slot_console/app/api/logic/FreeCreditsLogic.php)
|
||
|
||
在 **`buildConfigClientFields()`** 增加：
|
||
|
||
```php
|
||
'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()`** 顶层增加：
|
||
|
||
```php
|
||
'subsequent_min_recharge' => $configFields['subsequent_min_recharge'],
|
||
```
|
||
|
||
无需改 Model / Service；不新增中转 Service。
|
||
|
||
### 2. PHPDoc — [`FreeCreditsController.php`](slot_console/app/api/controller/FreeCreditsController.php)
|
||
|
||
在 `status()` 的 `data` 字段说明中，于 `recharge_unlock_amount` 后补充：
|
||
|
||
- `subsequent_min_recharge (float)` 解锁下一后续释放档所需**单笔**充值下限（来自 `ext_config.subsequent_min_recharge_qf`）
|
||
|
||
### 3. 单测
|
||
|
||
| 文件 | 改动 |
|
||
| --- | --- |
|
||
| [`FreeCreditsClientStatusTest.php`](slot_console/tests/Unit/FreeCreditsClientStatusTest.php) | `PLAYER_TOP_KEYS` 增加 `subsequent_min_recharge`；stub 配置加 `subsequent_min_recharge_qf`（如 `10000` → 展示 `10.0`）并断言 |
|
||
| [`FreeCreditsEligibilityTest.php`](slot_console/tests/Unit/FreeCreditsEligibilityTest.php) | `testStatusReturnsPreEnrollmentConfigWhenNoPlayer`：stub 加 `subsequent_min_recharge_qf`，断言 `subsequent_min_recharge` |
|
||
|
||
### 4. 验证
|
||
|
||
```bash
|
||
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. 上述单测通过
|