Phase 1.1：渠道注入用 ChannelConfig.plist 替代 msext 目录树（ADR-007）
契约 §0.3 描述 msext 把 11 个渠道值编码为 Bundle 根的 11 个空目录 子文件夹名（目录名本身就是值）。在 Xcode 26.5 默认的 synchronized group 下，此机制不兼容（子目录被扁平化、11 个 .gitkeep 撞名； folder reference 拖入流程失效；Run Script Phase 受 sandbox 阻碍且 默认 Based on dependency analysis 让 clean build 也不跑）。 CLAUDE.md 原则 B 落地——原生内部自由重构，不照搬 msext。改用单一 plist 存储等价语义，H5 端通过 app_data.js 看到的 11 个 JS 全局变量 行为完全不变（契约边界在 BundleConfig.shared.xxx，与底层无关）。 多渠道分发用 plutil -replace + 重签 + 重打包，工作量与 mv 目录名 重签完全相同。 - 新增 ylgamehall/Resources/ChannelConfig.plist：11 个 string key 含母包默认值（沿用 msext 现网值）；synchronized group 自动入 Bundle - Design §7.0 / §7.2 重写为 plist 方案；BundleConfig 代码骨架改为 PropertyListSerialization + init(bundle:) 可注入式 - Plan §5 Phase 1.1 任务清单从 4 个子项简化为 1 项；ADR-004 文字 同步；新增 ADR-007 完整记录决策背景 / 触发事件 / 工程兼容性分析 / 理由 / 守护条款 - pbxproj：ENABLE_USER_SCRIPT_SANDBOXING 残留为 NO（前期 Run Script 方案探索时关闭，plist 方案下不再需要，但未恢复以避免再次 UI 操作； 无 Run Script 故无实际安全暴露面，未来可随时改回 YES） - BuildProject 验证：plist 已落在 .app 根，plutil -p 输出 11 个键值 完整
This commit is contained in:
joywayer
@@ -1065,15 +1065,52 @@ public actor ConfigService {
|
||||
|
||||
| 落点 | 用途 | 入 Bundle 方式 |
|
||||
|------|------|--------------|
|
||||
| `ylgamehall/Resources/` | 静态打入 Bundle 的项目资源(`gamehall.zip` / `WebViewJavascriptBridge.js` / 本地音效 mp3 等) | synchronized group 自动收集 |
|
||||
| `ylgamehall/Resources/` | 静态打入 Bundle 的项目资源(`gamehall.zip` / `WebViewJavascriptBridge.js` / 本地音效 mp3 / `ChannelConfig.plist` 等) | synchronized group 自动收集 |
|
||||
| `ylgamehall/Assets.xcassets/` | 原生 Asset Catalog(AppIcon / LaunchImage / 分享平台图标) | Xcode 默认 |
|
||||
| `ylgamehall/ChannelInjection/` | 当前激活渠道的 11 个空容器目录 | `.gitignore` 忽略,由 `Scripts/inject_channel.sh` 在 build 前动态生成,synchronized group 自动收集进 Bundle |
|
||||
| `Scripts/channels/<channel>.env` | 各渠道的 11 个键值对模板(git 跟踪) | 不入 Bundle |
|
||||
| `Vendor/<SDK>/<SDK>.xcframework` | 闭源 SDK 二进制(微信 / QQ / 高德 / opencore-amr) | Target Build Phase「Frameworks」手动加入 |
|
||||
|
||||
#### 7.0.3 渠道注入运行时路径
|
||||
#### 7.0.3 渠道注入:ChannelConfig.plist 母包模式
|
||||
|
||||
H5 端 / 业务代码透过 `BundleConfig.readInjected(_:)` 读取渠道值,路径约定为 `Bundle.main.bundleURL.appendingPathComponent("ChannelInjection")` 下的 11 个目录;**具体注入位置由 §7.2 BundleConfig 实现细节定义**(可调整,只要 BundleConfig 与 `inject_channel.sh` 双方对齐)。
|
||||
**契约 §0.3 描述 msext 用"空目录名注入"机制存储 11 个渠道值,本项目按 ADR-007 改用 `ChannelConfig.plist` 等价实现** —— 契约边界(H5 通过 `app_data.js` 看到的 11 个 JS 全局变量)完全不变,实现内部更简洁。
|
||||
|
||||
**存储**:`ylgamehall/Resources/ChannelConfig.plist`,11 个 string key 一一对应渠道值:
|
||||
|
||||
```xml
|
||||
<dict>
|
||||
<key>qiniudomain</key> <string>iosaudio.daoqi88.cn</string>
|
||||
<key>gameid</key> <string>G2hw0u...</string>
|
||||
<key>channel</key> <string>FtJf07...</string>
|
||||
<key>gamedir</key> <string>FtJf07...</string>
|
||||
<key>gamestart</key> <string>gamehall</string>
|
||||
<key>gameconfig</key> <string>tsgames.daoqi88.cn-config_test-update_jsonv2_test</string>
|
||||
<key>market</key> <string>2</string>
|
||||
<key>agent</key> <string>veRa0qrBf0df2K1G4de2tgfmVxB2jxpv</string>
|
||||
<key>appversion</key> <string>43</string>
|
||||
<key>other</key> <string></string>
|
||||
<key>appleconfig</key> <string></string>
|
||||
</dict>
|
||||
```
|
||||
|
||||
**运行时读取路径**:`Bundle.main.bundleURL.appendingPathComponent("ChannelConfig.plist")`,由 `BundleConfig.swift`(§7.2)用 `PropertyListSerialization` 反序列化。
|
||||
|
||||
**多渠道分发**(IPA 后处理,不重新 Xcode build):
|
||||
|
||||
```bash
|
||||
unzip ylgamehall.ipa -d tmp/
|
||||
APP="tmp/Payload/ylgamehall.app"
|
||||
plutil -replace channel -string "<new_channel_id>" "$APP/ChannelConfig.plist"
|
||||
plutil -replace market -string "<new_market_id>" "$APP/ChannelConfig.plist"
|
||||
codesign --force --sign "$IDENTITY" --entitlements "$ENT" "$APP"
|
||||
cd tmp && zip -r ../ylgamehall_<channel>.ipa Payload/
|
||||
```
|
||||
|
||||
→ 修改 plist 与 msext 的"`mv` 目录名"机制工作量相当,但**完全规避 Xcode 26 synchronized group 与目录树的兼容问题**(详见 Plan ADR-007)。
|
||||
|
||||
> **为什么不照搬 msext 的目录树**:
|
||||
> - msext 那套在 Xcode 14 / 老 group 模型下能工作;但 Xcode 26 默认 synchronized group 把子目录扁平化,适配代价高(尝试过 folder reference / Run Script + sandboxing 均有阻碍)
|
||||
> - plist 是 iOS 原生最简单的配置存储,加入 `Resources/` 后 Xcode 自动入 Bundle,零配置
|
||||
> - 修改成本 / 重签流程 / 维护成本 / IPA 后处理脚本 / H5 业务可观察行为,**与目录树方案完全等价**
|
||||
> - CLAUDE.md 原则 B:"原生内部自由重构,不要照搬旧项目"——这是落地
|
||||
|
||||
### 7.1 SandboxPaths 集中管理
|
||||
|
||||
@@ -1109,42 +1146,53 @@ public enum SandboxPaths {
|
||||
|
||||
```swift
|
||||
// ResourceKit/BundleConfig.swift
|
||||
//
|
||||
// 从 Bundle 内的 ChannelConfig.plist 读取 11 个渠道注入值。
|
||||
// 详见 §7.0.3 ChannelConfig.plist 母包模式 / ADR-007。
|
||||
public final class BundleConfig: @unchecked Sendable {
|
||||
public static let shared = BundleConfig()
|
||||
|
||||
public private(set) var qiniuDomain = ""
|
||||
public private(set) var gameId = ""
|
||||
public private(set) var channel = ""
|
||||
public private(set) var market = ""
|
||||
public private(set) var agent = ""
|
||||
public private(set) var appVersion = ""
|
||||
public private(set) var gameDir = ""
|
||||
public private(set) var gameStart = ""
|
||||
public private(set) var gameConfig = ""
|
||||
public let qiniuDomain: String
|
||||
public let gameId: String
|
||||
public let channel: String
|
||||
public let gameDir: String
|
||||
public let gameStart: String
|
||||
public let gameConfig: String
|
||||
public let market: String
|
||||
public let agent: String
|
||||
public let appVersion: String
|
||||
public let other: String
|
||||
public let appleConfig: String
|
||||
|
||||
public static func preload() async {
|
||||
// 异步包装,实际是同步 IO,但放在后台 queue
|
||||
await Task.detached(priority: .userInitiated) {
|
||||
BundleConfig.shared.qiniuDomain = readInjected("qiniudomain")
|
||||
BundleConfig.shared.gameId = readInjected("gameid")
|
||||
BundleConfig.shared.channel = readInjected("channel")
|
||||
// ...
|
||||
}.value
|
||||
public init(bundle: Bundle = .main) {
|
||||
let dict = Self.loadPlist(bundle: bundle)
|
||||
qiniuDomain = dict["qiniudomain"] ?? ""
|
||||
gameId = dict["gameid"] ?? ""
|
||||
channel = dict["channel"] ?? ""
|
||||
gameDir = dict["gamedir"] ?? ""
|
||||
gameStart = dict["gamestart"] ?? ""
|
||||
gameConfig = dict["gameconfig"] ?? ""
|
||||
market = dict["market"] ?? ""
|
||||
agent = dict["agent"] ?? ""
|
||||
appVersion = dict["appversion"] ?? ""
|
||||
other = dict["other"] ?? ""
|
||||
appleConfig = dict["appleconfig"] ?? ""
|
||||
}
|
||||
|
||||
/// 扫描 Bundle 中指定名称的目录,返回其第一个非隐藏子项的名字
|
||||
/// (打包脚本约定:每个 key 对应一个 Bundle 目录,目录下唯一子目录名即为配置值)
|
||||
private static func readInjected(_ key: String) -> String {
|
||||
let dir = Bundle.main.bundleURL.appendingPathComponent(key)
|
||||
guard let items = try? FileManager.default.contentsOfDirectory(atPath: dir.path) else {
|
||||
return ""
|
||||
}
|
||||
return items.first { !$0.hasPrefix(".") && $0 != ".DS_Store" } ?? ""
|
||||
private static func loadPlist(bundle: Bundle) -> [String: String] {
|
||||
guard let url = bundle.url(forResource: "ChannelConfig", withExtension: "plist"),
|
||||
let data = try? Data(contentsOf: url),
|
||||
let plist = try? PropertyListSerialization.propertyList(
|
||||
from: data, format: nil) as? [String: String]
|
||||
else { return [:] }
|
||||
return plist
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
> 七牛 CDN 域名(用于录音上传后的公网 URL 组装)在新项目中统一从 `BundleConfig.shared.qiniuDomain` 读取,不暴露任何全局变量。所有 AudioKit / RecordUploader 等模块通过依赖注入获取 BundleConfig。
|
||||
>
|
||||
> **测试性**:`init(bundle:)` 接受任意 Bundle,单测可注入 mock bundle 验证不同 plist fixture。
|
||||
|
||||
### 7.3 Zip 解压(异步,非阻塞)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user