From 47a89aa49ce7437aeff2ea75c3469933cc835a0e Mon Sep 17 00:00:00 2001
From: joywayer <joywaygames@163.com>
Date: Mon, 22 Jun 2026 07:58:02 +0800
Subject: [PATCH] =?UTF-8?q?Contract=20=C2=A74.2=EF=BC=9A=E6=8C=89=E5=8E=9F?=
 =?UTF-8?q?=E9=A1=B9=E7=9B=AE=E4=BB=A3=E7=A0=81=E5=85=A8=E9=9D=A2=E4=BF=AE?=
 =?UTF-8?q?=E8=AE=A2=20app=5F*.js=20JS=20=E6=B3=A8=E5=85=A5=E6=B8=85?=
 =?UTF-8?q?=E5=8D=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Phase 1.17 联调准备时回归原项目（CLAUDE.md「先看原项目」规则），
grep daoqi/msext 全部 "var app_" 字面字符串，对照本文档 §4.2 早期记录
发现 4 类硬错误：

1. 多列了不存在的变量 — 原项目代码字面字符串里**根本不写**：
   - app_gameid    grep 0 命中  → 删除
   - app_compareCode grep 0 命中 → 删除

2. 文件名与变量名混淆 — msext 文件名不带 get、变量名带 get：
   - 文件 app_battery.js → 内容 "var app_getbattery=%lf;"  (gameController.m:1191 / NewRootVC.m:1706)
   - 文件 app_network.js → 内容 "var app_getnetwork=%d;"   (gameController.m:1198 / NewRootVC.m:1714)
   早期文档统一写成 app_battery / app_network 容易让实施者把变量名也
   去掉 get，导致 H5 业务读到 undefined → 修正

3. 漏列 6 项真实存在的变量（gameController.m:2160 / NewRootVC.m:1204
   / AppDelegate.m:259 字面字符串里都有）：
   - app_version           硬编码 "1"
   - app_Launchtype        大厅 0 / 子游戏 1（⚠️ L 大写）
   - app_getwifisignalLevel 硬编码 1（⚠️ wifi 小写、signal/Level 大小写区分）
   - app_gamename          大厅 = gameStart / 子游戏 = game_name
   - app_invitationcode    tuiguang_id 推广码 / 邀请码
   - app_gamesname         独立 app_gamesname.js 文件 (var<两空格>new Array)

4. 大厅 vs 子游戏字面差异之前未注明：
   - app_Launchtype = 0/1
   - app_gamedir：gamedir vs gamefilepath
   - app_gamestart + app_gamename：gamestart vs game_name

新增"修订记录"小节明示三处修订的代码依据行号，方便未来回溯。

至此 Contract §4.2 与 Design §7.5 完全对齐（15 项变量，全部对应到
daoqi 原项目真实代码行）。Phase 2 实施 AppDataWriter 时按 Contract §4.2
为准，H5 端验收按 Contract 不会再有差异。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 docs/H5-Native-Contract.md | 76 +++++++++++++++++++++++++++++---------
 1 file changed, 59 insertions(+), 17 deletions(-)

diff --git a/docs/H5-Native-Contract.md b/docs/H5-Native-Contract.md
index face404..e5b34f9 100644
--- a/docs/H5-Native-Contract.md
+++ b/docs/H5-Native-Contract.md
@@ -690,34 +690,76 @@ _webView.scrollView.showsHorizontalScrollIndicator = NO;
 - LocalStorage 由 H5 自管（WKWebView 默认走 WebsiteDataStore）
 - 加载方式：**`loadFileURL:fileURL allowingReadAccessToURL:dirURL`**（file://），不走 HTTP
 
-### 4.2 JS 注入
+### 4.2 JS 注入（**已按原项目代码全面修订** — 见底部"修订记录"）
 
-在 `viewWillAppear` 内（每次加载 H5 之前）写出三个文件：
+H5 业务通过 `<script src="app_*.js">` 同步引入 4 个预生成的 `.js` 文件，文件内全是 `var app_xxx=...` 全局变量声明。原 msext 写入位置：`NewRootVC.m:1204`（大厅 initJSdata）/ `gameController.m:2160`（子游戏 initJSdata）/ `gameController.m:1191` `NewRootVC.m:1706`（battery 更新）/ `gameController.m:1198` `NewRootVC.m:1714`（network 更新）/ `AppDelegate.m:259` `gameController.m:197`（gamesname 更新）。
+
+**⚠️ 关键约束：文件名 ≠ 变量名**
+
+| 文件名（不带 get） | 文件内变量名（带 get） |
+|---|---|
+| `app_battery.js` | `var app_getbattery=...` |
+| `app_network.js` | `var app_getnetwork=...` |
+
+H5 端 `<script src="app_battery.js">` 引入后读到的是 `app_getbattery`（带 get 前缀），**不是** `app_battery`。任何拼写错误都会让 H5 业务读到 undefined。
+
+#### `app_data.js`（写到 `{gamedir}/{gamestart}/app_data.js`）
+
+12 个变量（**没有** `app_gameid` / `app_compareCode`，那两个是 §4.2 早期文档错误记录，原项目代码 `NewRootVC.m:1204` / `gameController.m:2160` 字面字符串里**根本不写**它们）：
 
-#### app_data.js（写到 `{gamedir}/{gamestart}/app_data.js`）
 ```js
-var app_gameconfig = "<gameconfig>";
-var app_gamedir    = "<gamedir>";
-var app_gamestart  = "<gamestart>";
-var app_agent      = "<agent>";
-var app_appversion = "<appversion>";
-var app_market     = "<market>";
-var app_channel    = "<channel>";
-var app_gameid     = "<gameid>";
-var app_compareCode= "<getcompareCode>";   // NSUserDefaults
+var app_version            = "1";        // 硬编码，沿用历史
+var app_gameconfig         = "<gameconfig>";
+var app_gamedir            = "<gamedir>";
+var app_gamestart          = "<gamestart>";
+var app_agent              = "<agent>";
+var app_appversion         = "<appversion>";    // int 字面，msext "var app_appversion='%d'"
+var app_market             = "<market>";
+var app_channel            = "<channel>";
+var app_Launchtype         = 0;          // ⚠️ L 大写！大厅=0 / 子游戏=1
+var app_getwifisignalLevel = 1;          // ⚠️ wifi 小写、signal/Level 区分大小写，硬编码 1
+var app_gamename           = "<gamename>";
+var app_invitationcode     = "<tuiguang_id>";   // 推广码 / 邀请码
 ```
 
-#### app_battery.js
+> 大厅 / 子游戏的字面差异（详见 §7.5 Design）：
+> - `app_Launchtype`：大厅 `0` / 子游戏 `1`
+> - `app_gamedir`：大厅 = `self.gamedir`（即 BundleConfig.gameDir）/ 子游戏 = `self.gamefilepath`（子游戏目录）
+> - `app_gamestart` + `app_gamename`：大厅 = `self.gamestart` / 子游戏 = `self.game_name`（子游戏名）
+
+#### `app_battery.js`（写到 `{gamedir}/{gamestart}/app_battery.js`）
+
 ```js
-var app_battery = "<UIDevice batteryLevel>";   // e.g. "0.85"
+var app_getbattery = 0.85;   // ⚠️ 变量名带 get！msext "var app_getbattery=%lf" double 字面
 ```
 
-#### app_network.js
+更新时机：`viewWillAppear` + `UIDeviceBatteryLevelDidChangeNotification` + 前台切换通知。
+
+#### `app_network.js`（写到 `{gamedir}/{gamestart}/app_network.js`）
+
 ```js
-var app_network = "<state>";   // "1"/"2"/"3"
+var app_getnetwork = 2;   // ⚠️ 变量名带 get！msext "var app_getnetwork=%d" int 字面：1 无网 / 2 WiFi / 3 蜂窝
 ```
 
-> H5 模板里 `index.html` 通过 `<script src="app_data.js">` 等同步引入这三个文件。新外壳必须保证这些文件**在 loadFileURL 之前**就写好，否则 H5 启动时变量未定义直接崩。
+更新时机：`viewWillAppear` + 网络变化（msext 用 AFNetworkReachability，新外壳用 NWPathMonitor）+ 前台切换通知。
+
+#### `app_gamesname.js`（写到 `{gamedir}/{gamestart}/app_gamesname.js`）
+
+```js
+var  app_gamesname = new Array('game1','game2',...);   // ⚠️ var 后面两个空格，沿用 msext AppDelegate.m:259 字面
+```
+
+更新时机：`AppDelegate.applicationDidFinishLaunching`（首次写入）+ 子游戏 `gameController.viewInit`（新装一个子游戏后追加；msext gameController.m:197 注释掉了实际写入逻辑，仅 AppDelegate 首次写入是活的）。
+
+> H5 模板里 `index.html` 通过 `<script src="app_data.js">` 等同步引入这 4 个文件。新外壳必须保证这些文件**在 loadFileURL 之前**就写好，否则 H5 启动时变量未定义直接崩。
+
+#### 修订记录
+
+| 日期 | 修订点 | 依据 |
+|------|---|---|
+| 2026-06-22 | 删 `app_gameid` / `app_compareCode`：原项目 grep `var app_` 在 `NewRootVC.m:1204` / `gameController.m:2160` 字面字符串里没有这两项 | daoqi 原项目代码全面 grep 验证 |
+| 2026-06-22 | `app_battery` 改为 `app_getbattery`、`app_network` 改为 `app_getnetwork`：变量名带 `get` 前缀，与文件名（不带 get）不一致 | daoqi `gameController.m:1191/1198`、`NewRootVC.m:1706/1714` |
+| 2026-06-22 | 新增 `app_version` / `app_Launchtype` / `app_getwifisignalLevel` / `app_gamename` / `app_invitationcode` / `app_gamesname` 共 6 项 | daoqi `NewRootVC.m:1204`、`gameController.m:2160`、`AppDelegate.m:259` |
 
 ### 4.3 WKUIDelegate（H5 alert / confirm）