From fae7b3da82040307a396d846abc5604ec037cd7c Mon Sep 17 00:00:00 2001
From: joywayer <joywaygames@163.com>
Date: Mon, 22 Jun 2026 07:59:17 +0800
Subject: [PATCH] =?UTF-8?q?CLAUDE.md=EF=BC=9A=E6=96=B0=E5=A2=9E=E7=AC=AC?=
 =?UTF-8?q?=202=20=E4=B8=AA=E5=85=B8=E5=9E=8B=E6=A1=88=E4=BE=8B=E3=80=8CH5?=
 =?UTF-8?q?=20=E4=B8=8E=E5=8E=9F=E7=94=9F=E9=80=9A=E8=AE=AF=E6=8E=A5?=
 =?UTF-8?q?=E5=8F=A3=E7=9A=84=E7=9C=9F=E5=AE=9E=E8=B7=AF=E5=BE=84=E3=80=8D?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

补在 LaunchScreen 案例后，记录本轮发现：

- 症状：基于 Contract §附录 A 实现 window.settings.getXxx() polyfill 后
  H5 行为不对，user 反馈"读不到数据"
- 错误做法：把附录 A 9 项 getter 实现为 polyfill，认为是 H5 主路径
- 原项目真相：grep "var app_" 在 daoqi/msext NewRootVC.m:1204 /
  gameController.m:2160 / AppDelegate.m:259，发现 H5 主路径是写 .js 文件
  + <script src> 同步引入预生成的全局变量（不是 polyfill 函数）
- 同时发现 Contract §4.2 本身也写错（漏 6 项 / 多 2 项 / 文件名变量名混淆）
- 修复：撤销 §3.4.1 polyfill / 新增 §7.5 app_*.js 预注入 / 全面修订
  Contract §4.2

教训 3 条：
  1. 文档与代码冲突时原项目代码是真理。Contract 也可能写错（10 年前
     写就的文档遗漏/误传是常态），必须用 grep 验证字面字符串
  2. 优先验证字面字符串、不要依赖语义猜测：app_getbattery vs app_battery
     一字之差，凭"应该就是 app_battery 吧"100% 犯错
  3. iOS 最低系统版本是契约边界的天然过滤器：契约明示可不实现的旧接口
     新项目应主动剔除，不要"出于完备性"反而做一份用不到的实现

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 CLAUDE.md | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 38fb900..1c33be1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -76,6 +76,23 @@ daoqi 仓库当前并存两条工作线：
   - 改完启动相关任意一项**必须做**：长按 app → 删除 → Xcode 重新 Run；或模拟器 Erase All Content and Settings；或 `xcrun simctl uninstall booted <bundleID>`
   - **终端用户不受影响**：从 IPA 首次安装、或升级新 IPA 第一次启动后即被 iOS 自动刷新；只是开发期反复迭代同一台 device 时会被迷惑
 
+### 典型案例：H5 与原生通讯接口的真实路径
+
+- **症状**：Design / Contract 文档描述 H5 用 `window.settings.getXxx()` 同步函数读渠道值（如 `getothername` / `getchannelName`）；按文档实现完 polyfill 后 H5 业务行为不对，user 反馈"H5 读不到数据"
+- **错误做法**：基于 Contract §附录 A 列出的旧桥 JSExport 28 方法实现 polyfill，把 9 项 getter 注入到 `window.settings`，认为这是 H5 端的主路径
+- **去原项目找答案**：grep `var app_` 在 `daoqi/msext/Class/RootVC/NewRootVC.m:1204` / `gameController.m:2160` / `AppDelegate.m:259`
+  - 发现 1：原项目 `initJSdata()` 是 `[NSString stringWithFormat:@"var app_xxx=...;"]` + `writeToFile:` **写 .js 文件到沙盒**，H5 业务用 `<script src="app_data.js">` 同步引入预生成的 12 个全局变量直接读
+  - 发现 2：Contract §附录 A 自身标注「iOS<9 路径使用的旧协议，新外壳如最低系统 ≥ iOS 14 可不实现」，新项目最低 iOS 15.6 → 旧桥 polyfill **完全不必要**
+  - 发现 3：Contract §4.2 之前列的 11 项变量与原项目代码不一致 — 漏 6 项（version / Launchtype / getwifisignalLevel / gamename / invitationcode / gamesname）、多 2 项（gameid / compareCode 原项目根本不写）、文件名与变量名混淆（文件 `app_battery.js` 内的变量名是带 get 的 `app_getbattery`，文件名不带 get）
+- **修复**：
+  1. 撤销已实现的 `window.settings.getXxx()` polyfill 章节（Design §3.4.1）
+  2. 新增 Design §7.5「H5 `app_*.js` 预注入文件机制」覆盖 15 个变量的写入逻辑
+  3. 按原项目代码全面修订 Contract §4.2（删 gameid/compareCode、补 6 项、修正 battery/network 变量名带 get、注明大厅/子游戏字面差异、加修订记录小节）
+- **教训**：
+  - **文档与代码冲突时，原项目代码是真理**。Contract 也可能写错（一份 10 年前写就的文档遗漏 / 误传是常态），必须用 `grep` 验证字面字符串
+  - **优先验证字面字符串、不要依赖语义猜测**：`app_getbattery` 与 `app_battery` 一字之差，AI 助手凭语义"应该就是 app_battery 吧" 100% 会犯错
+  - **iOS 最低系统版本是契约边界的天然过滤器**：契约里 iOS<9 路径明示可不实现的接口（如 §附录 A 旧桥），新项目最低 iOS 15.6 应当主动剔除，不要"出于完备性"反而实现一份用不到的 polyfill
+
 ---
 
 ## 文档索引