ok

plans/register-bonus-decouple-254c9e72.plan.md

@@ -0,0 +1,78 @@
+<!-- 254c9e72-64e2-4a49-bb96-cb80c68065d7 -->
+---
+todos:
+  - id: "config"
+    content: "新建 slot-user/config/register_bonus.php，从 env 读默认开关/金额(大单位)/打码倍数，支持按 source 覆盖"
+    status: pending
+  - id: "service"
+    content: "新建 slot-user/app/service/wallet/RegisterBonusService.php：读配置+Redis NX 幂等+slot_sdk WalletClient->register+fail-open；删除旧 activity 网关"
+    status: pending
+  - id: "callers"
+    content: "AbstractRegisterService::grantRegisterBonusAfterNewUserRegistered 与 EventRegister::triggerRegisterBonus 切换到新服务"
+    status: pending
+  - id: "sdk-wagering"
+    content: "修复 slot_sdk WalletService::register() 补传 bonus_wagering"
+    status: pending
+  - id: "activity-cleanup"
+    content: "确认无其他调用方后，下线 slot-activity 注册赠金 innerapi 与 slot_sdk ActivityService::triggerRegisterBonus 相关代码"
+    status: pending
+  - id: "verify"
+    content: "注册各入口+MQ 兜底验证幂等与 wagering，跑后端门禁脚本"
+    status: pending
+isProject: false
+---
+# 注册赠金从活动服解耦到用户服
+
+## 背景与现状
+
+当前链路：`slot-user` 注册 → [`RegisterBonusGatewayService`](slot-user/app/service/activity/RegisterBonusGatewayService.php) → (slot_sdk) `ActivityClient` → [`slot-activity` `RegisterBonusLogic`](slot-activity/app/innerapi/logic/RegisterBonusLogic.php)（查活动配置 + Redis 幂等锁 + 调钱包 register）。
+
+问题：注册赠金强依赖活动服；活动服不可用时新用户拿不到赠金（且 register 类型钱包调用是钱包账户创建入口，间接影响）。
+
+目标（已确认）：**完全解耦**，赠金配置放 slot-user 的 **config 文件**，由用户服直接调钱包，不再依赖 slot-activity。
+
+```mermaid
+flowchart LR
+  reg["slot-user 注册 / EventRegister MQ"] --> svc["新 RegisterBonusService(读 config + Redis 幂等)"]
+  svc -->|slot_sdk WalletClient->register| wallet["slot-wallet RegisterService 入账+建账户"]
+```
+
+## 关键修复点（必须）
+
+- **slot_sdk 漏传 `bonus_wagering`**：[`WalletService::register()`](slot_sdk/src/service/wallet/WalletService.php) 仅拼 `type/fee/bonus` + base payload，`bonus_wagering` 被丢弃，导致钱包侧 [`RegisterService::resolveRegisterBonusRequiredWager`](slot-wallet/app/service/wallet/RegisterService.php) 始终按默认 1 倍。需补传。
+- **幂等归属转移**：钱包 `register` 无 `biz_id` 去重，原幂等靠活动服 Redis NX 锁。解耦后由 slot-user 持有 Redis NX 锁（沿用 `biz_id = register:bonus:{uid}`），避免同步路径与 `EventRegister` MQ 兜底重复发放。
+
+## 改动清单
+
+### 1. slot-user：新增赠金配置（config 文件）
+- 新建 `slot-user/config/register_bonus.php`：从 env 读默认开关/金额（大单位）/打码倍数，并支持按 `source` 覆盖；如 `enabled`、`default => ['amount' => env('REGISTER_BONUS_AMOUNT',0), 'wagering' => env('REGISTER_BONUS_WAGERING',1)]`、`sources => ['pwa_a' => [...]]`。
+- 金额大单位经 `slot\foundation\Tools\MoneyTool::bigUnitToSmallUnit` 转最小单位；币种取自 `UserShardModel->currency`。
+
+### 2. slot-user：新增直连钱包的赠金服务（替换活动网关）
+- 新建 `slot-user/app/service/wallet/RegisterBonusService.php`（公共能力：读配置 + 跨服务调钱包）：
+  - 按 `source` 解析金额/倍数；金额≤0 或未启用 → 记日志跳过。
+  - Redis `SET NX EX` 幂等锁（key 含 uid），命中重复直接返回。
+  - 经 slot_sdk `WalletClient->register(WalletRegisterEntity{uid,source,currency,organization,biz_id,bonus,bonus_wagering})` 入账。
+  - fail-open：catch `Throwable` 仅 `LoggerService::error`，不抛出（不阻断注册）；失败时删除锁以便 MQ 兜底重试。
+  - 日志含 `uid/source/currency/bonus/biz_id`。
+- 删除 [`slot-user/app/service/activity/RegisterBonusGatewayService.php`](slot-user/app/service/activity/RegisterBonusGatewayService.php)。
+
+### 3. slot-user：切换调用方
+- [`AbstractRegisterService::grantRegisterBonusAfterNewUserRegistered`](slot-user/app/service/register/AbstractRegisterService.php) 改调新 `RegisterBonusService`（影响 6 个 RegisterService 子类，无需逐个改）。
+- [`EventRegister::triggerRegisterBonus`](slot-user/app/command/EventRegister.php) 同步改为新服务（保留 MQ 兜底语义）。
+
+### 4. slot_sdk：补传 bonus_wagering
+- [`WalletService::register()`](slot_sdk/src/service/wallet/WalletService.php) 的 `WalletUpdateEntity` payload 增加 `'bonus_wagering' => $entity->bonus_wagering`（`WalletUpdateEntity`/钱包 DTO 已支持该字段）。
+
+### 5. slot-activity：下线注册赠金入口（清理，确认无其他调用方后执行）
+- 删除 `slot-activity/app/innerapi/{controller/RegisterBonusController, logic/RegisterBonusLogic, dto/RegisterBonusTriggerDto, validate/RegisterBonusValidate}.php` 及其路由。
+- 删除 slot_sdk `ActivityService::triggerRegisterBonus` 与 `RegisterBonusTriggerEntity`/响应实体（grep 确认仅 slot-user 旧网关使用）。
+- `activity_type=7 注册赠送` 活动数据保留与否由运营决定，本次不动表结构。
+
+## 待确认 / 决策
+- **是否对每个新用户都调一次 register 以确保钱包账户必建**（即便赠金为 0）：当前钱包账户由 register 调用创建，建议赠金=0 时仍调用 `register(bonus=0)` 兜底建账户；若钱包账户另有创建入口则无需。实现时按现状默认「仅金额>0 才发」，此点单独标注。
+- 按 `source` 区分金额的具体取值由运营提供；config 先给 `default`。
+
+## 验收
+- 注册（各 RegisterService）+ MQ 兜底各跑一次，确认：赠金按配置入账一次（幂等不重复）、`bonus_wagering` 生效（钱包 fund lot `required_wager` 正确）、活动服关停不影响注册与发放。
+- 收尾执行 `slot-backend-completion-report` 门禁（verify + `php -l`）。