cursor/plans/移除_pending_popup_表_8fea9a4d.plan.md

name, overview, todos, isProject

name	overview	todos	isProject
移除 pending popup 表	移除 Lucky Rewards 转盘邀请人 Claim Now 弹窗对 `user_pending_popup` 的依赖，改为在 HomeEvent 中根据 `lucky_reward_player.pending_spin_count > 0` 动态构建弹窗；未领取前每次回大厅重复展示，直至 `claim-inviter-spin` 清零。	id content status build-inviter-popup LuckyRewardInviteLogic 新增 buildInviterClaimNowPopup()，删除 notifyInviterInviteSuccess/enqueue completed id content status home-event-simplify HomeEvent 改用 buildInviterClaimNowPopup，移除 PendingPopupService completed id content status remove-pending-popup-infra 删除 PendingPopupService/Model/DTO/Entity 及 deploy DDL 引用 completed id content status update-tests-docs 更新集成测、需求文档与 lucky_reward_deploy 冒烟说明 completed	false

移除 user_pending_popup，改用 pending_spin_count 驱动转盘弹窗

背景与结论

当前邀请人「Claim Now」弹窗存在双源：

sequenceDiagram
    participant InviteBind as invite_bind
    participant Player as lucky_reward_player
    participant Grant as lucky_reward_spin_grant
    participant Popup as user_pending_popup
    participant Home as HomeEvent

    InviteBind->>Grant: 写 invite_inviter grant
    InviteBind->>Player: pending_spin_count += N
    InviteBind->>Popup: enqueue lr_invite:{cycle}:{invitee}
    Home->>Popup: fetchPending + consume
    Home->>Player: resolvePendingSpinCount 注入 payload

• LuckyRewardInviteLogic::notifyInviterInviteSuccess() 入队 user_pending_popup
• HomeEvent::appendLuckyRewardHomePopups() 再读 pending_spin_count 注入 payload

全仓库检索结果：PendingPopupService / user_pending_popup 仅被 Lucky Rewards 使用，无其它业务消费者。可以按你的要求移除该表及相关代码，改以 player 表为唯一触发源。

你已确认弹窗行为：pending_spin_count > 0 时每次回大厅都弹，直到 claim-inviter-spin 领完（比旧「consume 后不再弹」更符合待领语义）。

---

目标行为

场景	是否弹 Claim Now	数据来源
pending_spin_count > 0	是，每次 HomeEvent flush	resolvePendingSpinCount()
领取后 pending_spin_count = 0	否	claim 流程已有扣减
inviter_spin_reward = 0	否（无待领 Spin）	与 grant 逻辑一致
多次邀请、多笔待领	一条弹窗，pending_spin_count 为累计值；被邀请人信息取最早未领 grant	findUnclaimedInviterGrant() + 解析 biz_id invite_inviter:{cycle_id}:{invitee_uid}

弹窗 payload 保持与现网客户端兼容（type: lucky_reward_invite_success）：

{
  "type": "lucky_reward_invite_success",
  "data": {
    "invitee_uid": 200001,
    "invitee_nickname": "Alice",
    "invitee_avatar": "3",
    "spin_reward": 1,
    "cycle_id": 34,
    "pending_spin_count": 2,
    "title": "LUCKY YOU!",
    "content": "You've received 1 Free Spin",
    "button_text": "Claim Now",
    "priority": 50
  }
}

• spin_reward：当前最早未领 grant 的 spin_count（通常 1）
• pending_spin_count：player 累计待领总数（已有 resolvePendingSpinCount()）

Support Invite（被邀请人）弹窗不变，仍走 buildSupportInvitePopup() + ensureInviteeAutoOpenBox()。

---

代码改动

1. 新增邀请人弹窗构建方法

在 LuckyRewardInviteLogic 增加 public 方法，例如 buildInviterClaimNowPopup(int $uid, string $source): array|false：

• 活动关闭 / 无有效轮次 → false
• resolvePendingSpinCount($uid, $source) <= 0 → false
• 取 findUnclaimedInviterGrant($uid, $cycleId)；若 grant 为空但 count>0（脏数据）→ 打 error 日志并 false
• 从 grant biz_id 解析 invitee_uid，fetchUserProfile() 取昵称/头像
• 返回与现网一致的 type + data 结构

2. 简化 HomeEvent

HomeEvent::appendLuckyRewardHomePopups()：

• 删除 PendingPopupService 引用及 fetchPending / consume 循环
• 在 Support Invite 之后调用 buildInviterClaimNowPopup()，有则 $luckyRewardPopups[] 追加
• pending_spin_count 已在 popup data 内组装，无需二次注入

3. 删除 invite_bind 入队逻辑

LuckyRewardInviteLogic：

• 删除 notifyInviterInviteSuccess() 及对 PendingPopupService::enqueue 的调用（handleInviteBind 第 108 行）
• 移除 PendingPopupService / PendingPopupEnqueueDTO 依赖
• InviteBindProcessContextDTO::$popupBizId 若仅用于 popup，可一并删除（保留 inviterBizId 供 grant 幂等）

4. 移除 pending popup 基础设施（无其它引用）

删除 slot_console 内：

• app/service/PendingPopupService.php
• app/model/common/UserPendingPopupModel.php
• app/dto/pendingPopup/PendingPopupEnqueueDTO.php
• app/entity/pendingPopup/*

DDL / 部署文档：

• backend/slot_admin/db/user_pending_popup.sql 标记废弃或删除
• 可选新增 backend/slot_admin/db/user_pending_popup_drop.sql（DROP TABLE IF EXISTS user_pending_popup）供已部署环境执行
• 更新 slot_console/doc/lucky_reward_deploy.md 部署步骤（去掉第 2 步建表）

5. 测试

更新 LuckyRewardInviteBindIntegrationTest：

• 删除对 UserPendingPopupModel 的断言（约 61–78、96–99 行）
• 新增用例：buildInviterClaimNowPopup 在 bind 后返回非 false，且含 pending_spin_count；claimInviterSpin 后返回 false

更新 LuckyRewardDbTestCase：

• 去掉 user_pending_popup 表存在性检查与 cleanup

可选：新增单元测覆盖 buildInviterClaimNowPopup 的 grant biz_id 解析（mock 较少时可放集成测）。

6. 文档

• docs/requirements/lucky_rewards/05_slot_console_邀请助力与弹窗方案.md §5：Claim Now 改为 pending_spin_count > 0 + buildInviterClaimNowPopup
• docs/requirements/lucky_rewards/07_用户定向弹窗通知机制方案.md：标注 Lucky Rewards 已不再使用通用表；若整表无其它用途则机制废弃
• lucky_reward_deploy.md 冒烟：邀请人回大厅见 Claim Now（可重复至领取）

---

行为差异说明（验收时注意）

项	旧（user_pending_popup）	新（pending_spin_count）
未点 Claim 再次回大厅	不再弹（已 consume）	继续弹（你已确认）
多笔邀请	可能多条 popup 队列	一条，count 累计
inviter_spin_reward=0	仍入队通知	不弹（count 为 0）

---

验收清单

1. invite_bind success → pending_spin_count 增加，不写 user_pending_popup
2. 邀请人 HomeEvent → popList 含 lucky_reward_invite_success，pending_spin_count 正确
3. 未 claim 前多次回大厅 → 弹窗仍出现
4. POST claim-inviter-spin 后 → pending_spin_count=0，弹窗不再出现
5. 被邀请人 Support Invite + auto openBox 不受影响
6. RUN_DB_TESTS=1 集成测通过；verify + php -l PASS