ok

plans/wallet bet success MQ-8500b436.plan.md

@@ -0,0 +1,320 @@
+<!-- 8500b436-6684-4cb3-a26f-8d927dd70f9b -->
+---
+todos:
+  - id: "define-constants"
+    content: "在 slot-foundation 新增 WalletEventMQ 常量（exchange + routingKey）"
+    status: pending
+  - id: "add-publisher"
+    content: "在 slot-wallet 新增 WalletBetSuccessMqPublisher，封装 {type, uid, data, ts} 载荷组装"
+    status: pending
+  - id: "extend-wallet-dto"
+    content: "slot-wallet / slot-pwa DTO 与 Validate 增加 provider_code、game_code 透传字段"
+    status: pending
+  - id: "hook-bet-success"
+    content: "在 WalletBetWinLogic::bet() commit 后调用 publisher（幂等命中跳过）"
+    status: pending
+  - id: "pwa-pass-game-context"
+    content: "slot-pwa CashLogic 调 wallet 时透传 provider_code（如 pop）与 game_code"
+    status: pending
+  - id: "consumer-bind"
+    content: "各消费服务自建 queue 并 bind topic 模式（wallet.bet.success / wallet.bet.#）"
+    status: pending
+isProject: false
+---
+# wallet.bet.success 消息体设计方案
+
+## 背景与定位
+
+当前 `slot-wallet` 下注成功后已有两类 MQ，但都不适合作为**通用钱包事件总线**：
+
+| 现有通道 | 载荷 | 局限 |
+|---|---|---|
+| `slot_console` / `console_bus` | `{ uid, type:'bet', data:{ source, amount } }` | 仅统计，缺 biz_id / round_id / 资金拆分 |
+| `slot_activity` / `trial_reward_bus` | `{ type, uid, data, ts }` | 活动专用，且目前由 **slot-pwa** 在钱包 API 返回后投递，非 wallet 权威源 |
+| `slot_hub` | WebSocket 钱包刷新 | 面向客户端，非业务事件 |
+
+`slot-foundation` 文档/测试中的示例 `{"uid":1001,"bet_amount":500}` 过于简陋，无法支撑多服务幂等与金额语义区分。
+
+**新事件定位**：wallet 事务提交后的**权威下注成功事件**，供 activity / console / 统计 / 返水等各自按 Topic 模式订阅（如 `wallet.bet.#`、`wallet.#`）。
+
+```mermaid
+sequenceDiagram
+    participant Caller as 调用方_PWA或游戏网关
+    participant Wallet as slot_wallet
+    participant DB as wallet_log
+    participant Exchange as slot.wallet.event.exchange
+    participant Activity as slot_activity
+    participant Stats as 统计服务
+
+    Caller->>Wallet: bet(biz_id, fee, round_id, ...)
+    Wallet->>DB: commit 写入 biz_type=bet
+    Wallet->>Exchange: publish wallet.bet.success
+    Exchange-->>Activity: 各自 queue 绑定
+    Exchange-->>Stats: 各自 queue 绑定
+```
+
+---
+
+## 推荐信封结构
+
+沿用 [`TrialRewardMqPublisher`](slot-wallet/app/service/mq/TrialRewardMqPublisher.php) 的约定，便于消费方统一解析：
+
+```json
+{
+  "type": "wallet.bet.success",
+  "uid": 12345,
+  "ts": 1718092800,
+  "data": { }
+}
+```
+
+- `type`：与 routingKey 一致，便于日志/死信/转发时脱离 routing 元数据也能识别
+- `uid`：放信封层，消费方可快速过滤
+- `ts`：事件产生时间（Unix 秒），非 DB `created_at`
+- `data`：业务载荷（见下）
+
+---
+
+## 推荐 `data` 字段（通用可扩展）
+
+### 1. 幂等与追溯（必填）
+
+| 字段 | 来源 | 说明 |
+|---|---|---|
+| `biz_id` | `WalletUpdateRequestDTO->biz_id` | 业务幂等键，消费方应用 `uid + biz_id` 去重 |
+| `ledger_id` | `wallet_log.id` | wallet 侧唯一流水号，需查账时可直接定位 |
+| `round_id` | request | 关联同局 win |
+| `trace_id` | request（可空） | 链路追踪 |
+
+### 2. 渠道上下文（必填）
+
+| 字段 | 来源 |
+|---|---|
+| `currency` | request |
+| `source` | request |
+| `organization` | request |
+
+### 3. 金额语义（必填，三者不可混用）
+
+下注存在三种路径（[`WalletBetWinLogic::bet()`](slot-wallet/app/api/logic/WalletBetWinLogic.php)），金额字段必须区分：
+
+| 字段 | 含义 | 计算规则 |
+|---|---|---|
+| `bet_amount` | 名义下注额 | 恒等于 request `fee`（最小货币单位，*1000） |
+| `wallet_deduct_amount` | 实际扣款额 | real/trial = `fee`；FS 代付 = `0` |
+| `valid_bet_amount` | 计入打码/有效投注额 | real = `betResult.withdraw + betResult.deposit`；trial = `0`；FS 代付 = `fee`（全额计入，与 [`TrialValidBetNotifyService`](slot-wallet/app/service/trial/TrialValidBetNotifyService.php) 一致） |
+
+> 消费方按业务选用：`bet_amount` 做流水统计；`valid_bet_amount` 做活动/返水；`wallet_deduct_amount` 做资金变动核对。
+
+### 4. 下注分类（必填）
+
+| 字段 | 取值 | 判定 |
+|---|---|---|
+| `bet_mode` | `trial` / `real_money` / `free_spin` | 对应三条执行分支 |
+
+辅助布尔字段（便于过滤，与 `bet_mode` 冗余但实用）：
+
+- `is_fs_paid_bet`：0/1
+- `fs_account_id`：FS 路径时 > 0，否则 0
+
+### 5. 资金拆分摘要（real_money 路径建议带，trial/FS 可简化）
+
+```json
+"deduction": {
+  "bonus": 0,
+  "deposit": 3000,
+  "withdraw": 2000,
+  "hit_side": "deposit"
+}
+```
+
+来源：[`BetService::execute()`](slot-wallet/app/service/wallet/BetService.php) 返回的 `betResult`。供返水、RTP、资金归因等消费方使用。
+
+**不建议**在 MQ 中带完整 `fund_detail` / `remark` JSON（体积大、含 lot_no 等内部细节）；需要时可凭 `ledger_id` 回查 `wallet_log`。
+
+### 6. 游戏身份（多上游平台场景，建议必填）
+
+slot-pwa 已有完整游戏映射链（见下），但 **slot-wallet 不查 g_game 表**，因此游戏身份必须由调用方（通常是 slot-pwa）在下注请求中透传，wallet 原样写入 MQ。
+
+```mermaid
+flowchart LR
+    subgraph pwa [slot_pwa]
+        ProviderCode["provider_code 如 pop"]
+        ExternalCode["vendor_game_id 即 external_game_code"]
+        GameCode["game_code 本平台编码"]
+    end
+    subgraph mapping [g_game_platform_mapping]
+        MapRow["platform_id + external_game_code"]
+    end
+    subgraph game [g_game]
+        GameRow["game_code 全局唯一"]
+    end
+    ProviderCode --> MapRow
+    ExternalCode --> MapRow
+    MapRow --> GameRow
+    GameRow --> GameCode
+```
+
+| 字段 | 对应 slot-pwa 概念 | 说明 |
+|---|---|---|
+| `provider_code` | `GPlatformModel.code` / `GameRoundModel.provider_code` | 上游平台编码，如 `pop`；多平台并存时**必填** |
+| `game_code` | `GGameModel.game_code` / `PopTransferCallbackContext::gameCode()` | 本平台全局唯一游戏编码；消费方可直接关联 `g_game` |
+| `vendor_game_id` | `GGamePlatformMappingModel.external_game_code` | 上游原始游戏 ID（POP 回调 `gameid`）；与 `provider_code` 组合可唯一定位 mapping |
+| `game_category` | `WalletTrialGameContextResolver::resolveGameCategory()` | 如 `SLOTS`；默认 `SLOTS` |
+
+**唯一定位规则**（与 [`PopGameResolveService`](slot-pwa/app/service/game/PopGameResolveService.php) 一致）：
+
+- 主键语义：`provider_code` + `vendor_game_id` → `g_game_platform_mapping` → `g_game`
+- 消费方若只需本平台游戏：读 `game_code` 即可
+- 消费方若需区分上游来源：用 `provider_code` + `vendor_game_id`
+- 三者齐全时消费方可交叉校验，避免 mapping 变更导致歧义
+
+当前 gap：[`CashLogic::invokeWalletBetOrWin()`](slot-pwa/app/pop/logic/CashLogic.php) 已解析出 `boundGame` 与 `providerCode()`，但调 wallet 时**仅传了** `vendor_game_id` / `game_category`，**未传** `provider_code` / `game_code`——落地时需补齐。
+
+wallet 层**不持久化**游戏字段到 `wallet_log`，必须在 commit 后从 request 即时写入 MQ。
+
+---
+
+## 完整示例
+
+### 真实资金下注
+
+```json
+{
+  "type": "wallet.bet.success",
+  "uid": 12345,
+  "ts": 1718092800,
+  "data": {
+    "biz_id": "pg_tx_20240611_001",
+    "ledger_id": 987654321,
+    "currency": "USD",
+    "round_id": "round_abc123",
+    "source": "myslot",
+    "organization": 1001,
+    "trace_id": "trace_xyz",
+    "bet_amount": 5000,
+    "wallet_deduct_amount": 5000,
+    "valid_bet_amount": 5000,
+    "bet_mode": "real_money",
+    "is_fs_paid_bet": 0,
+    "fs_account_id": 0,
+    "provider_code": "pop",
+    "game_code": "pop_sweet_bonanza",
+    "game_category": "SLOTS",
+    "vendor_game_id": "pg_soft_001",
+    "deduction": {
+      "bonus": 0,
+      "deposit": 3000,
+      "withdraw": 2000,
+      "hit_side": "deposit"
+    }
+  }
+}
+```
+
+### FS 代付下注
+
+```json
+{
+  "type": "wallet.bet.success",
+  "uid": 12345,
+  "ts": 1718092800,
+  "data": {
+    "biz_id": "pg_tx_fs_001",
+    "ledger_id": 987654322,
+    "currency": "USD",
+    "round_id": "round_fs_001",
+    "source": "myslot",
+    "organization": 1001,
+    "trace_id": "",
+    "bet_amount": 2000,
+    "wallet_deduct_amount": 0,
+    "valid_bet_amount": 2000,
+    "bet_mode": "free_spin",
+    "is_fs_paid_bet": 1,
+    "fs_account_id": 5566,
+    "provider_code": "pop",
+    "game_code": "pop_sweet_bonanza",
+    "game_category": "SLOTS",
+    "vendor_game_id": "pg_soft_001",
+    "deduction": {
+      "bonus": 0,
+      "deposit": 0,
+      "withdraw": 0,
+      "hit_side": ""
+    }
+  }
+}
+```
+
+### 试玩期下注
+
+```json
+{
+  "type": "wallet.bet.success",
+  "uid": 12345,
+  "ts": 1718092800,
+  "data": {
+    "biz_id": "trial_bet_001",
+    "ledger_id": 987654323,
+    "currency": "USD",
+    "round_id": "round_trial_001",
+    "source": "myslot",
+    "organization": 1001,
+    "trace_id": "",
+    "bet_amount": 1000,
+    "wallet_deduct_amount": 1000,
+    "valid_bet_amount": 0,
+    "bet_mode": "trial",
+    "is_fs_paid_bet": 0,
+    "fs_account_id": 0,
+    "provider_code": "pop",
+    "game_code": "pop_trial_slots",
+    "game_category": "SLOTS",
+    "vendor_game_id": "pg_trial_001",
+    "deduction": {
+      "bonus": 1000,
+      "deposit": 0,
+      "withdraw": 0,
+      "hit_side": "bonus"
+    }
+  }
+}
+```
+
+---
+
+## 关键行为约定
+
+1. **仅首次成功投递**：幂等命中（`findByBizIdAndType` 已有记录）时**不**发 MQ，避免重复消费。
+2. **投递时机**：`commit()` 之后，与现有 `sendConsoleBus('bet')` 同级（[`WalletBetWinLogic` L106-108](slot-wallet/app/api/logic/WalletBetWinLogic.php)）。
+3. **失败策略**：MQ 发送失败只记 warning 日志，**不回滚**已提交的钱包事务（与 `TrialRewardMqPublisher` 一致）。
+4. **消费方幂等**：建议以 `uid + biz_id` 或 `ledger_id` 做唯一约束/去重。
+5. **与 trial_reward_bus 关系**：短期可并存；长期 activity 可改为订阅 `wallet.bet.success` 并按 `bet_mode` / `valid_bet_amount` 自行路由，逐步去掉 PWA 侧重复投递。
+
+---
+
+## 若落地实现（后续步骤）
+
+1. **slot-foundation**：新增 [`WalletEventMQ`](slot-foundation/src/Constants/MQ/) 常量类（`EXCHANGE = slot.wallet.event.exchange`、`ROUTING_KEY_BET_SUCCESS = wallet.bet.success`）。
+2. **slot-wallet**：
+   - `WalletUpdateRequestDTO` / Validate 增加 `provider_code`、`game_code`（字符串，可空但游戏下注场景应由调用方传入）
+   - 新增 `WalletBetSuccessMqPublisher`（或通用 `WalletEventMqPublisher`）
+   - 在 `WalletBetWinLogic::bet()` commit 后组装上述 `data` 并 publish
+   - 抽取 `resolveBetMode()` / `resolveValidBetAmount()` 私有方法，避免金额语义散落
+3. **slot-pwa**（游戏上下文来源）：
+   - `WalletWinOrBetRequestDTO` 增加 `provider_code`、`game_code`
+   - [`CashLogic::invokeWalletBetOrWin()`](slot-pwa/app/pop/logic/CashLogic.php) 从 `transferContext->providerCode()` 与 `boundGame->game_code` 透传
+   - [`WalletService::appendTrialGameContext()`](slot-pwa/app/service/WalletService.php) 非空时写入请求体
+   - 后续新上游平台（非 pop）沿用同一字段，平台 code 取自各自 `providerCode()` 实现
+4. **消费方**：各服务自建 queue + bind（如 `wallet.bet.success` 或 `wallet.bet.#`），按 `provider_code` / `game_code` 过滤统计。
+
+---
+
+## 设计原则小结
+
+- **信封统一**：`{ type, uid, data, ts }`，与 activity 事件一致
+- **金额三分**：`bet_amount` / `wallet_deduct_amount` / `valid_bet_amount`，避免 FS、trial、real 混用
+- **自洽但不臃肿**：含消费方 80% 场景所需字段；深度明细靠 `ledger_id` 回查
+- **游戏三元组**：`provider_code` + `vendor_game_id` + `game_code`，对齐 slot-pwa 映射，支持多上游平台
+- **权威源在 wallet**：从 PWA 侧活动通知逐步收敛到 wallet 发出的事件；游戏身份由 PWA 解析后透传