1.ws优化bet.win订阅

docs/36字花-数据库与实施计划.md

@@ -109,9 +109,12 @@
 | `streak_win_reward` | JSON：`rows[]` 每项含 `streak`（1～10）、`odds_factor`（与 33 相乘为整段赔率）、`is_jackpot`（是否大奖）。派彩公式：`total_amount × odds_factor × 33`。默认第 10 档 `is_jackpot=true`。 |
 | `deposit_tier` | 仍由「充值档位」独立菜单维护，**不出现在**「常规配置」列表。 |
 
-开奖结算后更新 **`user.current_streak`**：本期有中奖注单则 `min(streak_at_bet+1, 10)`，否则 **连胜归 0**（无档位配置）。**中奖 WebSocket（同一结算时刻）**：
-- 向相关用户推送 **`bet.win`**（小奖/大奖统一；`data.is_jackpot` 标记是否大奖档；含 `total_win`、`balance_after`、`bets[]` 等）。
-- 若存在大奖档命中，**再**向公共频道推送 **`jackpot.hit`**（`hits[]` 每项含 `user_id`、**`nickname`**（昵称优先、空则 fallback 到 username）、`period_no`、`total_win`、`result_number`），供全站公告；移动端个人弹窗以 **`bet.win`** 为准。
+开奖结算后更新 **`user.current_streak`**：本期有中奖注单则 `min(streak_at_bet+1, 10)`，否则 **连胜归 0**（无档位配置）。**中奖 WebSocket（同一结算批次）**（实现：`GameBetSettleService::publishSettlementWinsAfterCommit`）：
+- 向相关用户推送 **`bet.win`**（小奖/大奖统一；**个人中奖弹窗只认此主题**）。载荷含 `total_win`、`balance_after`、`bets[]`、`is_win=true`，并合并 `current_streak` / `streak_level` / `odds_factor` / **`is_jackpot`**（是否**大奖档**，由 `streak_at_bet` 对应 `streak_win_reward.is_jackpot` 决定，非 `bet.accepted` 的下注时展示含义）。
+- 若存在大奖档命中，**再**向公共频道推送 **`jackpot.hit`**（`hits[]` 每项含 `user_id`、**`nickname`**、`period_no`、`total_win`、`result_number`），供全站跑马灯；**个人弹窗仍以 `bet.win` 为准**。
+- **去重**：`user.streak` / `wallet.changed` / `jackpot.hit` 使用 `dfw:v1:settle:notify:{period_id}`；**`bet.win` 独立** `dfw:v1:ws:betwin:{period_id}:{user_id}`，避免整期 dedup 吞掉中奖推送。
+- **补偿**：库内已结算中奖但内存未聚合时，从 `bet_order` 重建并补发；运维可用 `php scripts/republish_bet_win.php`（见移动端草案 §7.1.4）。
+- **大奖审核**：`win_amount >= jackpot_max_amount` 时注单可先 `status=待审核`，仍推 `bet.win`；后台审核通过后再推一次 `bet.win`（`approveJackpot`）。
 
 > **派彩期间 `period.tick` 静默规则**：开奖到派彩宽限期结束（`status=payouting`）期间**不再推送 `period.tick`**，避免覆盖中奖动画；本期进入 `finished`/`void` 时各推一帧边界帧（每期号每状态去重，Redis Key `dfw:v1:ws:tick:boundary:{period_no}:{status}`，TTL 300s），下一期 `betting` 时恢复每秒推送。详见《36字花-移动端接口设计草案》§7.1.3。
 
@@ -282,6 +285,21 @@
 | 后台快照 `maintenance_ui` | `!game_live_runtime_enabled && !hasActiveRecord()` 时为 `true`：表示**当局已完全结束**（含派彩），此时后台页展示「维护中」并锁定操作区（仅顶部「游戏运行」开关可用）；当局尚在 0–3 状态时为 `false`，倒计时与操作区保持可用直至收尾完成 |
 | 作废本局（后台按钮） | 仅当本期为 **下注开放 / 已封盘**（`game_record.status` 为 `0` 或 `1`）：将所有 **待开奖** 注单（`bet_order.status = 1`）按 `total_amount` 退回余额并置 `bet_order.status = 3`，写钱包流水 `biz_type = bet_void`；本期 **`game_record.status = 5`**，写入 **`void_reason`**；并 **强制将 `game_live_runtime_enabled` 置为 `0`**。需管理员在后台再次打开「游戏运行」开关后，才恢复下注与后续期次创建 |
 | 后台接口 | `POST /admin/game.Live/runtime`（body：`enabled` 0/1）；`POST /admin/game.Live/voidPeriod`（body：`record_id` 可选、`void_reason` 必填） |
+| 实时快照 HTTP | `GET /admin/game.Live/snapshot`：**只读** `buildSnapshot`，不执行 `recoverLiveRoundState`，避免接口超时；对局自愈/自动开奖由 **`gameLiveTicker`**（每秒 `publishSnapshot`）与 `drawResult` 链路负责 |
+| WebSocket | `GET /admin/game.Live/wsConfig` 返回 `ws_url` 与推荐 `subscribe_topics`（含 `admin.live.snapshot`、`bet.win` 等）；`admin.live.snapshot` 由 WS 进程每秒直推（有订阅者时） |
+| WS 地址 | `WebSocketConfigHelper`：`.env` 中 `H5_WEBSOCKET_URL` 为 `127.0.0.1` 且请求 Host 非本机时自动改用 `ws(s)://{host}/ws/`；生产需 Nginx 将 `/ws/` 反代至 **3131** |
+
+#### 8.2.2 WebSocket 主题与 `bet.win`（联调清单）
+
+| 主题 | 触发 | 移动端 |
+|------|------|--------|
+| `bet.accepted` | 下注成功 | 扣款确认；`is_jackpot` 为下注时档位 |
+| `bet.win` | 开奖结算后中奖 | **中奖弹窗**；`is_jackpot` 为大奖档 |
+| `jackpot.hit` | 本期有大奖档命中 | 全站公告（可选） |
+| `wallet.changed` | 余额变动 | 含 `biz_type=payout` 派彩 |
+| `user.streak` | 每期结算后 | 连胜更新 |
+
+详见《36字花-移动端接口设计草案》§7.1.3、§7.1.4。
 
 ### 8.3 代理与结算（逻辑就绪后）
 

docs/36字花-移动端接口设计草案.md

@@ -760,7 +760,7 @@
 以下与代码 `app/process/GameWebSocketServer.php`、`config/process.php`、`app/common/library/admin/WebSocketConfigHelper.php` 一致，**文档此前未写明的条件**在此补齐：
 
 - **独立进程**：需在运行环境中启动 Webman 自定义进程 **`gameWebSocketServer`**（见 `config/process.php`），默认监听 **`H5_WEBSOCKET_LISTEN`**（缺省为 `websocket://0.0.0.0:3131`）。未启动进程则客户端无法建连或立刻断线。
-- **连接 URL**：优先使用环境变量 **`H5_WEBSOCKET_URL`**（完整 `ws://` / `wss://` 地址，建议带路径，如 `.env-example` 所示）。未配置时，后台 **`GET /admin/test.GameCurrentStatus/wsConfig`**（及游戏实时页同类接口）会通过 `WebSocketConfigHelper` 按当前请求的 `Host` / `X-Forwarded-*` 推导 `ws(s)://{host}/ws/`，本地兜底 **`ws://127.0.0.1:3131/ws/`**。
+- **连接 URL**：优先使用环境变量 **`H5_WEBSOCKET_URL`**（完整 `ws://` / `wss://` 地址，建议带路径，如 `.env-example` 所示）。**生产环境勿将 `H5_WEBSOCKET_URL` 配成 `127.0.0.1` / `localhost`**：浏览器无法访问服务端本机地址。若 `.env` 中为回环地址且 HTTP 请求来自外网域名，`WebSocketConfigHelper` 会**忽略该配置**，改按当前请求的 `Host` / `X-Forwarded-*` 推导 `ws(s)://{host}/ws/`。未配置时，后台 **`GET /admin/test.GameCurrentStatus/wsConfig`**、**`GET /admin/game.Live/wsConfig`** 等同理；本地兜底 **`ws://127.0.0.1:3131/ws/`**。HTTPS 站点需在 Nginx 等反向代理将 **`/ws/`** 转发至 `gameWebSocketServer` 监听端口（默认 **3131**）。
 - **移动端配置缺口**：**`POST /api/game/lobbyInit` 当前不下发 WebSocket 地址**；H5 需与运维约定同一套 `H5_WEBSOCKET_URL`（打包进前端配置、远程配置中心等），与 HTTP API 基址可不同域。
 - **混合内容**：若 H5 页面为 **HTTPS**，浏览器要求 WebSocket 使用 **`wss://`**，否则会被拦截。
 - **事件投递依赖 Redis**：HTTP 侧业务通过 **`GameWebSocketEventBus`**（Redis 列表）将事件投递到 WebSocket 进程；Redis 不可用或队列异常时，**除 `admin.live.snapshot` 外**的广播类推送可能收不到。后台若订阅了 `admin.live.snapshot`，服务端有**每秒直连构建快照**的兜底，不依赖队列。
@@ -819,7 +819,8 @@
   - `data.streak_level`：int
   - `data.odds_factor`：int
   - `data.is_jackpot`：bool
-- **`wallet.changed` / `bet.accepted`**：在原有字段上合并同上 **`current_streak`**、**`streak_level`**、**`odds_factor`**、**`is_jackpot`**；客户端按 `user_id` 过滤，仅处理本用户
+- **`wallet.changed` / `bet.accepted` / `bet.win`**：在原有字段上合并同上 **`current_streak`**、**`streak_level`**、**`odds_factor`**、**`is_jackpot`**；客户端按 `user_id` 过滤，仅处理本用户。
+- **`bet.accepted` 与 `bet.win` 的 `is_jackpot` 区别**：`bet.accepted` 表示**下注时**本笔适用档位是否大奖档（赔率展示）；**开奖中奖通知以 `bet.win` 为准**，其 `is_jackpot` 表示**结算时**该用户中奖注单是否含大奖档（`streak_at_bet` 对应 `streak_win_reward.is_jackpot=true`，通常为第 10 档）。
 
 #### 7.1.3 推送频率与触发规则（当前实现）
 
@@ -834,15 +835,20 @@
 - `admin.live.snapshot`：**每秒一次**（后台实时对局页全量快照；不受派彩静默期影响）。
 - `period.opened` / `period.payout` / `admin.live.opened`：按开奖流程阶段触发（事件触发型，非固定频率）。
 - `wallet.changed`：仅在余额发生变更时推送（如下注扣款、充值入账、派彩入账）。派彩时 `biz_type=payout`，并带 `amount`（本次派彩金额）、`period_no`、`period_id`、`result_number`（若有）。
-- **`bet.win`（本期中奖，小奖/大奖统一）**：开奖结算后，**凡本期有中奖的用户**均按用户聚合推送一帧（与 `wallet.changed(payout)` 同一结算时刻）；客户端**统一监听此事件**做中奖弹窗/横幅，用 `data.is_jackpot` 区分展示样式。
+- **`bet.win`（本期中奖，小奖/大奖统一）**：开奖结算后，**凡本期有中奖的用户**均按用户聚合推送一帧（与 `wallet.changed(payout)` 同一结算批次）；**个人中奖弹窗/横幅统一监听此主题**，用 `data.is_jackpot` 区分普通档与大奖档样式。**中大奖档用户同样会收到 `bet.win`**，无需仅依赖 `jackpot.hit`。
   - `data.user_id` / `data.period_id` / `data.period_no` / `data.result_number`
-  - `data.total_win`：本期该用户派彩合计（已结算入账部分；待审核大奖可能尚未入账，但仍会推送本事件）
+  - `data.total_win`：本期该用户派彩合计（已入账部分；若触发**后台大奖审核**（`win_amount >= game_config.jackpot_max_amount`）且注单为待审核，可能尚未入账，但仍会推送本事件）
   - `data.balance_after`：推送时用户余额（已派彩则为派彩后余额）
   - `data.bets[]`：`{ bet_id, win_amount }` 明细
-  - **`data.is_jackpot`**：`bool`，`true` 表示该用户本注适用档位为大奖（`streak_win_reward` 对应档 `is_jackpot=true`），`false` 为普通档
+  - **`data.is_jackpot`**：`bool`，`true` 表示该用户本期中奖注单含**大奖档**（`streak_win_reward` 中 `is_jackpot=true` 的档位，与下注时 `streak_at_bet` 对应），`false` 为普通档
+  - **`data.is_win`**：`bool`，固定为 `true`（便于与 `user.streak` 的 `extra.is_win` 对齐）
+  - **合并赔率字段**（与 §7.1.2A 一致）：`current_streak`、`streak_level`、`odds_factor`、`is_jackpot`
   - `data.server_time`：Unix 秒
-- **`jackpot.hit`（公共大奖广播，补充）**：在 **`bet.win` 之后**（同一结算批次内），若本期存在**大奖档命中**用户，**额外**向公共频道推送一帧，供全站公告/跑马灯；无大奖命中则不推送。
-  - **推送顺序**：先 `bet.win`（按用户，含 `is_jackpot`）→ 再 `jackpot.hit`（仅大奖）
+  - **服务端去重**：Redis Key `dfw:v1:ws:betwin:{period_id}:{user_id}`（TTL 86400s），**每期每用户至多推送一次**；与 `user.streak` / `wallet.changed` 的整期去重键 `dfw:v1:settle:notify:{period_id}` **分离**，避免后者先占位导致 `bet.win` 被吞。
+  - **补偿**：若内存聚合 `bet_wins` 为空但库内已有本期已结算中奖注单，结算服务会从库重建载荷并补发（`buildBetWinPayloadsFromSettledOrders`）。
+  - **大奖审核通过后**：后台 `approveJackpot` 会再次向该用户推送 `bet.win`（入账后）。
+- **`jackpot.hit`（公共大奖广播，补充）**：在 **`bet.win` 之后**（同一结算批次内），若本期存在**大奖档命中**用户，**额外**向公共频道推送一帧，供全站公告/跑马灯；无大奖命中则不推送。**个人弹窗仍以 `bet.win` 为主**；`jackpot.hit` 用于全站展示昵称与金额。
+  - **推送顺序**：先 `bet.win`（按用户，含 `is_jackpot`）→ 再 `jackpot.hit`（仅大奖档）
   - **载荷字段**：`period_id` / `period_no` / `result_number` / `hits[]` / `server_time`。
   - `hits[]` 数组每项字段：
     - `user_id`：int（中奖用户 ID）
@@ -851,11 +857,31 @@
     - `total_win`：string（本期该用户的命中大奖派彩合计，金额字符串）
     - `result_number`：int
 
+#### 7.1.4 结算推送去重与运维补发（2026-05）
+
+| Redis Key | 作用 |
+|-----------|------|
+| `dfw:v1:settle:notify:{period_id}` | 整期 `user.streak` / `wallet.changed`（结算批次内）/ `jackpot.hit` 仅推一次 |
+| `dfw:v1:ws:betwin:{period_id}:{user_id}` | 该用户本期 `bet.win` 仅推一次（与上表独立） |
+
+**运维补发**（已结算中奖但客户端未收到 `bet.win` 时）：
+
+```bash
+php scripts/republish_bet_win.php --play-record-id=1370
+php scripts/republish_bet_win.php --period-id=123
+php scripts/republish_bet_win.php --period-no=20260526-183418-c9c90ef1
+# 强制忽略 dedup 再推：加 --force
+```
+
+联调脚本：`php scripts/verify_ws_topic_subscribe.php`（含 `bet.win` 入队/订阅校验）。
+
 ### 7.1A 后台连接方式（管理端联调）
 
-- 后台菜单：仅保留一个菜单 `连接服务器websocket`，用于统一联调 WebSocket
-- 后台连接入口：
+- 后台菜单：`连接服务器websocket`（联调）、**`游戏管理` → `游戏实时对局`**（`/admin/game/live`，生产监控）
+- 后台 WebSocket 配置入口：
   - `/admin/test.GameCurrentStatus/wsConfig`
+  - `/admin/game.Live/wsConfig`（实时对局页自动拉取并订阅，含 `admin.live.snapshot`、`bet.win` 等）
+- **HTTP 快照**：`GET /admin/game.Live/snapshot` 为**只读**快照（`buildSnapshot`），**不在此接口执行** `recoverLiveRoundState` / 自动开奖，避免请求超时；对局推进由进程 **`gameLiveTicker`** 与开奖流程负责。
 - 后台页面能力：
   - 读取 `ws_url`、`connect_tip`、`sample_messages`
   - 手动连接/断开 WebSocket
@@ -881,9 +907,9 @@
 1. `GET /api/v1/authToken?secret=xxx&timestamp=xxx&device_id=xxx&signature=xxx` 获取 `auth-token`
 2. `POST /api/user/login` 登录（请求头带 `auth-token`）
 3. `POST /api/game/lobbyInit` 拉首页初始化（请求头带 `auth-token`）
-4. 取得 WebSocket 基址（**当前非 lobbyInit 下发**：与运维/打包配置中的 `H5_WEBSOCKET_URL` 或自建配置接口一致）后建立 WebSocket 连接，**立即发送 `subscribe`** 监听状态流（见 §7.0 / §7.1）
+4. 取得 WebSocket 基址（**当前非 lobbyInit 下发**：与运维/打包配置中的 `H5_WEBSOCKET_URL` 或自建配置接口一致）后建立 WebSocket 连接，**立即发送 `subscribe`** 监听状态流（见 §7.0 / §7.1；**务必包含 `bet.win`**）
 5. 用户下注调用 `POST /api/game/placeBet`
-6. 下单后以 `placeBet.balance_after` 与 `wallet.changed` 同步余额
+6. 下单后以 `placeBet.balance_after` 与 `wallet.changed` 同步余额；开奖结算后监听 **`bet.win`**（`data.user_id` 为本用户且 `is_win=true`）展示中奖，大奖档看 `data.is_jackpot`
 7. 断线或页面回前台时，重连 WebSocket 并重新订阅主题回补实时状态
 
 ## 8.2 充值到下注到提现闭环
@@ -915,7 +941,7 @@ flowchart TD
   E --> F[等待 wallet.changed 同步余额]
   D -- 否 --> G[进入封盘与开奖阶段]
   G --> H[服务端算票与开奖]
-  H --> I[WebSocket 推送状态变化]
+  H --> I[WebSocket: period.opened / bet.win / wallet.changed 等]
   I --> J[断线重连并重新订阅]
   J --> C
 ```