Phase 6 commit C：backgameData pop + getWebdata 反向 callback

- 新增 Source/Bridge/Handlers/BackGameDataHandler.swift（仅 SubGameViewController 注册）：
  - 调 AudioPlayer.stopAllBackground 停背景音
  - AppCoordinator.popSubGame(returningData:) → popViewController + 发 .subGameDidReturn
  - data 兼容 string / object（非字符串走 JSONSerialization 序列化透传）
  - 字面 cb "backgameData"（msext gameController.m:691-709 等价，
    WXApi 清理跳过 — 微信 SDK 待 Phase 4.E）
- AudioPlayer.stopAllBackground：无条件停背景音（msext 不看 type 直接 nil 行为）
- SubGameViewController.registerBridgeHandlers：挂上 BackGameDataHandler，
  注释更新 exitRoom/getVideoinfo/createRoom 推迟到 Phase 8
- WebContainerViewController：在 setupExternalSubscriptions 挂 .subGameDidReturn
  观察者 → bridge.call("getWebdata", .string(data))，teardown 时 removeObserver
  （生命周期与 battery/network/appservice 同一对，子游戏栈顶时大厅已 teardown
  避免双发）
- Plan §5.6.3 / 6.5 / 6.6 / §8 进度已勾选

至此 SwitchOverGameData → push 子游戏 → backgameData → pop + getWebdata
完整链路接通；子游戏视频房间（exitRoom/getVideoinfo/createRoom）留待 Phase 8。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

ylgamehall/Source/Audio/AudioPlayer.swift

@@ -82,4 +82,15 @@ public final class AudioPlayer {
         backgroundType = nil
         Self.log.debug("stopBackground done type=\(type, privacy: .public)")
     }
+
+    /// 无条件停止当前背景音。子游戏 `backgameData` 退出时统一调一次
+    /// （msext gameController.m:693-697 行为：不看 type，直接 stop + nil）。
+    public func stopAllBackground() {
+        guard backgroundPlayer != nil else { return }
+        let oldType = backgroundType ?? "nil"
+        backgroundPlayer?.stop()
+        backgroundPlayer = nil
+        backgroundType = nil
+        Self.log.debug("stopAllBackground done (was type=\(oldType, privacy: .public))")
+    }
 }

ylgamehall/Source/Bridge/Handlers/BackGameDataHandler.swift

@@ -0,0 +1,51 @@
+//
+//  BackGameDataHandler.swift
+//  ylgamehall
+//
+//  H5 → Native handler：backgameData — 子游戏退出并把数据回传给大厅。
+//  契约：docs/H5-Native-Contract.md §3.1 ［18］
+//
+//  与 msext gameController.m:691-709 等价：
+//    1) 停背景音（无条件，与 stopBackground 不同 — msext 不看 type 直接 nil）
+//    2) AppCoordinator.shared.popSubGame(returningData: data)
+//       内部 popViewController + 发 .subGameDidReturn 通知，由大厅监听后
+//       回调 H5 `getWebdata` 完成反向闭环
+//    3) responseCallback("backgameData") 无论 data 是否解析成功都回（msext 字面）
+//
+//  ⚠️ 仅注册到子游戏 SubGameViewController；大厅 WebContainerViewController 不注册。
+//  H5 大厅页若误调 backgameData 会落空（bridge 无对应 handler → JS 端的 callback 直接卡），
+//  msext 同款行为 — 这是契约边界，不在原生侧兜底。
+//
+
+import Foundation
+
+public enum BackGameDataHandler {
+
+    public static func register(on bridge: any BridgeProtocol) {
+        // 【18】backgameData
+        //   入参 data（字符串，子游戏 H5 自定义透传给大厅 getWebdata）
+        //   cb: "backgameData"
+        bridge.register("backgameData") { data, callback in
+            await MainActor.run {
+                // data 可能是 string / object，统一序列化为 string（msext NSString 透传等价）。
+                // - 直接是 .string → 取字面
+                // - 其它类型 → JSON 序列化（保留对象结构传给大厅 H5）
+                let payload = serialize(data)
+                AudioPlayer.shared.stopAllBackground()
+                AppCoordinator.shared.popSubGame(returningData: payload)
+            }
+            callback?(.string("backgameData"))
+        }
+    }
+
+    private static func serialize(_ data: BridgeData?) -> String {
+        if let s = data?.asString { return s }
+        guard let data else { return "" }
+        let any = data.jsonObject
+        if let bytes = try? JSONSerialization.data(withJSONObject: any, options: [.fragmentsAllowed]),
+           let s = String(data: bytes, encoding: .utf8) {
+            return s
+        }
+        return ""
+    }
+}

ylgamehall/Source/WebView/SubGameViewController.swift

@@ -83,8 +83,10 @@ public final class SubGameViewController: UIViewController {
         // OpenurlTitleData 在子游戏中也可能调（threeView 弹层 push 自子游戏页），保留 stub
         OpenurlTitleDataHandler.register(on: bridge)
 
-        // backgameData / exitRoom / getVideoinfo / createRoom 等子游戏专属 handler
-        // 留待 commit C / 后续 Phase 接入。
+        // 子游戏专属：backgameData（退出回大厅 + 反向 callback getWebdata）
+        BackGameDataHandler.register(on: bridge)
+
+        // exitRoom / getVideoinfo / createRoom 等视频房间 handler 留待 Phase 8 接入
     }
 
     // MARK: - 摇一摇支持

ylgamehall/Source/WebView/WebContainerViewController.swift

@@ -21,6 +21,10 @@ public final class WebContainerViewController: UIViewController {
 
     private let shakeHandler = ShakeHandler()
 
+    // MARK: - .subGameDidReturn 观察者（子游戏 backgameData pop 后回大厅，反向 callback getWebdata）
+
+    private var subGameReturnObserver: NSObjectProtocol?
+
     // MARK: - Boot pipeline 内部错误分类
     //
     // 用 enum 区分"终态阻塞"与"系统级错误"：
@@ -307,6 +311,21 @@ public final class WebContainerViewController: UIViewController {
         AppLifecycleObserver.shared.onForeground = {
             bridge.call("appservice", data: .string("2"), callback: nil)
         }
+
+        // §3.2 ［12］ getWebdata — 子游戏 pop 回大厅，反向把 backgameData 入参透传给 H5
+        //   （msext NewRootVC 监听 "backgameDatatwo" 通知 → callHandler:"getWebdata" 等价）
+        // 大厅栈顶时挂钩，pop 进子游戏时由 viewWillDisappear teardown 解绑，避免双发。
+        subGameReturnObserver = NotificationCenter.default.addObserver(
+            forName: .subGameDidReturn,
+            object: nil,
+            queue: .main
+        ) { note in
+            // queue=.main 保证 closure 在主线程；显式 hop 让 Swift 6 actor 推断通过
+            let data = (note.userInfo?["data"] as? String) ?? ""
+            MainActor.assumeIsolated {
+                bridge.call("getWebdata", data: .string(data), callback: nil)
+            }
+        }
     }
 
     private func teardownExternalSubscriptions() {
@@ -319,6 +338,11 @@ public final class WebContainerViewController: UIViewController {
         NetworkMonitor.shared.onChange = nil
         AppLifecycleObserver.shared.onBackground = nil
         AppLifecycleObserver.shared.onForeground = nil
+
+        if let token = subGameReturnObserver {
+            NotificationCenter.default.removeObserver(token)
+            subGameReturnObserver = nil
+        }
     }
 
     // MARK: - Alerts (terminal / retry states)