daoqi/youle_app_ios_v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
101 Commits 1 Branch 0 Tags
93bbbc3d597974da97bed55a59999f7c9dae3967
Commit Graph
61 Commits
Author SHA1 Message Date
joywayerandClaude Opus 4.7 93bbbc3d59 修复 1.8.2 WXApi 调用：用 Swift 简化后的方法名 
Swift 编译器对 ObjC API 自动应用名称简化规则（Swift 3+ SE-0044），
即使是 1.x 老 SDK header 也会被简化。ObjC selector 不变，运行时
仍调 +[WXApi getApiVersion] / +[WXApi sendReq:]，但 Swift 端必须
写简化后的名字：

- ObjC +(NSString *)getApiVersion → Swift WXApi.getVersion()
- ObjC +(BOOL)sendReq:(BaseReq*)req → Swift WXApi.send(_:)

错误信息里 Swift 编译器明确给出："has been renamed to 'getVersion()'"
+ "obsoleted in Swift 3"。

注释里同步说明 selector 与 Swift 名映射关系，避免未来维护者误以为
我们调到的是 2.x SDK 的 getVersion（实际仍是 1.8.2 的 getApiVersion）。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 09:13:08 +08:00
joywayerandClaude Opus 4.7 05f1396645 微信 SDK 降级 2.0.5 → 1.8.2（与 daoqi msext 同款，避开 UL 强制） 
H5 调 accreditlogin 后 sendAuthReq success=false，根因：微信 OpenSDK
2.0.x 强制 Universal Link，传空串被 SDK 拒绝；daoqi msext 用 1.8.x 不强制
UL，多年稳定上线。沿用 1.8.2 避免无谓的 UL 运维负担（HTTPS 域名 + AASA +
微信开放平台审核 30min-1d）。

文件改动：
- 新增 Vendor/WechatSDK/v1.8.2/{WXApi,WXApiObject,WechatAuthSDK}.h +
  libWeChatSDK.a（16MB，fat: i386+armv7+armv7s+x86_64+arm64，从 daoqi
  msext/Class/SDKExport/ 直接拷贝）
- 删除 Vendor/WechatSDK/WechatOpenSDK-NoPay.xcframework（2.0.5）
- 新增 ylgamehall/ylgamehall-Bridging-Header.h（1.x .a 无 Swift module，
  必须通过 Bridging Header 导入 WXApi.h / WXApiObject.h）

代码侧（5 个 Swift 文件）：
- WeChatSDK.swift：register() 改为 1.x 单参数 WXApi.registerApp(appID)，
  去掉 universalLink 参数；handleOpenURL 不变（1.x/2.x 同款）
- WeChatManager.swift：去掉 #if canImport(WechatOpenSDK) 守卫（Bridging
  Header 直接导入，符号编译期必在）；authorize sendAuthReq 改 1.x BOOL
  返回（无 completion）；shareLink/shareImage 改 WXApi.sendReq(req)
  （1.x BOOL 返回，无 completion）；getVersion → getApiVersion
- AccreditLoginHandler / WechatShare：同样去掉 canImport 守卫和 stub 分支
- BackGameDataHandler：更新注释说明 1.x WXApi delegate 由 sendAuthReq
  逐次传入，WeChatManager singleton 持有不需要清理（1.x 早期 setDelegate:
  API 已废弃）

文档：
- Vendor/WechatSDK/README.md 重写，说明 1.8.2 决策原因 + 文件结构 +
  Xcode 接入 5 步 + M Mac simulator 已知限制
- docs/SDK-Integration-Guide.md §A.1 同步重写

⚠️ **本 commit 后 BuildProject 会失败**，需要用户在 Xcode UI 完成 5 步：
1. 删 Frameworks 里旧 WechatOpenSDK-NoPay.xcframework 引用
2. Add Vendor/WechatSDK/v1.8.2/libWeChatSDK.a（Do Not Embed）
3. Add 4 个系统库：libz.tbd / libsqlite3.tbd / Security.framework /
   CFNetwork.framework（Do Not Embed）
4. Build Settings → Header Search Paths += $(PROJECT_DIR)/Vendor/WechatSDK/v1.8.2
5. Build Settings → Objective-C Bridging Header = ylgamehall/ylgamehall-Bridging-Header.h

详细操作步骤见 Vendor/WechatSDK/README.md「Xcode 接入步骤」。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 08:27:40 +08:00
joywayerandClaude Opus 4.7 a060f29070 微信授权诊断 print：定位 H5 调用 → 拉起微信卡在哪一步 
H5 调 accreditlogin 仍无反应。加临时 print 排查链路：

AccreditLoginHandler:
- 入口"H5 调用命中 ✅" → 确认 WVJB 协议握手 + handler 注册 OK
- canImport(WechatOpenSDK) 真值 → 确认 SDK 是否真链接进了 binary
- Task @MainActor 入口 → 确认 actor hop 没卡死
- 失败分支区分用户取消（errCode -2）/ 其它

WeChatManager.authorize():
- isWXAppInstalled() → 用户手机是否真装了微信
- getVersion() → 加载的 SDK 版本字符串（验证链接的 framework）
- topmostViewController() nil 检测 → present 上下文是否拿到
- sendAuthReq completion success=true/false → SDK 是否成功拉起微信 app

跑一次 H5 调 accreditlogin 看 Xcode console 输出序列，按 print 出现/缺失
精确定位卡点（H5 没调进来 / SDK 未链接 / VC 拿不到 / SDK 拉起失败）。
排查完成后可删除 print。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 07:36:57 +08:00
joywayerandClaude Opus 4.7 624dd93c65 修复微信授权无响应：authorize 改用 sendAuthReq:viewController:delegate: 
H5 调 accreditlogin 后无反应。对照 daoqi msext 找到根因：

msext NewRootVC.m → WXApiRequestHandler.m:sendAuthRequestScope: 用的是
`[WXApi sendAuthReq:req viewController:vc delegate:[WXApiManager sharedManager]]`
（新版 SDK 2.x 推荐路径，传 viewController + delegate）。

而 ylgamehall 之前用 `WXApi.send(req)`——旧版 1.x 方法，新版头里已无声明，
不传 viewController（SDK 无法弹起微信 modal context）+ 不传 delegate
（SDK 不知道往哪发回包）= H5 调了无反应。

修复：
- authorize：改用 `WXApi.sendAuthReq(_:viewController:delegate:completion:)`，
  传当前最顶层 VC（新增 topmostViewController() helper：connectedScenes →
  foregroundActive windowScene → keyWindow.rootVC → 穿过 presented / nav.visible）
  + self（WXApiDelegate）。completion 处理拉起失败立即 fail continuation。
- shareLink / shareImage：从旧 send 改新 `WXApi.send(_:completion:)`
  （sendReq:completion: 的 Swift 桥名）。分享回包仍由 SceneDelegate
  openURL → WXApi.handleOpen(url:delegate:WeChatManager.shared) → onResp
  路径接收，不需要在 send 时再传 delegate。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 07:33:58 +08:00
joywayerandClaude Opus 4.7 be09e6e697 splash 进度条宽度从屏幕 45% 加长到 70% 
原 0.45 倍宽度在横屏中央显得偏短，下载进度反馈不够明显。加长到 0.7 倍
更接近常见 app 启动进度条视觉。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 07:29:57 +08:00
joywayerandClaude Opus 4.7 1247c14351 splash 启动图改 scaleAspectFill 全屏覆盖（与 WebView 同款撤销黑边） 
接上一 commit f4307cc（WebView 全屏铺满）：splash 启动图也应保持一致策略，
否则启动瞬间（iOS 系统 LaunchScreen）和过渡期（SplashOverlay）仍会显示
左右大黑边，与 WebView 全屏的视觉不连续。

3 处 contentMode 从 scaleAspectFit 改为 scaleAspectFill：
- LaunchScreen.storyboard（iOS 启动瞬间）
- WebContainerViewController 内 SplashOverlay.imageView
- SubGameViewController 内 SplashOverlay.imageView

scaleAspectFill 行为：素材 1136×640（16:9）在现代 iPhone 横屏（19.5:9）
上高度撑满，宽度按比例放大→左右轻微裁切。启动图左右是空白底色，logo
+ 文字主体居中可见，裁切无影响。

等价 daoqi msext LaunchImage Asset Catalog 时代「启动图覆盖整屏」体感。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 07:26:15 +08:00
joywayerandClaude Opus 4.7 f4307ccc80 WebView 改全屏铺满（与 daoqi msext 同款），撤销 16:9 letterbox 
用户反馈：现代 iPhone 横屏（19.5:9 比例）下 16:9 letterbox 出现明显
左右大黑边，与原项目视觉不一致。

调研 daoqi msext NewRootVC.m:256：实际用 CGRectMake(0, 0, DEVW, DEVH)
直接全屏 WKWebView，没有任何 letterbox。H5 viewport 自身处理设计稿
（1280×720）→ 设备实际宽高的伸缩。msext 上线多年用户已习惯此视觉。

改 WebContainerViewController + SubGameViewController 的 setupBridgedWebView：
- 去掉 16:9 aspect 约束 + 居中 + width/height max/fill 优先级方案
- 改为 top/bottom/leading/trailing 四 edge 直接撑满 view

文件头注释同步：从「16:9 letterbox」改为「全屏铺满」。
原 Design §6.3.5 的 letterbox 决策已被现网实测推翻，未来如某些 H5
页面需要恢复 letterbox 再单独抽 LetterboxLayout（YAGNI）。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 07:23:34 +08:00
joywayerandClaude Opus 4.7 4ca4459ad5 启动期错误态精确分类：NWPath 区分真断网/权限拒，按钮语义动态切换 
用户反馈：之前的文案统一映射 NSURLError code，没区分"真没网"和"权限
被拒"——两类 iOS 14+ 上都报 -1009，但 NWPath.unsatisfiedReason 里有
wifiDenied / cellularDenied 标记可精确区分。点击重试时也没有针对权限
被拒场景做特殊处理（重发请求被同样的权限决定拒绝，原地循环）。

改动：

1. **NWPath snapshot 精确分类**
   - 新增 BootErrorKind: noNetworkAccess / wifiDenied / cellularDenied /
     networkTimeout / networkCannotReach / localResourceMissing / unknown
   - 新增 currentPathSnapshot() async：临时 NWPathMonitor 等首次 update
     拿当前 path
   - classifyBootError 接 path 参数：先看 NWPath.unsatisfiedReason
     （iOS 14.2+）区分权限拒/真断网；fallback 才按 NSURLError code
   - runBootPipeline 的 catch 内 await snapshot，传入精确 kind

2. **按钮语义按 kind 切换**（同一个按钮承担双语义，UX 一致）
   - 权限拒（wifiDenied / cellularDenied）→ 按钮显示"前往设置"，
     点击跳 UIApplication.openSettingsURLString
   - 其他（noNetworkAccess / timeout / unreachable / localResource）→
     按钮显示"重试"，点击重跑 runBootPipeline
   - SplashOverlay.showError 加 actionTitle 参数，通过 UIButton.Configuration
     动态改 title

3. **didBecomeActive 自动重试**（行业最佳做法）
   - 权限拒分支跳设置时挂 UIApplication.didBecomeActiveNotification 监听
   - 用户在设置改完权限切回 app → 自动 runBootPipeline → 进入大厅
     无需用户再点任何按钮
   - 一次性 observer：触发后自动取消，避免重复
   - runBootPipeline 入口同时 stop NWPathMonitor + stop settingsReturnObserver
     保证多次重试干净

文案精确化：
- noNetworkAccess："当前未联网 / 请检查 Wi-Fi 或蜂窝数据后重试"
- wifiDenied："未授权使用无线局域网 / 请前往 iOS 设置 → 本应用 → 打开
  「无线数据」，授权后将自动重试"
- cellularDenied："未授权使用蜂窝数据 / 请前往 iOS 设置 → 本应用 → 打开
  「无线数据」，或连接 Wi-Fi 后重试"

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 07:19:50 +08:00
joywayerandClaude Opus 4.7 0e446df97a splash 进度条配色：systemBlue 填充 + .label 15% alpha 轨道 
跟错误态"重试"主按钮 systemBlue 视觉一致；轨道用 .label 系统语义色
的 15% alpha，浅深模式自适应（浅模式淡灰、深模式淡白），在浅色启动图
上比默认 UIProgressView 灰条更显眼。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 07:13:13 +08:00
joywayerandClaude Opus 4.7 34f76e8824 启动期错误态 UX 调整：浅背景深色字，仅保留"重试"按钮 
按用户反馈精简错误态 UI：
- splash 启动图是浅色背景（米白底 + logo + 蓝色文字），白色文字在上面
  看不清。错误态显示时改为 backgroundColor = .systemBackground（浅模式
  白、深模式黑），同时隐藏启动图 imageView，文字用 .label / .secondaryLabel
  系统语义色确保两种 appearance 下都对比清晰
- 去掉"前往系统设置"次按钮：仅保留蓝色填充主按钮"重试"
- "无法连接服务器"文案删去"或前往系统设置"尾句

"权限弹窗"诉求的实际实现：
重试按钮直接重跑 runBootPipeline → RemoteConfigClient.fetch →
URLSession.dataTask 重新发起请求。这正是 Apple 推荐的"让网络请求
自然触发权限弹窗"模式：
- 首次启动若系统网络权限弹窗未响应/被拒，重新发请求会再次触发系统
  对权限状态的评估，可能复弹
- 用户在 iOS 隐私管理里改了权限后回 app，点重试就能成功
- NWPathMonitor 也在静默监听，切到正常网络后无需点击即自动重试

不需要额外的"手动申请权限" API 代码（iOS 没有公开的 API 强制弹起
被拒绝的网络权限弹窗）；现有「重新发请求」即是教科书做法。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 07:10:23 +08:00
joywayerandClaude Opus 4.7 5731588d33 启动期错误处理 v2：撤回降级，splash 错误态 + NWPathMonitor 自动重试 
撤回上一 commit 74f6925 的"远端 config 失败就降级进大厅"路径——错过升级
判定 = 用户用旧 IPA 不被强制升级 = 业务风险。新策略：

**远端 config 失败 → 停留 splash 显示错误态**（不弹 modal alert / 不暴露原始 NSError）

行业主流方案：
1. SplashOverlay 扩展错误态 UI（隐藏 label / progress，显示 title +
   message + "重试" 主按钮 + "前往系统设置" 次按钮），通过 onRetry /
   onOpenSettings closure 与 controller 解耦
2. WebContainerViewController.presentBootError 按 BootErrorKind 分类给出
   友好文案（networkOffline / networkTimeout / networkCannotReach /
   localResourceMissing / unknown）
3. 启动期独立 NWPathMonitor，仅在"从无网变有网"时静默自动重试一次
   （初始 nil 状态不触发，避免死循环；用户切到 Wi-Fi 后无需手动操作）
4. runBootPipeline 重新进入时 stopBootRetryWaiting + splash.hideError
   保证多次重试干净（防止 monitor 泄漏）

进大厅的必要条件（恢复严格）：
- ResourceUnzipper.ensureReady 成功（本地 H5 zip 就位）
- RemoteConfigClient.fetch 拿到正确 config（升级判定可执行）
- 本地 appVersion >= 远端（否则走 IPA 升级 modal alert）
- showmessage 为空（否则走运营 modal alert）
- LobbyZipUpgrader 完成（含跳过升级 / 真升级两路径）

业务流程信号（operationalMessage / ipaUpgradeRequired）继续用 modal alert
（这两类不是错误，是产品决策的弹窗永停）；技术错误（网络/解压/写文件等）
统一进 splash 错误态 + 自动重试。

raw error 仍 print 到 Xcode console（含 NSURLErrorDomain code 等开发期
排查信息），用户视角永不暴露技术细节。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 06:47:04 +08:00
joywayerandClaude Opus 4.7 74f6925be3 启动期错误处理 UX 改造：优雅降级 + 友好文案，不暴露技术细节 
修复用户反馈的体验问题：网络权限未同意 / 长期不响应权限弹窗时，
启动会弹出"启动失败" + 原始 NSError（"Error Domain=NSURLErrorDomain
Code=-1009 ...大量技术细节..."），用户被吓懵。

按行业主流做法（参考微信/支付宝/网易云音乐启动期错误处理）改两件事：

1. **优雅降级：远端 config 失败 ≠ 启动失败**
   runBootPipelineSteps 把"拉远端 config + 升级判定"整段包 do/catch：
   - 业务流程信号（operationalMessage / ipaUpgradeRequired）正常抛出弹窗
   - 网络 / 解析 / H5 zip 下载任何失败 → 用 LocalVersionReader 构造
     fallback ResolvedVersion，跳过升级判定，直接加载本地 H5 大厅
   - splash 文案区分在线 "加载大厅..." / 离线 "离线加载..."
   - raw error 仍 print 到 Xcode console 便于排查

   理论依据：ResourceUnzipper.ensureReady 之后本地 H5 zip 已就绪，
   远端 config 仅用于升级判定，失败时本地大厅完全可用。

2. **友好文案 + 多按钮 alert（showRetryableAlert）**
   - 新增 BootErrorKind 分类：剥洋葱看 NSURLError code 映射到
     networkOffline (-1009) / networkTimeout (-1001) / networkCannotReach
     (-1003/-1004/-1005/-1009/-1018/-1019/-1020) / localResourceMissing /
     unknown
   - 每类配友好标题 + 正文（"网络未连接"/"网络较慢"/"暂时无法连接服务器"
     而非 raw "Error Domain=..."）
   - 按钮组合按类别：网络类含"去设置"（跳 UIApplication.openSettingsURLString）
     + 重试 + 稍后再说；本地资源类只重试 + 稍后再说
   - "重试" 不强制（"稍后再说" 让用户自由退出，避免单按钮卡死）

结果：用户在断网 / 未授权 Wi-Fi / 测试域名不可达等场景下，splash 多停
约 7s（3 次重试 + 退避）后自动降级进入大厅，**不弹任何 alert**。仅当
本地资源也失效（极罕见）时才弹友好提示，永不暴露原始 NSError。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 03:12:33 +08:00
joywayerandClaude Opus 4.7 a1c5883cc5 Phase 9.2：H5ErrorRelay 把 H5 异常中继到原生 print 
零修改 H5（原则 A）：WKUserScript .atDocumentStart 在业务 JS 跑前 hook
三类异常源：
- `console.error(...)`：保留原函数链式调用 + 转发 args
- `window.onerror`：onmessage / filename / lineno / colno / error.stack
- `unhandledrejection`：reason + reason.stack

走独立的 webkit.messageHandlers.h5error 通道（与 WVJB 不同 channel，不冲突）。
原生侧 MessageProxy weak target 切断 retain cycle。仅 BridgedWebView 安装
（大厅+子游戏），OverlayViewController 是第三方外链，不挂。

开发期价值：H5 出错时 Xcode console 直接能看到 "[H5 onerror] ... at xxx.js:42:8"，
减少调试盲点。生产期 print 走 OSLog，对体积/性能影响极小。

新增：
- Source/Bridge/H5ErrorRelay.swift（@MainActor singleton）

接入：
- BridgedWebView.init：H5ErrorRelay.shared.install(into:) 在 WVJB 之后

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 02:04:46 +08:00
joywayerandClaude Opus 4.7 ded6b5d86b Phase 8.4：PhoneStateMonitor → phonestate 反向 callback 
契约 §3.1 ［14］phonestate 落地。msext 用已废弃的 CTCallCenter（iOS 10+
deprecated）；新外壳改用 CallKit CXCallObserver，对 H5 输出字符串一致：
- "2" = 来电响铃中（hasConnected=false / isOutgoing=false / hasEnded=false）
       或已连接（hasConnected=true）
- "0" = 挂断（hasEnded=true）
- 其它（拨出未连接、保持）不发

新增：
- Source/Resource/PhoneStateMonitor.swift（@MainActor singleton，与 BatteryMonitor /
  NetworkMonitor 同款 pattern；onChange closure + start/stop 生命周期）

接入：
- SubGameViewController.setupExternalSubscriptions：start + onChange
- SubGameViewController.teardownExternalSubscriptions：onChange=nil + stop
- 大厅 WebContainerViewController 不订阅（msext gameController 同款边界，
  契约表注「已注释」表示大厅不发；H5 子游戏才依赖此事件做哑麦/暂停）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 02:01:29 +08:00
joywayerandClaude Opus 4.7 8e4c36d1c8 Phase 4.F：微信截图分享 type=2 / 远端图分享 type=其它 
按 msext gameController.m:637-678 字面行为，WechatShare 按 content.type
分发：
- type=1 → shareLink（已有）
- type=2 → captureScreenshot → JPEG 0.6 + thumb 0.4x → shareImage
- type=其它 → downloadRemote(URL) → JPEG 0.9 + thumb 0.4x → shareImage

新增：
- ImageProvider.scaledThumb(_:scale:)：等价 msext FuncPublic
  imageByScalingAndCroppingForSize 0.4x 缩放；微信 SDK setThumbImage:
  内部再压到 32KB
- WeChatManager.ShareImage 结构 + shareImage(_:scene:) 异步包装
  （WXImageObject + WXMediaMessage.setThumbImage，FIFO 串行复用 sharePending）

契约：与 type=1 一致，调成功 → sharesuccess 反向 callback（success/cancelled
都发）；errCode=-2 → cancelled；其它 errCode → failed。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 01:33:17 +08:00
joywayerandClaude Opus 4.7 a3679aba7d 修复 SDK 真实接入后的 Swift 编译错误 + Xcode 链接配置 
实测三个 SDK（微信 / 高德 / 七牛）链接进 Target 后，暴露出 9 个 Swift 编译错误，逐一修正：

代码侧（5 个 Swift 文件）：
- AMapWrapper：updatePrivacyShow / updatePrivacyAgree 是 AMapLocationManager
  类方法（since 2.8.0），不在 AMapServices 上；改为 AMapLocationManager.*
  并补 import AMapLocationKit
- BackGameDataHandler：删 `WXApi.delegate = nil`。新版 SDK 2.x 无 static
  delegate API，delegate 由调用方逐次传给 handleOpenURL/sendAuthReq 并被
  SDK 弱引用；WeChatManager singleton 长生命周期不析构，无需 cleanup
- QiniuConfig / QiniuTokenSigner：所有 static 成员标 nonisolated，让 actor
  QiniuUploader 可直接调，无需 await MainActor.run
- QiniuUploader：QNUploadManager() 在七牛 SDK 8.x 已 kQNDeprecated，改用
  initWithConfiguration: + defaultConfigurationV2

工程侧（pbxproj，Xcode UI 自动写入）：
- 新 Frameworks group 容纳 Vendor/WechatSDK / Vendor/AMap 引用
- WechatOpenSDK-NoPay.xcframework：Embed & Sign（动态库）
- AMapFoundationKit / AMapLocationKit：Do Not Embed（静态 fat .framework）

BuildProject 验证：Swift 全部编译通过；剩余 AMap fat framework arch 冲突
（M Mac iOS-simulator）是工程配置选择，下个 commit 处理。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 01:03:29 +08:00
joywayerandClaude Opus 4.7 1d7e258130 Phase 4.E + Phase 5 + Phase 3.C 七牛上传：代码侧 SDK 接入（SPM 优先 / Vendor 兜底） 
选型（CLAUDE.md ADR-006「SPM 优先 + Vendor xcframework 兜底」）：
- 微信 → SPM（Tencent 官方 https://github.com/Tencent/WechatOpenSDK-XCFramework）；
  项目方下载的 WechatOpenSDK-NoPay.xcframework 已撤出 Vendor，docs/res 内副本作离线备份
- 高德 → Vendor 手动（官方未提供 SPM；Vendor/AMap/{AMapFoundationKit,AMapLocationKit}.framework
  随仓库分发，fat .framework 同时含 x86_64 + arm64，Do Not Embed）
- 七牛 → SPM（https://github.com/qiniu/objc-sdk v8.9.x）

代码侧（全部 #if canImport 守卫，Xcode 加 SDK 前编译为 no-op）：
- Source/SDK/WeChat/WeChatSDK.swift：WXApi.registerApp + handleOpenURL（沿用 msext AppID
  wx586a9b321e56efb7，universalLink 空字符串走非 ULAPI 路径）
- Source/SDK/WeChat/WeChatManager.swift：WXApiDelegate + state UUID 配对的 authorize +
  FIFO 串行 share async/await wrapper
- Source/Login/WeChatAuth.swift：客户端直拼 sns/oauth2/access_token + sns/userinfo →
  7 字段（Province 大写 P / city 经 danbian 去单引号），沿用 msext 同款路径
- Source/SDK/AMap/AMapWrapper.swift：iOS 14+ 隐私合规 3 步 + apiKey 注入
- Source/Location/LocationService.swift：actor + AMapLocationManager 异步包装 + 9 字段
- Source/Network/QiniuConfig.swift：4 项常量沿用 msext（AccessKey/SecretKey/Bucket/Domain）
- Source/Network/QiniuTokenSigner.swift：纯 Swift CryptoKit HMAC-SHA1 + Base64URL 自签
  token（与 msext QiniuManager.m:200-230 等价，不依赖 Qiniu SDK 工作）
- Source/Network/QiniuUploader.swift：actor 包 QNUploadManager async/await

Handler 升级：
- AccreditLoginHandler：拉起授权 → 反向 callback sharelogin 7 字段
- WechatShare：真实链接分享（type=2/3 截图待 Phase 4.F）
- StartLocationHandler：真实定位 → 9 字段（latitude/longitude string, province 小写 p）

生命周期：
- AppDelegate.didFinishLaunchingWithOptions：WeChatSDK.register + AMapWrapper.bootstrap
- SceneDelegate.openURLContexts：WeChatSDK.handleOpenURL 接入回调
- BackGameDataHandler：子游戏 backgameData pop 时 WXApi.delegate=nil + LocationService.stop()

Info.plist：CFBundleURLTypes 加 wx586a9b321e56efb7；LSApplicationQueriesSchemes 追加
weixin/weixinULAPI/weixinURLParamsAPI；NSLocationWhenInUseUsageDescription +
NSMicrophoneUsageDescription（gamehallname 中文文案）。

.gitignore：排除 docs/res/{AMap_iOS_Loc_ALL,objc-sdk-8.9.2}/（235MB 项目方下载副本，
已走 SPM/Vendor 接入不需要副本）。

文档：docs/SDK-Integration-Guide.md 重写 §A 用户手动 Xcode UI 三步（SPM × 2 +
Add Files × 2）；Vendor/{AMap,WechatSDK}/README.md 记录各自接入路径选型。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 22:22:23 +08:00
joywayerandClaude Opus 4.7 0427bb9542 Phase 7 完整实现：OpenurlTitleData 弹层（OverlayViewController + 3 个 settings） 
- AppCoordinator 扩 OverlayRequest + lastOverlayAt（3s 节流 / 栈深 < 3 守门） +
  showOverlay / popOverlay（data==nil 仅 pop 即 finishweb 路径；
  data!=nil 同时发 .subGameDidReturn 即 backgameData 路径）
- 新增 Source/WebView/OverlayViewController.swift：独立 WKWebView，
  WKWebViewConfiguration.websiteDataStore = .nonPersistent() 隔离 Cookie / 缓存；
  .atDocumentEnd 注入 polyfill：window.settings = {browser/finishweb/backgameData}
  → webkit.messageHandlers.<name>（与 WVJB 不同 channel 可同名共存）；
  ScriptMessageProxy weak target 切断 retain cycle
- OpenurlTitleDataHandler 升级为真实 push：解 url / "title "（末尾空格契约）/
  data / orientation → AppCoordinator.showOverlay，cb 字面始终回 "OpenurlTitleData"
- SubGameViewController.setupExternalSubscriptions 也订阅 .subGameDidReturn
  （overlay 可从子游戏 push，pop 回子游戏时需要 callback 子游戏 H5 的 getWebdata；
  与 viewWillAppear/Disappear 生命周期对齐，栈顶才挂钩避免双发）
- orientation 字段保留契约但 landscape-only app 暂不实施旋转（msext 旋转 transform
  在我们项目里无意义，记注释，如有 H5 反馈再补）
- Plan §5.7.1-7.7 / §8 进度已勾选

至此 SwitchOverGameData → push 子游戏 / OpenurlTitleData → push 弹层 / backgameData ↔
finishweb → pop + getWebdata 反向闭环全部接通。栈深永远 ≤ 3。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 21:30:03 +08:00
joywayerandClaude Opus 4.7 5b67e414b3 BackGameDataHandler：补 SDK 接入 TODO 清单（防止未来漏清理） 
记录 Phase 4.E 微信 / Phase 5 定位 / Phase 3.B-D 录音上传 / Phase 8 Agora
真实接入时必须在此处补的对应清理钩子（msext 在 backgameData / cleanUpAction
里逐项清理；我们当前 stub 状态无需要清的状态，但落地任一 SDK 后必须回到此处补 1 行）。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 21:23:56 +08:00
joywayerandClaude Opus 4.7 c77037f407 Phase 8 视频房间 3 件套 stub：createRoom / getVideoinfo / exitRoom 
业务暂未启用视频功能，按运营确认仅维持桥契约，让 H5 子游戏调用不报 "no handler"。

- 新增 Source/Bridge/Handlers/VideoRoomHandlers.swift：单一 enum.register 3 个 stub，
  各自 callback 字面回包名（与 OpenSaomaHandler 同款 stub 模式）
- SubGameViewController.registerBridgeHandlers 挂上 VideoRoomHandlers
- 不抽 VideoRoom protocol / NoopVideoRoom 类（违反"不为假设的未来需求设计"原则）；
  未来重新接入 Agora 时把 3 个 stub 展开实现即可，注册点不变
- Plan §5.6.3 / §5.8.1-8.3 进度已勾选

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 21:19:55 +08:00
joywayerandClaude Opus 4.7 5f3a435180 Phase 6 commit C：backgameData pop + getWebdata 反向 callback 
- 新增 Source/Bridge/Handlers/BackGameDataHandler.swift（仅 SubGameViewController 注册）：
  - 调 AudioPlayer.stopAllBackground 停背景音
  - AppCoordinator.popSubGame(returningData:) → popViewController + 发 .subGameDidReturn
  - data 兼容 string / object（非字符串走 JSONSerialization 序列化透传）
  - 字面 cb "backgameData"（msext gameController.m:691-709 等价，
    WXApi 清理跳过 — 微信 SDK 待 Phase 4.E）
- AudioPlayer.stopAllBackground：无条件停背景音（msext 不看 type 直接 nil 行为）
- SubGameViewController.registerBridgeHandlers：挂上 BackGameDataHandler，
  注释更新 exitRoom/getVideoinfo/createRoom 推迟到 Phase 8
- WebContainerViewController：在 setupExternalSubscriptions 挂 .subGameDidReturn
  观察者 → bridge.call("getWebdata", .string(data))，teardown 时 removeObserver
  （生命周期与 battery/network/appservice 同一对，子游戏栈顶时大厅已 teardown
  避免双发）
- Plan §5.6.3 / 6.5 / 6.6 / §8 进度已勾选

至此 SwitchOverGameData → push 子游戏 → backgameData → pop + getWebdata
完整链路接通；子游戏视频房间（exitRoom/getVideoinfo/createRoom）留待 Phase 8。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 21:05:23 +08:00
joywayerandClaude Opus 4.7 a9eaf86c63 Phase 6 commit B：SubGameDownloader zip 下载 + 解压 
- 新增 Source/Resource/SubGameDownloader.swift（actor）：URLSession + ZIPFoundation，
  缓存命中直接复用（看 {Caches}/{gameDir}/{gameStart}/index.html 是否存在），
  未命中下载 → staging 解压 → 原子 rename（与 LobbyZipUpgrader 同思路；
  msext gameController.m:1340-1401 等价，以 staging 替代 msext 直接覆盖避免半残留）
- SubGameViewController.runBootPipelineSteps：接入 ensureReady，splash 实时更新下载进度，
  移除 commit A 占位的 SubGameBootError
- DownloadProgressDelegate 与 LobbyZipUpgrader 同款就地复制（两处用不抽公共，
  三处出现时再合并）
- Plan §5.6.7 / §8 进度已勾选

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 21:01:53 +08:00
joywayerandClaude Opus 4.7 7a5644053d Phase 6 commit A：AppCoordinator + SubGameViewController 框架 + SwitchOverGameData push 
- AppCoordinator：2s 节流 + 栈深 < 2 守门 + .subGameDidReturn 通知名（Design §2.4.3）
- SubGameViewController：复用 BridgedWebView/Splash/16:9 letterbox/ExternalSubscriptions，
  AppDataWriter(.subGame) 写 4 个 app_*.js；H5 未安装时抛错（待 commit B 接入下载）
- SwitchOverGameHandler：解 Gamedirectory/gamedownloadurl/data → AppCoordinator.showSubGame
  （msext NewRootVC.m:541-566 等价，节流与栈深由 Coordinator 守门，cb 字面始终回）
- SceneDelegate：UINavigationController 承载大厅，nav 引用交给 AppCoordinator
- Plan 进度已勾选 §5 / §8（commit B/C 留待 SubGameDownloader 与 backgameData/getWebdata 链路）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 20:59:00 +08:00
joywayerandClaude Opus 4.7 68cf7140d7 Phase 6/7 stub：SwitchOverGameData + OpenurlTitleData 
补齐 H5 桥 §3.1 ［15］［17］两个 stub handler，让 H5 调子游戏切换 / 弹层
入口时不再报 "no handler registered"，避免业务流程卡住。完整流程留
Phase 6 / Phase 7 实施。

新增：
  - Source/Bridge/Handlers/SwitchOverGameHandler.swift §3.1 ［17］stub
    cb "SwitchOverGameData"（驼峰首字母大写沿用 msext 字面）
    完整实现需 AppCoordinator + SubGameViewController + SubGameDownloader
    （Phase 6.4 落地）
  - Source/Bridge/Handlers/OpenurlTitleDataHandler.swift §3.1 ［15］stub
    cb "OpenurlTitleData"
    完整实现需 OverlayViewController + window.settings polyfill + 3s 节流
    （Phase 7 落地）；注意契约硬约束 "title " 末尾空格已在注释提示

WebContainer.registerBridgeHandlers 接入。

至此 H5 桥 §3.1 大厅可调的全部 16 项 handler（除 backgameData / createRoom
等子游戏专属 §H 4 项）都已注册（含完整实现 / stub 两种状态），
H5 启动 / 业务期任何 handler 调用都不会报 "no handler"。

BuildProject 通过

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 20:14:31 +08:00
joywayerandClaude Opus 4.7 39c1b5164d Phase 4.D：DouyinShare URL Scheme + Photos 真实落地（不依赖 SDK） 
移植 msext DouyinShareManager.m:201-269 shareImageToDouyin 完整流程到 Swift。

新增基础设施（Phase 4.F 截图 / 远端图也共用）：

Source/Share/ImageProvider.swift：
  - captureScreenshot() throws -> UIImage：UIGraphicsImageRenderer 截
    keyWindow（含状态栏 + letterbox 黑边 + WebView），与 msext
    FuncPublic.getImageWithFullScreenshot 等价
  - downloadRemote(_:) async throws -> UIImage：URLSession.data(from:)
    下载远端 URL → UIImage 解码
  - ImageProviderError 错误分类（noKeyWindow / downloadFailed / decodeFailed /
    badURL）

Source/Share/PhotoLibrarySaver.swift：
  - save(_:) async throws：使用 PHAccessLevel.addOnly（iOS 14+ 推荐，仅写
    相册不读，弹窗更友好）+ PHAssetChangeRequest.creationRequestForAsset
  - 自动处理权限三态（authorized/notDetermined 请求 + denied/restricted 抛错）

DouyinShare.share 完整实现：
  - 拿图片源：
    * type == "2" 截图 / type == "1" 链接（退化为当前屏截屏，msext 行为）
      → ImageProvider.captureScreenshot
    * type == 其它（远端图 URL）→ ImageProvider.downloadRemote(webpageUrl)
  - PhotoLibrarySaver.save 保存到相册（含 .permissionDenied 错误回 .failed）
  - UIPasteboard.general.image = image 兜底（抖音可能从剪贴板读图）
  - 按 msext 顺序尝试 4 个 URL Scheme：
    snssdk1128://camera / publish / share/image / 基础 scheme
    canOpenURL 命中即 await UIApplication.open + 调起即 success
  - 全部失败返回 .failed("所有抖音 URL Scheme 都调起失败")

Info.plist 加 NSPhotoLibraryAddUsageDescription（"需要将分享内容保存到
相册，以便您在抖音中选取分享"），addOnly 权限弹窗用此文案。

BuildProject 通过

Plan §5 Phase 4.4 勾选

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 20:07:45 +08:00
joywayerandClaude Opus 4.7 aff5ee7633 Phase 4.C：QQShare URL Scheme 真实落地（不依赖 SDK） 
移植 msext QQShareManager.m:716-771 simpleShareToQQFriend 简化版到 Swift。

QQShare.share 完整实现：
  - canOpenURL("mqqapi://") 检测 QQ 安装；未装返回 .notInstalled
  - 仅链接分享走完整 URL Scheme（type == "1"）；type == "2"/其它（截图 /
    远端图）暂返回 .success 避免 H5 业务卡住，Phase 4.F 接入
  - URL 构造（与 msext 等价）：
    * scene == .timeline → mqqapi://share/to_qzone? （QQ 空间）
    * scene == .friend   → mqqapi://share/to_fri?   （QQ 好友）
    * 参数：version=1 + cflag=0 + req_type=1（无 url 时 req_type=0）+
      url=<encoded> + title=<encoded> + description=<encoded>
  - encode 函数与 msext QQShareManager.m:1262-1268 等价：仅保留 RFC 3986
    unreserved 字符（alphanumeric + "-._~"），其它全部 percent encode
  - canOpenURL 二次检查 + await UIApplication.open
  - 调起即视为 success（msext 同款乐观策略，URL Scheme 单向无返回）

Info.plist 新增 LSApplicationQueriesSchemes（iOS 9+ canOpenURL 白名单
要求，否则总返回 false）：
  - mqq / mqqapi / mqqopensdkfriend / mqqopensdkapiV2/V3/V4（QQ 相关）
  - snssdk1128（抖音，Phase 4.D 用）
  - 微信相关待 Phase 4.E 接入 SDK 时再加（weixin / weixinULAPI 等）

BuildProject 通过

Plan §5 Phase 4.3 勾选

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 20:04:36 +08:00
joywayerandClaude Opus 4.7 2ad4563d16 Phase 4.B：SharePlatform 框架 + SharePanel 三选一 UI + ShareCenter 分发 
按 msext gameController.m:575-597 / SharePanel.m 模式落地分享框架。

新增 Source/Share/：
  - SharePlatform.swift：
    * SharePlatform 协议（name / isInstalled / share async → ShareResult）
    * ShareContent struct（nonisolated Sendable，6 字段 sharefriend/sharetype/
      type/webpageUrl/title/desc）
    * ShareResult enum (success / cancelled / notInstalled / failed)
    * ShareScene enum (friend / timeline)
  - SharePanel.swift：
    * @MainActor UIView，半透明黑底覆盖全屏 + 底部圆角内容视图滑入
    * 三按钮（微信绿 / QQ 蓝 / 抖音黑）+ label 等间距居中布局
    * 已安装平台按钮高亮，未装置灰
    * 点击空白区 dismiss + completion(.cancelled)
    * 点击按钮 dismiss + 触发对应 SharePlatform.share + completion(result)
    * 0.25s 滑入/滑出动画
    * 与 msext SharePanel.m 等价行为
  - ShareCenter.swift：
    * sharefriend == "1" → SharePanel.show 三选一
    * sharefriend == "2" → WechatShare.share scene: .timeline 朋友圈
    * 与 msext gameController.m:585 行为 1:1
  - WechatShare.swift：stub（Phase 4.E 等微信 SDK 接入）
  - QQShare.swift：stub + canOpenURL("mqqapi://") 检测（Phase 4.C 升级
    URL Scheme 真实调起）
  - DouyinShare.swift：stub + canOpenURL("snssdk1128://") 检测（Phase 4.D 升级
    URL Scheme + Photos）

FriendsShareHandler 升级：
  - 入参解析为 ShareContent
  - 调 ShareCenter.dispatch
  - completion 内根据 result 触发 sharesuccess 反向 callback：
    * success / cancelled → bridge.call("sharesuccess", {success:"2", type:sharefriend})
    * notInstalled / failed → 不发（H5 业务期 timeout 后自行 fallback，msext 乐观策略）

ShareContent 标 nonisolated 解 Swift 6 actor 隔离（项目默认 MainActor isolation
让 struct 跨 actor 受限）。

BuildProject 通过

Plan §5 Phase 4.2 勾选

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 20:02:34 +08:00
joywayerandClaude Opus 4.7 aa80aec18c Phase 4.A：登录+分享 stub + QQ 改走 URL Scheme 不依 SDK 
按用户约定调整 Phase 4 方向：微信继续走 SDK（等项目方提供），QQ 分享
改用 URL Scheme 直接调起 QQ app，**不依赖 SDK**。

调研 daoqi/msext/Class/Utils/QQShareManager.m 发现已有完整的 URL Scheme
fallback 路径：
  - line 14: __has_include(<TencentOpenAPI/QQApiInterface.h>) 条件编译
  - line 231 注释: "Fallback: 使用 URL Scheme (mqqapi://) - 无需 SDK，
    直接调起 (Legacy)"
  - mqqapi://share/to_fri / mqqapi://share/to_qzone / mqqopensdkfriend://share
    等 schema 实现见 line 733/786/789

新增 handler stub（让 H5 启动 / 业务期调登录 / 分享不报 "no handler"）：
  - Source/Bridge/Handlers/AccreditLoginHandler.swift
    accreditlogin cb "Response from accreditlogin"
    完整实现需 Phase 4.B 微信 SDK + WeChatManager.authorize() + WeChatAuth.exchangeForUser
    + bridge.call("sharelogin", 7 字段含大写 Province) 反向 callback
  - Source/Bridge/Handlers/FriendsShareHandler.swift
    friendsSharetypeUrlToptitleDescript cb "sharefriend"
    完整实现需 ShareCenter 策略分发 + sharesuccess 反向 callback

WebContainer.registerBridgeHandlers 接入。

文档调整：
  - Plan §2.3 阻塞表：QQ OpenSDK 标"不需要"，改 URL Scheme 路径
  - Plan §5 Phase 4 前置：去掉 QQ OpenSDK 一行
  - Plan §5 Phase 4.2：完整改写为 URL Scheme 方案，含 LSApplicationQueriesSchemes
    清单 + URL 构造样例 + "调起即 success" 乐观策略说明
  - Plan §8 进度追踪：4.2 QQ SDK Vendor 标"不需要"
  - Plan §6.4 里程碑加 3 行（前两轮 commit hash 补 + 本次）
  - CLAUDE.md 依赖管理段加 "不接入 QQ SDK" 约定（与"不引入 CocoaPods"
    并列的负面清单）
  - Verification-Checklist Phase 4 章节：E.19/E.20 stub + K/L 待 4.B/4.C
    完整后填充验证项

BuildProject 通过

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 19:19:23 +08:00
joywayerandClaude Opus 4.7 0602b9d4b6 Phase 3.A：srcIsloop 本地音频 + 3.B/3.C/3.D handler stub 
3.A 本地音频完整落地（与 msext NewRootVC initJSdata 等价）：

  Source/Audio/AudioPlayer.swift（@MainActor 状态机）：
    - playOnce(url) 单次按钮音；buttonPlayers 数组保活池避免多次点击
      互相打断（duration + 0.5s 后清理）
    - loopBackground(url, type:) 循环背景音；numberOfLoops = -1 +
      backgroundType 记录用于同名停止
    - stopBackground(type:) 同名校验后才停止（msext 同款语义）

  Source/Bridge/Handlers/LocalAudioHandler.swift：
    - 注册 srcIsloop handler（@MainActor enum）
    - 入参 src + isloop，按 0/1/-1 分支调 AudioPlayer.shared 对应方法
    - audioFileURL 路径：{Caches}/{gamedir}/{gamestart}/assets/wav/{src}
      与 msext NewRootVC 路径约定 1:1（H5 zip 内 assets/wav 子目录）
    - audioFileURL 标 nonisolated 因 SandboxPaths 是 nonisolated 静态
    - cb 字面 "Response from srcIsloop" 严格保持

  Source/Bridge/Handlers/RemoteAudioHandler.swift（3.B/3.C/3.D stub）：
    - prepareaudio + mediaTypeAudio 仅 cb 维持契约，无真实业务
    - 待 Phase 3.B（opencore-amr .a 接入）+ 3.C（七牛 SPM + token）+
      3.D（远端播放）完整后升级
    - 按 CLAUDE.md 原则 A：H5 调啥就得有人接，即使是 stub

WebContainerViewController.registerBridgeHandlers 接入：
  - LocalAudioHandler.register（完整实现）
  - RemoteAudioHandler.register（stub）

Plan §5 Phase 3.1 勾选；3.2 真机验证留待 H5 提供音频文件后做。

Verification-Checklist.md 新增 Phase 3 章节：
  - H. 本地音频（E.14-E.16 srcIsloop 三个 isloop 值）
  - I. prepareaudio / mediaTypeAudio stub（E.17 E.18）

BuildProject 通过

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 19:11:34 +08:00
joywayerandClaude Opus 4.7 09f071e38f Phase 2.C：ExternalSubscriptions 生命周期管理（防双发预备） 
按 Design §2.4.2 把 battery / network / appservice 三组外部事件源的订阅
挂钩与 VC 生命周期配对：viewWillAppear → setup，viewWillDisappear →
teardown。配套约束：未来 Phase 6 子游戏 push 上来时大厅自动 teardown，
避免桥事件双发（栈深 ≤ 2，§2.4.3）。

WebContainerViewController 改造：
  - 新增 setupExternalSubscriptions()：
    * 幂等 start 3 个 monitor（NetworkMonitor / BatteryMonitor /
      AppLifecycleObserver）
    * 设 BatteryMonitor.onChange → evaluateJavaScript("window.app_getbattery=N")
      + bridge.call("getBattery", "%.2f")
    * 设 NetworkMonitor.onChange → evaluateJavaScript("window.app_getnetwork=N")
      + bridge.call("getnetwork", "1"/"2"/"3")
    * 设 AppLifecycleObserver.onBackground/Foreground → bridge.call("appservice",
      "1"/"2")
  - 新增 teardownExternalSubscriptions()：
    * 解绑 onChange / on{Background,Foreground} = nil
    * 释放对 bridge/webView 的 closure 引用避免子游戏 push 后双发
    * monitor 不停（保持后台 currentXxx 状态新鲜），下次 setup 直接 resume
  - viewWillAppear / viewWillDisappear override 调 setup / teardown 配对
  - writeAppDataFiles 精简：只写首次值 + 启动 NetworkMonitor/BatteryMonitor
    （需要 currentXxx 读首次值）；AppLifecycleObserver 启动挪到 setup

至此 Phase 2 全部完成（2.A 8 个 handler + 2.B 5 项反向 callback + 2.C
生命周期管理）。

BuildProject 通过

Plan §5 Phase 2.13 勾选

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 19:02:35 +08:00
joywayerandClaude Opus 4.7 4986f36967 业务期 app_getbattery / app_getnetwork 改为 evaluateJavaScript 重新赋值 
按用户指示调整变化时机制：

  启动期（保持）：loadFileURL 之前写 4 个 app_*.js 文件，H5 同步
    <script src> 引入读到实际值

  业务期（调整）：变化时**不重写文件**，改为
    webView.evaluateJavaScript("window.app_getbattery=N;") 直接重新赋值
    全局变量。原因：H5 已加载完后 <script src> 不会再 fetch，重写文件
    对当前页面无影响（仅影响下次 reload），改 evaluateJavaScript 即时
    生效 + 无文件 IO 开销。

  与 §3.2 反向 callback 双轨同时执行：
    - evaluateJavaScript 让 H5 业务期同步读 app_xxx 永远拿到最新值
    - bridge.call 让 H5 注册的 callback handler 收到事件主动响应

WebContainerViewController.writeAppDataFiles 改动：
  - BatteryMonitor.onChange：Task @MainActor await
    webView.evaluateJavaScript("window.app_getbattery=N;") + bridge.call
  - NetworkMonitor.onChange：同款 evaluateJavaScript + bridge.call
  - AppLifecycleObserver：appservice 无对应 app_* 全局变量，只走 bridge.call

文档同步：
  - Design §7.5.2 改为「两阶段」表述：启动期写文件 + 业务期 evaluateJavaScript
  - Design §7.5.4 接入点代码示例同步
  - Contract §4.2 app_battery.js / app_network.js 子节更新时机段
  - Contract §4.2 修订记录加一行
  - Plan §6.4 里程碑加一行 + 前两轮 commit hash 补充

BuildProject 通过

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 18:50:53 +08:00
joywayerandClaude Opus 4.7 23b3a1fdad Phase 2.B：3 项反向 callback 落地（getBattery / getnetwork / appservice） 
完成大厅业务期实时状态推送给 H5 的事件驱动链路。每次变化时同时（1）
重写对应 app_*.js 文件供下次 reload，（2）bridge.call 反向推送给当前
页 H5 — 双轨与原 msext 行为等价。

新增 Source/Resource/BatteryMonitor.swift：
  - @MainActor public final class BatteryMonitor，shared 单例 + 幂等 start()
  - 监听 UIDevice.batteryLevelDidChangeNotification + 启动期读首次值
  - currentLevel 同步快照（max(level, 0) 兜底模拟器 -1）+ onChange 回调
  - notification block 内 MainActor.assumeIsolated 安全跨到 main actor

新增 Source/Resource/AppLifecycleObserver.swift：
  - @MainActor public final class AppLifecycleObserver，shared 单例 + 幂等 start()
  - 监听 didEnterBackgroundNotification + willEnterForegroundNotification
  - onBackground / onForeground 双钩子；assumeIsolated 同上

WebContainerViewController.writeAppDataFiles 接入（替换 inline addObserver）：
  - 3 个 monitor 启动统一聚合（NetworkMonitor + BatteryMonitor + AppLifecycle）
  - BatteryMonitor.onChange：writeBattery + bridge.call("getBattery", "%.2f")
  - NetworkMonitor.onChange：writeNetwork + bridge.call("getnetwork", "1"/"2"/"3")
  - AppLifecycle.onBackground/Foreground：bridge.call("appservice", "1"/"2")
  - 首次值改读 BatteryMonitor.currentLevel 而非 UIDevice 原始值

至此 Phase 2.B 全部完成（5 项反向 callback：getphoneinfo / getBattery /
getnetwork / appservice / shakeEnd 全部接好）。

剩 Phase 2.C ExternalSubscriptions 生命周期管理（防双发，栈深 ≥ 2 时
下层不发桥事件）。

BuildProject 通过

Plan §5 Phase 2.B 全部勾选

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 18:45:03 +08:00
joywayerandClaude Opus 4.7 d38ff0f8c4 Phase 2.A：大厅 8 个简单 handler 落地 + BridgeData 加 nonisolated 
闭合 Phase 1.17 联调最后一公里（解决 Xcode 日志 4 个 "no handler registered"
+ 提前落地 4 个无外部依赖的简单 handler）。

新增 7 个 handler 模块（Source/Bridge/Handlers/）：
  - ClipboardHandler.swift           §3.1 ［13］［14］剪贴板 UIPasteboard.general
  - ShakeHandler.swift               §3.1 ［7］［8］［9］摇一摇 + §3.2 ［5］shakeEnd 反向
                                       canShake / canVoice 状态 + motionEnded 转发钩子
  - VoicePlayingHandler.swift        §3.1 ［6］actor VoiceCenter.shared 开关位
  - DeviceInfoHandler.swift          §3.1 ［21］+ §3.2 ［1］getphoneInfo 大写 I 入、
                                       getphoneinfo 小写 i 出反向 callback
                                       DeviceInfoSnapshot 6 字段（IDFA 用 idfv 兜底，
                                       CLAUDE.md 不接 ATT/IDFA）
  - BrowserHandler.swift             §3.1 ［16］UIApplication.open async（Task @MainActor
                                       异步打开，闭包先 cb 不等 open 完成）
  - OpenSaomaHandler.swift           §3.1 ［22］空 stub（契约要求注册）
  - StartLocationHandler.swift       §3.1 ［20］Phase 5 完整实现，Phase 2 stub

扩展 VibratorHandler.swift：
  - §3.1 ［10］vibrator（原有）+ ［11］repeatvibrator（msext RootVC.m:1820 沿用：
    实际单次 vibrate 不真循环）+ ［12］canclevibrator

BridgeProtocol.swift BridgeData 加 nonisolated：
  - 项目默认 SWIFT_DEFAULT_ACTOR_ISOLATION = MainActor 让 BridgeData 跨 actor
    访问被拦；asString / asDouble / asInt / asBool / asArray / asObject /
    subscript 全部标 nonisolated（纯值类型本就该是 isolation-free）
  - 影响所有 @Sendable async handler 闭包内的 data?.asXxx 访问

WebContainerViewController 接入：
  - 加 private let shakeHandler = ShakeHandler() 持有
  - registerBridgeHandlers() 注册 8 个 handler 模块
  - 加 canBecomeFirstResponder = true + viewDidAppear becomeFirstResponder
  - 加 motionEnded(_:with:) 转发到 shakeHandler.handleMotionEnded
    （motion 检测必需 first responder，否则不触发）

BuildProject 通过。重装 app 后 H5 启动应不再报 "no handler registered" 错误。

Plan §5 Phase 2.A 全部勾选（含 startlocation bonus stub + BridgeData
nonisolated 重构）。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 18:38:00 +08:00
joywayerandClaude Opus 4.7 0a313afe8e app_appversion 业务语义纠正：审核切换标志 0/1（非版本号） 
调研 daoqi/msext NewRootVC.m:1190-1208 initJSdata 发现 app_appversion
真实业务语义是审核切换标志，**不是 App 的版本号**：

  if (远端 ResolvedVersion.appVersion >= 本地 BundleConfig.appVersion) {
      app_gameconfig = BundleConfig.gameConfig;  // 正常业务接口
      app_appversion = '0';                       // 标志：正常
  } else {  // 远端 < 本地（罕见，审核期 / IPA 已升远端未跟上）
      app_gameconfig = BundleConfig.appleConfig; // 苹果审核期接口
      app_appversion = '1';                       // 标志：审核期
  }

H5 端 if (app_appversion === '1') 切苹果审核期分支；99% 时间下都是 '0'
+ gameconfig。

当前代码两处错误：
  ❌ app_appversion 写成 "43"（版本号字符串）
  ❌ app_gameconfig 永远是 BundleConfig.gameConfig 硬编码

不符合契约（H5 拿到错误标志会走错分支）。按 CLAUDE.md 原则 A 第一准则
必须 1:1 等价 msext。

修复（Source/WebView/AppDataWriter.swift writeAppData）：
  - 加 result 计算：localAppVer = Int(bc.appVersion), remoteAppVer =
    resolvedVersion?.appVersion ?? localAppVer；result = remoteAppVer >=
    localAppVer ? 0 : 1
  - 加 gameConfigStr 切换：result == 0 ? bc.gameConfig : bc.appleConfig
  - app_appversion 写字面 '\(result)' 单引号包裹（与 msext "var
    app_appversion='%d';" 等价）
  - Logger 输出加 result 说明 + local/remote 版本号便于调试

Contract §4.2：新增详细业务语义说明段（含 msext 原 ObjC 代码 + result
0/1 含义解读 + app_gameconfig 动态切换说明），修订记录加一行。

Design §7.5.1 表格：#2 app_gameconfig 数据源改为"动态切换"，#6
app_appversion 数据源改为"审核切换标志"。

Plan §6.4 里程碑加一行。

BuildProject 通过

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 18:28:08 +08:00
joywayerandClaude Opus 4.7 7c856d0d66 AppDataWriter：app_data.js 内 5 个关键字段提到声明顺序最前 
按用户要求调整 app_data.js 内 var 声明顺序，把 H5 调试时最关注的 5 个
核心字段提到最前：

  1. app_gameconfig     远端配置接口
  2. app_market         渠道市场标识
  3. app_agent          登录态 agent
  4. app_channel        渠道 ID
  5. app_Launchtype     大厅(0) / 子游戏(1) 标识

之后按原 msext 顺序：app_version / app_gamedir / app_gamestart /
app_appversion / app_getwifisignalLevel / app_gamename / app_invitationcode。

JS 内 var 声明的顺序对最终读取值无影响（var 提升 + 整段 script 同步
执行完才退出），契约不破，与 msext 行为等价。仅便于 H5 console 一眼
看到核心字段。

Logger.debug 输出顺序同步调整保持与文件内容顺序一致，便于联调对账。

BuildProject 通过

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 18:14:10 +08:00
joywayerandClaude Opus 4.7 829cc8f825 代码层落地 AppDataWriter + NetworkMonitor + WebContainer 接入 
按 Design §7.5 蓝图落地，让 H5 启动时能从沙盒读到实际渠道/启动/设备
值，闭合 Phase 1.17 联调"app_gameconfig 不正确"现象。

新增 Source/WebView/AppDataWriter.swift：
  - public struct AppDataWriter（@MainActor）
  - ContainerRole enum：.lobby / .subGame(name:, dir:)
  - writeInitial()：写 app_data.js（12 项）+ app_gamesname.js（暂只写当前
    gameStart 一项，Phase 6 子游戏完整时扩为扫描已装列表）
  - writeBattery(level:)：写 app_battery.js（var app_getbattery=N;）
  - writeNetwork(code:)：写 app_network.js（var app_getnetwork=N;）
  - 字面严格对齐 msext：
    * 字符串单引号包裹 'value'
    * 数值无引号（version=1 / Launchtype=0 / getwifisignalLevel=1）
    * app_gamesname 用 "var  app_gamesname=new Array(...)"（var 后两空格）
    * 大小写硬约束：Launchtype L 大、getwifisignalLevel wifi 小 + signal/Level 区分
  - escape 转义反斜杠 / 单引号 / 换行（避免渠道字段含单引号导致 H5 JS 解析错）
  - Logger debug 输出文件路径 + 每个 key=value 一行，便于 §7.5.8 联调对账

新增 Source/Resource/NetworkMonitor.swift：
  - @MainActor public final class NetworkMonitor
  - NWPathMonitor 最简 wrap：currentCode 同步快照（默认 2 WiFi，启动后被
    首次 path 更新）+ onChange MainActor 回调
  - shared 单例 + 幂等 start()

WebContainer.runBootPipelineSteps 接入：
  - switch outcome 前提取 let resolved: ResolvedVersion，避免变量作用域
    限制 case 内
  - 新增 writeAppDataFiles(resolved:)：启动 NetworkMonitor + 开 battery
    监控 + 写 4 个文件首次值 + 挂 addObserver(battery) + onChange(network)
  - 调用位置：step 5 LobbyZipUpgrader 之后、step 6 loadFileURL 之前
    （与 msext NewRootVC.initJSdata 等价时序）

BuildProject 通过

Plan §6.4 里程碑加一行。

Phase 1.17 联调验证：启动后 H5 console 应读到实际 app_channel /
app_gameconfig 等值，不再是 H5 zip 包内默认占位。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 12:44:45 +08:00
joywayerandClaude Opus 4.7 c95e80df9c Phase 1.16：SceneDelegate 接 WebContainer + 退役 RootViewController 
- SceneDelegate.scene(_:willConnectTo:options:) 中 rootViewController
  从 M0 占位 RootViewController() 改为 WebContainerViewController()
- 删除 ylgamehall/RootViewController.swift（M0 + Phase 1.2–1.13 烟雾测试
  整体退役）；所有 print 验证记录在 git log，留着是死代码
- File System Synchronized Group 自动适应文件删除，无需改 pbxproj
- BuildProject 通过

至此 Phase 1.16 完成；启动链路：
  SceneDelegate → WebContainerViewController.viewDidLoad
    → setupBridgedWebView + setupSplash + registerBridgeHandlers
    → runBootPipeline (ensureReady → fetch → resolve → upgrade → loadFileURL)
    → didFinish 淡出 splash

Plan 进度已勾选（§5 Phase 1.16 + §8）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 04:23:52 +08:00
joywayerandClaude Opus 4.7 6c943e2924 Phase 1.15：VibratorHandler 单次振动 handler 
新增 ylgamehall/Source/Bridge/Handlers/VibratorHandler.swift：
- 无状态 public enum VibratorHandler，static func register(on:)
- 入参忽略（参考原 msext RootVC.m:1816-1818：time 参数实际不读取）
- 副作用：AudioServicesPlaySystemSound(kSystemSoundID_Vibrate)
- responseCallback：.string("vibrator")，与契约 §3.1 ［10］一致
- 模拟器无振动硬件、调用静默忽略；真机才能感知

WebContainerViewController.viewDidLoad 新增 registerBridgeHandlers()
单一聚合点，Phase 2+ 在此追加更多 handler，便于发现 / 调试。

repeatvibrator / canclevibrator 严格守住 Plan §5 Phase 2.2 范围，不
提前实现。

BuildProject 通过

Plan 进度已勾选（§5 Phase 1.15 + §8）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 04:02:33 +08:00
joywayerandClaude Opus 4.7 a6433d9e95 修复启动图方向：Info.plist 补顶层 UISupportedInterfaceOrientations 
Xcode 26 General → Deployment Info UI 只把 orientation 写入带后缀的
INFOPLIST_KEY_UISupportedInterfaceOrientations_iPhone / _iPad，**没有**
顶层无后缀的 UISupportedInterfaceOrientations。LaunchScreen 阶段 iOS 处于
device idiom 尚未识别的早期窗口，只看顶层无后缀 key —— 缺失时 fallback
到 portrait 渲染再被旋转 90° 适配横屏设备，视觉表现是 splash 内容横躺
在中间一个竖向矩形里。

修复：在 Info.plist 显式补一份无后缀 UISupportedInterfaceOrientations =
landscape。Build 后 .app 内 Info.plist 三个 key（无后缀 + ~iphone +
~ipad）齐全，LaunchScreen 正确按 landscape 渲染。

参考：原 daoqi/msext 用的也是顶层无后缀 key（iOS 9 时代写法）+
ASSETCATALOG_COMPILER_LAUNCHIMAGE_NAME 自动旋转 portrait 资源；新项目
LaunchScreen.storyboard 没有自动旋转魔法，必须显式补 key。

注：开发期间改 Info.plist orientation 后 Xcode 覆盖安装不会刷 iOS
launch snapshot 缓存，需长按删除 app 重装才能看到新效果；终端用户
不受影响（IPA 首次安装即按当前 Info.plist 渲染）。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 03:59:14 +08:00
joywayerandClaude Opus 4.7 0ecfa4fb69 修复 SplashImage 方向：素材逆时针旋转 90° 改为真正横屏 
源素材 docs/res/Res/Default-568h@2x~iphone.png 是 CgBI PNG，物理 640×1136
但画面内容是"横躺"在竖向容器里 —— msext 旧 LaunchImage 系统依赖 device
orientation 自动旋转，现代 LaunchScreen.storyboard 没有这个魔法，直接显示
会看到躺倒的画面（用户反馈：启动图的横竖方向错误）。

处理：
- 用 sips -r -90 -s format png 一次性把素材逆时针旋转 90° 输出为标准
  PNG（顺便去掉 CgBI 优化标志），物理像素 1136×640，覆盖到
  ylgamehall/Assets.xcassets/SplashImage.imageset/SplashImage@2x.png
- LaunchScreen.storyboard 中 <image> 的 width/height 从 640/1136 改为
  1136/640；UIImageView 的 contentMode 从 scaleAspectFill 改为
  scaleAspectFit。aspectFit 在比 16:9 更宽的现代横屏 iPhone（如 16 Pro
  ≈2.17:1）上左右补黑边（黑底无视觉违和），保画面完整不裁切 logo
- WebContainer 的 SplashOverlay 用同款 scaleAspectFit，避免启动 → 容器
  视觉过渡时出现裁切方式跳变
- BuildProject 通过

Plan 进度已勾选（§5 Phase 1.14.b + §8 同步修订）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 03:10:53 +08:00
joywayerandClaude Opus 4.7 f795957eb1 Phase 1.14.e：webView didFinish 后 0.3s 淡出 splash 
把 WKNavigationDelegate.didFinish 里的 splash.isHidden = true 换成
UIView.animate(withDuration: 0.3) 渐变 alpha=0 + completion 内
removeFromSuperview，避免渲染瞬间硬切，也让 view 层级在大厅起来后
完全干净（无空持有的 splash 占位）。

BuildProject 通过

Plan 进度已勾选（§5 Phase 1.14.e + §8）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 02:51:25 +08:00
joywayerandClaude Opus 4.7 f247b81d6d Phase 1.14.d：WebContainerViewController（16:9 letterbox + Splash + 启动流水线） 
新增 ylgamehall/Source/WebView/WebContainerViewController.swift：

- 持有 BridgedWebView（间接持 BridgeBus）+ 文件内私有 SplashOverlay
- 16:9 letterbox 布局：required(aspect 16:9 + width/height ≤ superview)
  + low(width/height = superview) + center{X,Y} 居中。屏幕比 < 16:9 → 上下
  黑边，> 16:9 → 左右黑边。Auto Layout 自动选短边贴边、长边居中
- SplashOverlay：SplashImage(scaleAspectFill) + UIProgressView + UILabel；
  update(text:progress:) 切换状态机
- runBootPipeline 串：ensureReady → "拉取配置中..." → RemoteConfigClient.fetch
  → 分支(.shortText / .parsed → showmessage / IPA 升级 / LobbyZipUpgrader
  with onProgress hop 到 MainActor) → "加载大厅..." → loadFileURL(lobbyIndex,
  allowingReadAccessTo: lobbyRoot)
- 三种 alert：showBlockingAlert（短文本/showmessage，永停）/
  showIPAUpgradeAlert（确定→openURL，永停）/ showFatalAlert（重试→重跑 pipeline）
- WKNavigationDelegate.didFinish 暂用 splash.isHidden = true（1.14.e 改为
  0.3s 淡出动画）
- 横屏锁定 + statusBar 显示（与 RootViewController 一致）

不接 SceneDelegate，1.16 才换 rootViewController；本次仅落地容器代码。
BuildProject 通过

Plan 进度已勾选（§5 Phase 1.14.d + §8）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 02:50:16 +08:00
joywayerandClaude Opus 4.7 f3c66b670d Phase 1.14.c：LobbyZipUpgrader 加 0…1 progress 回调 
- upgradeIfNeeded 新增 onProgress: @escaping @Sendable (Double) -> Void 参数，
  默认 no-op 兼容仅做版本对比的烟雾测试
- 新增文件内私有 DownloadProgressDelegate（URLSessionDownloadDelegate
  + @unchecked Sendable），在 didWriteData 回调里把 totalBytesWritten /
  totalBytesExpectedToWrite 换算成 0…1 上报，clamp 到 [0,1]
- 通过 session.download(from:delegate:) 注入；下载完成后兜底报 1.0
  （部分 server 不发 Content-Length 或末尾片段晚到，避免进度条停在 99%）
- RootViewController 烟雾测试用 ProgressTicker 把回调节流到 10% 阶梯打印，
  避免几百行刷屏（NSLock 保护单 Int 状态，@unchecked Sendable）
- BuildProject 通过

Plan 进度已勾选（§5 Phase 1.14.c + §8）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 02:46:11 +08:00
joywayerandClaude Opus 4.7 ba34854133 Phase 1.14.b：LaunchScreen 替换为启动图（SplashImage） 
- 将 docs/res/Res/Default-568h@2x~iphone.png（msext 时代竖图 640×1136
  CgBI 压缩，29708 字节）拷入 ylgamehall/Assets.xcassets/SplashImage.imageset/，
  Contents.json 声明 universal idiom @1x/@2x/@3x（仅 @2x 提供物理文件）
- 改写 LaunchScreen.storyboard：黑底 + 单个 UIImageView（image="SplashImage"，
  contentMode=scaleAspectFill），四边约束到 superview 完成全屏铺满
- 启动瞬间用户看到的是启动图而非黑屏；竖图在横屏设备上会被 aspectFill
  上下裁剪，启动只展示 0.x s，接受此折衷，Phase 10 polish 时再考虑做
  专门的横屏素材
- BuildProject 通过（55s）

Plan 进度已勾选（§5 Phase 1.14.b + §8）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 02:43:14 +08:00
joywayer 45a8f483bc Phase 1.14.a：替换 AppIcon 为 docs/res 内 msext 旧版图标 
从 docs/res/Images.xcassets/AppIcon-1.appiconset 拷贝 9 个 png +
Contents.json 到 ylgamehall/Assets.xcassets/AppIcon.appiconset，替换
Xcode 默认空 universal 1024 模板。

- 9 个 png 覆盖 iPhone 29x29 / 40x40 / 57x57 / 60x60 三档分辨率 ×
  @1x/@2x/@3x 组合（msext 历史素材，分辨率名 "129x29" 等是文件名
  artifact，实际对应规格表里的 29x29）
- Contents.json 沿用旧版 iPhone-specific idiom，含 iOS marketing
  1024 占位（无文件名）
- BuildProject 通过，actool 3 个 warning 暂不处理（iPad 76/83.5
  缺失 → iOS 自动用 iPhone 缩放；1024 marketing 缺失 → App Store
  上架要求，企业签不强制）；Phase 10 上线前 polish 时补齐
- 顺手发现 BridgedWebView.swift:88 用 WKProcessPool 在 iOS 15+ 被弃用，
  Phase 1.14.d 实施 WebContainer 时一并清理

Plan §5 1.14.a / §8 进度已勾选
 2026-06-22 02:36:59 +08:00
joywayer 0887088bb8 Phase 1.13：LobbyZipUpgrader 完成 H5 zip 升级端到端链路 
Phase 1 远程配置链路（1.10-1.13）最后一环：把 VersionResolver 解出的
gameZip URL 下载 + 解压 + 原子 rename 到 lobbyRoot，触发条件是远端
gameVersion > 本地 version.xml /game/version@value。

- 新增 ylgamehall/Source/Resource/LobbyZipUpgrader.swift
  - public actor，单例 LobbyZipUpgrader.shared
  - upgradeIfNeeded(resolved:) async throws -> Outcome
    - .noop：远端版本 ≤ 本地，或 gameZip nil / 非法 URL，直接返回
    - .upgraded(from:to:)：完成升级，附前后版本号
  - URLSession.download(from:) 异步下载（60s 请求 / 300s 资源超时），
    HTTP 状态码非 2xx 抛 .httpStatus
  - 解压到 caches/lobby-staging-{UUID}/ 隔离目录（不直接覆盖 lobbyRoot，
    msext "removeItem + ZipArchive overWrite:YES" 半途崩溃会留半残；
    我们 staging 完整解压成功后才 rename）
  - 原子 rename：fm.removeItem(lobbyRoot) → fm.moveItem(staging,
    to: lobbyRoot)；任一步失败抛 .stagingMoveFailed，调用方决定回退
  - 类型化 UpgradeError 5 种：badGameZipURL / downloadFailed /
    httpStatus / unzipFailed / stagingMoveFailed
  - 实现照搬 msext NewRootVC.m:1789-1869 downFileFromServer + unzip
    + unzipDone 的语义，但用现代 async + 原子 rename 替代 ASIHTTPRequest
    + detachNewThreadSelector + ZipArchive overWrite:YES
- RootViewController 烟雾测试串接 LobbyZipUpgrader：
  调 upgradeIfNeeded → switch outcome → 升级后重新读 version.xml 验证
- 真机实测端到端链路：
  第一次：本地 260 vs 远端 261 → 升级完成 261，耗时 2.007s
    （下载 11.5 MB HTTP zip + ZIPFoundation 解压 + 原子 rename）
    重新读 version.xml = 261 ✓ lobbyIndex 仍存在 ✓
  第二次：本地 261 vs 远端 261 → .noop，耗时 0.001s（幂等验证）

Phase 1 远程配置链路（1.10-1.13）完整闭环。下一步 Phase 1.14
WebContainer 把这条链路插到 viewDidLoad 之前 + 16:9 letterbox 加载
lobbyIndex，第一次让真实大厅 H5 渲染出来。
 2026-06-22 02:27:48 +08:00
joywayer 9e50c38323 Phase 1.12：LocalVersionReader 读 version.xml + ATS 全局放行 
新增 LocalVersionReader 读两个本地版本号 + Info.plist 加
NSAllowsArbitraryLoads 全局放行 HTTP（为 Phase 1.13 zip 下载链路准备）。

- 新增 ylgamehall/Source/Resource/LocalVersionReader.swift
  - public enum LocalVersionReader，nonisolated static 命名空间
  - localAppVersion: Int 从 BundleConfig.shared.appVersion 转 Int
    （沿用 ChannelConfig.plist 注入），解析失败返回 0
  - localGameVersion: Int 用 Foundation XMLParser SAX 风格解析
    SandboxPaths.lobbyVersionXML 的 /game/version@value 节点，
    缺失 / 损坏返回 0（msext NewRootVC.m:664-682 `[nil intValue]=0`
    兜底语义，是首装后首次升级的关键机制）
  - subGameVersion(dir:start:) 子游戏版本号读取，Phase 6 用
  - 内部 VersionXMLHandler 标 nonisolated（Swift 6 严格并发下
    XMLParserDelegate 跨边界），SAX 风格只在 didStartElement 抓
    version 节点的 value 属性
- Info.plist 加 NSAppTransportSecurity / NSAllowsArbitraryLoads = true
  - 企业签 / 超签分发场景，后端域名易变（zip CDN / 配置服 /
    七牛 / 错误日志上报等），白名单维护成本高于安全收益
  - 全局放行的副作用主要影响第三方 SDK 流量；本项目无意外引入未审计
    SDK，且第三方 SDK 自身一般也走 HTTPS，不受影响
  - 详见 ADR-008 决策上下文与 CLAUDE.md「不上架 App Store，企业签 /
    超签 / TF 分发」契约
- RootViewController 烟雾测试串接 LocalVersionReader：打印本地 vs 远端
  对比 + IPA / zip 升级判定
- 真机实测（现网 .txt 本地 + 当前 IPA 内 gamehall.zip 解压物）：
  - 本地 appVersion = 43, 远端 = 43 → 不升级
  - 本地 gameVersion = 260（IPA 内 2023-12 zip 的 version.xml），
    远端 = 261 → 需要 zip 升级。Phase 1.13 将实现下载 +
    解压 + 替换链路
 2026-06-22 02:24:22 +08:00
joywayer dfbc26a024 Phase 1.11：VersionResolver chulishengji 双子树合并算法 
实现 msext NewRootVC.m:1372-1538 的 chulishengji 双子树合并算法的纯
函数 Swift 版本，把远端 RemoteConfig 化简为 5 个目标字段决策结果
（appVersion / appDownload / gameVersion / gameZip / showmessage）。

- 新增 ylgamehall/Source/Network/VersionResolver.swift
  - public enum VersionResolver + 纯函数 static func resolve
  - public struct ResolvedVersion: Sendable 含 5 字段
  - 内部 SubtreeExtract 中转 4 字段累加结果（每层非空才覆盖）
  - extractAgentSubtree 4 层（agent → channel → market → game 嵌
    market 命中后）按 NewRootVC.m:885-1013 复刻
  - extractGameSubtree 4 层（game → game-self → channel → market）
    按 NewRootVC.m:1015-1180 复刻
  - mergeIPA 默认 agent 赢；game.appVersion > agent.appVersion 时
    game 赢（NewRootVC.m:1416）
  - mergeZip 默认 game 赢；agent.gameVersion > game.gameVersion 时
    agent 赢（NewRootVC.m:1456）
  - showmessage 任意子树非空就用，最后写赢；回退到 config.showmessage
- 字段名 game_download vs game_zip 由 SubtreeExtract.gameZip 统一吸收，
  Codable 模型已用 gameZip 命名，故无需重复查两个 key
- RootViewController 烟雾测试串接 RemoteConfigClient + VersionResolver，
  打印 chulishengji 合并后的 5 字段
- 真机实测（现网 .txt JSON）：
  - appVersion = 43 → 等于本地 BundleConfig.appVersion，不触发 IPA 升级
  - gameVersion = 261 → 远端最新版（本地 version.xml 待 Phase 1.12 读取
    后对比；首装后 version.xml 实测 261 等于本地）
  - gameZip = http://tsgames.daoqi88.cn/zip2/gamehall.zip
    （HTTP，Phase 1.13 下载需 ATS NSExceptionDomains daoqi88.cn）
  - appDownload = itms-services://... 企业签 manifest URL
  - showmessage = ""（无运营公告）
- 单测目前未写（等 Phase 0.2 单测 target 建立后补齐），但生产数据
  已验证算法正确
 2026-06-22 02:18:27 +08:00
joywayer 1bc287bafc Phase 1.10：RemoteConfigClient 完整版（HTTPS + cache-busting + 短文本 + FlexibleString） 
第二轮调研 daoqi/NewRootVC.m 全文核对后，把对原项目远程配置流程的精确
理解固化进 ADR-008 + Design §6.3.2，并补齐 RemoteConfigClient 缺失的
3 个契约（cache-busting query、短文本响应识别、字段类型混乱兼容）。

核心修正：线上热路径是 chulishengji 双子树合并算法（NewRootVC.m:1372-1538），
不是 onnet 简单 4 层覆盖。viewWillAppear 与 gonet 都会强制把当前 agent 的
gamelist 提到 self.gamelist，只要服务器 JSON 含 agent.gamelist（线上 100% 都有），
self.gamelist 就非 nil，走 else 分支 → chulishengji。本次烟雾测试实测：
agent[0].gamelist = 7 个，完美印证 chulishengji 必要性。

- RemoteConfigClient 新增 cache-busting query：?vXXXXXXXXYYYYYYYY（两段 8 位 hex
  连写，无 =，照搬 msext NewRootVC.m:1226 契约），每次重试都重新生成
- 新增 RemoteConfigOutcome enum：.parsed(RemoteConfig) 与 .shortText(String)
  两种成功状态。短文本响应（trim 后 utf16.count ≤ 100）是服务端运营杀手锏 #1，
  msext 当 alert 文本弹窗 + 停止重试（NewRootVC.m:1239-1243）
- UTF-8 解码 + trim 跟 msext NewRootVC.m:1237-1238 严格对齐
- 所有 String? 字段改用 decodeFlexibleStringIfPresent 扩展（兼容 number-as-string）：
  agentid / channelid / marketid / gameid / showmessage / appVersion / appDownload
  / gameVersion / gameZip 全部 9 字段。msext 用 NSNumber.intValue/description 静默
  吞下 number，新外壳 Codable 严格类型必须显式处理
- 远端 URL 从 http 改为 https（后台已切，无需 ATS 例外）
- Plan ADR-008 修订为含 9 个子节（A-I）的精确决策记录，含 chulishengji
  双子树算法、agent 子树结构、game 子树结构、字段级合并优先级、决策顺序、
  与 msext 差异表
- Design §6.3.2 VersionResolver 重写：从"简单 4 层 reduce"改为"chulishengji
  双子树合并 + 字段级合并"，附 13 项单测覆盖矩阵
- RootViewController 烟雾测试切换为 outcome enum switch case，覆盖 .parsed
  与 .shortText 两条路径
- 实测烟雾：HTTPS 拉到 30 KB JSON 解析 .parsed 成功（耗时 2.7s 含 TLS 握手），
  agent[0].gamelist 含 7 个 game 节点，证明 chulishengji 路径是热路径
 2026-06-22 02:14:57 +08:00
joywayer 65505b0a79 Phase 1.9：BridgedWebView 封装 WKWebView + JS 注入 + BridgeBus 
WebContainerViewController（Phase 1.10）的视图层依赖项：把 WKWebView 配置 /
WVJB.js 注入 / 桥总线 / scrollView 契约配置 4 件事一锅端打包成单一 UIView，
后续大厅 / 子游戏 / 弹层 VC 直接 add 进自己的内容区即可。

- 新增 ylgamehall/Source/WebView/BridgedWebView.swift
  - @MainActor final class，继承 UIView
  - 内含 public let webView: WKWebView 与 public let bridge: BridgeBus
  - init() 全自动：
    - WKWebViewConfiguration 按契约 §4.1：
      defaultWebpagePreferences.allowsContentJavaScript = true（iOS 14+
      现代 API，替代已弃用的 preferences.javaScriptEnabled）、
      javaScriptCanOpenWindowsAutomatically = NO、minimumFontSize = 10、
      allowsInlineMediaPlayback = true、processPool = SharedProcessPool.shared
    - 用 WKUserScript(.atDocumentStart) 把 WebViewJavascriptBridge.js 注入
      所有加载的 H5 页面，确保 H5 业务代码运行前 bridge 已就绪
    - 创建 BridgeBus，自动向 controller 注册 WVJBHandler 通道
    - scrollView：bounces=NO / isScrollEnabled=NO（契约硬约束，漏则 H5
      上下滑动失控）/ contentInsetAdjustmentBehavior=.never / 双向无指示器
    - WebView 撑满 self，自动布局
  - SharedProcessPool 命名空间：跨 WebView 共享 WKProcessPool，Cookie /
    资源缓存复用，启动加速（Design §3.5）
- BuildProject 通过，下一步 Phase 1.10 WebContainerViewController 用
  BridgedWebView 嵌入 + 16:9 letterbox + 加载 lobbyIndex
 2026-06-22 00:19:51 +08:00