feat: 添加实时广播功能，支持风险预警、玩法切换和赔率更新，增强大厅公共频道的广播能力

app/Events/BalanceUpdateBroadcast.php

@@ -0,0 +1,69 @@
+<?php
+
+namespace App\Events;
+
+use Illuminate\Broadcasting\Channel;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcastNow;
+
+/**
+ * 界面文档 §2.1：`balance.update` —— 钱包余额变动推送。
+ *
+ * 触发时机：转入/转出/下注/派彩等导致余额变动时。
+ * 前端处理：更新余额显示 + Toast 提示。
+ */
+final class BalanceUpdateBroadcast implements ShouldBroadcastNow
+{
+    use Dispatchable, InteractsWithSockets, SerializesModels;
+
+    /**
+     * @param  int  $playerId  玩家 ID（用于频道隔离）
+     * @param  string  $currencyCode  币种代码
+     * @param  int  $balanceMinor  最新余额（最小货币单位）
+     * @param  int  $changeMinor  变动金额（最小货币单位，正数为增加，负数为减少）
+     * @param  string  $reason  变动原因：transfer_in, transfer_out, bet, prize, refund
+     * @param  int  $emittedAtMs  发送时间戳（毫秒）
+     */
+    public function __construct(
+        public readonly int $playerId,
+        public readonly string $currencyCode,
+        public readonly int $balanceMinor,
+        public readonly int $changeMinor,
+        public readonly string $reason,
+        public readonly int $emittedAtMs,
+    ) {}
+
+    /**
+     * 使用私有频道，只有指定玩家能收到自己的余额变动。
+     *
+     * @return array<int, Channel>
+     */
+    public function broadcastOn(): array
+    {
+        return [new Channel('player.'.$this->playerId)];
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'balance.update';
+    }
+
+    /**
+     * @return array{player_id: int, currency_code: string, balance_minor: int, balance_formatted: string, change_minor: int, change_formatted: string, reason: string, emitted_at_ms: int}
+     */
+    public function broadcastWith(): array
+    {
+        return [
+            'player_id' => $this->playerId,
+            'currency_code' => $this->currencyCode,
+            'balance_minor' => $this->balanceMinor,
+            'balance_formatted' => number_format($this->balanceMinor / 100, 2),
+            'change_minor' => $this->changeMinor,
+            'change_formatted' => ($this->changeMinor > 0 ? '+' : '').number_format($this->changeMinor / 100, 2),
+            'reason' => $this->reason,
+            'emitted_at_ms' => $this->emittedAtMs,
+        ];
+    }
+}

app/Events/OddsUpdateBroadcast.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Events;
+
+use Illuminate\Broadcasting\Channel;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcastNow;
+
+/**
+ * 界面文档 §2.1：`odds.update` —— 赔率变更推送。
+ *
+ * 触发时机：后台发布新赔率版本时。
+ * 前端处理：Toast 提示用户赔率已更新，建议重新预览注单。
+ */
+final class OddsUpdateBroadcast implements ShouldBroadcastNow
+{
+    use Dispatchable, InteractsWithSockets, SerializesModels;
+
+    /**
+     * @param  int  $versionId  新版本 ID
+     * @param  string  $versionName  版本名称/描述
+     * @param  array<string, mixed>|null  $diff  差异数据（哪些玩法赔率变化了，可选）
+     * @param  int  $emittedAtMs  发送时间戳（毫秒）
+     */
+    public function __construct(
+        public readonly int $versionId,
+        public readonly string $versionName,
+        public readonly ?array $diff,
+        public readonly int $emittedAtMs,
+    ) {}
+
+    /**
+     * 公共频道，所有在大厅的玩家都能收到。
+     *
+     * @return array<int, Channel>
+     */
+    public function broadcastOn(): array
+    {
+        return [new Channel('lottery-hall')];
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'odds.update';
+    }
+
+    /**
+     * @return array{version_id: int, version_name: string, diff: array<string, mixed>|null, message: string, emitted_at_ms: int}
+     */
+    public function broadcastWith(): array
+    {
+        return [
+            'version_id' => $this->versionId,
+            'version_name' => $this->versionName,
+            'diff' => $this->diff,
+            'message' => '赔率已更新，请重新预览注单',
+            'emitted_at_ms' => $this->emittedAtMs,
+        ];
+    }
+}

app/Events/PlayToggleBroadcast.php

@@ -0,0 +1,62 @@
+<?php
+
+namespace App\Events;
+
+use Illuminate\Broadcasting\Channel;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcastNow;
+
+/**
+ * 界面文档 §2.1：`play.toggle` —— 玩法开关变更推送。
+ *
+ * 触发时机：后台开启或关闭某玩法时。
+ * 前端处理：玩法列显示/隐藏或置灰/启用。
+ */
+final class PlayToggleBroadcast implements ShouldBroadcastNow
+{
+    use Dispatchable, InteractsWithSockets, SerializesModels;
+
+    /**
+     * @param  string  $playCode  玩法代码（如 straight_4d, box_2d 等）
+     * @param  bool  $enabled  是否启用
+     * @param  string|null  $reason  变更原因（可选）
+     * @param  int  $emittedAtMs  发送时间戳（毫秒）
+     */
+    public function __construct(
+        public readonly string $playCode,
+        public readonly bool $enabled,
+        public readonly ?string $reason,
+        public readonly int $emittedAtMs,
+    ) {}
+
+    /**
+     * 公共频道，所有在大厅的玩家都能收到。
+     *
+     * @return array<int, Channel>
+     */
+    public function broadcastOn(): array
+    {
+        return [new Channel('lottery-hall')];
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'play.toggle';
+    }
+
+    /**
+     * @return array{play_code: string, enabled: bool, reason: string|null, action: string, emitted_at_ms: int}
+     */
+    public function broadcastWith(): array
+    {
+        return [
+            'play_code' => $this->playCode,
+            'enabled' => $this->enabled,
+            'reason' => $this->reason,
+            'action' => $this->enabled ? 'enabled' : 'disabled',
+            'emitted_at_ms' => $this->emittedAtMs,
+        ];
+    }
+}

app/Events/RiskSoldOutBroadcast.php

@@ -0,0 +1,61 @@
+<?php
+
+namespace App\Events;
+
+use Illuminate\Broadcasting\Channel;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcastNow;
+
+/**
+ * 界面文档 §2.1：`risk.sold_out` —— 号码赔付池耗尽推送。
+ *
+ * 触发时机：某号码的风险池额度被完全占用时。
+ * 前端处理：该号码的玩法格子标记为售罄（置灰或禁用）。
+ */
+final class RiskSoldOutBroadcast implements ShouldBroadcastNow
+{
+    use Dispatchable, InteractsWithSockets, SerializesModels;
+
+    /**
+     * @param  int  $drawId  期号 ID
+     * @param  string  $drawNo  期号编号（如 20260101-001）
+     * @param  string  $normalizedNumber  标准化后的 4 位号码
+     * @param  int  $emittedAtMs  发送时间戳（毫秒）
+     */
+    public function __construct(
+        public readonly int $drawId,
+        public readonly string $drawNo,
+        public readonly string $normalizedNumber,
+        public readonly int $emittedAtMs,
+    ) {}
+
+    /**
+     * 公共频道，所有在大厅的玩家都能收到。
+     *
+     * @return array<int, Channel>
+     */
+    public function broadcastOn(): array
+    {
+        return [new Channel('lottery-hall')];
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'risk.sold_out';
+    }
+
+    /**
+     * @return array{draw_id: int, draw_no: string, normalized_number: string, emitted_at_ms: int}
+     */
+    public function broadcastWith(): array
+    {
+        return [
+            'draw_id' => $this->drawId,
+            'draw_no' => $this->drawNo,
+            'normalized_number' => $this->normalizedNumber,
+            'emitted_at_ms' => $this->emittedAtMs,
+        ];
+    }
+}

app/Events/RiskWarningBroadcast.php

@@ -0,0 +1,66 @@
+<?php
+
+namespace App\Events;
+
+use Illuminate\Broadcasting\Channel;
+use Illuminate\Queue\SerializesModels;
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Broadcasting\InteractsWithSockets;
+use Illuminate\Contracts\Broadcasting\ShouldBroadcastNow;
+
+/**
+ * 界面文档 §2.1：`risk.warning` —— 号码赔付池占用超 80% 预警推送。
+ *
+ * 触发时机：某号码的风险池占用比例超过阈值（默认 80%）时。
+ * 前端处理：该号码的玩法格子显示预警样式（如黄色边框或图标）。
+ */
+final class RiskWarningBroadcast implements ShouldBroadcastNow
+{
+    use Dispatchable, InteractsWithSockets, SerializesModels;
+
+    /**
+     * @param  int  $drawId  期号 ID
+     * @param  string  $drawNo  期号编号
+     * @param  string  $normalizedNumber  标准化后的 4 位号码
+     * @param  float  $usageRatio  占用比例（0-1 之间，如 0.85 表示 85%）
+     * @param  int  $emittedAtMs  发送时间戳（毫秒）
+     */
+    public function __construct(
+        public readonly int $drawId,
+        public readonly string $drawNo,
+        public readonly string $normalizedNumber,
+        public readonly float $usageRatio,
+        public readonly int $emittedAtMs,
+    ) {}
+
+    /**
+     * 公共频道，所有在大厅的玩家都能收到。
+     *
+     * @return array<int, Channel>
+     */
+    public function broadcastOn(): array
+    {
+        return [new Channel('lottery-hall')];
+    }
+
+    public function broadcastAs(): string
+    {
+        return 'risk.warning';
+    }
+
+    /**
+     * @return array{draw_id: int, draw_no: string, normalized_number: string, usage_ratio: float, usage_percent: int, warning_threshold: float, emitted_at_ms: int}
+     */
+    public function broadcastWith(): array
+    {
+        return [
+            'draw_id' => $this->drawId,
+            'draw_no' => $this->drawNo,
+            'normalized_number' => $this->normalizedNumber,
+            'usage_ratio' => round($this->usageRatio, 4),
+            'usage_percent' => (int) round($this->usageRatio * 100),
+            'warning_threshold' => 0.8, // 80% 阈值
+            'emitted_at_ms' => $this->emittedAtMs,
+        ];
+    }
+}

app/Services/Draw/LotteryHallRealtimeBroadcaster.php

@@ -2,12 +2,18 @@
 
 namespace App\Services\Draw;
 
+use App\Events\OddsUpdateBroadcast;
+use App\Events\PlayToggleBroadcast;
+use App\Events\RiskSoldOutBroadcast;
+use App\Events\RiskWarningBroadcast;
 use App\Events\DrawCountdownBroadcast;
 use App\Events\DrawStatusChangeBroadcast;
 use App\Events\DrawResultPublishedBroadcast;
 
 /**
- * 对齐界面文档 §2.1：`draw.countdown`、`draw.status_change`、`result.published`（频道 `lottery-hall`）。
+ * 对齐界面文档 §2.1：大厅公共频道广播（`lottery-hall`）。
+ * 包含：draw.countdown、draw.status_change、result.published、
+ *       risk.sold_out、risk.warning、play.toggle、odds.update
  */
 final class LotteryHallRealtimeBroadcaster
 {
@@ -66,6 +72,67 @@ final class LotteryHallRealtimeBroadcaster
         broadcast(new DrawResultPublishedBroadcast($data, (int) floor(microtime(true) * 1000)));
     }
 
+    /** `risk.sold_out` —— 号码赔付池耗尽 */
+    public function notifyRiskSoldOut(int $drawId, string $drawNo, string $normalizedNumber): void
+    {
+        if (! $this->driverSupportsRealtime()) {
+            return;
+        }
+
+        broadcast(new RiskSoldOutBroadcast(
+            $drawId,
+            $drawNo,
+            $normalizedNumber,
+            (int) floor(microtime(true) * 1000),
+        ));
+    }
+
+    /** `risk.warning` —— 号码赔付池占用超 80% 预警 */
+    public function notifyRiskWarning(int $drawId, string $drawNo, string $normalizedNumber, float $usageRatio): void
+    {
+        if (! $this->driverSupportsRealtime()) {
+            return;
+        }
+
+        broadcast(new RiskWarningBroadcast(
+            $drawId,
+            $drawNo,
+            $normalizedNumber,
+            $usageRatio,
+            (int) floor(microtime(true) * 1000),
+        ));
+    }
+
+    /** `play.toggle` —— 玩法开关变更 */
+    public function notifyPlayToggle(string $playCode, bool $enabled, ?string $reason = null): void
+    {
+        if (! $this->driverSupportsRealtime()) {
+            return;
+        }
+
+        broadcast(new PlayToggleBroadcast(
+            $playCode,
+            $enabled,
+            $reason,
+            (int) floor(microtime(true) * 1000),
+        ));
+    }
+
+    /** `odds.update` —— 赔率变更 */
+    public function notifyOddsUpdate(int $versionId, string $versionName, ?array $diff = null): void
+    {
+        if (! $this->driverSupportsRealtime()) {
+            return;
+        }
+
+        broadcast(new OddsUpdateBroadcast(
+            $versionId,
+            $versionName,
+            $diff,
+            (int) floor(microtime(true) * 1000),
+        ));
+    }
+
     private function driverSupportsRealtime(): bool
     {
         $default = config('broadcasting.default');

app/Services/PlayerRealtimeBroadcaster.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\Services;
+
+use App\Events\BalanceUpdateBroadcast;
+
+/**
+ * 玩家私有频道实时广播。
+ *
+ * 对齐界面文档 §2.1：balance.update（频道 `player.{id}`）。
+ * 注意：玩家私有频道广播与大厅公共频道分开管理。
+ */
+final class PlayerRealtimeBroadcaster
+{
+    /** `balance.update` —— 钱包余额变动 */
+    public function notifyBalanceUpdate(
+        int $playerId,
+        string $currencyCode,
+        int $balanceMinor,
+        int $changeMinor,
+        string $reason,
+    ): void {
+        if (! $this->driverSupportsRealtime()) {
+            return;
+        }
+
+        broadcast(new BalanceUpdateBroadcast(
+            $playerId,
+            $currencyCode,
+            $balanceMinor,
+            $changeMinor,
+            $reason,
+            (int) floor(microtime(true) * 1000),
+        ));
+    }
+
+    private function driverSupportsRealtime(): bool
+    {
+        $default = config('broadcasting.default');
+        if ($default === null || $default === 'null') {
+            return false;
+        }
+
+        $driver = config("broadcasting.connections.{$default}.driver") ?? $default;
+
+        return ! in_array($driver, ['null', 'log'], true);
+    }
+}