ok

plans/移除被邀请人spin配置_a6751847.plan.md

@@ -0,0 +1,140 @@
+---
+name: 移除被邀请人Spin配置
+overview: 去掉错误的「被邀请人 invite_bind 发 Spin / invitee_spin_reward」能力；保留 PRD 4.3 Support Invite，在轮次有效期内按 helper 关系为被邀请人自动开宝箱一次（复用现有 openBox 自动 Spin），过期轮次不建 helper、不开箱、不弹窗。
+todos:
+  - id: remove-invitee-spin-grant
+    content: 删除 grantInviteeSpin/claim-invitee-spin/ProcessContext invitee 字段及 Controller 路由
+    status: completed
+  - id: support-invite-auto-openbox
+    content: 实现 ensureInviteeAutoOpenBox + 重构 buildSupportInvitePopup；HomeEvent 接入
+    status: completed
+  - id: admin-remove-invitee-config
+    content: Admin/API/Model 去掉 invitee_spin_reward 配置项
+    status: completed
+  - id: docs-tests-invitee-removal
+    content: 更新 05/API 文档；调整集成测并跑 verify
+    status: completed
+isProject: false
+---
+
+# 移除被邀请人 Spin 配置，改为 helper + 自动开宝箱
+
+## 背景澄清
+
+- **错误理解**：`invitee_spin_reward` + `invite_bind` 给被邀请人预发 Spin（grant_type=3 / `claim-invitee-spin`）。
+- **产品本意**：被邀请人 Spin 来自**开宝箱**既有流程（[`LuckyRewardLogic::openBox`](slot_console/app/api/logic/LuckyRewardLogic.php) 内 `createOpenBoxAutoFirstSpinRecord` + `grantDailySpinIfNeeded`），**不**单独配置「被邀请人 Spin 次数」。
+- **Support Invite（PRD 4.3）保留**：有效期内按 **helper 关系**处理；**自动开宝箱一次**；轮次过期则**无 helper、不自动开箱、不弹 Support Invite**（与已有 `skipped_expired_cycle` 一致）。
+
+```mermaid
+sequenceDiagram
+    participant User as slot_user_register
+    participant Logic as LuckyRewardInviteLogic
+    participant Home as HomeEvent
+    participant Box as LuckyRewardLogic_openBox
+
+    User->>Logic: invite_bind wheel有效短码
+    alt cycle有效
+        Logic->>Logic: helper+邀请人pending_spin
+        Note over Logic: 不再 grantInviteeSpin
+    else cycle过期
+        Logic-->>User: skipped_expired_cycle
+    end
+
+    User->>Home: 被邀请人回大厅
+    alt helper存在且cycle有效且未开箱
+        Home->>Logic: ensureInviteeAutoOpenBox
+        Logic->>Box: openBox一次
+        Home->>User: SupportInvite弹窗my_amount
+    else 过期或无helper
+        Home-->>User: 无SupportInvite
+    end
+```
+
+---
+
+## 1. 删除「被邀请人发 Spin」链路
+
+### slot_console Logic / API
+
+| 删除/停用 | 文件 |
+|-----------|------|
+| `grantInviteeSpinForHelper()` 及事务内调用 | [`LuckyRewardInviteLogic.php`](slot_console/app/api/logic/LuckyRewardInviteLogic.php) |
+| `claimInviteeSpin()` / `claimPendingSpinByGrantType(... INVITEE)` | 同上 |
+| `POST claim-invitee-spin` | [`LuckyRewardController.php`](slot_console/app/api/logic/LuckyRewardController.php) + 路由 |
+| `InviteBindProcessContextDTO` 的 `inviteeSpinReward`、`inviteeBizId` | [`InviteBindProcessContextDTO.php`](slot_console/app/dto/luckyReward/InviteBindProcessContextDTO.php) |
+
+保留 `LuckyRewardSpinGrantModel::GRANT_TYPE_INVITEE` / 历史 grant 只读兼容（不在新流程写入）。
+
+### 配置与后台
+
+| 项 | 处理 |
+|----|------|
+| [`lucky_reward_config.invitee_spin_reward`](backend/slot_admin/db/lucky_reward.sql) | **停止读写**；可选后续 DDL 删列（本次可留列默认 0，避免强迁移） |
+| Admin 列表/编辑「被邀请人Spin」 | [`backend/slot_admin_vue/.../luckyReward/config/*.vue`](backend/slot_admin_vue/src/views/game/luckyReward/config/) 移除字段 |
+| slot_console 保存配置 API | 若 DTO/Validator 含该字段，一并移除 |
+| [`LuckyRewardConfigModel`](slot_console/app/model/common/LuckyRewardConfigModel.php) `@property` | 标注废弃或删除 |
+
+### 文档
+
+- 更新 [`05_slot_console_邀请助力与弹窗方案.md`](docs/requirements/lucky_rewards/05_slot_console_邀请助力与弹窗方案.md)：删除被邀请人 grant/claim 描述；改为「被邀请人 Spin = 开宝箱流程」。
+- 更新 [`lucky_reward_api.md`](slot_console/doc/lucky_reward_api.md)：移除 `claim-invitee-spin`。
+- 在 PRD 侧注记：`invitee_spin_reward` 配置项作废（可选改 [`转盘活动-功能需求文档.md`](docs/requirements/转盘活动-功能需求文档.md) 配置表一行）。
+
+---
+
+## 2. Support Invite + 自动开宝箱（有效期内）
+
+### 新增编排（`LuckyRewardInviteLogic`）
+
+**`ensureInviteeAutoOpenBox(int $uid, string $source): void`**
+
+1. 解析 active cycle（`resolveActiveCycle`）；无进行中轮次 → return。
+2. `LuckyRewardHelperModel::findByInviteeAndCycle($uid, $cycleId)` 无记录 → return（无 helper 不开箱）。
+3. `LuckyRewardPlayerModel` 已 `box_opened_at > 0` → return（幂等）。
+4. 调用 [`LuckyRewardLogic::openBox($uid, $source)`](slot_console/app/api/logic/LuckyRewardLogic.php)（吞「已开箱」类 BusinessException，打 info 日志）。
+
+**重构 `buildSupportInvitePopup()`**
+
+- **删除**对 `findUnclaimedInviteeGrant` / `pending_spin_count` 的依赖。
+- **条件**：helper 存在 + active cycle 有效（`end_at > now`）+ 已开箱（可先调 `ensureInviteeAutoOpenBox` 再读 player）。
+- **payload**：邀请人头像/昵称、`my_amount_qf`、`target_amount_qf`（去掉 spin 待领字段）。
+
+### HomeEvent 接入
+
+[`HomeEvent::appendLuckyRewardHomePopups`](slot_console/app/command/event/HomeEvent.php) 顺序调整为：
+
+```php
+$inviteLogic->ensureInviteeAutoOpenBox($uid, $source);
+$supportInvitePop = $inviteLogic->buildSupportInvitePopup($uid, $source);
+// 再 merge pendingPopup...
+```
+
+过期 wheel 短码：`invite_bind` 已 `skipped_expired_cycle` → **无 helper** → 上述两步自然 no-op。
+
+---
+
+## 3. 邀请人侧不变
+
+- 邀请人仍：`pending_spin_count` + Claim Now 弹窗 + `claim-inviter-spin`。
+- wheel 分享 cycle 绑定方案**不改动**。
+
+---
+
+## 4. 测试
+
+| 用例 | 预期 |
+|------|------|
+| invite_bind 成功 | 仅 inviter grant/helper；**无** invitee grant；invitee `spin_available` 仍为 0 |
+| invitee HomeEvent（helper + 有效 cycle） | 自动 `openBox` 一次；`spin_available` 来自 daily/openBox 逻辑；Support Invite 有 `my_amount_qf` |
+| 过期短码 invite_bind | `skipped_expired_cycle`；无 helper；HomeEvent 无开箱、无 Support Invite |
+| 删除 claim-invitee-spin 相关集成测 | 改为 auto openBox + Support Invite 断言 |
+
+更新 [`LuckyRewardInviteBindIntegrationTest`](slot_console/tests/Integration/LuckyRewardInviteBindIntegrationTest.php)、[`LuckyRewardDbTestCase`](slot_console/tests/Integration/LuckyRewardDbTestCase.php)（去掉 `invitee_spin_reward` seed）。
+
+---
+
+## 5. 不在本次范围
+
+- 修改开宝箱 / 每日 Spin 核心算法（仅**复用** `openBox`）。
+- 删除 DB 列 `invitee_spin_reward`（可后续单独 migration）。
+- 清理历史 `grant_type=3` 数据。