409 lines
20 KiB
Markdown
409 lines
20 KiB
Markdown
---
|
||
name: 每日返水需求文档
|
||
overview: 在现有 user_profit_daily 日下注统计基础上，新增「每日返水」活动：累进档位计费、仅充值用户参与、次日 00:00 起可领且 24 小时内有效；配套用户端 API、后台档位配置与综合统计页。
|
||
todos:
|
||
- id: schema
|
||
content: 设计并评审 daily_rebate_record、daily_rebate_tier_config 表结构与索引
|
||
status: in_progress
|
||
- id: calc-service
|
||
content: 实现累进分段 RebateCalcService + tier_snapshot + 单元测试（含 $2000→$50 等用例）
|
||
status: pending
|
||
- id: cron
|
||
content: slot_console：dailyRebateSettle / dailyRebateExpire 定时任务
|
||
status: pending
|
||
- id: user-api
|
||
content: slot_console 用户端 info/claim API + slot_wallet 入账与新 transaction type
|
||
status: pending
|
||
- id: admin-tier
|
||
content: slot_admin 每日返水档位 CRUD 页
|
||
status: pending
|
||
- id: admin-stats
|
||
content: slot_admin 综合统计/每日返水统计（列表+筛选+排序+汇总，参考 FreeCreditsStats）
|
||
status: pending
|
||
- id: pwa-ui
|
||
content: 前端三态 UI、7 日表、倒计时、领取按钮
|
||
status: pending
|
||
isProject: false
|
||
---
|
||
|
||
# 每日返水（Daily Rebate 3%）需求规格书
|
||
|
||
## 1. 背景与目标
|
||
|
||
- **业务目标**：对已充值用户，按自然日累计有效下注给予累进比例返水，提升留存与投注激励。
|
||
- **数据基础**：`[slot_console](slot_console)` 已通过 `[LoseReturnDeposit](slot_console/app/command/LoseReturnDeposit.php)` + Redis `[UserProfitService](slot_pwa/app/service/user/UserProfitService.php)` 维护 `[s_statistics.user_profit_daily](slot_console/app/model/statistics/UserProfitDaily.php)`（字段 `bet`/`win`/`profit`/`create_date`/`source`）。
|
||
- **与 VIP 亏损返利的区别**：VIP 返利基于「当日净亏损」且需 VIP 等级；本活动基于「当日总下注额」、仅需历史充值、档位为累进分段，产品独立。
|
||
|
||
---
|
||
|
||
## 2. 术语
|
||
|
||
|
||
| 术语 | 定义 |
|
||
| ---- | ------------------------------------------------------------------------------------------------------------- |
|
||
| 自然日 | 服务器时区 `Asia/Shanghai`（与 `[slot_center/config/app.php](slot_center/config/app.php)` 一致）的 `00:00:00`–`23:59:59` |
|
||
| 有效下注 | **等于** `user_profit_daily.bet`（厘），与 PWA 下注时 `incBet` 累计值一致；无单独过滤规则 |
|
||
| 返水金额 | 按档位配置对当日有效下注做**累进分段**计算后的金额（厘） |
|
||
| 统计日期 | 发生下注的自然日 `create_date`，非领取日 |
|
||
| 充值用户 | 结算时刻钱包 `total_deposit > 0`（`[WalletStatModel](slot_wallet/app/model/multi/WalletStatModel.php)`） |
|
||
|
||
|
||
---
|
||
|
||
## 3. 核心业务规则
|
||
|
||
### 3.1 参与资格
|
||
|
||
- **未充值**：不参与返水；前端展示「锁定」态（Unlock Cashback），不可领、列表可置灰或仅展示引导文案。
|
||
- **已充值**：自充值成功当日起，当日及之后有有效下注的自然日可产生返水记录；历史未充值日的下注不补发。
|
||
|
||
### 3.2 返水计算（累进分段，非整笔单一比例）
|
||
|
||
**已确认**：采用分段累进，与原型及后台示例一致（$2000 → $50）。
|
||
|
||
默认档位（首版种子数据，**后台可配置**）：
|
||
|
||
|
||
| 分段序号 | 下注区间（含边界，美元展示） | 比例 |
|
||
| ---- | --------------- | ---- |
|
||
| 1 | $0 – $1,000 | 3% |
|
||
| 2 | $1,001 – $3,000 | 2% |
|
||
| 3 | $3,001 – $5,000 | 1% |
|
||
| 4 | $5,001 及以上 | 0.5% |
|
||
|
||
|
||
**计算公式**（`B` = 当日有效下注，美元；存储与计算用厘，`1 USD = 1000` 厘，与 `[share_config.moneyFormat](slot_center/config/share_config.php)` 一致）：
|
||
|
||
```
|
||
rebate_li = Σ segment_i( min(B, max_i) - min(B, min_i) + ε_i ) × rate_i
|
||
```
|
||
|
||
- 各档 `min_i`/`max_i` 以后台配置为准（最后一档 `max` 为空表示无上限）。
|
||
- 分段左闭右闭：第 1 档覆盖 `[0, 1000]`，第 2 档覆盖 `(1000, 3000]`，依此类推（实现时用「上一档上限 + 1」作为下一档起点，避免重复计费）。
|
||
- **舍入**：返水金额入库前 `floor` 到厘；前端展示保留 2 位小数美元。
|
||
|
||
**计算示例**：
|
||
|
||
|
||
| 有效下注 | 计算过程 | 返水 |
|
||
| ------- | --------------------------------------- | ------ |
|
||
| $125.56 | 125.56 × 3% | $3.77 |
|
||
| $200 | 200 × 3% | $6.00 |
|
||
| $2,000 | 1000×3% + 1000×2% | $50.00 |
|
||
| $6,000 | 1000×3% + 2000×2% + 2000×1% + 1000×0.5% | $95.00 |
|
||
|
||
|
||
**待定态（当天）**：用 Redis 当日 `bet` 实时重算返水预览；不入库终态金额，或与 DB 行 `status=pending` 同步更新。
|
||
|
||
### 3.3 结算与领取时间轴
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant User
|
||
participant PWA as slot_pwa
|
||
participant Redis
|
||
participant Cron as slot_console_cron
|
||
participant DB as daily_rebate_record
|
||
|
||
Note over User,Redis: D日 00:00-23:59
|
||
User->>PWA: 下注
|
||
PWA->>Redis: incBet
|
||
Note over DB: status=pending 实时 bet/rebate
|
||
|
||
Note over Cron,DB: D+1日 00:00后 cron
|
||
Cron->>Redis: 读取 D日 bet
|
||
Cron->>DB: 写入/更新 settle: claimable, dead_time=D+2 00:00
|
||
|
||
Note over User,DB: D+1日 仅可领 D日 返水
|
||
User->>PWA: claim(stat_date=D)
|
||
PWA->>DB: status=claimed
|
||
|
||
Note over DB: 超过 dead_time 未领
|
||
Cron->>DB: status=expired
|
||
```
|
||
|
||
|
||
|
||
|
||
| 时点 | 行为 |
|
||
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| D 日进行中 | 状态 **待定**；有效下注、返水金额随 Redis 刷新 |
|
||
| D+1 日 00:00 | 定时任务结算 D 日：有 `bet>0` 且已充值 → 生成/更新记录，状态 **待领取**；`claimable_at = D+1 00:00:00`，`expire_at = D+2 00:00:00`（领取窗口 **24 小时**，对齐 VIP `[vip_rebate_lose_time](slot_center/config/share_config.php)`） |
|
||
| D+1 日全天 | 用户**只能领取 stat_date=D** 的返水（「前一天」） |
|
||
| D+2 日 00:00 前未领 | 状态 **过期**；`rebate_amount>0` 且未领 |
|
||
| 领取成功 | 状态 **已领**；记 `claimed_at`；钱包入账 |
|
||
|
||
|
||
**无有效下注**：不生成记录（后台列表、前端 7 日表均不展示该日）。
|
||
|
||
**返水为 0**：若档位计算为 0（`bet=0` 已排除），`bet>0` 但舍入为 0 时可不落库或落库且不可领——建议 **不落库**，与「未有有效下注不显示」一致。
|
||
|
||
### 3.4 状态机
|
||
|
||
|
||
| 状态码 | 中文 | 条件 |
|
||
| ----------- | --- | --------------------------------------------------------------------- |
|
||
| `pending` | 待定 | `stat_date = 今天`；实时统计未结束 |
|
||
| `claimable` | 待领取 | `stat_date < 今天`；`rebate_amount > 0`；`claimed_at` 空；`now < expire_at` |
|
||
| `claimed` | 已领 | `claimed_at` 非空 |
|
||
| `expired` | 过期 | `rebate_amount > 0`；未领；`now >= expire_at` |
|
||
|
||
|
||
状态迁移：
|
||
|
||
- `pending` → `claimable`：日切结算任务（仅昨日及更早批量处理；今日保持 pending）
|
||
- `claimable` → `claimed`：用户领取接口（幂等）
|
||
- `claimable` → `expired`：过期扫描任务或领取时校验
|
||
|
||
前端映射（英文 UI）：
|
||
|
||
|
||
| 状态 | 展示 | 行样式 |
|
||
| --------- | --------- | -------------------- |
|
||
| pending | Pending | 绿色标签（进行中） |
|
||
| claimable | Claimable | 绿色可点 |
|
||
| claimed | Claimed | 白色/灰色 |
|
||
| expired | Expired | 红色/灰色 |
|
||
| 无记录 | No Bets | 灰字（仅前端 7 日占位，无 DB 行） |
|
||
|
||
|
||
### 3.5 领取规则
|
||
|
||
- 每次领取**一条**指定 `stat_date`（通常为昨日）。
|
||
- 并发：DB 行级锁 / `UPDATE ... WHERE status=claimable` 防重复领。
|
||
- 入账：新增钱包流水类型（建议 `TRANSACTION_TYPE_DAILY_REBATE = 65`，在 `[Consts.php](slot_lib/src/common/const/Consts.php)` 登记）；更新 `total_cashback`。
|
||
- 失败：事务回滚，状态不变。
|
||
|
||
---
|
||
|
||
## 4. 数据设计
|
||
|
||
### 4.1 沿用表
|
||
|
||
- `**s_statistics.user_profit_daily`**：只读来源，提供 `bet`、`source`、`create_date`；**不扩展**状态/返水字段。
|
||
|
||
### 4.2 新建表 `daily_rebate_record`（建议库：`s_common`）
|
||
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
| ----------------------- | ----------------- | ----------------------------------------- |
|
||
| id | bigint PK | |
|
||
| uid | bigint | 用户 ID |
|
||
| source | varchar | 渠道号（结算时快照） |
|
||
| stat_date | date | 统计日期（下注日） |
|
||
| bet_amount | bigint | 有效下注（厘） |
|
||
| rebate_amount | bigint | 返水金额（厘） |
|
||
| status | tinyint | 1 pending 2 claimable 3 claimed 4 expired |
|
||
| tier_snapshot | json | 结算时档位快照（审计） |
|
||
| claimable_at | datetime | 可领取开始 |
|
||
| expire_at | datetime | 过期时间 |
|
||
| claimed_at | datetime nullable | 领取时间 |
|
||
| created_at / updated_at | datetime | |
|
||
|
||
|
||
**唯一索引**：`(uid, stat_date)`。
|
||
|
||
**索引**：`(stat_date, status)`、`(source, stat_date)`、`(uid)`。
|
||
|
||
### 4.3 新建表 `daily_rebate_tier_config`（后台可配置）
|
||
|
||
|
||
| 字段 | 说明 |
|
||
| ----------------------- | ------------------ |
|
||
| id | PK |
|
||
| sort | 排序（从小到大） |
|
||
| min_bet | 区间下限（厘，含） |
|
||
| max_bet | 区间上限（厘，含；NULL=无上限） |
|
||
| rate_percent | 比例，如 3.00 表示 3% |
|
||
| status | 启用/停用 |
|
||
| updated_by / updated_at | 审计 |
|
||
|
||
|
||
校验：档位连续无空洞、无重叠；至少一档；最后一档可无 `max_bet`。
|
||
|
||
---
|
||
|
||
## 5. 定时任务（slot_console）
|
||
|
||
|
||
| 任务 | 触发 | 职责 |
|
||
| ----------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------- |
|
||
| `dailyRebateSettle` | 每日 00:05（可配置） | 结算 **昨日** `user_profit_daily` + 充值校验 → upsert `daily_rebate_record` 为 claimable |
|
||
| `dailyRebateExpire` | 每小时或 00:10 | 将 `claimable` 且 `now>=expire_at` 置为 expired |
|
||
| （可选）与现有 `[loseReturnDeposit](slot_console/app/command/LoseReturnDeposit.php)` | 同批读 Redis | 避免重复扫 Redis；**推荐独立命令**以免耦合 VIP 逻辑 |
|
||
|
||
|
||
**待定实时**：用户打开活动页时，Logic 读 Redis `user:profit:{Ymd}` + 当前档位配置计算预览，不写 claimable。
|
||
|
||
---
|
||
|
||
## 6. 用户端（PWA / Gateway）
|
||
|
||
### 6.1 页面态（对齐原型）
|
||
|
||
|
||
| 态 | 条件 | 主按钮 | 表格 |
|
||
| --- | ------------------------------- | --------------- | ------------- |
|
||
| 锁定 | `total_deposit==0` | Unlock Cashback | 模糊/遮罩 |
|
||
| 已解锁 | 已充值，无可领 | Play Now | 近 7 日明细 |
|
||
| 可领取 | 存在 `claimable` 且 `stat_date=昨天` | Claim($X.XX) | 昨日行 Claimable |
|
||
|
||
|
||
**倒计时**：「THIS ROUND」= 距今日自然日结束的秒数（与 Rates reset 00:00 文案一致）。
|
||
|
||
### 6.2 API（建议落在 slot_console `/api/daily-rebate/*`，经 gateway 转发）
|
||
|
||
**GET `/api/daily-rebate/info`**
|
||
|
||
响应示例字段：
|
||
|
||
```json
|
||
{
|
||
"unlocked": true,
|
||
"countdown_seconds": 86399,
|
||
"claimable": { "stat_date": "2026-05-25", "rebate_amount": 3000, "display": "3.00" },
|
||
"tiers": [{ "min": 0, "max": 1000000, "rate": 3 }],
|
||
"records": [
|
||
{ "stat_date": "05/26", "bet_amount": 125560, "rebate_amount": 3770, "status": "pending" }
|
||
]
|
||
}
|
||
```
|
||
|
||
- `records`：最近 7 个自然日，**有 bet 或 DB 行**的日期；无下注日可不返回或前端填 No Bets。
|
||
- 打开弹窗时 **强制刷新** 当日 pending 数据。
|
||
|
||
**POST `/api/daily-rebate/claim`**
|
||
|
||
- 入参：`stat_date`（可选，默认昨天）
|
||
- 校验：已充值、status=claimable、未过期、rebate>0
|
||
- 出参：领取后余额/流水号
|
||
|
||
**GET `/api/daily-rebate/tiers`**（可选，info 已含则省略）
|
||
|
||
---
|
||
|
||
## 7. 管理后台（slot_admin + slot_admin_vue）
|
||
|
||
### 7.1 菜单
|
||
|
||
- **活动配置 / 每日返水档位**（新建）：CRUD [`daily_rebate_tier_config`]，校验区间连续。
|
||
- **综合统计 / 每日返水统计**（新建）：列表 + 汇总。
|
||
|
||
实现参考：列表+汇总 `[FreeCreditsStats](backend/slot_admin/app/game/logic/FreeCreditsStatsLogic.php)` + 前端 `[freeCreditsStats/index.vue](backend/slot_admin_vue/src/views/game/freeCreditsStats/index.vue)`。
|
||
|
||
### 7.2 统计列表
|
||
|
||
**列**：ID(uid) | 渠道号 | 有效下注额⇅ | 返水金额⇅ | 状态 | 统计日期
|
||
|
||
**筛选**：
|
||
|
||
- UID（精确）
|
||
- 渠道（`source`，可搜索下拉，复用 `commonStore.allSourcesOptionsNoAll`）
|
||
- 状态：待定 / 待领取 / 已领 / 过期（多选）
|
||
- 统计日期范围（`stat_date[]`）
|
||
|
||
**排序白名单**：`bet_amount`、`rebate_amount`（默认 `stat_date desc, id desc`）
|
||
|
||
**数据范围**：仅 `total_deposit>0` 用户在结算时已入库的记录；**待定**行可对「今天」合并 Redis 实时 bet（与 Free Credits「打开刷新」一致）。
|
||
|
||
### 7.3 顶部汇总（随筛选变化）
|
||
|
||
|
||
| 指标 | 计算 |
|
||
| ---- | ----------------------------------------------- |
|
||
| 总领取 | `status=claimed` 的 `sum(rebate_amount)` |
|
||
| 总待领取 | `status=claimable` 的 sum |
|
||
| 总过期 | `status=expired` 的 sum |
|
||
| 待定 | `status=pending` 的 sum；**若筛选日期范围不含今天则为 0** |
|
||
| 领取率 | `总领取 / (总领取 + 总过期 + 总待领取)`；分母为 0 时显示 `0%` 或 `-` |
|
||
|
||
|
||
展示格式：`$888.88`（`rebate_amount / 1000`，2 位小数）。
|
||
|
||
---
|
||
|
||
## 8. 非功能需求
|
||
|
||
- **幂等**：结算任务对 `(uid, stat_date)` upsert；领取 CAS 更新状态。
|
||
- **性能**：日活结算批量按日期分页；后台列表分页默认 100，最大 100。
|
||
- **审计**：`tier_snapshot` 保留结算时档位；领取写 wallet log `biz_extra: {activity:"daily_rebate", stat_date}`。
|
||
- **监控**：结算失败/领取失败打日志 + 指标；过期数量日报。
|
||
|
||
---
|
||
|
||
## 9. 边界与异常
|
||
|
||
|
||
| 场景 | 处理 |
|
||
| ------------- | ----------------------------------------------------------- |
|
||
| 结算日用户刚充值、昨日下注 | 昨日结算时已按当时 `total_deposit` 判断；若需「充值后立即对历史补发」→ **不做**，以结算时刻为准 |
|
||
| 结算任务重复跑 | upsert，不重复入账 |
|
||
| 时区变更 | 禁止随意改；变更需重算规则文档化 |
|
||
| bet>0 未充值 | 不生成记录 |
|
||
| 领取时档位已改 | 以 `tier_snapshot` 为准，不受后续配置变更影响 |
|
||
| 跨天未关弹窗 | 前端倒计时结束刷新 info；pending→claimable 由后端状态驱动 |
|
||
|
||
|
||
---
|
||
|
||
## 10. 实施拆分（供研发排期）
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph phase1 [Phase1 数据与配置]
|
||
T1[daily_rebate_tier_config]
|
||
T2[daily_rebate_record]
|
||
T3[admin 档位 CRUD]
|
||
end
|
||
subgraph phase2 [Phase2 结算与过期]
|
||
C1[dailyRebateSettle]
|
||
C2[dailyRebateExpire]
|
||
L1[rebate calc service]
|
||
end
|
||
subgraph phase3 [Phase3 用户端]
|
||
A1[info API]
|
||
A2[claim API + wallet]
|
||
F1[PWA 三态 UI]
|
||
end
|
||
subgraph phase4 [Phase4 后台统计]
|
||
B1[DailyRebateStats Logic]
|
||
B2[admin vue 列表汇总]
|
||
end
|
||
phase1 --> phase2 --> phase3
|
||
phase2 --> phase4
|
||
```
|
||
|
||
|
||
|
||
|
||
| 仓库 | 改动要点 |
|
||
| ---------------------- | ---------------------------------------------------------- |
|
||
| slot_console | Model、结算/过期 Command、RebateCalcService、用户 API、Redis 读当日 bet |
|
||
| slot_wallet | 新 transaction type、领取入账 |
|
||
| slot_lib | Consts 新类型 |
|
||
| backend/slot_admin | Controller/Logic/Validate、菜单 SQL |
|
||
| backend/slot_admin_vue | 档位页 + 统计页 |
|
||
| slot_sdk | 若 gateway 经 sdk 调 console，补 Client 方法 |
|
||
|
||
|
||
**不建议**复用 `vip_rebate_record` 表：业务语义、状态机、计费基础均不同。
|
||
|
||
---
|
||
|
||
## 11. 验收标准（摘要）
|
||
|
||
1. 充值用户 D 日下注 $2000，D+1 00:00 后显示待领取 $50，24h 内领取成功，流水类型正确。
|
||
2. 未充值用户仅见锁定态，无领取接口成功路径。
|
||
3. 超 24h 未领变过期，不可再领。
|
||
4. 后台筛选/status/排序/汇总与文档公式一致；改档位仅影响新结算日。
|
||
5. 前端 7 日表、Claim 按钮金额与后台一致；当日为 Pending 且随下注刷新。
|
||
|
||
---
|
||
|
||
## 12. 已确认决策
|
||
|
||
- 计费方式：**累进分段**（非整笔落档单一比例）。
|
||
- 有效下注：**等同 `user_profit_daily.bet`**。
|
||
- 档位：**后台可配置**（`daily_rebate_tier_config`）。
|
||
|