中优 3 项收尾：Plan §6.4 里程碑 + Design §20.1 拆分 + Contract §10 验收清单
补完本轮 audit 与 Design 大改后的文档边界，避免后续 Phase 实施者
按陈旧描述走弯路。
1. Plan §6.4 文档同步段新增「Design 接口骨架覆盖里程碑」表：
- 4 行时间线记录 Phase 1 闭环 / Design 全 51 项接口骨架 / Contract §4.2
按 daoqi 原项目修订 / CLAUDE.md 加典型案例的 commit hash
- 末尾澄清「§3.4.1 撤销说明」与 §7.5 主路径关系，避免新人疑惑
2. Design §20.1 LobbyHandlers 加架构说明段：
- 明示实际拆为 AudioHandlers / DeviceHandlers / LocationHandlers /
ShakeHandlers / OpenurlTitleDataHandler 5 个 sub-struct（§8.1.1 /
§8.4.1 / §8.6 / §8.7 / §3.4.2 各自归属）
- LobbyHandlers 成为聚合点，依次调子 .register()
- 保留 monolithic register 速查表作为与 Contract §3.1 编号对账用
- 每行注释 §3.1 ［N］ 编号便于追溯
3. Contract §10 验收清单加 5 项硬约束：
§A 启动新增：
- app_*.js 4 个文件存在
- 15 个 app_* 全局变量命名 100% 正确（大小写硬约束）
- 大厅 vs 子游戏 app_Launchtype = "0"/"1" 字面差异
- app_gameid / app_compareCode 必须 undefined（早期 Contract 误列）
§B 桥接新增：
- H5 alert(msg) → UIAlertController 单按钮
- H5 confirm(msg) → 取消/确定 双按钮 + 正确返回 bool
至此 Plan / Design / Contract 三文档完全对齐 51 项接口（含 §7.5 app_*.js
15 个、§3.7 WKUIDelegate 2 个）。Phase 2 实施可直接对照 Contract §10
验收清单做契约测试。
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
joywayer
co-authored by
Claude Opus 4.7
Claude Opus 4.7
parent
fae7b3da82
commit
0cdd709e66
@@ -758,6 +758,17 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
|
|||||||
- 桥接 handler 任何变动必须同步更新 Contract（Design §18.6）
|
- 桥接 handler 任何变动必须同步更新 Contract（Design §18.6）
|
||||||
- Phase 完成时如发现 Contract 描述与实测不符 → 优先修 Contract（事实为准）
|
- Phase 完成时如发现 Contract 描述与实测不符 → 优先修 Contract（事实为准）
|
||||||
|
|
||||||
|
#### Design 接口骨架覆盖里程碑
|
||||||
|
|
||||||
|
| 日期 | 完成 | 涉及 commit |
|
||||||
|
|------|------|-------------|
|
||||||
|
| 2026-06-22 | Phase 1 闭环（1.10–1.16）完整启动链路打通：SceneDelegate → WebContainer → ensureReady → fetch → resolve → upgrade → loadFileURL → fade out splash | `c95e80d` 及之前 |
|
||||||
|
| 2026-06-22 | Design 蓝图按 Contract 全 51 项接口补完实现骨架（H5↔Native 5 条通讯路径）：22 项 §3.1 异步 handler / 15 项 §3.2 反向 callback / 3 项 §3.4 弹层 polyfill / 15 项 §7.5 `app_*.js` 预注入全局变量 / 2 项 §3.7 WKUIDelegate alert/confirm | `92298b6` / `c6221d3` / `d48ecc0` / `a06a18c` / `5f5f6a9` / `33574a1` / `f68b0db` |
|
||||||
|
| 2026-06-22 | Contract §4.2 按 daoqi 原项目代码（grep `var app_` 字面字符串）全面修订：删 `app_gameid` / `app_compareCode`（原项目不写）/ 修正 `app_battery` → `app_getbattery`、`app_network` → `app_getnetwork`（文件名不带 get、变量名带 get）/ 补 6 项遗漏（version / Launchtype / getwifisignalLevel / gamename / invitationcode / gamesname） | `47a89aa` |
|
||||||
|
| 2026-06-22 | CLAUDE.md 新增第 2 个典型案例「H5 与原生通讯接口的真实路径」记录"凭语义猜测会一字之差犯错、必须 grep 字面字符串验证"的教训 | `fae7b3d` |
|
||||||
|
|
||||||
|
> **§3.4.1 撤销说明**：早期 commit `82bad8a` 实现的 `window.settings.getXxx()` polyfill 已撤销 — Contract §附录 A 自身明示「iOS<9 路径，新外壳如最低系统 ≥ iOS 14 可不实现」，本项目最低 iOS 15.6 → polyfill 路径未启用，H5 用 §7.5 的 `app_*.js` 文件路径作为唯一主路径。详细缘由见 Design §3.4.1（撤销说明）和 CLAUDE.md「典型案例」段。
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 7. 真实风险与缓解（项目独有）
|
## 7. 真实风险与缓解（项目独有）
|
||||||
|
|||||||
@@ -979,6 +979,10 @@ Library/Caches/
|
|||||||
- [ ] 重装 + 热启动：< 1 秒进入大厅
|
- [ ] 重装 + 热启动：< 1 秒进入大厅
|
||||||
- [ ] 渠道注入：把 `msext/channel/xxx` 目录名改成 `yyy`，重打包后大厅显示的渠道 ID 变为 `yyy`
|
- [ ] 渠道注入：把 `msext/channel/xxx` 目录名改成 `yyy`，重打包后大厅显示的渠道 ID 变为 `yyy`
|
||||||
- [ ] iOS 18 / 19 / 26 上启动不卡死
|
- [ ] iOS 18 / 19 / 26 上启动不卡死
|
||||||
|
- [ ] **`app_*.js` 4 个文件存在**：`{gamedir}/{gamestart}/` 下 `app_data.js` / `app_battery.js` / `app_network.js` / `app_gamesname.js` 全部生成、loadFileURL 前已落盘
|
||||||
|
- [ ] **`app_*` 12 + 1 + 1 + 1 = 15 个全局变量命名 100% 正确**（参 §4.2）：H5 console 检查 `app_version` / `app_gameconfig` / `app_gamedir` / `app_gamestart` / `app_agent` / `app_appversion` / `app_market` / `app_channel` / `app_Launchtype` / `app_getwifisignalLevel` / `app_gamename` / `app_invitationcode` / `app_getbattery` / `app_getnetwork` / `app_gamesname` 全部 `!== undefined`；尤其大小写 `app_Launchtype`（L 大写）/ `app_getwifisignalLevel`（wifi 小写 + signal/Level 区分）/ `app_getbattery`、`app_getnetwork`（带 get 前缀）必须精确
|
||||||
|
- [ ] **大厅 vs 子游戏字面差异**：大厅 H5 内 `app_Launchtype === "0"`、子游戏 H5 内 `app_Launchtype === "1"`
|
||||||
|
- [ ] **不要存在已撤销的变量**：H5 console 检查 `app_gameid` / `app_compareCode` 应为 `undefined`（早期 Contract §4.2 误列，原项目代码字面字符串里不写）
|
||||||
|
|
||||||
### B. 桥接
|
### B. 桥接
|
||||||
- [ ] H5 调 `accreditlogin` → 微信弹授权页 → 同意后 H5 收到 `sharelogin` 回调，7 字段完整
|
- [ ] H5 调 `accreditlogin` → 微信弹授权页 → 同意后 H5 收到 `sharelogin` 回调，7 字段完整
|
||||||
@@ -993,6 +997,8 @@ Library/Caches/
|
|||||||
- [ ] H5 调 `OpenurlTitleData`（大厅 WVJB）→ 打开内嵌弹层；弹层内 H5 调 `settings.finishweb()`（弹层 JSExport）关闭，且弹层内 `settings.backgameData(data)` 能把 data 传回大厅，大厅 H5 收到 `getWebdata`
|
- [ ] H5 调 `OpenurlTitleData`（大厅 WVJB）→ 打开内嵌弹层；弹层内 H5 调 `settings.finishweb()`（弹层 JSExport）关闭，且弹层内 `settings.backgameData(data)` 能把 data 传回大厅，大厅 H5 收到 `getWebdata`
|
||||||
- [ ] H5 调 `browser` → Safari 打开外链
|
- [ ] H5 调 `browser` → Safari 打开外链
|
||||||
- [ ] H5 调 `SwitchOverGameData` → push 到子游戏；子游戏内调 `backgameData` → 回到大厅；H5 收到 `getWebdata`
|
- [ ] H5 调 `SwitchOverGameData` → push 到子游戏；子游戏内调 `backgameData` → 回到大厅；H5 收到 `getWebdata`
|
||||||
|
- [ ] **H5 调 `alert("登录失败")`** → 弹出原生 UIAlertController，标题 = appDisplayName，单"确定"按钮（不实现 WKUIDelegate 则 H5 提示完全不弹）
|
||||||
|
- [ ] **H5 调 `confirm("是否退出")`** → 弹"取消"/"确定"两按钮 → 取消返回 false / 确定返回 true，H5 业务正常分支
|
||||||
|
|
||||||
### C. 系统事件
|
### C. 系统事件
|
||||||
- [ ] 切后台 → H5 收到 `appservice("1")`；回前台 → 收到 `appservice("2")`
|
- [ ] 切后台 → H5 收到 `appservice("1")`；回前台 → 收到 `appservice("2")`
|
||||||
|
|||||||
@@ -3985,34 +3985,62 @@ final class AppCoordinator {
|
|||||||
|
|
||||||
### 20.1 LobbyHandlers — 大厅注册 20 个 handler
|
### 20.1 LobbyHandlers — 大厅注册 20 个 handler
|
||||||
|
|
||||||
|
> **架构说明**（与 §8.x 各 module 章节同步）：本节早期版本把 20 项 handler 全列在单一 `LobbyHandlers struct.register()` 内，便于一眼看全。实际实施时（§8.1.1 / §8.4.1 / §8.6 / §8.7 / §3.4.2）按 module 维度拆为多个 sub-struct（`AudioHandlers` / `DeviceHandlers` / `LocationHandlers` / `ShakeHandlers` / `OpenurlTitleDataHandler` 等），`LobbyHandlers` 成为聚合点：
|
||||||
|
>
|
||||||
|
> ```swift
|
||||||
|
> public struct LobbyHandlers {
|
||||||
|
> let bridge: BridgeProtocol
|
||||||
|
> let audioHandlers: AudioHandlers // §8.1.1
|
||||||
|
> let deviceHandlers: DeviceHandlers // §8.4.1
|
||||||
|
> let locationHandlers: LocationHandlers // §8.6
|
||||||
|
> let shakeHandlers: ShakeHandlers // §8.7
|
||||||
|
> let openurlHandler: OpenurlTitleDataHandler // §3.4.2
|
||||||
|
> // 其它单点：accreditLogin / friendsShare / browser / SwitchOverGameData /
|
||||||
|
> // opensaoma stub 留在 LobbyHandlers 本体
|
||||||
|
>
|
||||||
|
> public func register() {
|
||||||
|
> audioHandlers.register()
|
||||||
|
> deviceHandlers.register()
|
||||||
|
> locationHandlers.register()
|
||||||
|
> shakeHandlers.register()
|
||||||
|
> openurlHandler.register()
|
||||||
|
> registerLobbyOnly() // accreditLogin / friendsShare / browser / SwitchOverGameData / opensaoma
|
||||||
|
> }
|
||||||
|
> }
|
||||||
|
> ```
|
||||||
|
>
|
||||||
|
> 下方 monolithic register 调用清单**作为 20 项接口的速查表保留**（与 Contract §3.1 编号对账用），实际实施请按上述 sub-struct 拆分。
|
||||||
|
|
||||||
```swift
|
```swift
|
||||||
|
// LobbyHandlers 聚合视角的 20 项接口速查表（与 Contract §3.1 编号一一对应）
|
||||||
func register() {
|
func register() {
|
||||||
// 登录 / 分享
|
// 登录 / 分享 （留在 LobbyHandlers 本体）
|
||||||
bridge.register("accreditlogin", handler: accreditLogin)
|
bridge.register("accreditlogin", handler: accreditLogin) // §3.1 ［1］
|
||||||
bridge.register("friendsSharetypeUrlToptitleDescript", handler: friendsShare)
|
bridge.register("friendsSharetypeUrlToptitleDescript", handler: friendsShare) // §3.1 ［2］
|
||||||
// 音频 / 录音
|
// 音频 / 录音 （AudioHandlers, §8.1.1）
|
||||||
bridge.register("srcIsloop", handler: srcIsLoop)
|
bridge.register("srcIsloop", handler: srcIsLoop) // §3.1 ［3］
|
||||||
bridge.register("prepareaudio", handler: prepareAudio)
|
bridge.register("prepareaudio", handler: prepareAudio) // §3.1 ［4］
|
||||||
bridge.register("mediaTypeAudio", handler: mediaTypeAudio)
|
bridge.register("mediaTypeAudio", handler: mediaTypeAudio) // §3.1 ［5］
|
||||||
bridge.register("voicePlaying", handler: voicePlaying)
|
bridge.register("voicePlaying", handler: voicePlaying) // §3.1 ［6］
|
||||||
// 摇一摇 / 振动
|
// 摇一摇 （ShakeHandlers, §8.7）
|
||||||
bridge.register("startshake", handler: startShake)
|
bridge.register("startshake", handler: startShake) // §3.1 ［7］
|
||||||
bridge.register("stopshake", handler: stopShake)
|
bridge.register("stopshake", handler: stopShake) // §3.1 ［8］
|
||||||
bridge.register("SwitchShake", handler: switchShake)
|
bridge.register("SwitchShake", handler: switchShake) // §3.1 ［9］
|
||||||
bridge.register("vibrator", handler: vibrator)
|
// 振动 + 剪贴板 + 设备 （DeviceHandlers, §8.4.1）
|
||||||
bridge.register("repeatvibrator", handler: repeatVibrator)
|
bridge.register("vibrator", handler: vibrator) // §3.1 ［10］
|
||||||
bridge.register("canclevibrator", handler: cancelVibrator)
|
bridge.register("repeatvibrator", handler: repeatVibrator) // §3.1 ［11］
|
||||||
// 剪贴板
|
bridge.register("canclevibrator", handler: cancelVibrator) // §3.1 ［12］
|
||||||
bridge.register("gamepastetext", handler: gamePasteText)
|
bridge.register("gamepastetext", handler: gamePasteText) // §3.1 ［13］
|
||||||
bridge.register("gameCopytext", handler: gameCopyText)
|
bridge.register("gameCopytext", handler: gameCopyText) // §3.1 ［14］
|
||||||
// 网页 / 浏览器 / 跳子游戏
|
bridge.register("getphoneInfo", handler: getPhoneInfo) // §3.1 ［21］
|
||||||
bridge.register("OpenurlTitleData", handler: openUrlTitleData)
|
// 网页 / 浏览器 / 跳子游戏 （OpenurlTitleDataHandler §3.4.2 + LobbyHandlers 本体）
|
||||||
bridge.register("browser", handler: browser)
|
bridge.register("OpenurlTitleData", handler: openUrlTitleData) // §3.1 ［15］
|
||||||
bridge.register("SwitchOverGameData", handler: switchOverGameData)
|
bridge.register("browser", handler: browser) // §3.1 ［16］
|
||||||
// 定位 / 设备 / 扫码
|
bridge.register("SwitchOverGameData", handler: switchOverGameData) // §3.1 ［17］
|
||||||
bridge.register("startlocation", handler: startLocation)
|
// 定位 （LocationHandlers, §8.6）
|
||||||
bridge.register("getphoneInfo", handler: getPhoneInfo)
|
bridge.register("startlocation", handler: startLocation) // §3.1 ［20］
|
||||||
bridge.register("opensaoma", handler: openSaoma) // ⚠️ 空实现仍要注册
|
// 扫码 stub （LobbyHandlers 本体）
|
||||||
|
bridge.register("opensaoma", handler: openSaoma) // §3.1 ［22］ ⚠️ 空实现仍要注册
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|||||||
Reference in New Issue
Block a user