ok

2026-05-29 11:21:40 +08:00
parent 5d6d482efe
commit f71a5c59af
447 changed files with 32245 additions and 116 deletions
--- a/plans/每日返水活动化改造_dd1575a1.plan.md
+++ b/plans/每日返水活动化改造_dd1575a1.plan.md
@@ -0,0 +1,225 @@
+---
+name: 每日返水活动化改造
+overview: 将每日返水从独立档位表方案，改为与首充定格（Free Credits, type=11）一致的活动配置模式：新增活动类型 12、档位写入 recharge_gift_config.ext_config，保留 daily_rebate_record 做用户日统计与领取，综合统计页独立不变。
+todos:
+  - id: activity-type-12
+    content: 新增 TYPE_DAILY_REBATE=12：RechargeGiftConfigModel、getDailyRebateActiveInfo、Consts、activity_type 字典 SQL
+    status: completed
+  - id: activity-ext-config
+    content: ActivityValidate::checkDailyRebateExt + ActivityController save/update；activity/edit.vue & index.vue type=12 档位 UI
+    status: completed
+  - id: refactor-daily-rebate-service
+    content: DailyRebateService 改读 recharge_gift_config.ext_config；daily_rebate_record 增加 activity_id
+    status: completed
+  - id: remove-tier-table
+    content: 删除 daily_rebate_tier_config 及相关 Admin CRUD/菜单；更新 daily_rebate.sql
+    status: completed
+  - id: complete-stats-api
+    content: 补全 dailyRebateStats 前端页 + 确认 DailyRebateSettle/Expire/API/流水类型 65
+    status: completed
+  - id: tests-acceptance
+    content: DailyRebateCalcServiceTest + 端到端验收（配置→结算→领取→统计）
+    status: completed
+isProject: false
+---
+
+# 每日返水 — 活动化改造方案（对齐首充定格）
+
+## 背景与纠偏
+
+你已指出：**这是活动，应新增活动类型，返水档位在「活动配置」里维护**，参考首充定格（Free Credits）。
+
+现有代码库中首充定格模式：
+
+| 层级 | 实现 |
+|------|------|
+| 配置表 | [`s_recharge_gift_config`](slot_console/app/model/common/RechargeGiftConfigModel.php)（后台称「充值活动配置」） |
+| 活动类型 | `TYPE_FREE_CREDITS = 11` |
+| 业务参数 | `ext_config` JSON（千分位 `_qf` 字段） |
+| 后台入口 | [活动管理 → 充值活动配置](backend/slot_admin_vue/src/views/game/activity/index.vue) + [edit.vue type==11 表单项](backend/slot_admin_vue/src/views/game/activity/edit.vue) |
+| 校验 | [`ActivityValidate::checkFreeCreditsExt`](backend/slot_admin/app/game/validate/ActivityValidate.php) + [`ActivityController::save/update`](backend/slot_admin/app/game/controller/ActivityController.php) |
+| 运行时查询 | [`RechargeGiftConfigModel::getFreeCreditsActiveInfo`](slot_console/app/model/common/RechargeGiftConfigModel.php) |
+| 用户状态 | 独立表 `free_credits_player` / `free_credits_package` |
+
+**先前中断实现的问题**：已创建 [`daily_rebate_tier_config`](slot_console/db/daily_rebate.sql) 独立表及 [`DailyRebateTierConfig*`](backend/slot_admin/app/game/controller/DailyRebateTierConfigController.php) 后台 — **与产品约定不符，应废弃并改为 ext_config**。
+
+**可保留部分**（逻辑正确，仅需改配置来源）：
+
+- [`DailyRebateCalcService`](slot_console/app/service/DailyRebateCalcService.php) — 累进分段计算
+- [`daily_rebate_record`](slot_console/db/daily_rebate.sql) — 用户日返水记录（需加 `activity_id`）
+- [`DailyRebateSettle` / `DailyRebateExpire`](slot_console/app/command/DailyRebateSettle.php) 定时任务
+- [`DailyRebateController`](slot_console/app/api/controller/DailyRebateController.php) C 端 info/claim
+- [`DailyRebateStats*`](backend/slot_admin/app/game/controller/DailyRebateStatsController.php) — **综合统计/每日返水统计**（独立菜单，同 Free Credits 统计）
+
+```mermaid
+flowchart TB
+  subgraph admin [活动管理 slot_admin]
+    ActivityUI["activity/edit.vue type=12"]
+    ActivityAPI["ActivityController + ActivityService"]
+  end
+  subgraph config [s_common]
+    RGC["recharge_gift_config ext_config.tiers"]
+    DRR["daily_rebate_record"]
+  end
+  subgraph runtime [slot_console]
+    Settle["dailyRebateSettle"]
+    API["DailyRebateService info/claim"]
+  end
+  ActivityUI --> ActivityAPI --> RGC
+  Settle --> RGC
+  Settle --> DRR
+  API --> RGC
+  API --> DRR
+```
+
+---
+
+## 1. 新增活动类型 `12` — 每日返水
+
+### 1.1 常量与模型
+
+- [`RechargeGiftConfigModel`](slot_console/app/model/common/RechargeGiftConfigModel.php) 增加：
+  ```php
+  const TYPE_DAILY_REBATE = 12; // 每日返水
+  ```
+- 新增方法 `getDailyRebateActiveInfo(string $source)`，逻辑**复制** `getFreeCreditsActiveInfo`：`status=1`、`type=12`、时间窗、`source` 优先于 `all`。
+- [`slot_lib/Consts.php`](slot_lib/src/common/const/Consts.php) 增加 `ACTIVITY_TYPE_DAILY_REBATE = 12`（与现有 1–9 并列，便于订单/日志引用）。
+- 字典 `activity_type` 增加一条（SQL 或后台字典）：`value=12, label=每日返水`（与 type=11「首充定格/Free Credits」同级）。
+
+### 1.2 `ext_config` 结构（档位配置）
+
+```json
+{
+  "tiers": [
+    { "sort": 1, "min_bet_qf": 0, "max_bet_qf": 1000000, "rate_percent": 3 },
+    { "sort": 2, "min_bet_qf": 1000001, "max_bet_qf": 3000000, "rate_percent": 2 },
+    { "sort": 3, "min_bet_qf": 3000001, "max_bet_qf": 5000000, "rate_percent": 1 },
+    { "sort": 4, "min_bet_qf": 5000001, "max_bet_qf": null, "rate_percent": 0.5 }
+  ]
+}
+```
+
+- 金额与全站一致：**存储千分位（厘）**；后台表单用美元展示，提交时 `×1000`（与 type=11 的 `toQf` 一致）。
+- 默认种子：可在活动保存时由前端预填 4 档，或提供 migration 插入一条 `type=12` 的 default 活动（`source=all`）。
+
+### 1.3 校验
+
+在 [`ActivityValidate`](backend/slot_admin/app/game/validate/ActivityValidate.php) 新增 `checkDailyRebateExt(array $extConfig)`：
+
+- `tiers` 非空数组，每档含 `sort/min_bet_qf/rate_percent`；非最后一档 `max_bet_qf` 必填。
+- 复用 [`DailyRebateCalcService::validateTiersContinuous`](slot_console/app/service/DailyRebateCalcService.php)（入参转为 `min_bet`/`max_bet` 厘）。
+
+在 [`ActivityController`](backend/slot_admin/app/game/controller/ActivityController.php) 的 `save` / `update`（`updateData` 时）对 `type === 12` 调用该校验（与 type=11 并列）。
+
+---
+
+## 2. 管理后台 — 活动配置 UI（核心）
+
+参考 type=11，在 [`activity/edit.vue`](backend/slot_admin_vue/src/views/game/activity/edit.vue) 增加 **`formData.type == 12`** 区块：
+
+| 表单项 | 说明 |
+|--------|------|
+| 返水档位表 | 可增删行：排序、下限($)、上限($，最后一档可空)、比例(%) |
+| 规则说明 | 复用活动主表 `help` 字段（与 Free Credits 一致） |
+| 展示时间/生效时间 | 复用现有 `show_*` / `start_time` / `end_time` |
+
+**交互约束**（与 type=11 相同）：
+
+- `onlyGift` 计算属性加入 `12` → 不展示「赠送配置 goods」区块。
+- `submit` 时：`type===12` → `data.goods=[]`，`ext_config.tiers` 做 `toQf` 转换。
+- `setFormData` 时：`tiers` 从 `_qf` 还原为美元展示。
+
+[`activity/index.vue`](backend/slot_admin_vue/src/views/game/activity/index.vue) 列表 `ext_config` 列：type=12 时展示各档比例摘要（类似 type=11 展示门槛）。
+
+**删除**（不再单独维护档位）：
+
+- [`DailyRebateTierConfigController`](backend/slot_admin/app/game/controller/DailyRebateTierConfigController.php) 及 Logic/Validate/Model
+- [`dailyRebateTierConfig.js`](backend/slot_admin_vue/src/api/game/dailyRebateTierConfig.js) 与对应 vue（若已创建）
+- [`menu-daily-rebate.sql`](backend/slot_admin/db/menu-daily-rebate.sql) 中「每日返水档位」菜单项（3082）
+- 表 `daily_rebate_tier_config`（不建或迁移后 DROP）
+
+**保留菜单**：仅「综合统计 → 每日返水统计」（3084），挂在活动管理同级或统计分组下。
+
+---
+
+## 3. 运行时改造（slot_console）
+
+### 3.1 配置读取
+
+改造 [`DailyRebateService`](slot_console/app/service/DailyRebateService.php)：
+
+- 删除对 `DailyRebateTierConfigModel` 的依赖。
+- 通过 `RechargeGiftConfigModel::getDailyRebateActiveInfo($source)` 取活动；无生效活动 → C 端 `unlocked=false` 或整活动不可用（与未开 Free Credits 一致）。
+- 从 `ext_config['tiers']` 解析为 `DailyRebateCalcService` 入参（`min_bet`/`max_bet`/`rate_percent`）。
+- `info()` 返回的 `tiers` 来自当前活动配置；`tier_snapshot` 结算时写入完整 tiers JSON。
+
+### 3.2 用户记录表
+
+调整 [`daily_rebate_record`](slot_console/db/daily_rebate.sql)：
+
+- 增加 `activity_id bigint`（`recharge_gift_config.id`），结算/待定时写入。
+- **删除** `daily_rebate_tier_config` 建表与种子 SQL。
+
+### 3.3 结算与领取
+
+- [`DailyRebateSettle`](slot_console/app/command/DailyRebateSettle.php)：按渠道解析活动配置后再算返利；未充值用户仍跳过。
+- 领取：继续 `TRANSACTION_TYPE_DAILY_REBATE = 65`（已在 [`Consts.php`](slot_lib/src/common/const/Consts.php) 规划/部分落地）。
+
+### 3.4 C 端 API（不变路径）
+
+- `GET /api/daily-rebate/info`
+- `POST /api/daily-rebate/claim`
+
+需校验：**当前用户渠道存在生效的 type=12 活动**，否则返回活动未开启。
+
+---
+
+## 4. 综合统计页（保持独立）
+
+与 [Free Credits 统计](backend/slot_admin/app/game/controller/FreeCreditsStatsController.php) 相同定位：
+
+- 菜单：**综合统计 / 每日返水统计**（非活动配置页）
+- 实现：沿用已规划的 [`DailyRebateStatsLogic`](backend/slot_admin/app/game/logic/DailyRebateStatsLogic.php) + [`dailyRebateStats/index.vue`](backend/slot_admin_vue/src/views/game/dailyRebateStats/index.vue)（若 vue 未写完则补全）
+- 数据源：`daily_rebate_record`；筛选/汇总规则不变
+
+---
+
+## 5. 与首充定格的差异对照
+
+| 项 | Free Credits (11) | 每日返水 (12) |
+|----|-------------------|---------------|
+| ext_config | 门槛、分档金额、Banner | **tiers 累进档位** |
+| 用户状态表 | free_credits_player/package | daily_rebate_record |
+| 统计页 | Free Credits 统计 | 每日返水统计 |
+| 充值门槛 | 首充定格业务 | **历史充值过即可**（wallet `r>0`） |
+| 计费基础 | 定格池 | 当日 `user_profit_daily.bet` |
+
+---
+
+## 6. 实施步骤（建议顺序）
+
+1. **活动类型与 ext_config 契约**：Model 常量 + `getDailyRebateActiveInfo` + ActivityValidate + ActivityController + 字典 SQL。
+2. **后台 activity/edit.vue + index.vue**：type=12 档位表 UI 与 qf 换算。
+3. **重构 DailyRebateService**：读活动 ext_config；record 加 `activity_id`。
+4. **清理**：移除 tier 独立表/Controller/菜单；更新 `daily_rebate.sql`。
+5. **补全**：统计 vue、PWA 流水类型 65、单元测试仍用 tiers 数组驱动 CalcService。
+6. **验收**：后台新建 type=12 活动 → 用户下注 → 日切结算 → 领取 → 统计页数字一致。
+
+---
+
+## 7. 验收要点
+
+1. 仅在「充值活动配置」可创建/编辑 type=12，档位保存后 `ext_config.tiers` 正确落库。
+2. 同渠道多条 type=12 时行为与 type=11 一致（优先具体 source）。
+3. 改档位仅影响**新结算日**（`tier_snapshot` 审计旧记录）。
+4. 不再出现「每日返水档位」独立菜单。
+5. $2000 下注 → 次日返水 $50，与累进公式一致。
+
+---
+
+## Definition of Done（硬规则对齐）
+
+- [ ] `grep -r DailyRebateService ~/Documents/project/www/slot --include='*.php'` → 无命中（排除 vendor）
+- [ ] [`DailyRebateController`](slot_console/app/api/controller/DailyRebateController.php) 对齐 [`FreeCreditsController`](slot_console/app/api/controller/FreeCreditsController.php)（`BaseController` + Logic + Validate）
+- [ ] 已删除 orphan：`slot_admin_vue` 下 `dailyRebateTierConfig/*`、`api/game/dailyRebateTierConfig.js`
+- [ ] `~/.cursor/hooks/verify-slot-backend.sh` 输出 `PASS`