docs：剥离 docs/res/ 为私人素材池，废止仓库根 Resources/ 假设

明确 docs/res/ 是项目维护者的私人原始素材池，与项目架构无关；项目代码 / 构建脚本 / Xcode 工程都不感知它的存在，需要时从中拷一份到项目按现代实践规划的位置。原 ADR-004「Resources/ 在仓库根 + Build Phase 引入」语义已崩塌（gamehall.zip / Images.xcassets / Res/ 均被挪入 docs/res/），修订为「项目内资源目录由各 Phase 按需落地」：静态 Bundle 资源走 ylgamehall/Resources/、原生 Asset Catalog 走 ylgamehall/Assets.xcassets/、渠道注入产物走 ylgamehall/ChannelInjection/ （.gitignore + Scripts/inject_channel.sh 生成）、闭源 SDK 走 Vendor/。 - CLAUDE.md 原「Resources/ 目录约定」节改写为「docs/res/ 与项目资源的关系」，禁止把 docs/res 当项目资源目录使用 - Design §7.0 整节重写为「项目资源目录约定」三小节（docs/res 与项目无关 / 项目内资源目录在 Phase 实施时按需落地 / 渠道注入运行时路径） - Plan ADR-004 修订为「项目资源目录由各 Phase 按需落地」；ADR-002 / §2.2 / Phase 1.1.a-d / 1.5 同步调整为 docs/res → ylgamehall/Resources 的拷贝模型；Phase 1 任务清单细化渠道注入由 Scripts/inject_channel.sh 生成 - 物理迁移：仓库根 Resources/gamehall.zip / Images.xcassets / Res/ 全部 rename 到 docs/res/（git rename detection 自动识别）
2026-06-21 22:32:38 +08:00
parent 17a8b96cf8
commit cabdc1ed42
42 changed files with 73 additions and 59 deletions
@@ -45,26 +45,24 @@ daoqi 仓库当前并存两条工作线：

 ---

-## Resources/ 目录约定
+## docs/res/ 与项目资源的关系

-仓库根目录的 `Resources/` 是新外壳运行所需的**项目方提供资源**统一入库位置，由打包脚本在 Build Phase 引入，**不**直接放进 Xcode 工程内的 `ylgamehall/` 源码目录。
+`docs/res/` 是**项目维护者的私人原始素材池**，**与项目架构无关**：

-### 当前内容（2026-06-21）
+- 仅作为开发期可能用到的素材的随手存放点（H5 团队提供的 zip / 美术给的 png / 原 msext 沉淀的 mp3 / 历史 Asset Catalog 等）
+- **项目代码 / 构建脚本 / Xcode 工程都不感知它的存在**，不依赖它的目录结构，不引用它的任何文件
+- 内容、结构、命名随时可由维护者调整，不影响构建
+- git 跟踪它只是为了多机同步素材，而不是因为项目需要它

- **`gamehall.zip`** — 大厅 H5 资源包（≈ 11 MB）。启动时由 `ResourceUnzipper` 解压到 `Library/Caches/{gamedir}/`。当前文件为 **2023-12 旧版**，开发期足以跑通管道，**上线前必须由 H5 团队提供最新版替换**
- **`Images.xcassets/`** — 原生层 Asset Catalog（AppIcon / LaunchImage / 微信/QQ/抖音分享平台图标）
- **`Res/`** — 散落原生资源：
-  - `sharelogo.png` — 分享缩略图（契约 §3.1【2】`friendsSharetypeUrlToptitleDescript` type=1 时使用）
-  - `shake_sound_male.mp3` — 摇一摇音效（受 `SwitchShake` 开关控制）
-  - `BackBT.png` / `Sistem_back.png` / `Default-568h@2x~iphone.png` / `Icon180.png` — 原 msext 兼容图，新外壳是否还需引用待 Phase 1 验证
+### 项目自己的资源目录由项目独立规划

-### 后续约定
+**禁止把 `docs/res/` 当作项目的资源目录使用**（即不要在代码 / 脚本 / Build Phase 中直接引用 `docs/res/xxx`）。当某项工作需要某个素材时：

- 11 个**渠道注入目录**（`qiniudomain` / `gameid` / `channel` / `gamedir` / `gamestart` / `gameconfig` / `market` / `agent` / `appversion` / `other` / `appleconfig`）将放在 `Resources/ChannelInjection/` 子目录下，由 `Scripts/inject_channel.sh` 打包前按渠道动态生成
- 任何新增需打入包的项目方资源（CDN 兜底图、本地音效、字体等）一律放 `Resources/`，**不**散落到 `ylgamehall/` 内
- `Resources/` 内文件可入 git（与 `Vendor/` 同 — 为闭源资源 / 二进制锁定版本，保证多人 + CI 可复现）；唯一例外是签名 / 敏感配置（已被 `.gitignore` 拦截）
+1. 从 `docs/res/` **拷贝一份**到项目按现代 iOS 实践规划的目标目录（如 `ylgamehall/Resources/`、`ylgamehall/Assets.xcassets/`、`Vendor/<SDK>/` 等）
+2. 由 Xcode 工程结构 / synchronized group / Build Phase 接管该素材的打包流程
+3. 后续维护与 `docs/res/` 不再有任何关联——`docs/res/` 那份是"原始备份"，工程内那份是"在用版本"

-详细资源加载流程见 `docs/H5-Native-Implementation-Design.md` §7 资源 & 渠道注入。
+**约定**：项目实际需要的资源目录结构由 Design / Plan 在各 Phase 实施时按需定义并落到工程内；不预先把"所有未来可能用到的资源"硬塞进某个固定 Resources 目录。

 ---

@@ -42,15 +42,17 @@ Contract       Design          Plan（本文档）
 - [x] CLAUDE.md 加入"及时提交"规则
 - [x] BuildProject 验证通过

-### 2.2 已就位的项目方资源
+### 2.2 已就位的原始素材

-仓库根 `Resources/` 已包含（详见 CLAUDE.md「Resources/ 目录约定」与 Design §7.0）：
+项目维护者的私人素材池 `docs/res/` 已包含以下可按需取用的素材（详见 CLAUDE.md「docs/res/ 与项目资源的关系」与 Design §7.0）：

- ✅ `Resources/gamehall.zip`（2023-12 旧版，开发期足够，上线前替换最新版）
- ✅ `Resources/Images.xcassets`（AppIcon / LaunchImage / 分享平台图标）
- ✅ `Resources/Res/`（`sharelogo.png` / `shake_sound_male.mp3` 等散落原生资源）
+- `docs/res/gamehall.zip`（2023-12 旧版，11.5 MB；用时拷贝到 `ylgamehall/Resources/`）
+- `docs/res/Images.xcassets/`（AppIcon / LaunchImage / 分享平台图标；用时迁移 / 拷贝条目到 `ylgamehall/Assets.xcassets/`）
+- `docs/res/Res/`（`sharelogo.png` / `shake_sound_male.mp3` 等散落原生资源；用时拷贝到 `ylgamehall/Resources/Sounds/` 等子目录）

-→ Phase 1 不再阻塞于 H5 团队，可立即展开。
+> `docs/res/` 不进 Bundle 也不被工程引用。Phase 1 / 3 / 4 等实施时按需从中拷贝到 `ylgamehall/Resources/` 或 `ylgamehall/Assets.xcassets/`。
+
+→ Phase 1 不再阻塞于 H5 团队（gamehall.zip 旧版可用于打通管道），可立即展开。

 ### 2.3 待项目方协调的外部资源（阻塞项）

@@ -217,7 +219,7 @@ Contract       Design          Plan（本文档）

 #### 前置
 - ✅ Phase 0 基线
- ✅ `Resources/gamehall.zip`（2023-12 旧版，足以验收 Phase 1）
+- ✅ `docs/res/gamehall.zip`（2023-12 旧版，足以验收 Phase 1；实施时拷贝到 `ylgamehall/Resources/gamehall.zip`）
 - ⏳ 项目方提供 11 个渠道注入目录名值（缺则用临时 demo 值）
 - 备选：若 zip 加载有问题，临时用一个最小 H5（`<html>` 含一个 button 调 `bridge.callHandler('vibrator')`）做工程内测排查

@@ -225,17 +227,19 @@ Contract       Design          Plan（本文档）

 ##### 1.A 资源层

- [ ] **1.1** 创建 `Resources/ChannelInjection/` 目录结构（11 个空容器目录占位）
-  - `qiniudomain/<待填>`、`gameid/<待填>` 等 11 项
-  - 文件夹下放 `.gitkeep`
- [ ] **1.2** 实现 `Source/Resource/BundleConfig.swift`
-  - `static func readInjected(_ key: String) -> String`：扫描 Bundle 子目录，返回首个非隐藏子项名
+- [ ] **1.1.a** 写 `Scripts/channels/dev.env`：11 个渠道键值对（沿用 msext 现网 demo），git 跟踪
+- [ ] **1.1.b** 写 `Scripts/inject_channel.sh`：读 env → 清空并重新生成 `ylgamehall/ChannelInjection/` 目录树
+- [ ] **1.1.c** `.gitignore` 加 `ylgamehall/ChannelInjection/`
+- [ ] **1.1.d** 跑一次 `Scripts/inject_channel.sh dev` 生成本地 dev 渠道目录
+- [ ] **1.2** 实现 `ylgamehall/Source/Resource/BundleConfig.swift`
+  - `static func readInjected(_ key: String) -> String`：扫描 `Bundle.main.bundleURL.appendingPathComponent("ChannelInjection")` 下 `key` 子目录，返回首个非隐藏子项名
  - 单测 fixture：建立 mock bundle，验证 11 个 key 全部能读出
- [ ] **1.3** 实现 `Source/Resource/SandboxPaths.swift`
+- [ ] **1.3** 实现 `ylgamehall/Source/Resource/SandboxPaths.swift`
  - 常量：`caches` / `documents` / `bundle`
  - `lobbyIndex() -> URL` 拼出 `{Caches}/{gamedir}/{gamestart}/index.html`
 - [ ] **1.4** 加 ZIPFoundation SPM 依赖
- [ ] **1.5** 实现 `Source/Resource/ResourceUnzipper.swift`（actor）
+- [ ] **1.5** 实现 `ylgamehall/Source/Resource/ResourceUnzipper.swift`（actor）
+  - 从 `docs/res/gamehall.zip` 拷贝一份到 `ylgamehall/Resources/gamehall.zip`
  - `ensureReady() async throws`：检测 `version.xml` 不存在则解压 Bundle 内 `gamehall.zip` 到 caches
  - 单测：用 fixture zip 验证解压幂等性

@@ -858,26 +862,36 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
 - **回滚条件**：单 target 编译时间 > 30s 时切 SPM

 ### ADR-002：使用已就位的 2023-12 旧版 gamehall.zip 起步（2026-06-21，原方案"H5 demo 先行"已作废）
- **背景**：仓库根 `Resources/gamehall.zip` 已存在（旧版，2023-12，11.5 MB），无需等 H5 团队最新版即可启动 Phase 1
- **决策**：Phase 1 直接用该 zip 跑通"渠道注入 → 解压 → 加载 H5 → 桥消息"全链路；旧 H5 业务代码与新版的契约差异不影响"桥本身是否工作"的验证
+- **背景**：私人素材池 `docs/res/gamehall.zip` 已存在（旧版，2023-12，11.5 MB），无需等 H5 团队最新版即可启动 Phase 1
+- **决策**：Phase 1 实施时从 `docs/res/gamehall.zip` 拷贝到 `ylgamehall/Resources/gamehall.zip` 入 Bundle，跑通"渠道注入 → 解压 → 加载 H5 → 桥消息"全链路；旧 H5 业务代码与新版的契约差异不影响"桥本身是否工作"的验证
 - **理由**：
  - 桥接口名 / 参数字段名 / JS 协议属于契约范畴，按 Contract 1:1 实现即可，不依赖 H5 业务代码新旧
  - 提早用真 H5 跑通比 demo H5 更能暴露真实问题（如 WVJB 握手时序、JS 注入文件路径等）
 - **风险**：联调期遇到的契约疑点可能来自旧版 H5 已废弃接口，需对照现网 msext + H5 团队双确认
- **切换条件**：Phase 10 灰度前必须由 H5 团队提供最新版替换并复跑契约 §10 全部 26 项
+- **切换条件**：Phase 10 灰度前必须由 H5 团队提供最新版替换 `ylgamehall/Resources/gamehall.zip` 并复跑契约 §10 全部 26 项

 ### ADR-003：微信登录走后台中转 vs 客户端 fallback（2026-06-21）
 - **决策**：默认走后台 `/wechat/login` 中转；后台未就绪时临时客户端直拼，但代码标 `// FIXME` 且**禁止以 fallback 状态上线**
 - **理由**：客户端 secret 一旦进 IPA 永久泄露 + AppSecret 不可重置（Contract §0.4 / Design §17）；上线前必须闭环
 - **复盘节点**：Phase 4 完成时检查后台接口状态

-### ADR-004：Resources/ 目录位于仓库根（非 Xcode 工程内）（2026-06-21）
- **决策**：项目方提供的所有资源（`gamehall.zip` / 原生 Asset Catalog / 散落 png / mp3 / 后续渠道注入目录）统一放仓库根 `Resources/`，由打包脚本通过 Build Phase 引入；**不**直接放进 Xcode 工程的 `ylgamehall/` 源码目录
+### ADR-004：项目资源目录结构由各 Phase 按需落地，不预先建仓库根 Resources/（2026-06-21 修订）
+- **背景**：原 ADR-004（2026-06-21 初版）决议"项目资源统一放仓库根 `Resources/` + 打包脚本 Build Phase 引入"，并将 `gamehall.zip` / `Images.xcassets` / `Res/` 入库到 `Resources/`。但 `docs/res/` 后被维护者重新定义为**私人原始素材池**（不被项目感知，详见 CLAUDE.md），原 `Resources/` 入库的素材被搬走，使该 ADR 的语义崩塌
+- **修订决策**：废止"仓库根 `Resources/`"的固定结构假设，**项目内资源目录由各 Phase 实施时按需落地**：
+  - 静态 Bundle 资源 → `ylgamehall/Resources/`（synchronized group 自动收集）
+  - 原生 Asset Catalog → `ylgamehall/Assets.xcassets/`
+  - 当前激活渠道注入产物 → `ylgamehall/ChannelInjection/`（.gitignore 忽略，由 `Scripts/inject_channel.sh` 生成）
+  - 渠道值模板 → `Scripts/channels/<channel>.env`（git 跟踪）
+  - 闭源 SDK 二进制 → `Vendor/<SDK>/<SDK>.xcframework`
+  - 私人原始素材池 → `docs/res/`（项目不感知，需要时拷贝到上述工程内目录）
 - **理由**：
-  - 与源码物理隔离，git diff 更清晰（资源变动 vs 代码变动不混淆）
-  - Build Phase 引入便于按渠道动态切换内容（同一份源码 × 多个 Resources 配置）
-  - 符合 Design §2.2 的 SPM 包结构规划（`Resources/` 与 `Sources/` 并列）
- **现状**：`Resources/` 已含 `gamehall.zip` / `Images.xcassets/` / `Res/`；11 个渠道注入目录预留位 `Resources/ChannelInjection/` 待 Phase 1 由 `Scripts/inject_channel.sh` 生成
+  - `docs/res/` 既已剥离为私人素材池，原"项目方资源统一放仓库根 Resources/"的前提不存在
+  - synchronized group 模式下，把资源直接放 `ylgamehall/Resources/` 而非仓库根 `Resources/` 更省一步 Build Phase 配置
+  - "不预先建 Resources/ 目录"避免空壳目录污染仓库；目录在该 Phase 真正需要时再建
+- **影响**：
+  - 仓库根 `Resources/` 不再存在（已删除）
+  - Plan §2.2 / Phase 1 任务 / ADR-002 同步调整为 `docs/res/` → `ylgamehall/Resources/` 的拷贝模型
+  - Design §7.0 同步重写

 ### ADR-005：JAnalytics（极光）首版降为 NoopAnalytics 占位（2026-06-21）
 - **背景**：Design §14.2 原标注极光"✅ 启用，启动注册"，但项目方在 2026-06-21 评审时确认**首版无用户激活 / 留存分析需求**
@@ -1045,33 +1045,35 @@ public actor ConfigService {

 ## 7. 资源 & 渠道注入

-### 7.0 仓库根 `Resources/` 目录现状（2026-06-21）
+### 7.0 项目资源目录约定

-新外壳运行所需的项目方资源统一存放在仓库根 `Resources/`（**不**在 Xcode 工程内的 `ylgamehall/` 源码目录里）。这与 §2.2 的 SPM 包结构里 `Resources/` 是同一份物理目录,后续打包脚本通过 Build Phase 引用。
+项目资源目录的最终结构**由各 Phase 实施时按需定义**,本节列出固定规则,具体目录形态在落地时决定。

-当前实际内容(可直接展开 Phase 1 开发):
+#### 7.0.1 仓库内素材池 `docs/res/` 与项目无关

-```
-Resources/
-├── gamehall.zip              ← 大厅 H5 资源包 (≈ 11 MB, 2023-12 旧版)
-│                                启动时 ResourceUnzipper 解压到
-│                                Library/Caches/{gamedir}/
-│                                ⚠️ 上线前必须由 H5 团队提供最新版替换
-├── Images.xcassets/          ← 原生 Asset Catalog (AppIcon /
-│                                LaunchImage / 微信 / QQ / 抖音
-│                                分享平台图标)
-└── Res/                      ← 散落原生资源 (未走 Asset Catalog 的旧文件):
-    ├── sharelogo.png            ← 分享缩略图 (友圈/微信链接分享用)
-    ├── shake_sound_male.mp3     ← 摇一摇音效 (SwitchShake 开关控制)
-    ├── BackBT.png               ← msext 兼容图,新外壳是否引用待 Phase 1 验证
-    ├── Sistem_back.png          ← 同上
-    ├── Icon180.png              ← 同上
-    └── Default-568h@2x~iphone.png ← 同上
-```
+`docs/res/` 是项目维护者的**私人原始素材池**,**与项目架构无关**(详见 `CLAUDE.md` 「docs/res/ 与项目资源的关系」):

-> **Phase 1 含义**:`gamehall.zip` 实物已就位,虽是旧版但足以跑通"渠道注入 → 解压 → 加载 H5 → 桥消息"全链路,不必等 H5 团队最新版才开始。版本差异不影响契约边界(handler 名 / 参数 / 数据结构)。
+- 项目代码 / 构建脚本 / Xcode 工程都**不感知**它的存在,不引用任何 `docs/res/xxx` 路径
+- 它的目录结构 / 命名 / 内容可由维护者任意调整,不影响构建
+- git 跟踪只是为了多机同步素材,而非项目需要

-后续 11 个**渠道注入目录**(`qiniudomain` / `gameid` / `channel` / `gamedir` / `gamestart` / `gameconfig` / `market` / `agent` / `appversion` / `other` / `appleconfig`)将由 `Scripts/inject_channel.sh` 在打包前于 `Resources/ChannelInjection/` 下动态生成,运行时通过 `BundleConfig.readInjected(_:)` 扫描 Bundle 子目录读取(§7.2)。
+需要某素材时,**从 `docs/res/` 拷一份**到项目内规划好的位置,后续维护与 `docs/res/` 不再有任何关联。
+
+#### 7.0.2 项目内资源目录(Phase 实施时落地)
+
+按现代 iOS 单 target + synchronized group 实践,推荐落点如下,**但具体目录在该 Phase 真正需要时再创建**(避免预先空目录):
+
+| 落点 | 用途 | 入 Bundle 方式 |
+|------|------|--------------|
+| `ylgamehall/Resources/` | 静态打入 Bundle 的项目资源(`gamehall.zip` / `WebViewJavascriptBridge.js` / 本地音效 mp3 等) | 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 渠道注入运行时路径
+
+H5 端 / 业务代码透过 `BundleConfig.readInjected(_:)` 读取渠道值,路径约定为 `Bundle.main.bundleURL.appendingPathComponent("ChannelInjection")` 下的 11 个目录;**具体注入位置由 §7.2 BundleConfig 实现细节定义**(可调整,只要 BundleConfig 与 `inject_channel.sh` 双方对齐)。

 ### 7.1 SandboxPaths 集中管理