调整极光

docs/Development-Plan.md

@@ -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/ 目录记录）