226 lines
11 KiB
Markdown
226 lines
11 KiB
Markdown
---
|
||
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`
|