---
name: Lucky Reward 双弹窗分析
overview: 被邀请人 Support Invite 应从 HomeEvent 迁到 lucky_reward_invite_bind 成功时 WS 即时推送（只弹一次）；HomeEvent 仅保留邀请人 Claim Now（pending_spin_count，可重复补弹）。这样同一 uid 在 HomeEvent 不再同时命中两种 Lucky Rewards 弹窗。
todos:
  - id: diagnose-no-helper
    content: 按日志/SQL 排查 invite_bind 全链路，定位 helper 未落库的具体 status/reason
    status: pending
  - id: move-support-invite-to-bind
    content: invite_bind success 后：ensureInviteeAutoOpenBox + buildSupportInvitePopup + WsService::notifyClientPOP；HomeEvent 移除被邀请人逻辑
    status: pending
  - id: update-tests-docs-yapi
    content: 更新集成测、05 方案文档、YApi #109 WS 弹窗示例；Claim Now 仍走 HomeEvent
    status: pending
  - id: confirm-product-rule
    content: 确认产品规则：双角色用户允许两种弹窗，还是同一 flush 只保留一种（及优先级）
    status: cancelled
  - id: implement-mutex-if-needed
    content: 若需互斥：在 LuckyRewardInviteLogic 抽 resolveHomePopups，HomeEvent 只 merge 一种；补互邀集成测
    status: cancelled
  - id: support-invite-once
    content: （可选）若 Support Invite 应只弹一次：增加 consume/已读状态，与互斥分开评估
    status: cancelled
isProject: false
---

# Lucky Rewards 同一人两种弹窗 — 根因与可选改法

## 现象对应代码

[`HomeEvent::appendLuckyRewardHomePopups`](slot_console/app/command/event/HomeEvent.php) 对**同一个** `$uid` 顺序做两件事，**互不排斥**：

```437:455:slot_console/app/command/event/HomeEvent.php
protected function appendLuckyRewardHomePopups(array &$popList, int $uid, UserInfoEntity $userInfoEntity): void
{
    // ...
    $inviteLogic->ensureInviteeAutoOpenBox($uid, $source);
    $supportInvitePop = $inviteLogic->buildSupportInvitePopup($uid, $source);
    if ($supportInvitePop !== false) {
        $luckyRewardPopups[] = $supportInvitePop;
    }

    $inviterClaimNowPop = $inviteLogic->buildInviterClaimNowPopup($uid, $source);
    if ($inviterClaimNowPop !== null) {
        $luckyRewardPopups[] = $inviterClaimNowPop->toHomePopListItem();
    }
    $popList = array_merge($luckyRewardPopups, $popList);
}
```

两种弹窗判定维度不同：

| 弹窗 | type | 判定方法 | 核心条件（同一 uid） |
| --- | --- | --- | --- |
| Support Invite | `lucky_reward_support_invite` | [`buildSupportInvitePopup`](slot_console/app/api/logic/LuckyRewardInviteLogic.php) | `lucky_reward_helper` 存在 **invitee_uid = uid** 且 **已开箱** |
| Claim Now | `lucky_reward_invite_success` | [`buildInviterClaimNowPopup`](slot_console/app/api/logic/LuckyRewardInviteLogic.php) | `pending_spin_count > 0` 且存在 **未领的 GRANT_TYPE_INVITER grant** |

需求文档 [`05_slot_console_邀请助力与弹窗方案.md`](docs/requirements/lucky_rewards/05_slot_console_邀请助力与弹窗方案.md) 表格里写的是「邀请人 / 被邀请人」两种**角色**，但代码**没有**写「同一 uid 只能占一种角色」。

```mermaid
flowchart TD
    homeFlush["HomeEvent flush uid=X"]
    openBox["ensureInviteeAutoOpenBox(X)"]
    checkInvitee["buildSupportInvitePopup(X)\nhelper.invitee_uid=X ?"]
    checkInviter["buildInviterClaimNowPopup(X)\npending_spin_count>0 ?"]
    popSupport["lucky_reward_support_invite"]
    popClaim["lucky_reward_invite_success"]
    merge["array_merge 两种都进 popList"]

    homeFlush --> openBox --> checkInvitee
    checkInvitee -->|是| popSupport
    checkInvitee -->|否| checkInviter
    popSupport --> checkInviter
    checkInviter -->|是| popClaim
    popClaim --> merge
    checkInviter -->|否| merge
```

## 为什么「一个人」会同时有两种？

**正常单链邀请（A 邀 B）不会出现**：A 只有 Claim Now，B 只有 Support Invite（见 [`LuckyRewardInviteBindIntegrationTest`](slot_console/tests/Integration/LuckyRewardInviteBindIntegrationTest.php)）。

**同一 uid 双角色时会出现**，典型场景：

1. **互邀 / 双链**：A 邀 B，B 也邀 A（同一 `cycle_id`，均新注册有效助力）
   - A：`helper(invitee=A)` → Support Invite；`pending_spin_count>0` → Claim Now
   - B：同理
2. **先被邀、后又成功邀别人**：用户 C 邀了 A（A 为被邀请人）；之后 A 又邀了 D（A 为邀请人且未 claim）→ 回大厅两种都满足
3. **邀请人未 claim 的重复提醒 + 被邀请身份长期有效**：Claim Now 在 `pending_spin_count>0` 期间**每次回大厅都弹**；Support Invite 在 helper 存在且已开箱后**每次回大厅都弹**（无 consume/已读标记）→ 双角色用户会**持续**收到两个 pop

`ensurePlayerRow` 会在 invite_bind 时为**邀请人**创建 player 行（不必先开箱），因此「邀请人侧 Claim Now」与「被邀请人侧 Support Invite」在数据上可以并存。

## 这不是 invite_bind 写错

[`persistInviteHelperInTransaction`](slot_console/app/api/logic/LuckyRewardInviteLogic.php) 只给**邀请人**写 grant + `pending_spin_count`；被邀请人**不再**写 invitee grant（测试也断言 `invite_invitee:` grant 为 null）。双弹窗来自 **HomeEvent 合并逻辑**，不是一次回调写了两种状态。

## 若产品期望「同一时刻只弹一种」

~~需产品定优先级，再在 HomeEvent 加互斥~~ **已按产品意见调整方案**：被邀请人弹窗**不再走 HomeEvent**，见下文 §「被邀请人弹窗迁出 HomeEvent」；HomeEvent 只留邀请人 Claim Now，从架构上消除「同一人两种 Lucky Rewards 弹窗」。

---

# 被邀请人 Support Invite 迁出 HomeEvent（产品定案）

## 背景

- **被邀请人**：IMEI 进游戏即注册，`invite_bind` 发生时用户**在线**，Support Invite **只弹一次**，不存在「离线补弹」。
- **邀请人**：可能正在玩游戏/离线，Claim Now 须 **`pending_spin_count` + 每次回大厅重复弹**，继续走 HomeEvent。

当前实现把两者都塞进 [`appendLuckyRewardHomePopups`](slot_console/app/command/event/HomeEvent.php)，导致：
- 被邀请人**每次回大厅重复弹** Support Invite（无 consume）
- 双角色用户同一 flush 可能同时出现两种 type

## 目标架构

```mermaid
sequenceDiagram
    participant Agent as agent_invite_bind
    participant ConsoleBus as console_bus
    participant Logic as LuckyRewardInviteLogic
    participant WS as WsService_notifyClientPOP
    participant Home as HomeEvent

    Agent->>ConsoleBus: lucky_reward_invite_bind
    ConsoleBus->>Logic: handleInviteBind success
    Logic->>Logic: ensureInviteeAutoOpenBox(invitee)
    Logic->>Logic: buildSupportInvitePopup(invitee)
    Logic->>WS: 即时推送 invitee 仅一次

    Note over Home: 邀请人路径不变
    Home->>Logic: buildInviterClaimNowPopup(inviter)
    Home->>WS: home flush popList
```

| 弹窗 | 触发点 | 下发方式 | 重复策略 |
| --- | --- | --- | --- |
| Support Invite | `lucky_reward_invite_bind` → `status=success` 后 | `WsService::notifyClientPOP(inviteeUid, [...])` | **一次**（bind 幂等保证不重复推） |
| Claim Now | HomeEvent flush | 合并进 `popList` | **未 claim 前每次回大厅** |

## 代码改动要点

### 1. [`EventBus::luckyRewardInviteBindEvent`](slot_console/app/command/EventBus.php)

`handleInviteBind` 返回 `success` 后新增（建议封装为 `LuckyRewardInviteLogic::pushInviteeSupportInvitePopup()`）：

1. `ensureInviteeAutoOpenBox($inviteeUid, $source)` — 从 HomeEvent **挪到这里**（弹窗需要 `my_amount`）
2. `buildSupportInvitePopup($inviteeUid, $source)`
3. 非 false 则 `WsService::notifyClientPOP($inviteeUid, [$popup])`

`already_processed` / 各类 `skipped_*` **不推送**。

### 2. [`HomeEvent::appendLuckyRewardHomePopups`](slot_console/app/command/event/HomeEvent.php)

**删除**：
- `ensureInviteeAutoOpenBox`
- `buildSupportInvitePopup` 及 merge

**保留**：
- `buildInviterClaimNowPopup` → Claim Now

方法可重命名为 `appendInviterClaimNowPopup` 或保持原名但注释只服务邀请人。

### 3. 测试

- [`LuckyRewardInviteBindIntegrationTest`](slot_console/tests/Integration/LuckyRewardInviteBindIntegrationTest.php)：`testEnsureInviteeAutoOpenBoxAndSupportInvitePopup` 改为断言 bind 成功路径（mock/spy `WsService` 或抽 `pushInviteeSupportInvitePopup` 返回值）
- 新增：bind 幂等第二次不推 WS
- HomeEvent 单测：被邀请人 uid flush **不应**再含 `lucky_reward_support_invite`

### 4. 文档

- [`05_slot_console_邀请助力与弹窗方案.md`](docs/requirements/lucky_rewards/05_slot_console_邀请助力与弹窗方案.md) §5 表格拆分触发点
- YApi #109 WS popup 示例补 Support Invite 即时推送说明

## 边界说明

| 点 | 处理 |
| --- | --- |
| MQ 消费略晚于注册完成 | 产品认定被邀请人在线；仍走 WS 即时推。若 hub 未连上，**不做 HomeEvent 补弹**（与「只弹一次、无离线」一致） |
| 游戏内禁弹 | bind 发生在注册链路，通常不在 `enter_game`；若需硬约束可后续加 hub 侧 scene 判断 |
| openBox 失败 | 记录 error，不推 Support Invite（无 my_amount） |
| 双角色用户 | HomeEvent 仅可能出 Claim Now；Support Invite 仅在作为被邀请人 bind 当时推一次 |

## 与「没有 helper」排查的关系

Support Invite 迁出 **不解决** helper 未落库；须先保证 `handleInviteBind` → `success` 写 helper，再在 success 分支推 WS。

---

# 「没有助力」（DB 无 lucky_reward_helper）— 排查结论

> 你已确认：**不是弹窗问题**，而是 `lucky_reward_helper` 没有新记录 / `valid_invite_count` 不涨。

## 有效助力必须满足的链路

```mermaid
sequenceDiagram
    participant User as slot_user注册
    participant AgentMQ as agent_bus
    participant Agent as slot_agent_EventBus
    participant Gateway as LuckyRewardInviteCallbackGateway
    participant ConsoleMQ as console_bus
    participant Console as slot_console_EventBus
    participant Logic as handleInviteBind

    User->>AgentMQ: TYPE_INVITE_BIND\nshare_origin=wheel\nis_new_register=1
    Agent->>Agent: ref_invite_relation 新建?
    Agent->>Gateway: 仅 isNewInviteRelation=true 时调用
    Gateway->>Gateway: lucky_reward_callback_enabled\nshare_origin=wheel
    Gateway->>ConsoleMQ: TYPE_LUCKY_REWARD_INVITE_BIND
    Console->>Logic: handleInviteBind
    Logic->>Logic: 无 skip 则写 helper + inviter grant
```

**任意一环失败 → DB 无 helper。**

## 按概率排序的常见原因

### 1. 用了 Agent 中心短码，不是转盘 wheel 短码（最常见误用）

- **agent 网关硬过滤**：[`LuckyRewardInviteCallbackGatewayService`](slot_agent/app/service/LuckyRewardInviteCallbackGatewayService.php) 仅 `share_origin=wheel` 才投递 console_bus；`user_agent` → `reason=skipped_not_wheel_origin`，**console 根本收不到消息**。
- **console 侧也会再拦**：[`resolveInviteBindSkipResult`](slot_console/app/api/logic/LuckyRewardInviteLogic.php) `share_origin !== wheel` → `skipped_not_wheel`。
- **正确链接**：须来自 `GET /api/lucky-reward/invite-link` 或 `Gift/createShareUrl from=wheel`（绑定当前 `lucky_reward_cycle` 的 `share_url.origin=wheel`）。

### 2. wheel 短码已过期（「以前有，现在没有」高概率）

- 轮次轮转后，旧短码 `share_url.biz_id` 指向**已结束 cycle**，与当前 active cycle 不一致 → console 返回 [`STATUS_SKIPPED_EXPIRED_CYCLE`](slot_console/app/entity/luckyReward/InviteBindResultEntity.php)，**不写 helper**（见集成测 `testHandleInviteBindSkipsWhenShareCycleMismatchActiveCycle`）。
- **处理**：邀请人重新拉 `invite-link`，用**本轮**短码测。

### 3. 被邀请人不是「本次新注册」

- console 要求 `is_new_register=1`；老 IMEI 登录 / 手动绑码 → `is_new_register=0` → `skipped_old_user`。
- IMEI 路径：仅 [`ImeiRegisterService::run`](slot_user/app/service/register/ImeiRegisterService.php) **新建账号**时 `notifyAgentInviteBind`；已存在 IMEI 走 login，**不发 invite_bind**。
- 手动绑码 [`UserController`](slot_user/app/innerapi/controller/UserController.php) 固定 `is_new_register=0`，且返回体**未带** `share_origin`（MQ 里为空）→ agent 网关 wheel 过滤失败。

### 4. 活动未开启或无 active cycle

- 种子数据默认 [`lucky_reward_config.status=2`（关闭）](backend/slot_admin/db/lucky_reward.sql)。
- console `resolveInviteBindProcessContext` 活动关闭 → `activity_closed`。
- 弹窗/开宝箱也依赖开启配置，与 helper 同源。

### 5. agent 仅「首次 ref_invite_relation」才回调 console

[`slot_agent EventBus::inviteBindEvent`](slot_agent/app/command/EventBus.php)：

```php
if ($isNewInviteRelation) {
    LuckyRewardInviteCallbackGatewayService::...->notifyFromInviteBindEntity($entity);
}
```

若该 `invitee_uid` 在 `ref_invite_relation` **已有行**（历史任何来源绑过），**不会再投递** `lucky_reward_invite_bind`，即使本次 MQ 仍处理 agent 奖励。

### 6. MQ / 开关 / 进程

| 检查项 | 位置 |
| --- | --- |
| `lucky_reward_callback_enabled=1` | center → agent |
| `php webman event:bus` 消费 agent_bus | slot_agent |
| `php webman event:bus` 消费 console_bus | slot_console |
| agent 日志 `luckyRewardCallback` | `dispatched` / `reason` |
| console 日志 `luckyRewardInviteBindEvent` | `status` 字段 |

## 建议排查步骤（按顺序执行）

1. **复现一次邀请注册**，记录：邀请短码、`share_url.origin`、`share_url.biz_id`、当前 `lucky_reward_cycle.id`。
2. **查 agent 日志** `inviteBindEvent` + `luckyRewardCallback`：
   - 无 `luckyRewardCallback` → 看 `isNewInviteRelation` 或 MQ 未进 agent。
   - `reason=skipped_not_wheel_origin` → 短码/来源不对。
   - `reason=callback_disabled` → center 开关。
3. **查 console 日志** `EventBus::luckyRewardInviteBindEvent` 的 `status`：
   - 无日志 → console_bus 未消费或 agent 未投递。
   - `skipped_expired_cycle` / `skipped_old_user` / `activity_closed` / `skipped_not_wheel` → 对号入座。
4. **SQL 验证**（替换 uid/cycle）：
   - `SELECT * FROM lucky_reward_helper WHERE invitee_uid=? ORDER BY id DESC LIMIT 5;`
   - `SELECT * FROM ref_invite_relation WHERE invitee_uid=?;`
   - `SELECT id,status,cycle_no,end_at FROM lucky_reward_cycle WHERE source='default' ORDER BY id DESC LIMIT 3;`
   - `SELECT short_code,origin,biz_type,biz_id FROM share_url WHERE short_code='?';`

## 若日志 status=success 仍无 helper

才考虑事务异常/库连接错误（少见）；查 console `LuckyReward inviteBind failed` error 日志。

## 与弹窗问题的关系

helper **未落库**时：`valid_invite_count` 不涨、Record/helpers 为空、Claim Now / Support Invite **都不会出现**（弹窗是 helper/grant 的下游展示）。应先修 invite_bind 链路，再谈弹窗互斥。