调整极光

2026-06-21 20:48:41 +08:00
parent d18ea4f1c5
commit 2a3d985dd7
2 changed files with 42 additions and 24 deletions
@@ -64,7 +64,7 @@ Contract       Design          Plan（本文档）
 | 后台 `/wechat/login` 中转接口 | secret 不入 IPA 的前提 | Phase 4 | 后台团队 |
 | 高德地图 `APIKey` + SDK Pod | 定位 | Phase 5 | 已有 key `b0d4a8e3fcbbcc0dd96283b7df6a4494`，但需新建 Bundle ID 注册 |
 | 七牛上传 token 颁发接口 | 录音上传 | Phase 3 | 后台团队 |
-| 极光 AppKey | 用户统计 | Phase 9 | 项目方 |
+| ~~极光 AppKey~~ | ~~用户统计~~ | **已决策暂不集成（ADR-005），未来启用时再协调** | — |
 | Sentry DSN | 崩溃监控 | Phase 9 | 项目方（需开通账号） |
 | Agora AppID（视频房间） | 子游戏视频 | Phase 8（默认 stub，可延后） | 项目方 |
 | 闲聊 SDK | 闲聊分享 | Phase 9（默认 stub） | 项目方 |
@@ -161,7 +161,7 @@ Contract       Design          Plan（本文档）
 | **P6** | 子游戏容器 | `SubGameViewController` + `Coordinator` + `SwitchOverGameData` / `backgameData` | 契约 §10 中 `SwitchOverGameData` 项 | 中 |
 | **P7** | 弹层 | `OverlayViewController` + `window.settings` polyfill + 节流 | 契约 §10 中 `OpenurlTitleData` / `settings.*` 项 | 中 |
 | **P8** | 视频房间 stub | 3 个 stub handler + Native→H5 `getVideoinfo` / `phonestate` / `recordSuccess` callback | 契约 §10 D 节（NoopVideoRoom 路径） | 小 |
-| **P9** | SDK 真实化 + 监控 | Sentry / 极光 / 七牛 SPM 接入；闲聊 / Bugly 决策落地 | 契约 §10 全 26 项 | 中 |
+| **P9** | SDK 真实化 + 监控 | Sentry / 七牛 SPM 接入；极光 / 闲聊 / Bugly 决策落地为 Noop / 不集成 | 契约 §10 全 26 项 | 中 |
 | **P10** | 多渠道 + 灰度 | 渠道注入脚本 / CI 多渠道出包 / 真机回归 / 灰度切流 | 真机验收 + 灰度无回退 | 大 |

 **相对成本说明**：
@@ -591,7 +591,7 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
 ### Phase 9: SDK 真实化 + 监控接入

 #### 目标
-把所有 Noop / stub 替换成真实 SDK；接入 Sentry 崩溃监控 + 极光统计。
+首版 SDK 集成定型：接入 Sentry 崩溃监控；极光 / 闲聊 / Agora 维持 Noop 占位（编译开关 OFF）；Bugly 不集成。

 #### 前置
 - Phase 1–8 完成
@@ -602,7 +602,10 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
  - 编译开关 `SENTRY_ENABLED`（默认 ON）+ `NoopCrashReporter` fallback
  - DSN 通过 xcconfig 注入，不入 git
 - [ ] **9.2** `Source/Bridge/Handlers/H5ErrorRelay.swift`：注入 `window.onerror` / `unhandledrejection` polyfill + `reportH5Error` 桥 handler（Design §11.4，新增 handler 不破坏契约）
- [ ] **9.3** 极光 SDK（Vendor）+ `Source/Analytics/JAnalytics.swift` 启动期注册
+- [ ] **9.3** 极光（JAnalytics）：保持 `NoopAnalytics` stub（**ADR-005 决策**）
+  - `Source/Analytics/Tracker.swift` 协议 + `NoopAnalytics` 实现
+  - `JAnalyticsTracker.swift` 留蓝图骨架（`#if JANALYTICS_ENABLED` 包裹，默认 OFF）
+  - 上线后业务真要做用户激活 / 留存分析时再启用：放 Vendor、切换实现、加 AppKey、Bootstrapper 注册
 - [ ] **9.4** 闲聊：保持 NoopSharePlatform（业务方未启用闲聊分享，stub 已满足契约）
 - [ ] **9.5** Agora：保持 NoopVideoRoom + 编译开关 OFF
 - [ ] **9.6** Bugly：不集成（Sentry 已覆盖）
@@ -611,12 +614,12 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin

 - 强制崩溃 → Sentry 后台收到 issue
 - H5 内 `throw new Error()` → Sentry 看到 H5 错误 + `container_role` 标签
- 极光后台看到设备激活
+- `Tracker` 协议存在且默认绑到 `NoopAnalytics`，业务调用 `Tracker.event(...)` 不崩、不阻塞

 #### 风险

 - Sentry 账号必须 ≥ 2 人持有访问凭证（避免重蹈 Bugly 覆辙）
- 极光 / Sentry / 自家后台埋点数据重叠：明确每个监控的"唯一职责"（Sentry=崩溃，极光=用户激活，自家=业务事件）
+- 首版无用户统计，业务侧若想看激活 / 留存只能等启用 JAnalytics 或自建埋点

 ---

@@ -679,7 +682,7 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
 |---------|-----|----------|
 | **SPM 优先** | ZIPFoundation / Sentry / 七牛 v8+ | Phase 1 / 9 / 3 |
 | **CocoaPods** | 高德 AMap | Phase 5 |
-| **Vendor `.framework`** | 微信 / QQ / 闲聊（暂不） / Agora（暂不） / JAnalytics | Phase 4 / 9 |
+| **Vendor `.framework`** | 微信 / QQ；闲聊 / Agora / **JAnalytics** 均暂不集成（Noop 占位） | Phase 4 |
 | **Vendor `.a`** | opencore-amr | Phase 3 |

 每集成一个 SDK 立即提交一个独立 commit（CLAUDE.md "及时提交" 规则）。
@@ -825,9 +828,9 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
 ### Phase 9 SDK 真实化 + 监控
 - [ ] 9.1 Sentry SPM + CrashReporter
 - [ ] 9.2 H5ErrorRelay
- [ ] 9.3 极光 SDK
- [ ] 9.4 闲聊保持 Noop
- [ ] 9.5 Agora 编译开关 OFF
+- [ ] 9.3 极光保持 NoopAnalytics（JANALYTICS_ENABLED OFF）
+- [ ] 9.4 闲聊保持 NoopSharePlatform
+- [ ] 9.5 Agora 保持 NoopVideoRoom（AGORA_ENABLED OFF）
 - [ ] 9.6 不集成 Bugly

 ### Phase 10 多渠道 + 回归 + 灰度
@@ -863,6 +866,11 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
 - **风险**：联调期遇到的契约疑点可能来自旧版 H5 已废弃接口，需对照现网 msext + H5 团队双确认
 - **切换条件**：Phase 10 灰度前必须由 H5 团队提供最新版替换并复跑契约 §10 全部 26 项

+### ADR-003：微信登录走后台中转 vs 客户端 fallback（2026-06-21）
+- **决策**：默认走后台 `/wechat/login` 中转；后台未就绪时临时客户端直拼，但代码标 `// FIXME` 且**禁止以 fallback 状态上线**
+- **理由**：客户端 secret 一旦进 IPA 永久泄露 + AppSecret 不可重置（Contract §0.4 / Design §17）；上线前必须闭环
+- **复盘节点**：Phase 4 完成时检查后台接口状态
+
 ### ADR-004：Resources/ 目录位于仓库根（非 Xcode 工程内）（2026-06-21）
 - **决策**：项目方提供的所有资源（`gamehall.zip` / 原生 Asset Catalog / 散落 png / mp3 / 后续渠道注入目录）统一放仓库根 `Resources/`，由打包脚本通过 Build Phase 引入；**不**直接放进 Xcode 工程的 `ylgamehall/` 源码目录
 - **理由**：
@@ -871,12 +879,23 @@ H5 调 `OpenurlTitleData` 打开弹层 WebView，弹层内 H5 用 `window.settin
  - 符合 Design §2.2 的 SPM 包结构规划（`Resources/` 与 `Sources/` 并列）
 - **现状**：`Resources/` 已含 `gamehall.zip` / `Images.xcassets/` / `Res/`；11 个渠道注入目录预留位 `Resources/ChannelInjection/` 待 Phase 1 由 `Scripts/inject_channel.sh` 生成

-### ADR-003：微信登录走后台中转 vs 客户端 fallback（2026-06-21）
- **决策**：默认走后台 `/wechat/login` 中转；后台未就绪时临时客户端直拼，但代码标 `// FIXME` 且**禁止以 fallback 状态上线**
- **理由**：客户端 secret 一旦进 IPA 永久泄露 + AppSecret 不可重置（Contract §0.4 / Design §17）；上线前必须闭环
- **复盘节点**：Phase 4 完成时检查后台接口状态
+### ADR-005：JAnalytics（极光）首版降为 NoopAnalytics 占位（2026-06-21）
+- **背景**：Design §14.2 原标注极光"✅ 启用，启动注册"，但项目方在 2026-06-21 评审时确认**首版无用户激活 / 留存分析需求**
+- **决策**：与 Xianliao / Agora 同款渐进集成策略——首版不集成极光 SDK，`AnalyticsKit.tracker` 默认绑到 `NoopAnalytics`，业务调用 `Tracker.event(...)` 立即返回不做任何事；编译开关 `JANALYTICS_ENABLED` 默认 OFF，留蓝图 `JAnalyticsTracker.swift` 待启用
+- **理由**：
+  - 减少首版外部依赖（首版 SDK 集成清单：微信 / QQ / 高德 / 七牛 / opencore-amr / Sentry / ZIPFoundation，共 7 个；不集成 4 个：极光 / 闲聊 / Agora / Bugly）
+  - 现网 msext 的极光后端运维状态不可知，与 Bugly 同样有"账号断档监控失效"风险（CLAUDE.md / 父级 msext 已有先例），新外壳起步不重蹈
+  - Sentry 的 breadcrumb / transaction 可兜一部分用户行为路径，初期定位够用
+  - 接入成本（AppKey 申请 / Vendor 二进制 / Info.plist 隐私文案）推迟到真有业务需求时
+- **后续启用路径**（保持契约不变，业务无感）：
+  1. 在 `Vendor/` 放入 `JAnalytics.framework`
+  2. 把 `AnalyticsKit.tracker` 从 `NoopAnalytics()` 切换为 `JAnalyticsTracker()`
+  3. xcconfig 注入 `JANALYTICS_ENABLED=1`
+  4. Bootstrapper.registerSDKs 加 `JAnalytics.setup(appKey:)`
+  5. Info.plist 加 AppKey + 隐私授权文案
+- **复盘节点**：上线 3 个月后业务方根据数据需求决定是否启用

 ---

 文档完成日期：2026-06-21
-最后更新：2026-06-21（初版）
+最后更新：2026-06-21（ADR-005 极光降级 + Resources/ 目录记录）
@@ -132,15 +132,15 @@ Daoqi/
 │   ├── LocationKit/              # 高德定位
 │   ├── DeviceKit/                # 设备信息/电池/网络/振动
 │   ├── VideoRoomKit/             # Agora 封装
-│   ├── AnalyticsKit/             # 极光、Sentry
+│   ├── AnalyticsKit/             # Sentry(默认启用) / JAnalytics 极光(暂不集成,Noop 占位)
 │   ├── Logger/                   # 统一日志
 │   └── Foundation+/              # 通用扩展
 ├── Vendor/                       # 闭源 SDK(.framework / .a)
 │   ├── WechatSDK.framework       # 启用
 │   ├── AMapLocationKit.framework # 启用
-│   ├── JAnalytics.framework      # 启用
 │   └── libopencore-amr*.a        # 启用
 │   # 暂不集成(对应代码模块用 Noop 占位):
+│   # - JAnalytics.framework      # 启用用户统计时再放入
 │   # - XianliaoSDK.framework     # 启用闲聊分享时再放入
 │   # - AgoraRtcKit.framework     # 启用视频房间时再放入(或改用 SPM)
 ├── Resources/
@@ -191,7 +191,7 @@ Daoqi/
 | `LocationKit` | `LocationService` | AMapKit Wrapper |
 | `DeviceKit` | `DeviceInfo`, `BatteryMonitor`, `NetworkMonitor`, `Vibrator`, `Pasteboard` | Foundation+ |
 | `VideoRoomKit` | `VideoRoom`(协议) → `NoopVideoRoom` 当前启用 / `AgoraVideoRoom` 留蓝图 | (Agora SDK 暂未引入) |
-| `AnalyticsKit` | `Analytics`(协议) → `SentryCrashReporter` / `JAnalytics` | SDK Wrappers |
+| `AnalyticsKit` | `CrashReporter`(协议) → `SentryCrashReporter` 启用 / `Tracker`(协议) → `NoopAnalytics` 当前启用 / `JAnalyticsTracker` 留蓝图 | SDK Wrappers |

 ---

@@ -548,10 +548,9 @@ SceneDelegate.scene(_:willConnectTo:options:)        T=0
    │
    ├─► (并行) SDK 注册                              T=0
    │       • WeChat                  ~10 ms
-    │       • JAnalytics              ~10 ms
    │       • AMap (privacy + key)    ~15 ms
    │       • crashReporter.start()   ~20 ms(Sentry 默认启用)
-    │       (Xianliao / Agora / Bugly 当前未集成,见 §14.2)
+    │       (JAnalytics 极光 / Xianliao 闲聊 / Agora 声网 / Bugly 当前未集成,见 §14.2)
    │       并发 Task,await 全部完成
    │
    ├─► Window 创建 + LobbyViewController push       T=50ms
@@ -618,8 +617,8 @@ final class Bootstrapper {
    private func registerSDKs() async {
        await withTaskGroup(of: Void.self) { group in
            group.addTask { WeChatSDK.registerFull(appId: AppIDs.weChat) }   // 含 contentFlag
-            // XianliaoSDK 暂不集成(§14.2);Agora 同样,懒加载也无需启动注册
-            group.addTask { AnalyticsKit.start() }
+            // JAnalytics(极光) / XianliaoSDK(闲聊) / Agora(声网) 暂不集成(§14.2)
+            // — 对应模块用 Noop 占位,首版不参与启动注册
            group.addTask { AMapWrapper.configure() }
            group.addTask { crashReporter.start() }     // SentryCrashReporter by default; Noop if SENTRY_ENABLED=0
        }
@@ -2085,7 +2084,7 @@ done

 1. **首选 SPM** —— Apple 官方,Xcode 原生集成,无第三方工具依赖,无衍生工程文件污染,新人 clone 即用。适用于:Sentry、ZIPFoundation、Agora 4.x、七牛 v8+ 等**已发布官方 Swift Package** 的库
 2. **CocoaPods 兜底** —— 用于"有 podspec 但暂无 SPM 包"的 SDK,主要是高德定位、部分 Agora 旧版兼容场景。Podfile 仅写必须的 Pod,不引入大规模 transitive 依赖
-3. **Vendor 手动** —— `Vendor/` 目录直接放闭源 `.framework` / `.a`,xcconfig 配置 link flag。适用于:微信 OpenSDK、QQ OpenSDK、闲聊 SDK、JAnalytics、opencore-amr 等**官方不提供 SPM / Pod 的私有 framework**
+3. **Vendor 手动** —— `Vendor/` 目录直接放闭源 `.framework` / `.a`,xcconfig 配置 link flag。适用于:微信 OpenSDK、QQ OpenSDK、闲聊 SDK(暂不集成)、JAnalytics(暂不集成)、opencore-amr 等**官方不提供 SPM / Pod 的私有 framework**

 #### 为什么不选纯 SPM
 微信 / QQ / 闲聊 / JAnalytics 等闭源 SDK 官方至今(2026)未提供 Swift Package,强行纯 SPM 化需要自己包一层私有 Package,维护成本反而上升。
@@ -2109,7 +2108,7 @@ Sentry / ZIPFoundation 等纯 Swift 包走 Pods 需绕一道 podspec,失去 SPM
 | opencore-amr | 静态 `.a`(直接接入 — H5 端通过此库收发的 AMR 音频是契约边界) | 2014 版本 | ✅ 启用 |
 | ZIPFoundation | **SPM** | latest | ✅ 启用 |
 | Sentry-Cocoa | **SPM**(默认 ON,编译开关 `SENTRY_ENABLED` 提供逃生口) | latest | ✅ 启用,启动并发注册 |
-| JAnalytics | Vendor | 现网版本 | ✅ 启用,启动注册 |
+| **JAnalytics(极光)** | — | — | ⏸️ **暂不集成**(`AnalyticsKit.tracker = NoopAnalytics`)。新外壳首版不接用户统计 — 现网 msext 的极光后端运维状态不可知,且 Sentry 的 breadcrumb / transaction 可兜一部分行为指标。启用时:① Vendor `.framework` 放入 ② `NoopAnalytics` 换为 `JAnalyticsTracker` ③ Info.plist 加 AppKey ④ Bootstrapper 注册 |
 | **Bugly** | — | — | ⏸️ **不集成**。Sentry 已覆盖崩溃 / 性能监控,无需 Bugly。未来若有强需求(如旧外壳数据迁移),再单独评估 |

 > **微信 OAuth 架构决策**:新项目走**后台中转** —— 客户端把 `code` 发给后台 `/wechat/login` 接口,由后台完成 `access_token` + `userinfo` 拉取,再回传 7 个字段给客户端,客户端最终 `callHandler:@"sharelogin"` 给 H5。