启动文字提示，h5调试加入

docs/H5-Native-Contract.md

@@ -11,7 +11,7 @@
 新外壳与现网外壳之间，**只有以下三类内容是契约，必须 1:1 一致**：
 
 1. **桥接接口名** — H5 调用的 handler 名字符串（如 `mediaTypeAudio`、`friendsSharetypeUrlToptitleDescript`、`OpenurlTitleData`），少一个字符 H5 就找不到。
-2. **参数字段名 & 数据结构** — H5 传入的 `data` 字段名、Native 回调时的 payload 结构。**含历史包袱**：`sharelogin.Province`（大写 P）、`OpenurlTitleData` 的入参键名 `"title "`（末尾有空格）、`appservice` 用 `"1"`/`"2"` 字符串而不是数字、字段值约定（如 `isloop: -1/0/1` 三态），**必须照抄**。
+2. **参数字段名 & 数据结构** — H5 传入的 `data` 字段名、Native 回调时的 payload 结构。**含历史包袱**：`sharelogin.Province`（大写 P）、`OpenurlTitleData` 的入参键名 `"title "`（末尾有空格）、`appservice` 用字符串 `"2"`=进入后台 / `"1"`=回到前台（值错位，沿用 msext WKWebView 路径历史，参 §3.2 第 4 行）、字段值约定（如 `isloop: -1/0/1` 三态），**必须照抄**。
 3. **空实现接口也必须注册** — `opensaoma`、`getGameplay` 等当前为空实现的 handler，新外壳必须以同名空 handler 注册（响应 callback 但不做任何事），否则 H5 调用时会触发"bridge not found"错误分支。
 
 **除以上三类之外，原生内部一切都可以重写**：技术栈（Swift/SwiftUI/Combine 都行）、WebView 接入方式（直接用 WKScriptMessageHandler 或继续用 WebViewJavascriptBridge）、网络层（URLSession/Alamofire）、解压库（ZIPFoundation）、状态机、控制器层级、命名风格——只要外部行为不变，怎么实现都行。本文档后续章节中描述的"现有实现细节"只是为了帮助你理解**为什么 H5 期待某种行为**，不是要求你照抄实现方式。
@@ -558,7 +558,7 @@ window.rootViewController = NavgationController
 | 1 | `getphoneinfo` | 注册 `getphoneInfo` handler 收到调用后 | 见下方表 A | ✓ | ✓ |
 | 2 | `getBattery` | UIDeviceBatteryLevelDidChangeNotification | 字符串 `"%.2f"` 形式的小数电量（0~1）| ✓ | ✓ |
 | 3 | `getnetwork` | AFNetworkReachability 变化 | 字符串 `"1"`/`"2"`/`"3"` （1=无网，2=WiFi，3=蜂窝）| ✓ | ✓ |
-| 4 | `appservice` | App 前后台切换 | 字符串 `"1"`=进入后台，`"2"`=回到前台（命名错位，沿用历史）| ✓ | ✓ |
+| 4 | `appservice` | App 前后台切换 | 字符串 `"2"`=进入后台，`"1"`=回到前台（值错位，沿用 msext WKWebView 路径历史。详见下方注释）| ✓ | ✓ |
 | 5 | `shakeEnd` | motionEnded 摇一摇结束 | `nil` | ✓ | ✓ |
 | 6 | `getlocationinfo` | 定位成功/失败 | 见下方表 B | ✓ | ✓ |
 | 7 | `gameui_play_voice` | mediaTypeAudio 开始播放（且 voicePlaying=1 时）| 字符串 user_id | ✓ | ✓ |
@@ -575,6 +575,16 @@ window.rootViewController = NavgationController
 - `phonestate`：H5 子游戏会在收到 `"2"` 时主动哑麦/暂停，收到 `"0"` 恢复，跟视频房间体验强相关
 - `recordSuccess`：H5 收到后会拿 `fileUrl` 而非 `audiourl` 走业务（早期接口与新接口并存的兼容产物）；新外壳两个 handler 都得发，data 字段不同
 
+**`appservice` 值错位说明**（极容易看反，新人务必照抄不要"修正"）：
+
+原 msext WKWebView 路径（`NewRootVC.m:1769-1786` / `gameController.m:1319-1336`）的真实代码是：
+- iOS `applicationDidEnterBackground`（**真·进入后台**）→ `AppDelegate` post 一个**名为 `enterForeground` 的 NSNotification**（NSNotification 名错位，沿用历史）→ VC 的 `-enterForeground` 方法触发 → `[_bridge callHandler:@"appservice" data:@"2"]`
+- iOS `applicationDidBecomeActive`（**真·回到前台**）→ `AppDelegate` post 一个**名为 `applicationWillResignActive` 的 NSNotification**（NSNotification 名错位）→ VC 的 `-applicationWillResignActive` 方法触发 → `[_bridge callHandler:@"appservice" data:@"1"]`
+
+H5 端 N 年来收到的实际语义就是：**`"2"` = 进入后台、`"1"` = 回到前台**。新外壳不论 NSNotification 内部命名怎么改、用 `willEnterForegroundNotification` 还是 `didBecomeActiveNotification`，桥发出的字符串值必须按上面这套对应关系发，**不要被 NSNotification 名误导而把值发反**。
+
+（顺带：原 msext 还有一条 iOS<9 UIWebView 路径 `RootVC.m:516-543` / `fourviewVC.m:1254-1282`，发的值反过来：进入后台 → `"1"` / 回到前台 → `"2"`。该路径在新外壳最低 iOS 15.6 下完全不可达，**不能作为对齐依据**，请忽略。）
+
 **表 A — `getphoneinfo`**：
 ```json
 {
@@ -880,18 +890,18 @@ zip 包下载 + 解压由 `ASIHTTPRequest`（旧）/ `AFNetworking`（新）+ `Z
 
 | 通知名 | 发送方 | 接收方 | 用途 |
 |--------|--------|--------|------|
-| `enterForeground` | AppDelegate `applicationDidEnterBackground` | Root/NewRootVC/fourview/game/three | 转 `appservice("2")` |
-| `applicationWillResignActive` | AppDelegate `applicationDidBecomeActive`（节流 0.3s） | 同上 | 转 `appservice("1")` |
+| `enterForeground` | AppDelegate `applicationDidEnterBackground`（真·进入后台）| Root/NewRootVC/fourview/game/three | 转 `appservice("2")`（即 H5 收到 "2" 才是真·进入后台）|
+| `applicationWillResignActive` | AppDelegate `applicationDidBecomeActive`（真·回到前台，节流 0.3s） | 同上 | 转 `appservice("1")`（即 H5 收到 "1" 才是真·回到前台）|
 | `backgameDatatwo` | threeView / 子游戏 / RootVC.backgameData: | 父大厅 | 转 `getWebdata(data)` |
 | `stopradio` | 任意 | 主 VC | 暂停 backgroundPlayer |
 | `canbackye` | 任意（防抖恢复）| 主 VC | 允许返回手势 |
 | `UIDeviceBatteryLevelDidChangeNotification` | 系统 | 主 VC | 转 `getBattery(level)` |
 
-**命名注意**：旧 msext 中 `enterForeground` 实际表示"进入后台"，`applicationWillResignActive` 实际表示"回到前台"（命名被换反，历史包袱）。
+**命名注意**：旧 msext 中 `enterForeground` 实际表示"进入后台"，`applicationWillResignActive` 实际表示"回到前台"（命名被换反，历史包袱）。**这个命名错位顺势把桥的字符串值也带反了**——H5 收到 `appservice("2")` 才表示进入后台、收到 `appservice("1")` 才表示回到前台。
 
-这些 NSNotification 是**模块内通讯**，**不是 H5 可见的契约边界** —— H5 只能看到桥事件 `appservice("1")`/`appservice("2")`。
+这些 NSNotification 是**模块内通讯**，**不是 H5 可见的契约边界** —— H5 只能看到桥事件 `appservice("2")`（后台）/`appservice("1")`（前台）。
 
-新项目自由命名（推荐用 `.appDidEnterBackground` / `.appDidBecomeActive` 等清晰命名），只要最终把 `"1"`/`"2"` 正确转发给 H5 桥即可。详见 `H5-Native-Implementation-Design.md` §4.4。
+新项目自由命名（推荐用 `.appDidEnterBackground` / `.appDidBecomeActive` 等清晰命名），但桥发出的值**必须按上面错位关系**对应：`didEnterBackground → "2"` / `willEnterForeground → "1"`，**不要按 NSNotification 字面语义改回去**。详见 `H5-Native-Implementation-Design.md` §4.4 与 §3.2 `appservice` 值错位说明。
 
 ---
 
@@ -1049,7 +1059,7 @@ Library/Caches/
 - [ ] **H5 调 `confirm("是否退出")`** → 弹"取消"/"确定"两按钮 → 取消返回 false / 确定返回 true，H5 业务正常分支
 
 ### C. 系统事件
-- [ ] 切后台 → H5 收到 `appservice("1")`；回前台 → 收到 `appservice("2")`
+- [ ] 切后台 → H5 收到 `appservice("2")`；回前台 → 收到 `appservice("1")` ⚠️ 值错位沿用历史，参 §3.2 `appservice` 值错位说明
 - [ ] 电量变化 → H5 收到 `getBattery("0.XX")`
 - [ ] 飞行模式开关 → H5 收到 `getnetwork("1")` / `getnetwork("2"|"3")`
 - [ ] 摇一摇（startshake==YES 时）→ H5 收到 `shakeEnd`