173 lines
8.1 KiB
Markdown
173 lines
8.1 KiB
Markdown
---
|
||
name: 转盘分享周期绑定
|
||
overview: 推荐在 `share_url` 增加通用 `biz_type` + `biz_id`（转盘绑定 `lucky_reward_cycle.id`），按当前轮次复用/新建短码；过期校验以 `lucky_reward_cycle.end_at` 为真源，invite_bind 侧对过期轮次返回 skipped 而不影响注册。
|
||
todos:
|
||
- id: ddl-share-url-biz
|
||
content: share_url 增加 biz_type/biz_id + 唯一键；同步 slot_console/slot_user Model PHPDoc
|
||
status: completed
|
||
- id: share-service-wheel-reuse
|
||
content: ShareService wheel 分支：按 active cycle_id 复用或新建短码
|
||
status: completed
|
||
- id: invite-bind-expired-check
|
||
content: LuckyRewardInviteLogic invite_bind 校验 share 绑定 cycle 未过期且匹配 active cycle，返回 skipped_expired_cycle
|
||
status: completed
|
||
- id: docs-tests
|
||
content: 更新 05 文档；单测/集成测覆盖同轮复用、跨轮新建、过期跳过
|
||
status: completed
|
||
isProject: false
|
||
---
|
||
|
||
# 转盘分享链接与活动轮次绑定方案
|
||
|
||
## 结论（直接回答你的二选一）
|
||
|
||
**推荐：`biz_type` + `biz_id`（转盘 `biz_id = cycle_id`），不推荐单独加 `expire_at` 作为唯一方案。**
|
||
|
||
| 方案 | 优点 | 缺点 |
|
||
|------|------|------|
|
||
| **仅 `expire_at`** | 查询简单（`expire_at > now`） | 与 `lucky_reward_cycle.end_at` **双份真源**，易漂移；`user_agent`/`red_packet` 等 origin 语义不同，全局 `expire_at` 难统一 |
|
||
| **`biz_type` + `biz_id`（推荐）** | 与业务轮次一一对应；**有效期以 `lucky_reward_cycle.end_at` 为准**；同轮次内复用、新轮次新建；可扩展其它活动 | 需改 `ShareService` 查询与唯一键；invite_bind 需多一步校验 |
|
||
|
||
可选：**可冗余 `expire_at = cycle.end_at` 仅作索引加速**，但判定仍应 join/查 `lucky_reward_cycle`，不以 `share_url.expire_at` 为 SSOT。
|
||
|
||
---
|
||
|
||
## 现状问题
|
||
|
||
[`ShareService::createUrl`](slot_console/app/service/ShareService.php) 通过 [`ShareUrlModel::isPlayerCreated($uid, $from)`](slot_console/app/model/ShareUrlModel.php) 按 `(creator_id, origin)` **永久复用**一条记录：
|
||
|
||
```php
|
||
$model = ShareUrlModel::isPlayerCreated($this->userEntity->uid, $from);
|
||
if ($model === false) { /* 新建 */ }
|
||
```
|
||
|
||
[`LuckyRewardInviteLogic::buildInviteLink`](slot_console/app/api/logic/LuckyRewardInviteLogic.php) 每次调 `createUrl(SHARE_FROM_WHEEL)`，**新 cycle 开始后仍返回旧短码**。
|
||
|
||
注册侧 [`slot_user` AbstractRegisterService](slot_user/app/service/register/AbstractRegisterService.php) 只校验 `short_code` 存在，**不校验轮次**；console `handleInviteBind` 直接用**当前 active cycle** 发奖，导致**旧链接可能计入新轮次**（与「每轮转盘有有效期」不符）。
|
||
|
||
你已确认过期策略：**注册/agent 关系照常；Lucky Rewards 不计助力**。
|
||
|
||
---
|
||
|
||
## 推荐数据模型
|
||
|
||
在 [`s_common.share_url`](slot_user/app/model/ShareUrlModel.php) 增加：
|
||
|
||
```sql
|
||
ALTER TABLE share_url
|
||
ADD COLUMN biz_type varchar(32) NOT NULL DEFAULT '' COMMENT '业务类型，wheel填lucky_reward_cycle',
|
||
ADD COLUMN biz_id bigint NOT NULL DEFAULT 0 COMMENT '业务ID，wheel填lucky_reward_cycle.id';
|
||
|
||
-- wheel：同一用户同一轮次唯一；其它 origin 保持 biz 为空
|
||
ADD UNIQUE KEY uk_creator_origin_biz (creator_id, creator_type, origin, biz_type, biz_id);
|
||
```
|
||
|
||
语义约定：
|
||
|
||
| origin | biz_type | biz_id | 行为 |
|
||
|--------|----------|--------|------|
|
||
| `user_agent` / `red_packet` / `user_self` | `''` | `0` | 现网永久短码，不变 |
|
||
| `wheel` | `lucky_reward_cycle` | `cycle.id` | **每轮一条**，同轮复用 |
|
||
|
||
`code` 加密 JSON 可冗余写入 `cycle_id` 便于排查，但**复用查询走 DB 列**，不走解密。
|
||
|
||
---
|
||
|
||
## 核心流程
|
||
|
||
```mermaid
|
||
sequenceDiagram
|
||
participant Client as ActivityPage
|
||
participant Console as ShareService
|
||
participant Cycle as lucky_reward_cycle
|
||
participant Share as share_url
|
||
participant User as slot_user_register
|
||
participant Logic as LuckyRewardInviteLogic
|
||
|
||
Client->>Console: invite-link / createShareUrl from=wheel
|
||
Console->>Cycle: resolveActiveCycle
|
||
Console->>Share: find uid+wheel+biz(cycle_id)
|
||
alt 当前轮次已有短码
|
||
Share-->>Console: 复用 short_code
|
||
else 新轮次或无记录
|
||
Console->>Share: insert 新 short_code + biz_id
|
||
end
|
||
Console-->>Client: code + land_url
|
||
|
||
User->>Share: invite_code 查 short_code
|
||
User->>Logic: invite_bind share_origin=wheel
|
||
Logic->>Share: invite_code -> biz_id(cycle_id)
|
||
Logic->>Cycle: 校验 cycle 仍进行中且 end_at>now
|
||
alt cycle 已结束或不匹配 active
|
||
Logic-->>User: skipped_expired_cycle
|
||
else
|
||
Logic-->>User: 正常助力流程
|
||
end
|
||
```
|
||
|
||
---
|
||
|
||
## 实现要点（按服务）
|
||
|
||
### 1. slot_console — 分享创建
|
||
|
||
改动 [`ShareService::createUrl`](slot_console/app/service/ShareService.php)：
|
||
|
||
- **`from !== wheel`**：保持 `isPlayerCreated(uid, from)`（biz 为空）。
|
||
- **`from === wheel`**：
|
||
1. `LuckyRewardConfigService::requireEnabledConfig` + `resolveActiveCycle`
|
||
2. `ShareUrlModel::findByPlayerBiz($uid, 'wheel', 'lucky_reward_cycle', $cycleId)`
|
||
3. 命中则复用；否则新建并写入 `biz_type/biz_id`
|
||
4. （可选）冗余 `expire_at = cycle.end_at` 仅索引
|
||
|
||
同步改 [`GiftController::createShareUrl`](slot_console/app/api/controller/GiftController.php) 与 [`LuckyRewardInviteLogic::buildInviteLink`](slot_console/app/api/logic/LuckyRewardInviteLogic.php) 路径（均走 ShareService，一处改即可）。
|
||
|
||
[`ShareUrlModel`](slot_console/app/model/ShareUrlModel.php) + [`slot_user/ShareUrlModel`](slot_user/app/model/ShareUrlModel.php) 补 `@property` 与新查询方法。
|
||
|
||
### 2. slot_console — invite_bind 过期校验
|
||
|
||
在 [`LuckyRewardInviteLogic::handleInviteBind`](slot_console/app/api/logic/LuckyRewardInviteLogic.php) 有效助力判定链中（`skipped_not_wheel` 之后）增加：
|
||
|
||
1. 用 `invite_code` 查 `share_url`（console 可读 `share_url` 或经 slot_user innerapi；优先 console 直读同库 `s_common.share_url`）
|
||
2. 若 `origin=wheel` 且 `biz_type=lucky_reward_cycle`：
|
||
- 查 `lucky_reward_cycle` by `biz_id`
|
||
- 若 `status=已结束` 或 `end_at <= now()` → 返回新 status **`skipped_expired_cycle`**（注册/agent 不受影响，仅不发 Spin）
|
||
- 若 `biz_id != 当前 active cycle.id` → 同上（旧轮短码不计新轮助力）
|
||
|
||
在 [`InviteBindResultEntity`](slot_console/app/entity/luckyReward/InviteBindResultEntity.php) 增加常量 + 文档表更新（[05 文档](docs/requirements/lucky_rewards/05_slot_console_邀请助力与弹窗方案.md) §3 判定表）。
|
||
|
||
### 3. slot_user — 无需阻断注册
|
||
|
||
按你的选择：**不在注册阶段 reject invite_code**。`AbstractRegisterService` 可不改，或仅补日志（`share_url.biz_id` + cycle 状态）便于排障。
|
||
|
||
### 4. 文档
|
||
|
||
更新 [05_slot_console_邀请助力与弹窗方案.md](docs/requirements/lucky_rewards/05_slot_console_邀请助力与弹窗方案.md) §2.1：
|
||
|
||
- wheel 短码 **按 cycle 复用/新建**，非永久一条
|
||
- 过期短码：注册 OK，Lucky Rewards `skipped_expired_cycle`
|
||
|
||
---
|
||
|
||
## 测试
|
||
|
||
- **Unit**：`ShareService` wheel 分支 — mock cycle，`findByPlayerBiz` 命中复用 / 新 cycle 新建
|
||
- **Integration**：同一 uid 同 cycle 两次 `invite-link` 返回相同 `code`；模拟新 cycle 返回不同 `code`
|
||
- **Integration**：旧 cycle 短码 + invite_bind → `skipped_expired_cycle`，无 helper/grant
|
||
|
||
---
|
||
|
||
## 为何不选「只加 expire_at」
|
||
|
||
1. **真源重复**：cycle 结束时间已在 [`lucky_reward_cycle.end_at`](backend/slot_admin/db/lucky_reward.sql)；单独 `expire_at` 需与轮转任务同步，易不一致。
|
||
2. **无法表达「属于哪一轮」**：仅有 `expire_at` 难以区分「同用户第 N 轮 vs 第 N+1 轮」历史短码；`biz_id=cycle_id` 可精确归因与审计。
|
||
3. **影响面**：`expire_at` 若加在全局 `share_url`，需约定 `user_agent` 等为 0/NULL；而 `biz_id` 对非 wheel 恒为 0，更清晰。
|
||
|
||
---
|
||
|
||
## 不在本次范围
|
||
|
||
- 修改 `user_agent` 分享逻辑
|
||
- 前端 Copy Link 缓存策略（后端保证同 cycle 幂等即可）
|
||
- 删除历史 cycle 的 `share_url` 行（可保留作审计；过期靠 invite_bind 拦截）
|