cursor/plans/dailyrebate_max_rate_5541d0bb.plan.md

name, overview, todos, isProject

name	overview	todos	isProject
DailyRebate max_rate	将每日返水 C 端 `info` 接口的 `tiers` 数组改为返回档位中最高返水比例 `max_rate`（float），并清理不再使用的格式化方法。	id content status update-info-return 修改 DailyRebateLogic::info()：移除 tiers 返回，新增 max_rate completed id content status add-resolve-max-rate 新增 resolveMaxRateFromTiers()，删除 formatTiersForClient() completed id content status sync-phpdoc 更新 info() PHPDoc 与 Controller 注释 completed id content status verify 执行 verify-slot-backend.sh 验证 completed	false

每日返水 info 返回 max_rate

背景

当前 DailyRebateLogic::info() 会把全部档位格式化为 C 端展示数组：

$tierDisplay = $this->formatTiersForClient($tiers);
// ...
'tiers' => $tierDisplay,

C 端不需要完整 tiers，只需要所有档位里 rate_percent 最大的那个比例，字段名定为 max_rate（float，如 3.0 表示 3%）。

改动范围

仅改 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 返回结构：

/**
 * @return array{
 *     ...
 *     max_rate: float,
 *     records: list<...>
 * }
 */

2. 新增私有方法 resolveMaxRateFromTiers()

替换原 formatTiersForClient()，语义更清晰：

/**
 * 从档位配置中取最高返水比例（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() 注释「档位、近 7 日记录…」改为「最高返水比例、近 7 日记录…」。

接口变更（Breaking Change）

变更前	变更后
tiers: [{min, max, rate}, ...]	移除
—	max_rate: 3.0

示例（有 4 档配置，最高 3%）：

{
  "unlocked": true,
  "title": "...",
  "max_rate": 3.0,
  "records": [...]
}

当前仓库内 slot_pwa 尚未引用 tiers，后端先改即可；C 端接入时用 max_rate 展示「最高 X% 返水」类文案。

数据流（不变部分）

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