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 自动识别）
This commit is contained in:
joywayer
@@ -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 集中管理
|
||||
|
||||
|
||||
Reference in New Issue
Block a user