daoqi/youle_app_ios_v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
143 Commits 1 Branch 0 Tags
a54d1511be4f73003c64845479be2c31a4380e62
Commit Graph
68 Commits
Author SHA1 Message Date
joywayerandClaude Opus 4.7 a54d1511be audio_domain/audio_bucket 改 4 层 fallback + 顶层兜底，修"音频服务不可用"误报 
【bug】
ADR-009 初版只从 RemoteConfig 顶层读 audio_domain / audio_bucket，但渠道方
配置时习惯把这俩字段放在 agent 节点（与 app_version / game_zip 等版本字段同
款层级），导致客户端读到空值后误报 BootError.audioConfigMissing 启动期致命。

【方案】
对齐版本字段的 4 层 fallback 算法：
- Agent / Game / Channel / Market 4 个节点 struct 各加 audioDomain / audioBucket
- RemoteConfigNode 协议加这俩 getter
- VersionResolver 新增 resolveAudio(...) → (domain:String?, bucket:String?)
  逻辑：agent → game → channel → market 倒序找第一个非空，整链空时 fallback 顶层
- WebContainerViewController parsed 分支改用 resolveAudio + print 诊断日志

【兼容性】
顶层 audio_domain / audio_bucket 仍然支持（作为整链兜底），后台不需要改配置
位置；放节点上也能读到——任意一种 layout 都工作。

【文档】
Plan ADR-009 决策表 + 注入时序段 同步更新 + 加 2026-06-27 修订说明记录此次踩坑。

BuildProject 通过，Xcode 诊断 clean。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-27 21:30:10 +08:00
joywayerandClaude Opus 4.7 83d9502dee ADR-009 凭证集中化：AppSecrets.plist + 七牛运行参数走 RemoteConfig.audio_*（契约影响） 
【数据流改造（三分制）】
- 微信 AppID  唯一源 = Info.plist CFBundleURLTypes (URLName=weixin first scheme)
- 应用级凭证 唯一源 = AppSecrets.plist (wxAppSecret/qiniuAccessKey/qiniuSecretKey)
- 七牛运行参数 唯一源 = RemoteConfig 顶层 audio_domain / audio_bucket（远端动态注入）

【契约影响】
- ChannelConfig.plist：11 key → 10 key，移除 qiniudomain（ADR-007 守护规则同步）
- BundleConfig：删除 qiniuDomain 属性
- RemoteConfig：顶层新增可选字段 audioDomain / audioBucket（JSON snake_case 自动归一化）
- 启动期：WebContainerViewController parsed 分支校验 audio_domain/audio_bucket 非空，
  缺失抛 BootError.audioConfigMissing 弹 modal 永停（与 showmessage 同等致命）
- 上线前置：测试 / 生产远端 .txt 配置必须先补 audio_domain / audio_bucket 两个顶层 key
- WeChatSDK.appID / WeChatAuth.appSecret / QiniuConfig.* 调用方零签名变化

【新增】
- ylgamehall/Resources/AppSecrets.plist（3 key）
- ylgamehall/Source/Resource/AppSecrets.swift（单例加载，对齐 BundleConfig 模式）
- QiniuConfig 改 actor：cdnDomain/bucketName 进 actor 状态 + update(...) async；
  accessKey/secretKey 仍 nonisolated（直接读 AppSecrets）
- QiniuTokenSigner.uploadToken() 改 async（bucketName 来自 actor）
- QiniuUploader 预取 cdnDomain 闭包外，SDK 同步 callback 内直接拼 URL

【删除】
- WeChatSDK.swift  static let appID  硬编码 → Info.plist 启动期解析
- WeChatAuth.swift static let appSecret 硬编码 → AppSecrets.shared.wxAppSecret
- QiniuConfig 中 accessKey / secretKey / bucketName / cdnDomain 四处硬编码
- ChannelConfig.plist 的 qiniudomain 字段（plist 与代码双源僵尸字段）

【文档同步】
- Plan：新增 ADR-009 + ADR-007 守护规则改 10 key + §236 BundleConfig 描述
- Design §3.4 多处 "11 项" → "10 项"；§7.0.3 plist 示例 + BundleConfig 代码骨架
  + Scripts/inject_channel.sh 同步
- SDK-Integration-Guide §0 凭证位置改三分制 + §尾"七牛域名读取"加新外壳路径
- Verification-Checklist L69 "（11 项）" → "（10 项）"

参考契约章节：docs/Development-Plan.md ADR-009、docs/H5-Native-Implementation-Design.md §7.0.3
BuildProject 通过，Xcode 即时诊断 0 警告。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-27 21:07:55 +08:00
joywayerandClaude Opus 4.7 8125dd4d11 1.11 修订：VersionResolver 改单链 4 层 fallback，删除双子树合并算法（契约影响） 
【契约影响】
- RemoteConfig 模型：Agent 节点移除 channellist 字段（线上 JSON 实际只挂 gamelist；此前误读 chulishengji 引入的 channellist 是空 schema）
- VersionResolver 解析算法：从"双子树 + 字段级合并"改为"agentlist → gamelist → channellist → marketlist 单链 4 层 fallback"，行为按 daoqi NewRootVC.m:689-810 主路径
- 对外 API ResolvedVersion / resolve(config:agentId:channelId:marketId:gameId:) 签名零变化，WebContainerViewController / SubGameViewController 调用点未动

【设计要点】
- 4 节点类型 conform 同一 private protocol RemoteConfigNode
- 5 字段共用 pickString / pickInt 两个倒序 fallback 工具，不允许为某字段单独写 if 链
- buildChain 集中处理"任一层 id 不匹配立刻截断"语义

【文档同步】
- Design §6.3.2 整段重写
- Plan ADR-008 顶部追加"第三轮修订（2026-06-27）"小节 + 第二轮误读复盘
- Plan ADR-008-D 替换为单链 4 层算法说明 + 保留修订史
- Plan §1.11 / ADR-008-I / 最后更新日期 / Verification-Checklist L73 同步

参考契约章节：docs/H5-Native-Implementation-Design.md §6.3.2、docs/Development-Plan.md ADR-008-D
BuildProject 通过。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-27 20:04:19 +08:00
joywayerandClaude Opus 4.7 800497fd18 新增 H5-Debug-Guide：Safari Web Inspector 调试 H5 控制台的操作手册 
整理大厅 / 子游戏 / 弹层三处 WKWebView 的 isInspectable 启用条件、
Mac Safari 与真机端开关、多 WebView 排查思路（Develop 菜单不刷新等
常见坑），并在 CLAUDE.md 文档索引登记。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-24 21:37:09 +08:00
joywayer 06b7686e17 启动文字提示，h5调试加入 2026-06-24 21:20:05 +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 323fb9074b 修复 AMap 真机链接错：补 3 个系统 framework + 永久文档化 
真机首次跑 ylgamehall 时 linker 报 7 个 Undefined symbol：
- _CNCopyCurrentNetworkInfo / _CNCopySupportedInterfaces / _SCNetworkReachability*
  → SystemConfiguration.framework
- _OBJC_CLASS_$_CTTelephonyNetworkInfo → CoreTelephony.framework
- _OBJC_CLASS_$_EAAccessoryManager → ExternalAccessory.framework

根因：AMap 是 fat 静态库（`Vendor/AMap/*.framework`），它内部引用的系统 API
不会被自动带入 transitive 依赖，必须项目方手动 link。CocoaPods 时代由
podspec 自动声明（daoqi msext 走 Pods 故未在 pbxproj 显式 link
ExternalAccessory）；本项目走 Vendor 手动接入路线，必须显式补齐。

工程：pbxproj 加 3 个 PBXBuildFile + PBXFileReference（Xcode UI 操作自动写入）

文档（永久记录避免重蹈）：
- Vendor/AMap/README.md「工程接入步骤」第 5 步补齐 3 个系统 framework
  + 列出每个 framework 对应的 symbol
- Vendor/AMap/README.md 末尾加「如果未来真机链接报 C++ symbol 缺失」
  备用方案（加 libc++.tbd，daoqi 已加；当前 AMap 2.12.0 未触发）
- docs/SDK-Integration-Guide.md §A.2 第 5 步同步

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 02:50:29 +08:00
joywayerandClaude Opus 4.7 e6bcb32820 Verification-Checklist：覆盖 Phase 3.6 / 4.B-F / 5 / 6 / 7 / 8.4 / 9.2 
之前 Verification-Checklist 只覆盖到 Phase 1 / 2 / 3.A / 4 stub；后续
Phase 全部留 "待实现" 占位。一次性补齐，并：

- §I.5 七牛 token 自签 + 上传单元验证（Phase 3.6 落地后的真机/单测项）
- §J 微信授权 → sharelogin 7 字段（Province 大写 P）
- §K 微信链接分享 type=1 → sharesuccess 反向
- §L SharePanel 三选一（动画 / 半透明背景 / 平台未装行为）
- §M QQ URL Scheme 分享（中文 encode / 朋友圈 to_qzone / 乐观策略）
- §N 抖音相册 + URL Scheme 4 候选
- §O 微信截图 type=2 / 远端图 type=3（thumb 0.4x / errCode -2 cancelled）
- §P 高德定位 9 字段（latitude/longitude string、province 小写 p、errorCode 12）
- §Q 子游戏 push + 节流 + 栈深 + backgameData + ExternalSubscriptions 防双发 + SubGameDownloader 缓存/升级
- §R 弹层 OpenurlTitleData + finishweb/browser/backgameData 三 settings + Cookie 隔离 + overlay→sub-game 链路
- §S 视频房间 stub + 大厅不注册边界
- §T phonestate（CXCallObserver 真机；仅子游戏订阅；pop 后停止）
- §U H5ErrorRelay 三类异常源 + Overlay 不挂 + 原始 console.error 链未断

新增「通用准备 → 真机 vs 模拟器跑哪些」清单，明示 M Mac 模拟器
不能跑的章节（§J/K/L/M/N/O/P/T/I.5.3）+ 建议路径（先模拟器跑大头，
再真机跑特定章节）。

末尾「契约 §10 映射表」从 11 行扩到 23 行，每行带 Phase 状态。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 02:37:04 +08:00
joywayerandClaude Opus 4.7 f7d472d91c Phase 9.3-9.6 决策落定：极光/闲聊/Agora/Bugly 全部不集成 
四个 SDK 的「集成与否」决策对齐当前项目状态：
- 9.3 极光 JAnalytics：YAGNI，H5 业务不调埋点 handler，建空协议反而
  misleading；未来真要启用按 Vendor → 抽 Tracker 协议 → Noop fallback
- 9.4 闲聊：SDK 已停更 + 业务方未启用；SharePanel 三按钮已只含
  微信/QQ/抖音，连 stub 都不需要
- 9.5 Agora：用户明确视频房暂不需要；VideoRoomHandlers stub 已满足
  契约边界（H5 调 3 个 handler 不报 not found），未来重启按 8.6 蓝图
- 9.6 Bugly：沿用 msext CLAUDE.md「账号已废弃」决策，崩溃监控完全
  依赖 Sentry（如 9.1 启用）+ 用户/运营反馈链

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 02:05:37 +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 5885f97715 Plan §8 进度补漏：Phase 8.1-8.3 视频房间 stub 全勾 
8.1/8.2/8.3 视频房间 3 件套 stub 实际在 Phase 6 commit C（VideoRoomHandlers.swift）
就已落地，§5 已勾，§8 当时遗漏，一并补上并明确「不抽 protocol/Noop 类
避免过度设计」的选择。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 02:02:05 +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 8fc37b0827 Plan §8 进度补漏：Phase 2 / 4.11-4.12 / 7.6-7.7 全勾 
Phase 2 大厅简单 handler 实际在 Phase 1 / 4.B 顺带都已落地（13 个文件全
存在于 Source/Bridge/Handlers/ + Source/Resource/），只是 §8 进度表
长期未同步。一次性补勾，并附实际实现文件路径方便检索。

Phase 4.11 / 4.12（截图 / 远端图分享）由 commit 8e4c36d 落地，§5 已勾，
§8 这里也勾上。

Phase 7.6 finishweb / 7.7 browser overlay 实际在 OverlayViewController
首版（commit 0427bb9）就已实现 handleMessage 三分支，与 7.5 同时落地，
但 §8 当时只勾了 7.1-7.5，遗漏 7.6/7.7。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 01:59:01 +08:00
joywayerandClaude Opus 4.7 d9d9554d9f Plan 进度同步：Phase 3.6 / 4.1 / 4.3-4.10 / 5.1-5.6 勾选 
按 CLAUDE.md「进度同步规范」要求，把已落地的子项在 Development-Plan.md
§5 / §8 中同步勾选。同时修正几处描述与当前实现的差异：

- 4.1 微信 SDK：xcframework 2.0.5 入库 Vendor（不是 Embed Frameworks），
  Universal Links 不接（企业签分发不需要）
- 4.3 WeChatSDK：新 SDK 2.x 无 MMAPP_SUPPORT_* flag，简单 registerApp
- 4.6 WeChatAuth：客户端直拼 sns/oauth2/access_token + sns/userinfo，
  接受 msext 同款 secret 路径（不走后台 /wechat/login）
- 5.1 AMap：高德官方不出 xcframework，回退 fat .framework，M Mac 模拟器
  链接失败是接受的现状（详见 Vendor/AMap/README.md「已知限制」）
- 5.3 AMapWrapper：updatePrivacyShow/Agree 是 AMapLocationManager 类方法
- 5.4 LocationService：仅 requestOnce + stop，未实现持续模式（msext 也
  只是单次，H5 未要求持续）
- 3.6 Qiniu：CryptoKit HMAC-SHA1 自签 token + QNUploadManager 走
  initWithConfiguration + defaultConfigurationV2

Phase 4.11 / 4.12（截图 / 远端图分享）下个 commit 实现。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 01:33:05 +08:00
joywayerandClaude Opus 4.7 01780704cd docs：明确 AMap fat framework 不含 simulator arm64 是项目接受的现状 
高德官方至今不提供 xcframework，只发布 fat .framework（含 x86_64 + device
arm64）。M 芯片 Mac iOS-simulator target 链接失败是 fat 库的物理限制，与
daoqi msext 维护实践一致——开发期跑真机即可。

不动 Build Settings、不自造 xcframework、不切 CocoaPods 三条「不要做」也
一并明示，避免未来维护者花时间在这条死路上：
- Vendor/AMap/README.md 新增「已知限制」章节，含决策原因 + 三条「不要做」
- docs/SDK-Integration-Guide.md §A.2 简明提示 + 链回 README

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 01:07:02 +08:00
joywayerandClaude Opus 4.7 52ad421d22 SDK 选型修正：微信回 Vendor 路径（Tencent 无官方 SPM） 
之前文档把 https://github.com/Tencent/WechatOpenSDK-XCFramework 当作
SPM 入口，实际该仓库不存在（404）。Tencent 官方至今未维护 SPM；社区
wrapper（yanyin1986 / anotheren）非官方，按 daoqi CLAUDE.md ADR-006
「闭源 SDK 走 Vendor」否决。微信改回与 AMap 同款 Vendor .xcframework
处置：

- Vendor/WechatSDK/README.md 重写为腾讯开放平台下载页 + Embed & Sign 说明
- docs/SDK-Integration-Guide.md §A / §A.1 / §1.3 同步修正
  - §A 总览：SPM × 1（七牛）+ Vendor × 2（微信 / 高德）
  - §A.1：重写为 Vendor Add Files 流程，强调 Embed & Sign 与 AMap
    静态库 Do Not Embed 的区别
  - §1.3：微信 xcframework 状态标记 ⏳ 等用户从官方下载放置

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-23 00:02:45 +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 a2baf742b6 docs：新增 SDK-Integration-Guide.md（微信 / 高德定位 / opencore-amr / 七牛） 
按 CLAUDE.md ADR-006「禁 CocoaPods，SPM 优先 + Vendor xcframework」组织，
每个 SDK 章节给出：凭证清单 / 工程接入 / 代码触点 / BackGameData 清理钩子 / 验收 /
风险，便于项目方发凭证后开发者按表落地。

关键约束（写入指南）：
- 微信：不复用 msext AppID；AppSecret 客户端泄露风险，fallback 路径上线前必须切后台
- 高德：APIKey 与 Bundle ID 绑死，必须重新申请（msext 的 key 不可用）；
  iOS 14+ 隐私合规三步（updatePrivacyShow → updatePrivacyAgree → apiKey）
- opencore-amr：复用 msext 已 segalign 8 修复版 .a，免重编源码；MRC wrapper 加
  -fno-objc-arc 文件级标志
- 七牛：SPM 拉官方 objc-sdk v8.9.x；token 缓存 + 失效前 30s 预刷新
- 每个 SDK 都标明在 BackGameDataHandler 必须加的清理钩子（WXApi.delegate=nil /
  LocationService.stop / AudioRecorder.cancel / QiniuUploader.cancelInFlight）

CLAUDE.md 文档索引追加一行指向新文件。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 21:36:51 +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 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 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 b071ced657 Phase 4 方向再次纠正：撤销 A，QQ + 抖音 SharePanel 三选一不依 SDK 
用户提示"原项目还有 QQ 分享、抖音分享"。深度调研发现：

  上一轮 A 方向决策 (a6095ef) 错了 — grep 范围之前仅看 NewRootVC.m，
  漏了 gameController.m。msext gameController.m:575-597 显示 H5 调
  friendsShare 时原生**弹 SharePanel 三选一面板**：

    sharefriend == 1 → SharePanel.showWithDictionary（微信好友 / QQ / 抖音）
    sharefriend == 2 → WechatShareManager.shareWithContent（朋友圈）

  Contract §3.1 ［2］旧描述（sharetype=3 闲聊）已被 msext 新代码覆盖；
  sharetype 字段在新代码里读了但不用。

调研 QQ + 抖音是否需要 SDK：
  - QQShareManager.m:14: __has_include(<TencentOpenAPI/QQApiInterface.h>)
    条件编译 + line 716-771 simpleShareToQQFriend URL Scheme fallback
    （mqqapi://share/to_fri?...） — **不依赖 SDK**
  - DouyinShareManager.m: 只 import Photos + MobileCoreServices；
    全程 URL Scheme（snssdk1128://share/video / camera）+ 保存截图到
    相册让用户在抖音里选 — **不依赖 SDK**

撤销 A 决策。新方向（Plan §5 4.2-4.4）：
  - 4.2 SharePanel 三选一面板（msext gameController.m:585 等价行为）
  - 4.3 QQShare URL Scheme（移植 simpleShareToQQFriend）
  - 4.4 DouyinShare URL Scheme + Photos
  - 4.5（原 4.B）微信 SDK 接入（仍需项目方提供 framework + AppID + UL）

文档同步：
  - Plan §2.3 阻塞表：QQ 改为"不需要 SDK，走 URL Scheme"；抖音同款
  - Plan §5 Phase 4：4.2 重写为 SharePanel 设计 + 4.3 QQ + 4.4 抖音 + 4.5 微信
  - CLAUDE.md 依赖管理段："不接入 QQ SDK / 也不接入抖音 SDK"，
    含 LSApplicationQueriesSchemes + NSPhotoLibraryAddUsageDescription 说明
  - Verification-Checklist L/M/N 章节：SharePanel + QQ + 抖音验证项
  - Plan §6.4 里程碑加纠正记录（标 a6095ef 已撤销）

下一步：代码实施 4.B SharePlatform 协议 + SharePanel UI + ShareCenter 分发。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 19:59:00 +08:00
joywayerandClaude Opus 4.7 a6095ef4c8 Phase 4 方向最终决策 A：QQ 不在 H5 桥范围，不实施 
深度 grep msext NewRootVC.m / gameController.m 未发现 QQShareManager
引用 — QQ 完全不接 H5 桥。Contract §3.1 ［2］ sharetype 取值仅 "1"/"2"=
微信 / "3"=闲聊，无 QQ 选项。

按 CLAUDE.md 原则 A（H5 端零修改不可妥协）：契约不变 → H5 桥不实现
QQ 分享。msext 里 QQShareManager 只服务于原生 SharePanel（独立功能），
新外壳无原生 SharePanel-like 入口需求 → 也不需要 QQShareManager。

文档同步调整为"不实施"：
  - Plan §2.3 阻塞表：QQ OpenSDK 改写为详细理由（H5 桥契约无 QQ
    选项 + msext QQShareManager 不接 H5 桥的 grep 证据）
  - Plan §5 Phase 4.2：从"QQ 改走 URL Scheme"改为"不实施"，但保留
    URL Scheme 备用知识库（未来如需原生入口可参 msext fallback）
  - CLAUDE.md 依赖管理段："不接入 QQ SDK 也不实现 QQ 分享"，明示
    原因（契约无 QQ + msext 行为）
  - Verification-Checklist L 章节：QQ 验证项删除（不实施无需验证）

Phase 4 至此剩 4.B 微信 SDK 接入（项目方阻塞）+ 4.D 截图/远端图分享
（依赖 4.B）。当前 stub 已让 H5 调登录/分享不报 "no handler"，
等微信 SDK 到位后升级。

Plan §6.4 里程碑加一行决策记录。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 19:45:12 +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 b2ee1b38eb 新增 Verification-Checklist 功能验证清单 + Phase 1-2 验证步骤 
按用户指示：功能验证写到专门的文档用来说明指导，等功能开发完毕统一
验证，不在 Phase 进行中频繁跑（避免反复重装 app 浪费时间）。

新增 docs/Verification-Checklist.md：
  - 文档定位：开发期累积 / 统一验收的操作手册，与 Contract §10
    契约边界保持独立
  - 通用准备：环境工具（Xcode console / Safari Web Inspector / 模拟器
    Features 菜单）+ 重装 app 清 launch snapshot + xcrun simctl
    get_app_container 沙盒访问
  - Phase 1 章节（已实现）：
    A. 启动图 + LaunchScreen 方向（3 项）
    B. 启动流水线时序（含 Xcode console 期望输出 + 黑边 + 总耗时）
    C. app_*.js 落盘 + 命名（含 cat 命令）— 6 项硬约束
    D. window.app_* H5 console 对账（15 项变量 + 撤销变量验证）
  - Phase 2 章节（已实现）：
    E. H5→Native handler 响应（13 项验证步骤）
    F. Native→H5 反向 callback（5 项触发场景含模拟器手动操作）
    G. ExternalSubscriptions 生命周期（Phase 6 才能完整验证）
  - Phase 3-10 占位章节：实施后陆续填充
  - 附录：与 Contract §10 26 项验收清单的章节映射表
  - 维护规则：每完成 Phase 子项补勾、不复制到 Contract §10、bug 修复
    时在 commit message 引用本文档 checkbox 编号

CLAUDE.md 文档索引表新增一行指向 Verification-Checklist.md。

Plan §6.4 里程碑加 3 行（前面遗漏的 4986f36 / 09f071e + 本次 commit）。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 19:08:32 +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 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 13cc24b463 §7.5 路径回退到 writeToFile：撤销 evaluateJavaScript 路径 
CLAUDE.md 原则 A 升级为第一准则（H5 端零修改不可妥协）后，重新评估
上一轮 commit 246f215 引入的 evaluateJavaScript 路径：

  - WKUserScript(.atDocumentStart) 注入会被 H5 自带 var app_xxx 声明
    覆盖回退
  - WKUserScript(.atDocumentEnd) 又太晚，H5 业务顶层 <script> 已经
    读过默认值
  - 没有"在 <script src> 之后、业务 <script> 之前"的精确时机
  - 任何"让 H5 改一行 / 改一个文件"的妥协方案违反原则 A 第一准则
  - 详细分析见 CLAUDE.md「典型案例 3」

撤销方案：回到原 msext writeToFile 路径，原生在 loadFileURL 之前写
4 个 app_*.js 文件到沙盒，H5 启动时 <script src> 同步引入即可读到
实际值，时序 100% 等价 msext。

Design §7.5 全面回退（-285 / +126 行）：
  - §7.5 头部：标题 / 简介改回写文件路径；中间走过两次弯路的完整决策
    链记录在头部（commit f68b0db → 246f215 → 本次 commit）
  - §7.5.2 注入时机表 → 4 个文件写入时机表，附"为什么不要照搬
    WKUserScript 注入"警告段
  - §7.5.3 删除 AppDataInjector + .legacy 标注；AppDataWriter 升回主路径
    （保留 logger debug 输出 / msext 字面对齐细节 / 转义 / 大小写）
  - §7.5.4 接入点：writeInitial + writeBattery + writeNetwork 三阶段，
    addObserver 持续监听
  - §7.5.5 大厅 / 子游戏 / 弹层差异表回到 "app_data.js / app_gamesname.js
    / app_battery.js / app_network.js" 维度
  - §7.5.6 与 msext 差异表回到"writeToFile 等价化"对比
  - §7.5.7 与 §3.4.1 polyfill 关系：§7.5 文件预写为主路径；
    WKUserScript + evaluateJavaScript "探索后撤回"
  - §7.5.8 联调路径恢复 cat 文件路径，加 4 种现象诊断表

Contract §4.2 同步：
  - 头部说明改回 "原生 writeToFile 写文件" + 撤销中间 evaluateJavaScript
    路径的复盘段
  - 子节标题回到 "写到 {gamedir}/{gamestart}/app_*.js"
  - 子节"更新时机"段回到 loadFileURL 前 / addObserver / 前台切换
  - 删除"H5 团队 zip 自带 + 默认占位"约定（不再适用，原生重新负责写入）
  - 修订记录新增一行"路径再次调整（最终）"

Contract §10 验收清单同步：
  - "H5 zip 自带 4 个 .js" → "沙盒下 4 个 .js 存在（xcrun simctl + cat 验证）"
  - 删"原生 WKUserScript 覆盖生效"项 → 加"值是实际渠道值而非占位"
  - "阶段 B 动态覆盖" → "battery/network 变化重写文件"

Plan §6.4 里程碑加两行：CLAUDE.md A 升级 + §7.5 最终回退。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 12:40:07 +08:00
joywayerandClaude Opus 4.7 246f215d6f §7.5 重大路径调整：app_* 改为 evaluateJavaScript 覆盖 window.app_xxx 
H5 团队新约定：app_*.js 4 个文件由 H5 团队自带在 gamehall.zip 内（含
默认占位值），原生**不再写文件**，只用 WKUserScript(.atDocumentEnd) +
evaluateJavaScript 覆盖 window.app_xxx 全局变量的实际值。

Design 三处大改 (+339/-91 净 +248 行)：

§7.5 标题 / 头部：
  - 标题：H5 app_*.js 预注入文件机制 → 修改 H5 端 app_*.js 全局变量值
    （evaluateJavaScript 路径）
  - 新增「2026-06-22 重大方向调整」说明段：3 条理由 + 旧路径降级为
    §7.5.3.legacy

§7.5.2 注入时机：
  - 旧：4 个文件写入时机表
  - 新：两阶段注入表（A 首次 documentEnd UserScript / B 动态
    evaluateJavaScript）+ 为什么必须 documentEnd 不能 documentStart
    （H5 的 var 声明会回退我们的值）+ 为什么不直接走异步 callHandler
    （违反契约原则 A）

§7.5.3 Swift 骨架：
  - AppDataWriter (writeToFile) → AppDataInjector (UserScript +
    evaluateJavaScript)
  - 阶段 A makeInitialUserScript：拼装 (function(){window.app_xxx=...})()
    documentEnd 注入；包含 13 项启动期已知字段
  - 阶段 B injectBattery / injectNetwork：async evaluateJavaScript 单条覆盖
  - Logger.debug 保留所有 key=value 打印（联调可观察性）
  - 旧 AppDataWriter 保留为 §7.5.3.legacy（明示不要实施）

§7.5.4 接入点：
  - configuration.userContentController.addUserScript（阶段 A）
  - addObserver(batteryLevelDidChange) → injectBattery
  - networkMonitor.stateDidChange → injectNetwork
  - bridgedWebView.didFinishOnce 首次补一次 battery + network

§7.5.5 / .6 / .7 / .8 同步调整：差异表 / msext 对比 / 联调路径
  - §7.5.8 路径 2 从「沙盒 cat .js 文件」改为「Safari Web Inspector 看
    window.app_xxx 实时值」（不再写文件无文件可 cat）
  - 加阶段 B 手动触发验证（模拟器 Battery State / Network Link Conditioner）

Contract §4.2 同步：
  - 新增 msext 旧契约 vs 新契约对比表（3 维度：文件来源 / 赋值机制 / 路径感知）
  - 子节标题从「app_battery.js（写到 ...）」改为「H5 zip 包内，含
    app_getbattery 默认占位」+ 更新时机改写为 evaluateJavaScript 时机
  - 「H5 团队保证 zip 内 4 个 app_*.js 存在 + 合理默认占位」约定
  - 修订记录加一行路径调整

Contract §10 验收清单调整：
  - 文件验收：4 个 .js 由 H5 zip 自带（不是原生生成）
  - 新增「原生覆盖生效」验收：Web Inspector 读 window.app_channel 必须
    是 ChannelConfig.plist 实际值，不是 H5 默认占位
  - app_Launchtype 类型修正为数字 0/1（不是字符串）
  - 新增「阶段 B 动态覆盖」验收：模拟器手动触发 battery/network 变化

Plan §6.4 里程碑加新一行记录本次路径调整。

至此 H5↔Native 通讯 5 条路径全部按新契约对齐：
  1. WVJB 异步 callback（22 项）
  2. Native→H5 反向 callback（15 项）
  3. **window.app_xxx evaluateJavaScript 覆盖（15 项）** ← 本次重写
  4. 弹层 settings.* polyfill（4 项）
  5. WKUIDelegate alert/confirm（2 项）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 08:19:53 +08:00
joywayerandClaude Opus 4.7 9f4ccb762e Design §7.5.3/.8：AppDataWriter 加 os.log 调试输出 + 联调可观察性 
用户在 Phase 1.17 联调准备时反馈：app_*.js 写入时应该有控制台输出，
方便调试。本 commit 在 §7.5 蓝图层落实可观察性，Phase 2 实施按此骨架
就有完整 debug log。

§7.5.3 AppDataWriter 改动（同时修正若干与 msext 字面不一致的细节）：
  - 引入 os.Logger(subsystem: ylgamehall, category: AppDataWriter)
  - writeAppData / writeGamesName / writeBattery / writeNetwork 全部打印
    {ContainerRole} + 文件路径 + 每个 key=value 一行，便于和 H5
    console.log(app_xxx) 逐项对账
  - ContainerRole 实现 CustomStringConvertible（"lobby" / "subGame(name)"）
  - Logger.debug 级别：Debug 出 Xcode 控制台，Release 自动过滤
  - privacy: .public 标注（确保字符串值不被 Logger 模糊化为 <private>）

**字面修正**（对照 daoqi/msext 实际代码二次校对）：
  - 字符串包裹符 " → '（msext 用 "var x='%@';" 单引号）
  - escape 转义对象从 \" 改为 \'（与单引号包裹配套）
  - 数值字段（version / Launchtype / getwifisignalLevel / appversion）
    去掉引号，沿用 msext "var app_version=1;" / "var app_appversion='%d';"
  - app_gamesname 从 JS array literal [...] 改为 new Array(...)，
    var 后两空格，严格 AppDelegate.m:259 字面

§7.5.8 新增「联调时的可观察性（Phase 1.17 调试手段）」：
  - 路径 1：Xcode 控制台 — 原生 os.log 输出格式样例
  - 路径 2：沙盒文件直接 cat — xcrun simctl get_app_container 命令 +
    4 个 .js 文件 cat 验证
  - 路径 3：H5 console — Safari Web Inspector 逐项 console.log(app_xxx)
    样例，标注 ⚠️ 大小写硬约束（Launchtype L 大写 / battery 带 get 前缀）
  - 路径 4：真机 Safari 调试启用方法
  - Release 注意事项：os.log .debug 自动过滤避免性能开销和敏感字段外泄

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 08:09:57 +08:00
joywayerandClaude Opus 4.7 0cdd709e66 中优 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>
 2026-06-22 08:02:24 +08:00
joywayerandClaude Opus 4.7 47a89aa49c Contract §4.2：按原项目代码全面修订 app_*.js JS 注入清单 
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>
 2026-06-22 07:58:02 +08:00
joywayerandClaude Opus 4.7 f68b0dba93 Design §7.5：补 H5 app_*.js 预注入文件机制（15 个变量），§3.4.1 polyfill 撤销 
按 CLAUDE.md「先看原项目」规则深度审查 daoqi/msext NewRootVC.initJSdata /
gameController.initJSdata / AppDelegate 写入逻辑后发现：

**关键纠正**：H5 在 iOS 9+ 路径下的真实读值机制是 §4.2「写 app_*.js 文件
+ H5 <script src> 同步引入」，不是早期 commit 82bad8a 实现的
§3.4.1 window.settings.getXxx() polyfill（那是 §附录 A 旧桥 JSExport
路径，契约明示「新外壳如最低系统 ≥ iOS 14 可不实现」，本项目最低
iOS 15.6 → 无需实现）。

§3.4.1 处理：标题改为「⚠️ 撤销」+ 完整说明撤销原因；旧 polyfill 代码
骨架保留为 §3.4.1.legacy 作为数据源映射参考（不删除以保 git log 整洁，
也方便 Phase 2 实施者了解 9 项 getter 的等价数据来源）。

§7.5 新章节覆盖 15 个变量（用户列 14 + audit 发现 app_invitationcode）：
  - §7.5.1 完整映射表：变量名 / 大厅值 / 子游戏值 / 数据源 / 文件
  - §7.5.2 4 个文件写入时机（一次性 vs 事件驱动）+ 为什么写文件不
    evaluateJavaScript（保证 <script src> 同步引入时机）
  - §7.5.3 AppDataWriter struct Swift 骨架（escape 4 种特殊字符避免
    渠道字段含引号导致 H5 JS 解析错）
  - §7.5.4 WebContainerViewController 接入点：loadFileURL 前 writeInitial
    + writeBattery + writeNetwork；持续监听 batteryLevelDidChange /
    NWPathMonitor 触发增量重写
  - §7.5.5 大厅 / 子游戏 / 弹层 4 维度差异（弹层不写 app_*）
  - §7.5.6 与 msext 6 维度差异表（单一真相 / 转义 / 大小写严格）
  - §7.5.7 §7.5 vs §3.4.1 vs §3.4 OverlayBridge vs §3.2 callback 四条
    路径关系澄清

大小写严格契约：app_Launchtype（L 大写）/ app_getwifisignalLevel（wifi
小写、signal/Level 区分大小写）— 任何拼写错误会让 H5 业务读到 undefined。

至此 H5 端 JS 与原生通讯的完整 5 条路径全部覆盖：
  1. WebViewJavascriptBridge 异步 callback（§5/§8/§3.1，22 项 handler）
  2. Native→H5 反向 callback（§3.2，15 项）
  3. app_*.js 文件预注入全局变量（§7.5，15 项）
  4. 弹层 window.settings 同步 polyfill（§3.4，3 项 + §3.4.2 OpenurlTitleData）
  5. WKUIDelegate alert / confirm（§3.7，2 项）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 07:51:13 +08:00
joywayerandClaude Opus 4.7 33574a1cc2 Design §3.7：补 WKUIDelegate alert / confirm 2 项接口 
覆盖契约 §4.3 H5 alert(msg) / confirm(msg) 触发原生弹窗的硬约束。

WKWebView 默认行为是直接吞掉 H5 的 alert/confirm 不弹任何窗口，必须实现
WKUIDelegate 才有响应。不实现的代价：H5 业务里 alert("登录失败")
之类的提示用户完全看不见，业务哑火无可视化报错。

§3.7 实现骨架：
  - runJavaScriptAlertPanelWithMessage → UIAlertController .alert，
    标题 appDisplayName，单"确定"按钮，completionHandler() 必须调一次
  - runJavaScriptConfirmPanelWithMessage → "取消"/"确定" 两按钮，
    completionHandler(false/true) 必须调一次
  - 接入点：bridgedWebView.webView.uiDelegate = self 在 viewDidLoad
    与 navigationDelegate 一起设置

§3.7.1 与 msext 4 维度差异表（标题来源 / 按钮顺序 / 样式 / 并发）+
明示"未实现导致的现象"提醒，方便 1.17 真机联调时排查。

至此契约 §3 + §附录 A + §4.3 共 51 项接口（22 异步 handler + 15 反向 callback
+ 3 弹层 polyfill + 9 同步 getter polyfill + 2 WKUIDelegate）的 Design 实现
骨架全部覆盖完整。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 07:33:33 +08:00
joywayerandClaude Opus 4.7 5f5f6a9ff9 Design §3.4.2：补 OpenurlTitleData handler — 大厅打开 threeView 弹层 
覆盖 §3.1 ［15］OpenurlTitleData，是大厅 WVJB 桥的异步 handler，作用是
触发新的 OverlayViewController push 到导航栈。补在 §3.4 弹层桥章节内
（与 §3.4 settings polyfill 一脉相承），叫 §3.4.2。

§3.4.2 OpenurlTitleDataHandler：
  - 节流：throttle final class 持 lastOpen Date，3 秒内重复调用被吞掉但
    cb 仍要回（否则 H5 会等）
  - 入参解析：url 必填；"title " 末尾有空格（msext 历史契约硬约束，必须
    obj["title "]）；data 透传；orientation 0/1 但本项目固定横屏
  - 调 LobbyCoordinator.pushOverlay 打开 OverlayViewController

OverlayViewController 接入：
  - WKWebViewConfiguration + UserScript 注入：
    1. §3.4 OverlayBridge.polyfill（settings.backgameData/browser/finishweb）
    2. window.app_data = "<escaped data>" 把业务数据透传到 H5
  - 等价于 msext threeView 的 JSContext setObject:forKey:@"settings" 行为

§3.4.3 与 msext 5 维度差异表：UIWebView → WKWebView / "title " 末尾空格
严格保持 / 节流类替代静态变量 / UserScript atDocumentStart 注入避免 race

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 07:32:30 +08:00
joywayerandClaude Opus 4.7 a06a18c3aa Design §8.7：新增 ShakeKit + 4 项接口实现骨架 
覆盖 §3.1 ［7］startshake / ［8］stopshake / ［9］SwitchShake +
§3.2 ［5］shakeEnd 反向 callback 共 4 项接口。

§8.7.1 ShakeKit module 骨架：
  - canShake / canVoice 开关位（@MainActor 实例属性，取代 msext 全局变量）
  - handleMotionEnded(.motionShake) 集中处理：判 canShake → 播音效 → 触发 callback
  - shake_sound_male.mp3 复用 AudioKit.AudioPlayer.playOnce 统一路径

§8.7.1 接入 VC：
  - WebContainerViewController.canBecomeFirstResponder = true
  - viewDidAppear 调 becomeFirstResponder（必要，否则 motionEnded 不触发）
  - motionEnded(_:with:) 转发到 shakeKit.handleMotionEnded

§8.7.2 H5 handler 实现：
  - 【7】startshake  : canshake=YES + cb "startshake from accreditlogin"
                      （字面字符串带 "from accreditlogin" 后缀沿用历史）
  - 【8】stopshake   : canshake=NO  + cb 同上
  - 【9】SwitchShake : data int → canvoice = (1==YES) + cb "SwitchShake"
  - 反向 ［5］shakeEnd: data=nil，由 motionEnded → onShakeEnded 触发

§8.7.3 与 msext 6 维度差异表（全局变量 → 实例属性 / 音效统一 /
motionEnded 集中处理 / canBecomeFirstResponder 基类统一 / responseCallback 字面保留）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 07:31:08 +08:00
joywayerandClaude Opus 4.7 d48ecc0473 Design §8.6：新增 LocationKit + 2 项接口实现骨架 
覆盖 §3.1 ［20］startlocation + §3.2 ［6］getlocationinfo 反向 callback。

§8.6.1 LocationService module 骨架：
  - AMapServices.bootstrap：privacy + key 启动期完成
  - locateOnce() async/await 包装 AMapLocationManager.requestLocation
  - startContinuous / stopContinuous + onContinuousUpdate 闭包钩子
  - LocationInfo struct 转契约 §3.2 表 B 9 字段（latitude/longitude string
    化用 String(format: "%f")，province 小写 p）
  - LocationError.permissionDenied(code: 12)

§8.6.2 H5 handler（LocationHandlers.startLocation）：
  - 入参 data: int 1=持续 / 其他=一次性，与 msext RootVC 沿用
  - 持续模式：onContinuousUpdate 挂钩 → 每次位置变化推 getlocationinfo
  - 一次性：await locateOnce → 单次推
  - responseCallback: "startlocation"
  - 失败 callback 数据结构 errorCode 数字 12 不是 string（契约硬约束）

§8.6.3 与 msext 6 维度差异表（SDK 接入 / 隐私合规集中 / async wrapper /
入参解析 / latitude string / province 小写 p）

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 07:30:06 +08:00
joywayerandClaude Opus 4.7 c6221d30ca Design §8.4.1：补 DeviceKit 9 项接口实现骨架 
覆盖 §3.1 异步 handler 6 项 + §3.2 反向 callback 3 项，含本轮全文 audit
新发现的 3 项反向 callback（前一轮 audit 漏列）：

§3.1 异步 handler 6 项（DeviceHandlers.register）：
  - 【10】vibrator           — AudioServicesPlaySystemSound + cb "vibrator"
  - 【11】repeatvibrator     — 同 vibrator（msext RootVC.m:1820 沿用历史）
  - 【12】canclevibrator     — AudioServicesDisposeSystemSoundID + cb "canclevibrator"
  - 【13】gamepastetext      — UIPasteboard.general.string → cb 返回内容
  - 【14】gameCopytext       — UIPasteboard.general.string = data + cb "gameCopytext"
  - 【21】getphoneInfo       — cb "getphoneInfo"（大写 I）+ bridge.call("getphoneinfo"
                              小写 i！，data: 表 A 6 字段)
                              ※ 大小写 i 不一致是 msext 历史契约，严格保持

§3.2 反向 callback 3 项（DeviceHandlers.bindReverseCallbacks）：
  - 【2】 getBattery   — UIDevice.batteryLevelDidChangeNotification
                        data: String(format: "%.2f", level) 0~1
  - 【3】 getnetwork   — NWPath 变化 data: "1"无网/"2"WiFi/"3"蜂窝
  - 【4】 appservice   — App 前后台 data: "1"=后台/"2"=前台（命名错位沿用）

辨析 polyfill 与 callback 同名问题：契约 §3.4.1 polyfill 的同步 getter
`getbattery()` / `getnetwork()` 与 §3.2 反向 `getBattery` / `getnetwork`
名字重合但语义不同（前者 H5 同步问当前值，后者 Native 事件推变化），
两条路径并存互不矛盾。在 §8.4.1 新增辨析段澄清。

支撑组件骨架：BatteryMonitor / AppLifecycleMonitor（NetworkMonitor 已在
§8.4 现有）；§8.4.2 与 msext 6 维度差异表。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 07:28:34 +08:00
joywayerandClaude Opus 4.7 82bad8a85d Design §3.4.1：补 window.settings 同步 getter polyfill（9 项含 getothername） 
audit 第二轮发现：Contract §附录 A 旧桥 JSExport 共 28 方法，与 §3.1
异步主桥去重后多出 9 项 H5 同步只读 getter。前一轮 audit 只覆盖 §3.1
主表的 22 项异步 handler，这 9 项 getter 在 Design 完全无覆盖：

  - getchannelName / getmarketname / getOther / getothername(name)
  - getcompareCode / getbattery / getnetwork
  - getGameinstall(name) / getGameplay(jsondata)

这些接口 H5 端形式是同步表达式（var ch = window.settings.getchannelName()），
WKWebView 无法同步返回 JS 值。唯一不破契约（H5 端零修改）的路径：
documentStart 注入数据快照 + 纯 JS getter polyfill，本地查询零延迟。

§3.4.1 新增覆盖：
  - 9 项 getter 业务语义 + 数据源映射表（驳到 BundleConfig / DeviceKit /
    SandboxPaths.installedSubGames）
  - 数据快照时机：静态字段（11 项渠道注入）启动期一次；动态字段
    （battery / network / installedGames）每次 loadFileURL 前重新快照
  - SettingsBridgePolyfill.makeUserScript 完整 JS 注入骨架
  - WebContainerViewController 接入点（runBootPipelineSteps 末尾、
    loadFileURL 前调 installSettingsPolyfill）
  - 与原 msext JSExport 5 维度差异表

待 Phase 2 实施时查清：getcompareCode 在 msext RootVC.m:1560 附近的真实
返回值语义（业务校验码，可能与 zip 版本号或固定值相关）。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 07:24:01 +08:00
joywayerandClaude Opus 4.7 92298b657e Design §8.1：补 AudioKit 4 项 handler 完整实现骨架（方案 A 示范） 
H5↔Native 接口实现层缺口补全启动（用户选 A：分散到各 module 章节补）。
本 commit 作为风格示范，后续 commit 按相同模板补 DeviceKit / Location /
Shake / OpenurlTitleData 共 11 项 handler。

§8.1 末尾新增两小节：

§8.1.1 — H5 audio handlers 实现骨架（185 行）
  - AudioHandlers struct 集中注册 4 项 handler，便于发现 / 单测
  - 【3】srcIsloop  入参解析 src/isloop → SandboxPaths.lobbyAssets/wav
        + AudioPlayer.playOnce / loopBackground / stopBackground 三态
        + responseCallback "Response from srcIsloop"
  - 【4】prepareaudio  权限三态分支（denied → bridge.call alertMessage
        而非原生弹窗，契约 §6.2 ifauth 语义）+ recordAndUpload
        + getaudiourl 反向 callback（time 字段必须 string，契约硬约束）
  - 【5】mediaTypeAudio  voiceCenter 总开关短路 + 下载 → AMR→WAV
        → playVoice with onStart/onEnd 桥到 gameui_play_voice/
        gameui_stop_voice；失败也补 stop_voice 避免 H5 UI 卡"播放中"
  - 【6】voicePlaying  actor VoiceCenter 隔离 isEnabled 状态

§8.1.2 — 与原 msext 的差异（不要照抄的部分）
  - 录音 UI / 上传后端 / 状态共享 / 总开关 / 路径拼接 5 维度对照表

骨架级别（结构 + 关键调用 + 注释 + 契约引用），不是产品代码 — 实施
Phase 2 时按此骨架落地真实代码。

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
 2026-06-22 07:14:15 +08:00