youle_app_ios_v2/docs/SDK-Integration-Guide.md

# SDK 接入指南

> 本文档面向项目方 + 开发者，描述 Phase 4.E / Phase 5 / Phase 3.B-D 三组 SDK 的真实接入步骤。
>
> **使用方式**：每接入一个 SDK 走一遍对应章节的"凭证清单 / 工程接入 / 代码触点 / 清理钩子 / 验收"五步，全程对照 CLAUDE.md「原则 A — H5 端零修改」与 ADR-006「禁止 CocoaPods」。

---

## 0. 总览

| SDK | 触发的契约项 | 选型 | 阻塞 |
|---|---|---|---|
| **微信 OpenSDK** | `accreditlogin` / `friendsSharetypeUrlToptitleDescript`（微信路径）/ `sharelogin` 反向 callback / `sharesuccess` | Vendor `.xcframework` 手动 | AppID + Universal Links + 后台 `/wechat/login`（或客户端 fallback） |
| **高德定位（AMap）** | `startlocation` / `getlocationinfo` 反向 callback（9 字段）| Vendor `.xcframework` 手动 | **新 APIKey（绑死 Bundle ID，不可复用 msext）** + 隐私合规调用 |
| **opencore-amr** | `prepareaudio`（录音上传）/ `mediaTypeAudio`（远端语音回放）AMR ↔ WAV 转码 | 从 msext 拷贝已修复版 `.a`（fat header segalign 8） | 无外部凭证；二进制已在 msext 仓库内 |
| **七牛云上传** | `prepareaudio` → `getaudiourl({audiourl, time})` / `recordSuccess` 反向 callback | SPM 官方 `https://github.com/qiniu/objc-sdk` v8.9.x | 后台 token 颁发接口 / 长 token 缓存策略 |

**两条铁律（CLAUDE.md）**：
1. 任何接入步骤都不允许触碰 H5 端任何文件（包括 `app_*.js`）
2. 不引入 CocoaPods；SPM 优先，闭源走 Vendor `.xcframework`

---

## 1. 微信 OpenSDK（Phase 4.E）

### 1.1 凭证清单（项目方提供）

- [ ] **AppID**：微信开放平台「移动应用」面板新建一个应用（新 Bundle ID 不能复用 msext 的 `wx586a9b321e56efb7`，必须为本项目重新申请）
- [ ] **Universal Links**：项目方拥有的域名 + `apple-app-site-association` 文件（部署到 `https://your-domain.com/.well-known/apple-app-site-association`，HTTPS 必须）
- [ ] **后台 `/wechat/login` 中转接口**（强烈推荐）：客户端拿 `code` 调后台，后台用 `AppSecret` 换 `access_token` + `unionid` + `userinfo`，回 7 字段给客户端
  - 若后台未就绪，客户端走 fallback：`api.weixin.qq.com/sns/oauth2/access_token` + `sns/userinfo`，**`AppSecret` 客户端硬编码 = 安全风险**，CLAUDE.md 父项目已明确警告。新项目尽量直接走后台中转
- [ ] **微信 OpenSDK XCFramework**：从 [微信开放平台官网下载](https://developers.weixin.qq.com/doc/oplatform/Downloads/iOS_Resource.html)，使用 1.9.x 或最新（避免 1.8.x 的 ITMS-90809 历史包袱）

### 1.2 工程接入

1. **放置 SDK**
   ```
   Vendor/WechatSDK/
     ├── WechatOpenSDK.xcframework
     └── README.md       # 记录版本号 + 下载日期 + 来源
   ```
   按 Design §14.1 Vendor 接入标准流程：Target → General → Frameworks → Embed & Sign

2. **Info.plist 改动**（仅原生侧，不动 H5）
   ```xml
   <!-- 1. URL Scheme：让微信 App 回调能打开本 App -->
   <key>CFBundleURLTypes</key>
   <array>
     <dict>
       <key>CFBundleURLName</key>
       <string>weixin</string>
       <key>CFBundleURLSchemes</key>
       <array><string>YOUR_WX_APPID</string></array>
     </dict>
   </array>

   <!-- 2. 查询微信是否安装 -->
   <key>LSApplicationQueriesSchemes</key>
   <array>
     <string>weixin</string>
     <string>weixinULAPI</string>
     <string>weixinURLParamsAPI</string>
     <!-- 已有的 mqq* / snssdk1128 别覆盖 -->
   </array>
   ```

3. **Entitlement 改动**（Signing & Capabilities）
   - Associated Domains 添加 `applinks:your-domain.com`（与 `apple-app-site-association` 的域名严格一致）

### 1.3 代码触点（接入此 SDK 必须改的文件）

| 文件 | 改动 |
|---|---|
| **`Source/SDK/WeChat/WeChatSDK.swift`**（新建） | `WXApi.registerApp(_:universalLink:)` 启动注册；包含全部 12 个 `MMAPP_SUPPORT_*` flag（Design §4.2） |
| **`AppDelegate.swift`** | `application(_:didFinishLaunchingWithOptions:)` 内调 `WeChatSDK.register()` |
| **`SceneDelegate.swift`** | `openURLContexts` 内按 **QQ → WXApi** 顺序判（msext `AppDelegate.m` 顺序硬约束，QQ 必须先判） |
| **`Source/SDK/WeChat/WeChatManager.swift`**（新建） | 持久 delegate；`authorize() async throws -> WXAuthCode`（state UUID 配对）；`share(_:scene:) async throws`（FIFO 串行）。Design §8.5 |
| **`Source/Login/WeChatAuth.swift`**（新建） | `authorize()` 拿 code → 转后台 `/wechat/login`（或 fallback 拼 `sns/oauth2/access_token` + `sns/userinfo`）→ 拿到 7 字段 user。Fallback 文件头标 `// FIXME: 待后台 /wechat/login 就绪后切换为后台中转` |
| **`Source/Bridge/Handlers/AccreditLoginHandler.swift`** | 移除 stub 返回，调 `WeChatAuth.authorize()` → 反向 `bridge.call("sharelogin", 7 字段)`<br>**字段名严格 1:1（含历史包袱）**：`openid` / `headimgurl` / `nickname` / `sex` / `city` / `Province`（**大写 P**！）/ `unionid` |
| **`Source/Share/WechatShare.swift`** | 移除 stub `return .success`，调 `WeChatManager.share`；`isInstalled` 改为 `WXApi.isWXAppInstalled()` |
| **`Source/Bridge/Handlers/BackGameDataHandler.swift`** | **必须加** `WXApi.delegate = nil`（清理子游戏 push 期间的 delegate 指针） |

### 1.4 清理钩子（CLAUDE.md 第 6.0 节回响）

`BackGameDataHandler.swift` 的 `MainActor.run` 块加一行：
```swift
WXApi.delegate = nil    // ← Phase 4.E 接入时取消注释
```
理由：msext `gameController.m:699` 在 backgameData 里清 delegate，防止 pop 后微信回调指向已销毁的 SubGameVC。

### 1.5 验收（H5 端零修改前提下跑）

- [ ] H5 调 `bridge.callHandler('accreditlogin')` → 拉起微信 → 同意授权 → 大厅收 `sharelogin({openid,...,Province})`，**`Province` 是大写 P**
- [ ] H5 调 `bridge.callHandler('friendsSharetypeUrlToptitleDescript', {sharefriend:"2", ...})` → 直接调起微信朋友圈
- [ ] H5 调 `sharefriend:"1"` → SharePanel 三按钮，点微信 → 拉起微信好友选择 → 分享成功后大厅收 `sharesuccess({success:"2",type:"1"})`
- [ ] **关键回归**：截图分享 / QQ 分享 / 抖音分享路径不受影响

### 1.6 风险

- **AppSecret 客户端泄露**：fallback 路径上线前必须切到后台中转，否则 secret 一旦泄露不可重置（CLAUDE.md 父项目「已识别为安全风险，明确接受不修」的同款问题，新项目从一开始避免）
- **Universal Links 配置错误**：授权回不来。验证方式：`xcrun simctl openurl booted "https://your-domain.com/test"` 看是否拉起本 App
- **微信审核**：审核期间 OpenSDK 行为差异（部分 API 限频），上线初期保持后台监控

---

## 2. 高德定位 SDK（Phase 5）

### 2.1 凭证清单

- [ ] **新 APIKey**：[高德控制台](https://lbs.amap.com/dev/key/app) 用项目方账号新建应用，绑定本项目的 Bundle ID（**msext 的 `b0d4a8e3fcbbcc0dd96283b7df6a4494` 不能复用**，APIKey 与 Bundle ID 一一绑死）
- [ ] **AMap SDK XCFramework**：[官方下载页](https://lbs.amap.com/api/ios-location-sdk/download)拉取最新（截至 2026-06 推荐 v2.10.x+）
  - `AMapLocationKit.xcframework` — 定位主库
  - `AMapFoundationKit.xcframework` — 基础库（必须配合 LocationKit）

### 2.2 工程接入

1. **放置 SDK**
   ```
   Vendor/AMap/
     ├── AMapLocationKit.xcframework
     ├── AMapFoundationKit.xcframework
     └── README.md     # 记录 SDK 版本 + APIKey 创建日期 + 绑定 Bundle ID
   ```
   Target → General → Frameworks → Embed & Sign（两个都要）

2. **Info.plist**（仅原生侧）
   ```xml
   <key>NSLocationWhenInUseUsageDescription</key>
   <string>{gamehallname}需要访问您的位置以提供本地化服务</string>
   ```
   `{gamehallname}` 占位由 ChannelConfig.plist 注入或硬编为渠道名。

### 2.3 代码触点

| 文件 | 改动 |
|---|---|
| **`Source/SDK/AMap/AMapWrapper.swift`**（新建） | 启动期调用顺序：`updatePrivacyShow(.didShow, privacyInfo: .didContain)` → `updatePrivacyAgree(.didAgree)` → `AMapServices.shared().apiKey = "..."`（**iOS 14+ 隐私合规必走的 3 步**，少一步定位拿不到结果） |
| **`AppDelegate.swift`** | `didFinishLaunchingWithOptions` 内调 `AMapWrapper.bootstrap()` |
| **`Source/Location/LocationService.swift`**（新建，actor） | `requestOnce() async throws -> LocationPayload`（一次定位）<br>`startContinuous(onUpdate:)` / `stop()`（持续定位）<br>包 `AMapLocationManager`，回调转 `async` |
| **`Source/Bridge/Handlers/StartLocationHandler.swift`** | 移除 stub，按 `data == 1` 持续 / 其它一次性<br>反向 callback `bridge.call("getlocationinfo", 9 字段)`<br>**字段名严格 1:1**：`address` / `city` / `cityCode` / `country` / `district` / `latitude`（**string**，`String(format: "%f", lat)`）/ `longitude`（**string**）/ `province`（**小写 p**！与 `sharelogin.Province` 不同）/ `street`<br>失败：`getlocationinfo({errorCode:12, errorMsg:"缺少定位权限"})` |
| **`Source/Bridge/Handlers/BackGameDataHandler.swift`** | **必须加** `LocationService.shared.stop()` |

### 2.4 清理钩子

`BackGameDataHandler.swift` 的 `MainActor.run` 块加：
```swift
LocationService.shared.stop()    // ← Phase 5 接入时取消注释
```
理由：msext `gameController.m:2473-2478 cleanUpAction` 在 backgameData 里调 `[locationManager stopUpdatingLocation]` + delegate nil；防止 pop 后后台定位继续耗电 + 回调悬空。

### 2.5 验收

- [ ] 首次启动 → 系统权限弹框（文案为 Info.plist 设置的中文）
- [ ] H5 调 `bridge.callHandler('startlocation', "1")` → 收到 `getlocationinfo({...9 字段...})`，`latitude` / `longitude` 是 string 类型，`province` 是小写 p
- [ ] 拒绝权限 → H5 收 `getlocationinfo({errorCode:12,errorMsg:"缺少定位权限"})`
- [ ] 子游戏定位中 → 调 `backgameData` 退出 → 大厅不再收到悬挂定位回调（验证 cleanUp 钩子）

### 2.6 风险

- **APIKey 绑定**：Bundle ID 改了 / 多 Target 用不同 ID 都要重新申请 key，否则定位失败但无明显报错（高德回 errorCode 7「KEY 校验失败」）
- **隐私合规调用顺序**：iOS 14+ 必须先 `updatePrivacyShow` → `updatePrivacyAgree` 再 `apiKey`，否则定位接口直接拒绝
- **模拟器**：高德定位在模拟器走 Apple 的 CoreLocation 模拟坐标，定位精度低，必须真机测

---

## 3. opencore-amr 转码库（Phase 3.B）

### 3.1 凭证清单

- 无凭证。二进制已在 msext 仓库内，**且已经过 fat header `segalign 8` 修复**（参 CLAUDE.md 父项目「已处理的定时炸弹」一节，2026-06-20 摘掉 `-ld_classic` 的同一组 `.a`）

### 3.2 工程接入

1. **拷贝二进制**（已修复版）
   ```bash
   mkdir -p ylgamehall/Vendor/opencore-amr/
   cp ../daoqi/msext/msext/Class/Common/VoiceConvert/lib/libopencore-amrnb.a ylgamehall/Vendor/opencore-amr/
   cp ../daoqi/msext/msext/Class/Common/VoiceConvert/lib/libopencore-amrwb.a ylgamehall/Vendor/opencore-amr/
   # 拷头文件
   cp -r ../daoqi/msext/msext/Class/Common/VoiceConvert/include ylgamehall/Vendor/opencore-amr/
   ```

2. **拷 VoiceConverter（ObjC wrapper）**
   ```
   ylgamehall/Vendor/opencore-amr/VoiceConverter/
     ├── VoiceConverter.h    # ObjC interface（保留 ObjC，wrapper 简单不重写 Swift）
     ├── VoiceConverter.m    # MRC 代码可保留，加 -fno-objc-arc 编译标志或转 ARC
     ├── amrFileCodec.h/m
     └── interf_*.h/c
   ```

3. **Xcode 工程配置**
   - Target → Build Phases → Link Binary With Libraries 加入两个 `.a`
   - Target → Build Settings → Library Search Paths 加 `$(PROJECT_DIR)/ylgamehall/Vendor/opencore-amr`
   - Target → Build Settings → Header Search Paths 加 `$(PROJECT_DIR)/ylgamehall/Vendor/opencore-amr/include`
   - **不需要** `-ld_classic`（已用 `lipo -segalign 8` 修复 fat header，CLAUDE.md 父项目记录的修复同样适用）
   - 若复用 msext MRC 的 `VoiceConverter.m`，加文件级 `-fno-objc-arc` 编译标志

4. **Bridging Header**（已有 `ylgamehall-Bridging-Header.h` 则追加；无则新建）
   ```objc
   #import "VoiceConverter.h"
   ```

### 3.3 代码触点

| 文件 | 改动 |
|---|---|
| **`Source/Audio/VoiceCoder.swift`**（新建） | Swift wrapper：`static func amrToWav(_ amrPath: URL) throws -> URL` / `static func wavToAmr(_ wavPath: URL) throws -> URL`<br>内部调 ObjC `VoiceConverter` |
| **`Source/Audio/AudioRecorder.swift`**（新建，actor） | `record() async throws -> AudioFile`：`AVAudioRecorder` 录 WAV + 麦克风权限<br>录音参数与 msext `ChatVoiceRecorderVC` 等价：16kHz / 单声道 / 16-bit |
| **`Source/Bridge/Handlers/RemoteAudioHandler.swift`** | 移除 stub，分别接入：<br>**`prepareaudio`**（录音上传）→ `AudioRecorder.record()` → WAV→AMR `VoiceCoder.wavToAmr` → `QiniuUploader.upload`（见 §4） → `bridge.call("getaudiourl", {audiourl, time})`，**子游戏页额外触发** `bridge.call("recordSuccess", {fileUrl, fileName, fileKey})`<br>**`mediaTypeAudio`**（远端回放）→ URLSession 下载 AMR → AMR→WAV `VoiceCoder.amrToWav` → `AVAudioPlayer` 播放<br>开始播放 `bridge.call("gameui_play_voice", user)` / 播放结束 `bridge.call("gameui_stop_voice", user)`<br>受 `VoicePlayingHandler` 的开关短路（=1 才播） |
| **`Info.plist`** | 加 `NSMicrophoneUsageDescription = "{gamehallname}需要访问您的麦克风录制语音消息"` |
| **`Source/Bridge/Handlers/BackGameDataHandler.swift`** | **必须加** `AudioRecorder.shared.cancel()` |

### 3.4 清理钩子

```swift
AudioRecorder.shared.cancel()        // ← Phase 3.C 接入时取消注释
QiniuUploader.shared.cancelInFlight() // ← Phase 3.C 接入时取消注释
```
理由：录音 / 上传任务跨 VC 生命周期容易遗留；msext 通过 `ChatVoiceRecorderVC` 生命周期间接清理，我们的 actor 实现不绑 VC 必须显式 cancel。

### 3.5 验收

- [ ] H5 调 `prepareaudio` → 弹麦克风权限 → 同意后开始录音 → 录完上传七牛 → 大厅收 `getaudiourl({audiourl:"https://...", time:"3"})`
- [ ] 子游戏同样路径，额外收到 `recordSuccess({fileUrl, fileName, fileKey})`
- [ ] H5 调 `mediaTypeAudio({audiourl, user})` → 听到对方语音 + 收到 `gameui_play_voice` / 结束收 `gameui_stop_voice`
- [ ] `voicePlaying` 总开关设 0 → 调 `mediaTypeAudio` 不播放

---

## 4. 七牛云上传（Phase 3.C / 3.D）

### 4.1 凭证清单

- [ ] **后台 token 颁发接口**：每次录音前向后台 GET `/api/qiniu/upload-token?scene=voice` 拿到上传凭证 + 域名
- [ ] **七牛 Bucket 名 / CDN 域名**：项目方提供（可硬编到 BundleConfig，或随 ChannelConfig 注入）

### 4.2 工程接入（SPM，优于二进制）

1. Xcode → File → Add Package Dependencies
2. URL：`https://github.com/qiniu/objc-sdk`
3. 版本：`8.9.x` 最新（avoid 7.x 历史 API）
4. 勾选 target → Add Package

注：七牛官方 SPM 包是 ObjC，但 SPM 直接支持 ObjC + Swift 混合，不需要 bridging header（SPM 自动处理）。

### 4.3 代码触点

| 文件 | 改动 |
|---|---|
| **`Source/Network/QiniuTokenService.swift`**（新建，actor） | `fetchUploadToken() async throws -> QiniuToken`（含 token / 上传域名 / Key 模板 / 过期时间）<br>缓存策略：token 失效前 30 秒强制刷新；并发请求合并 |
| **`Source/Network/QiniuUploader.swift`**（新建，actor） | `upload(_ file: URL, token: QiniuToken) async throws -> UploadedFile`<br>内部用 `QNUploadManager` 包成 async；UploadedFile 含 `fileUrl` / `fileName` / `fileKey`<br>取消语义：`cancelInFlight()` 取消所有进行中任务（接清理钩子用） |
| **`Source/Bridge/Handlers/RemoteAudioHandler.swift`** | `prepareaudio` 完整链路第 3 步：`QiniuUploader.upload(amrFile, token: await QiniuTokenService.shared.fetchUploadToken())` |

### 4.4 清理钩子

见 §3.4（与 opencore-amr 同一处加 `QiniuUploader.shared.cancelInFlight()`）。

### 4.5 验收

- [ ] H5 调 `prepareaudio` → 录音 3 秒 → 上传 → 大厅收 `getaudiourl({audiourl:"https://your-cdn.com/voice/xxx.amr", time:"3"})`
- [ ] 录音中 / 上传中 → 退出子游戏 → 任务被 cancel，不再有悬空网络写
- [ ] token 过期场景：模拟后台返回过期 token → uploader 自动刷新重试一次

### 4.6 风险

- **token 时效**：通常 1 小时；高频录音场景需要 caching + 失效前预刷新
- **上传失败重试**：默认 3 次，超时建议设 30s（语音文件通常 < 100KB）
- **CDN 域名 HTTPS**：H5 业务侧拿到 `audiourl` 后会请求播放，必须保证域名 HTTPS（NSAppTransportSecurity 我们没收紧 ATS，但七牛默认走 HTTPS）

---

## 5. 接入完毕的清单检查

每接入完一个 SDK，跑一遍：

- [ ] `BuildProject` 成功
- [ ] `Vendor/<SDK>/README.md` 已记录版本号 / 来源 / 凭证创建日期
- [ ] Info.plist 改动只在原生侧，未触 H5 任何文件
- [ ] `BackGameDataHandler.swift` 对应清理钩子已加（每个 SDK 都要回到此处补 1 行）
- [ ] `docs/Development-Plan.md §5 / §8` 进度勾选已同步（提交时附 commit 备注「Plan 进度已勾选」）
- [ ] `docs/Verification-Checklist.md` 对应 Phase 验证项已补充
- [ ] 真机跑过该 SDK 的验收项（模拟器对 SDK 行为不可靠：高德、微信、AVAudioRecorder 都受影响）

---

## 6. 与原项目 daoqi 的关系

接入过程中若行为与文档描述不一致，**优先参考原 daoqi 工程实现**（参 `CLAUDE.md`「原项目 daoqi：遇到问题时的参考来源」一节）：

- 微信回调字段：`daoqi/msext/Class/RootVC/NewRootVC.m:2428`（`sharelogin` 7 字段，含 `Province` 大写）
- 高德 9 字段：`daoqi/msext/Class/RootVC/gameController.m:2528 / 2557`（`getlocationinfo` 字段顺序与类型）
- AMR 转码：`daoqi/msext/Class/Common/VoiceConvert/`（`VoiceConverter.h/m`、`amrFileCodec.h/m`）
- 七牛上传：`daoqi/msext/Class/Utils/QiniuManager.m`（参数命名 + 回调结构）

**遇到契约边界 / 历史包袱时**：照搬 msext 字面 + 字段名 + 顺序，不要凭语义猜测。原项目稳定运行多年的写法是真理，文档 / 设计稿可能有传抄错误（已在 CLAUDE.md「典型案例」积累若干）。