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
+37
-23
@@ -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 评审时确认**首版无用户激活 / 留存分析需求**
|
||||
|
||||
Reference in New Issue
Block a user