139 lines
3.7 KiB
Markdown
139 lines
3.7 KiB
Markdown
---
|
||
name: DailyRebate max_rate
|
||
overview: 将每日返水 C 端 `info` 接口的 `tiers` 数组改为返回档位中最高返水比例 `max_rate`（float），并清理不再使用的格式化方法。
|
||
todos:
|
||
- id: update-info-return
|
||
content: 修改 DailyRebateLogic::info()：移除 tiers 返回，新增 max_rate
|
||
status: completed
|
||
- id: add-resolve-max-rate
|
||
content: 新增 resolveMaxRateFromTiers()，删除 formatTiersForClient()
|
||
status: completed
|
||
- id: sync-phpdoc
|
||
content: 更新 info() PHPDoc 与 Controller 注释
|
||
status: completed
|
||
- id: verify
|
||
content: 执行 verify-slot-backend.sh 验证
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# 每日返水 info 返回 max_rate
|
||
|
||
## 背景
|
||
|
||
当前 [`DailyRebateLogic::info()`](slot_console/app/api/logic/DailyRebateLogic.php) 会把全部档位格式化为 C 端展示数组：
|
||
|
||
```php
|
||
$tierDisplay = $this->formatTiersForClient($tiers);
|
||
// ...
|
||
'tiers' => $tierDisplay,
|
||
```
|
||
|
||
C 端不需要完整 `tiers`，只需要**所有档位里 `rate_percent` 最大的那个比例**，字段名定为 **`max_rate`**（float，如 `3.0` 表示 3%）。
|
||
|
||
## 改动范围
|
||
|
||
仅改 [`slot_console/app/api/logic/DailyRebateLogic.php`](slot_console/app/api/logic/DailyRebateLogic.php)（Controller 注释可选同步一行）。
|
||
|
||
`tiers` 仍保留在内部用于 `buildInfoViewContext()` 计算近 7 日返水，**结算/领取逻辑不动**。
|
||
|
||
## 实现步骤
|
||
|
||
### 1. 修改 `info()` 返回结构
|
||
|
||
在 `info()` 中：
|
||
|
||
- 删除 `$tierDisplay = $this->formatTiersForClient($tiers);`
|
||
- 新增 `$maxRate = $this->resolveMaxRateFromTiers($tiers);`
|
||
- 返回字段由 `'tiers' => $tierDisplay` 改为 `'max_rate' => $maxRate`
|
||
|
||
更新 `info()` PHPDoc 返回结构：
|
||
|
||
```php
|
||
/**
|
||
* @return array{
|
||
* ...
|
||
* max_rate: float,
|
||
* records: list<...>
|
||
* }
|
||
*/
|
||
```
|
||
|
||
### 2. 新增私有方法 `resolveMaxRateFromTiers()`
|
||
|
||
替换原 `formatTiersForClient()`，语义更清晰：
|
||
|
||
```php
|
||
/**
|
||
* 从档位配置中取最高返水比例（C 端展示用）。
|
||
*
|
||
* @param list<array{sort:int,min_bet:int,max_bet:?int,rate_percent:float}> $tiers
|
||
*/
|
||
protected function resolveMaxRateFromTiers(array $tiers): float
|
||
{
|
||
if ($tiers === []) {
|
||
return 0.0;
|
||
}
|
||
|
||
$maxRatePercent = 0.0;
|
||
foreach ($tiers as $tier) {
|
||
$maxRatePercent = max($maxRatePercent, (float) $tier['rate_percent']);
|
||
}
|
||
|
||
return $maxRatePercent;
|
||
}
|
||
```
|
||
|
||
边界处理：
|
||
|
||
- 无活动 / `$tiers === []` → 返回 `0.0`
|
||
- 多档同比例 → 取该值即可（`max()` 自然处理）
|
||
|
||
### 3. 删除 `formatTiersForClient()`
|
||
|
||
该方法仅在 `info()` 使用，删除避免 dead code。
|
||
|
||
### 4. 同步 Controller 注释（可选）
|
||
|
||
[`DailyRebateController::info()`](slot_console/app/api/controller/DailyRebateController.php) 注释「档位、近 7 日记录…」改为「最高返水比例、近 7 日记录…」。
|
||
|
||
## 接口变更（Breaking Change）
|
||
|
||
| 变更前 | 变更后 |
|
||
| --- | --- |
|
||
| `tiers: [{min, max, rate}, ...]` | **移除** |
|
||
| — | `max_rate: 3.0` |
|
||
|
||
示例（有 4 档配置，最高 3%）：
|
||
|
||
```json
|
||
{
|
||
"unlocked": true,
|
||
"title": "...",
|
||
"max_rate": 3.0,
|
||
"records": [...]
|
||
}
|
||
```
|
||
|
||
当前仓库内 **slot_pwa 尚未引用 `tiers`**，后端先改即可；C 端接入时用 `max_rate` 展示「最高 X% 返水」类文案。
|
||
|
||
## 数据流（不变部分）
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
config[DailyRebateConfigService.resolveForSource]
|
||
tiers[tiers内部数组]
|
||
info[DailyRebateLogic.info]
|
||
maxRate[max_rate]
|
||
records[records近7日]
|
||
config --> tiers
|
||
tiers --> info
|
||
info --> maxRate
|
||
info --> records
|
||
```
|
||
|
||
## 验证
|
||
|
||
- 跑 `~/.cursor/hooks/verify-slot-backend.sh`
|
||
- 手动调 `DailyRebate info`：有活动时应返回 `max_rate` 等于配置中最大 `rate_percent`；无活动时为 `0.0`
|