ok

plans/dailyrebate_max_rate_5541d0bb.plan.md

@@ -0,0 +1,138 @@
+---
+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`