From 730574a2e25224cf8c304c31d327c094e399f641 Mon Sep 17 00:00:00 2001
From: joywayer <joywaygames@163.com>
Date: Sun, 21 Jun 2026 23:52:23 +0800
Subject: [PATCH] =?UTF-8?q?Phase=201.3=EF=BC=9ASandboxPaths=20=E7=BB=9F?=
 =?UTF-8?q?=E4=B8=80=E6=B2=99=E7=9B=92=20/=20Bundle=20/=20H5=20=E8=B7=AF?=
 =?UTF-8?q?=E5=BE=84=E5=85=A5=E5=8F=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

集中管理 NSSearchPathFor... 调用，避免散落，方便后续 ResourceUnzipper
（Phase 1.5）与 WebView 加载（Phase 1.10）复用。

- 新增 ylgamehall/Source/Resource/SandboxPaths.swift
  - 基础：caches / documents / bundle
  - 大厅 H5：lobbyRoot / lobbyIndex / lobbyVersionXML（基于 BundleConfig
    当前渠道值动态拼接）
  - 子游戏 H5：subGameRoot(_:) / subGameIndex(_:_:)（Phase 6 调用，
    入参传 SwitchOverGameData 解出的 dir/start）
  - 全部 enum + static，无状态，Swift 6 严格并发零负担
- RootViewController.viewDidLoad 补 SandboxPaths 烟雾打印 6 项路径，
  便于首次启动 console 校验：
  - lobbyIndex 应为 {Caches}/FtJf073.../gamehall/index.html
  - lobbyVersionXML 应为 {Caches}/FtJf073.../gamehall/version.xml
- BuildProject 通过，synchronized group 自动收编新文件
---
 ylgamehall/RootViewController.swift           | 11 +++
 ylgamehall/Source/Resource/SandboxPaths.swift | 71 +++++++++++++++++++
 2 files changed, 82 insertions(+)
 create mode 100644 ylgamehall/Source/Resource/SandboxPaths.swift

diff --git a/ylgamehall/RootViewController.swift b/ylgamehall/RootViewController.swift
index d2018e8..b868e6c 100644
--- a/ylgamehall/RootViewController.swift
+++ b/ylgamehall/RootViewController.swift
@@ -29,6 +29,17 @@ final class RootViewController: UIViewController {
           other        = "\(cfg.other)"
           appleConfig  = "\(cfg.appleConfig)"
         """)
+
+        // Phase 1.3 烟雾测试：打印 SandboxPaths 计算路径
+        print("""
+        [SandboxPaths] 路径计算结果:
+          caches          = \(SandboxPaths.caches.path)
+          documents       = \(SandboxPaths.documents.path)
+          bundle          = \(SandboxPaths.bundle.path)
+          lobbyRoot       = \(SandboxPaths.lobbyRoot.path)
+          lobbyIndex      = \(SandboxPaths.lobbyIndex.path)
+          lobbyVersionXML = \(SandboxPaths.lobbyVersionXML.path)
+        """)
     }
 
     override var supportedInterfaceOrientations: UIInterfaceOrientationMask {
diff --git a/ylgamehall/Source/Resource/SandboxPaths.swift b/ylgamehall/Source/Resource/SandboxPaths.swift
new file mode 100644
index 0000000..ff45e2a
--- /dev/null
+++ b/ylgamehall/Source/Resource/SandboxPaths.swift
@@ -0,0 +1,71 @@
+//
+//  SandboxPaths.swift
+//  ylgamehall
+//
+//  集中管理沙盒与 Bundle 路径，避免散落 NSSearchPathFor...。
+//  详见 docs/H5-Native-Implementation-Design.md §7.1。
+//
+
+import Foundation
+
+/// 沙盒、Bundle、H5 资源路径的统一入口。所有 ResourceUnzipper / WebView 加载
+/// 等模块通过此命名空间获取路径，禁止重新写 `urls(for:in:)` 等散落调用。
+public enum SandboxPaths {
+
+    // MARK: - 基础沙盒目录
+
+    /// `Library/Caches/`（系统空间不足时可能被清，需可重建）
+    public static var caches: URL {
+        FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)[0]
+    }
+
+    /// `Documents/`（用户级持久化，iCloud 备份）
+    public static var documents: URL {
+        FileManager.default.urls(for: .documentDirectory, in: .userDomainMask)[0]
+    }
+
+    /// `<App>.app/`
+    public static var bundle: URL {
+        Bundle.main.bundleURL
+    }
+
+    // MARK: - 大厅 H5 路径（基于 BundleConfig.shared 的当前渠道）
+
+    /// 大厅 H5 解压根目录：`{Caches}/{gamedir}/`
+    public static var lobbyRoot: URL {
+        caches.appendingPathComponent(BundleConfig.shared.gameDir)
+    }
+
+    /// 大厅 H5 入口 HTML：`{Caches}/{gamedir}/{gamestart}/index.html`
+    public static var lobbyIndex: URL {
+        let cfg = BundleConfig.shared
+        return caches
+            .appendingPathComponent(cfg.gameDir)
+            .appendingPathComponent(cfg.gameStart)
+            .appendingPathComponent("index.html")
+    }
+
+    /// 大厅 H5 版本标记文件：`{Caches}/{gamedir}/{gamestart}/version.xml`
+    /// 由 ResourceUnzipper 判断是否需要解压初始 gamehall.zip。
+    public static var lobbyVersionXML: URL {
+        let cfg = BundleConfig.shared
+        return caches
+            .appendingPathComponent(cfg.gameDir)
+            .appendingPathComponent(cfg.gameStart)
+            .appendingPathComponent("version.xml")
+    }
+
+    // MARK: - 子游戏 H5 路径（参数化，由 SwitchOverGameData 传入）
+
+    /// 子游戏 H5 解压根目录：`{Caches}/{dir}/`
+    public static func subGameRoot(_ dir: String) -> URL {
+        caches.appendingPathComponent(dir)
+    }
+
+    /// 子游戏 H5 入口 HTML：`{Caches}/{dir}/{start}/index.html`
+    public static func subGameIndex(_ dir: String, _ start: String) -> URL {
+        caches.appendingPathComponent(dir)
+              .appendingPathComponent(start)
+              .appendingPathComponent("index.html")
+    }
+}