---
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`