@tencent-rtc/trtc-agent-skills 0.1.0

package/knowledge-base/slices/live/ios/anchor-lifecycle.md

@@ -0,0 +1,313 @@
+---
+id: live/anchor-lifecycle
+platform: ios
+---
+
+# 主播开播与结束生命周期 — iOS 实现
+
+## 前置条件
+
+**依赖安装（Podfile）**
+```ruby
+pod 'AtomicXCore', '~> 4.0'
+```
+
+**前置状态**：
+- `LoginStore.shared` 登录成功
+- `DeviceStore.shared.openLocalCamera` 已成功（摄像头就绪）
+- `DeviceStore.shared.openLocalMicrophone` 已成功（麦克风就绪）
+- `LiveInfo` 已配置完毕（通过 `init(seatTemplate:)` 初始化，liveID 必填）
+
+## API 调用（真实签名）
+
+```swift
+// LiveCoreView 初始化：参数名是 viewType（不是 liveScene）
+// CoreViewType 枚举：.pushView（推流/主播端）、.playView（拉流/观众端）
+LiveCoreView(viewType: CoreViewType, frame: CGRect = .zero)
+
+// 开播：第一参数无标签；completion 返回 LiveInfo
+LiveListStore.shared.createLive(_ liveInfo: LiveInfo,
+                                completion: LiveInfoCompletionClosure?)
+// LiveInfoCompletionClosure = (Result<LiveInfo, ErrorInfo>) -> Void
+
+// 结束直播：无 liveID 参数
+LiveListStore.shared.endLive(completion: StopLiveCompletionClosure?)
+// StopLiveCompletionClosure = ...  // TODO: 待验证 — 确认实际签名
+
+// 订阅直播列表事件（Combine）
+LiveListStore.shared.liveListEventPublisher  // PassthroughSubject<LiveListEvent, Never>
+```
+
+**LiveListEvent 完整签名**
+```swift
+enum LiveListEvent {
+    // 直播被动结束（服务端强制终止/超时）
+    case onLiveEnded(liveID: String, reason: LiveEndedReason, message: String)
+
+    // 被踢出直播间
+    case onKickedOutOfLive(liveID: String, reason: LiveKickedOutReason, message: String)
+}
+```
+
+**关键类型说明**
+```swift
+// LiveInfo 初始化（必须传 seatTemplate）
+var liveInfo = LiveInfo(seatTemplate: .videoDynamicGrid9Seats)
+liveInfo.liveID   = "your-live-id"
+liveInfo.liveName = "直播间名称"
+
+// 通用回调
+typealias CompletionClosure         = (Result<Void, ErrorInfo>) -> Void
+typealias LiveInfoCompletionClosure = (Result<LiveInfo, ErrorInfo>) -> Void
+
+struct ErrorInfo {
+    var code: Int
+    var message: String
+}
+```
+
+## 代码示例
+
+```swift
+import AtomicXCore
+import Combine
+
+var cancellables = Set<AnyCancellable>()
+var isLiving = false
+
+// MARK: - 开播
+
+func startLive(liveID: String, liveName: String) {
+    // ⚠️ 必须用 init(seatTemplate:)，不是 LiveInfo()
+    var liveInfo = LiveInfo(seatTemplate: .videoDynamicGrid9Seats)
+    liveInfo.liveID   = liveID
+    liveInfo.liveName = liveName
+
+    // ⚠️ 第一参数无标签（unnamed first param）
+    LiveListStore.shared.createLive(liveInfo) { result in
+        switch result {
+        case .success(let createdLiveInfo):
+            // 成功时回调携带服务端确认的 LiveInfo（含 createTime 等字段）
+            isLiving = true
+            print("[Lifecycle] 开播成功, liveID: \(createdLiveInfo.liveID)")
+
+        case .failure(let errorInfo):
+            print("[Lifecycle] 开播失败, code: \(errorInfo.code), msg: \(errorInfo.message)")
+            handleCreateError(errorInfo)
+        }
+    }
+}
+
+// MARK: - 结束直播
+
+func stopLive() {
+    guard isLiving else { return }
+    isLiving = false
+
+    // Step 1: 关闭设备（先关设备再结束房间）
+    DeviceStore.shared.closeLocalCamera()
+    DeviceStore.shared.closeLocalMicrophone()
+
+    // Step 2: 结束直播（无 liveID 参数，endLive 结束当前房间）
+    LiveListStore.shared.endLive { result in
+        switch result {
+        case .success:
+            print("[Lifecycle] 直播结束成功")
+            cleanupSubscriptions()
+
+        case .failure(let errorInfo):
+            // 即使失败也应清理本地资源
+            print("[Lifecycle] endLive 失败, code: \(errorInfo.code)")
+            cleanupSubscriptions()
+        }
+    }
+}
+
+// MARK: - 订阅被动结束事件（先订阅再开播，防止事件丢失）
+
+func subscribeLiveEvents(currentLiveID: String) {
+    LiveListStore.shared.liveListEventPublisher
+        .receive(on: DispatchQueue.main)
+        .sink { event in
+            switch event {
+            // ⚠️ onLiveEnded 有三个关联值：liveID, reason, message
+            case .onLiveEnded(let liveID, let reason, let message)
+                where liveID == currentLiveID:
+                print("[Lifecycle] 直播被动结束, reason: \(reason), msg: \(message)")
+                handlePassiveEnd(reason: message)
+
+            // ⚠️ onKickedOutOfLive 有三个关联值：liveID, reason, message
+            case .onKickedOutOfLive(let liveID, let reason, let message)
+                where liveID == currentLiveID:
+                print("[Lifecycle] 被踢出直播间, reason: \(reason), msg: \(message)")
+                handleKickedOut(message: message)
+
+            default:
+                break
+            }
+        }
+        .store(in: &cancellables)
+}
+
+// MARK: - 被动结束处理
+
+func handlePassiveEnd(reason: String) {
+    isLiving = false
+    DeviceStore.shared.closeLocalCamera()
+    DeviceStore.shared.closeLocalMicrophone()
+    cleanupSubscriptions()
+    print("[Lifecycle] 被动结束处理完成：\(reason)")
+}
+
+func handleKickedOut(message: String) {
+    isLiving = false
+    DeviceStore.shared.closeLocalCamera()
+    DeviceStore.shared.closeLocalMicrophone()
+    cleanupSubscriptions()
+    print("[Lifecycle] 被踢出处理完成：\(message)")
+}
+
+// MARK: - 错误处理
+
+func handleCreateError(_ errorInfo: ErrorInfo) {
+    switch errorInfo.code {
+    case -2105: print("直播间 ID 格式非法")
+    case -2107: print("直播间名称非法（超长或含特殊字符）")
+    case -2108: print("您已在其他直播间，请先退出")
+    default:    print("开播失败（code: \(errorInfo.code)）: \(errorInfo.message)")
+    }
+}
+
+// MARK: - 清理
+
+func cleanupSubscriptions() {
+    cancellables.removeAll()
+}
+```
+
+## 调用时序
+
+```
+设备就绪（openLocalCamera + openLocalMicrophone 成功）
+        │
+        ▼
+subscribeLiveEvents(currentLiveID:)     ← ① 先订阅事件，防止 createLive 前丢失
+        │
+        ▼
+构建 LiveInfo(seatTemplate: .videoDynamicGrid9Seats)
+设置 liveID + liveName（+ 其他选填字段）
+        │
+        ▼
+// 第一参数无标签
+LiveListStore.shared.createLive(liveInfo) { result in ... }
+        │
+        ├─ .failure(errorInfo)
+        │       ├─ code -2105/-2107/-2108 → 展示错误，退出
+        │       └─ 其他 → 展示错误信息
+        │
+        └─ .success(createdLiveInfo)
+                │
+                ▼
+        isLiving = true
+        UI 更新为「🔴 直播中」
+                │
+        ┌───────────────────────────┐
+        │       直播进行中          │
+        │   onLiveEnded →被动结束   │  liveID + reason + message
+        │   onKickedOutOfLive→踢出 │  liveID + reason + message
+        └───────────────────────────┘
+                │
+        [用户主动结束 / 被动结束]
+                │
+                ▼
+        步骤1: DeviceStore.closeLocalCamera()
+               DeviceStore.closeLocalMicrophone()
+        步骤2: LiveListStore.shared.endLive(completion:)
+                │
+                └─ .success / .failure
+                        │
+                        ▼
+        步骤3: cancellables.removeAll()     ← 取消事件订阅
+               返回上层页面
+```
+
+## 平台特有注意事项
+
+### 1. createLive 第一参数无标签
+```swift
+// ✅ 正确
+LiveListStore.shared.createLive(liveInfo) { result in ... }
+
+// ❌ 错误（带标签）
+LiveListStore.shared.createLive(liveInfo: liveInfo) { ... }
+```
+
+### 2. endLive 无 liveID 参数
+`endLive(completion:)` 结束的是 SDK 当前所在的直播间，不需要传 liveID：
+```swift
+// ✅ 正确
+LiveListStore.shared.endLive { result in ... }
+
+// ❌ 错误（没有此参数）
+LiveListStore.shared.endLive(liveID: liveID) { ... }
+```
+
+### 3. LiveListEvent 关联值有三个字段
+`onLiveEnded` 和 `onKickedOutOfLive` 的关联值均为 `(liveID: String, reason: …, message: String)`，不是只有 `liveID`：
+```swift
+// ✅ 正确
+case .onLiveEnded(let liveID, let reason, let message):
+    // 使用 liveID 过滤当前直播间
+
+// ❌ 错误（缺少 reason 和 message）
+case .onLiveEnded(let liveID):
+```
+
+### 4. Combine 订阅生命周期管理
+`liveListEventPublisher` 的 Combine 订阅存储在 `cancellables` 中。务必在退出直播间时调用 `cancellables.removeAll()`，否则：
+- ViewController 被释放后订阅仍存活（内存泄漏）
+- 后续事件可能触发已释放对象的回调（野指针）
+
+### 5. endLive 失败时的兜底处理
+网络异常可能导致 `endLive` 回调超时或失败。即使失败也应清理本地资源（关闭设备、取消订阅），并在下次启动时通过服务端状态检查直播间是否仍存在。
+
+### 6. 导航返回的拦截
+通过 `viewWillDisappear` + `isMovingFromParent` 检测用户通过导航返回键意外退出：
+```swift
+override func viewWillDisappear(_ animated: Bool) {
+    super.viewWillDisappear(animated)
+    if isLiving && isMovingFromParent {
+        stopLive()
+    }
+}
+```
+
+### 7. LiveCoreView 初始化参数名是 `viewType`（不是 `liveScene`）
+`LiveCoreView` 的初始化方法参数名为 `viewType`，类型为 `CoreViewType` 枚举（`.pushView` 推流 / `.playView` 拉流）：
+```swift
+// ✅ 正确：参数名是 viewType
+let liveCoreView = LiveCoreView(viewType: .pushView)
+
+// ❌ 错误：没有 liveScene 参数
+let liveCoreView = LiveCoreView(liveScene: .pushView)
+```
+
+### 8. StatePublisher 读取属性必须通过 `.value`
+所有 Store 的 `.state` 属性类型是 `StatePublisher<T>`，不是 `T` 本身。读取当前状态值必须通过 `.value`：
+```swift
+// ✅ 正确：通过 .value 访问 state 属性
+let count = audienceStore?.state.value.audienceCount ?? 0
+
+// ❌ 错误：StatePublisher 上没有 audienceCount 成员
+let count = audienceStore?.state.audienceCount ?? 0
+```
+同理适用于所有 StatePublisher 包装的状态结构体：`LiveListState`、`DeviceState`、`BarrageState` 等。
+
+### 9. MUST: 文件头必须 `import AtomicXCore`
+使用 LiveCoreView、LiveListStore、DeviceStore、LiveAudienceStore 等类型时，必须在文件顶部显式 import：
+```swift
+import UIKit
+import AtomicXCore   // ← 必须，否则编译报 "cannot find type 'XXX' in scope"
+import Combine       // 如果使用 Publisher/AnyCancellable
+```
+不要将 import 写在注释中，必须是真正的 import 语句。

package/knowledge-base/slices/live/ios/anchor-preview.md

@@ -0,0 +1,228 @@
+---
+id: live/anchor-preview
+platform: ios
+---
+
+# 主播预览 — iOS 实现
+
+## 前置条件
+
+**依赖安装（Podfile）**
+```ruby
+pod 'AtomicXCore', '~> 4.0'
+```
+
+**Info.plist 权限声明**
+```xml
+<key>NSCameraUsageDescription</key>
+<string>需要访问摄像头以进行视频直播</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>需要访问麦克风以进行语音直播</string>
+```
+
+**前置状态**：
+- `LoginStore.shared` 登录成功（须完成登录）
+- 摄像头/麦克风系统权限已授予
+
+## API 调用（真实签名）
+
+```swift
+// LiveCoreView 初始化：主播端用 .pushView（推流模式）
+// ⚠️ 参数名是 viewType（不是 liveScene）
+LiveCoreView(viewType: .pushView, frame: CGRect = .zero)
+
+// 绑定直播间 ID（创建后必须立即调用，否则黑屏）
+liveCoreView.setLiveID(_ liveID: String)
+
+// 1. 打开前/后置摄像头（含 completion 回调）
+DeviceStore.shared.openLocalCamera(isFront: Bool, completion: CompletionClosure?)
+// CompletionClosure = (Result<Void, ErrorInfo>) -> Void
+
+// 2. 打开麦克风
+DeviceStore.shared.openLocalMicrophone(completion: CompletionClosure?)
+
+// 3. 不中断采集情况下切换前后摄像头
+DeviceStore.shared.switchCamera(isFront: Bool)
+
+// 4. 退出预览时关闭设备
+DeviceStore.shared.closeLocalCamera()
+DeviceStore.shared.closeLocalMicrophone()
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `isFront` | `Bool` | `true` = 前置摄像头（默认），`false` = 后置 |
+| `completion` | `CompletionClosure?` | `(Result<Void, ErrorInfo>) -> Void`；`nil` 表示不关心结果 |
+
+## 代码示例
+
+```swift
+import UIKit
+import AtomicXCore
+import AVFoundation
+import Combine
+
+// MARK: - 主播预览核心逻辑（SDK API 使用为主）
+
+// Step 1: 检查摄像头权限，通过后打开设备
+func setupPreview() {
+    switch AVCaptureDevice.authorizationStatus(for: .video) {
+    case .authorized:
+        openCameraAndMic()
+    case .notDetermined:
+        AVCaptureDevice.requestAccess(for: .video) { granted in
+            DispatchQueue.main.async {
+                if granted { openCameraAndMic() }
+            }
+        }
+    case .denied, .restricted:
+        showPermissionAlert(for: .video)
+    @unknown default:
+        break
+    }
+}
+
+// Step 2: 先打开摄像头，成功后再打开麦克风
+func openCameraAndMic() {
+    DeviceStore.shared.openLocalCamera(isFront: true) { result in
+        switch result {
+        case .success:
+            print("[Preview] 摄像头打开成功")
+            openMicrophone()
+
+        case .failure(let errorInfo):
+            // errorInfo: ErrorInfo（.code + .message）
+            print("[Preview] 摄像头打开失败, code: \(errorInfo.code), msg: \(errorInfo.message)")
+            handleDeviceError(errorInfo)
+        }
+    }
+}
+
+func openMicrophone() {
+    DeviceStore.shared.openLocalMicrophone { result in
+        switch result {
+        case .success:
+            print("[Preview] 麦克风打开成功，预览就绪")
+        case .failure(let errorInfo):
+            print("[Preview] 麦克风打开失败, code: \(errorInfo.code)")
+            handleDeviceError(errorInfo)
+        }
+    }
+}
+
+// Step 3: 退出预览时关闭设备
+func teardownPreview() {
+    DeviceStore.shared.closeLocalCamera()
+    DeviceStore.shared.closeLocalMicrophone()
+}
+
+// Step 4: 不中断预览切换前后置摄像头
+func flipCamera(toFront: Bool) {
+    DeviceStore.shared.switchCamera(isFront: toFront)
+}
+
+// MARK: - 错误处理（使用 ErrorInfo 的 .code 字段）
+
+func handleDeviceError(_ errorInfo: ErrorInfo) {
+    let message: String
+    switch errorInfo.code {
+    case -1101: message = "摄像头权限被拒，请前往系统设置开启"
+    case -1102: message = "摄像头被其他应用占用，请关闭后重试"
+    case -1103: message = "当前设备不支持摄像头（请使用真机测试）"
+    case -1105: message = "麦克风权限被拒，请前往系统设置开启"
+    default:    message = "设备打开失败（错误码 \(errorInfo.code)），请重试"
+    }
+    // 业务自行展示 Alert
+    print("[Preview] 设备错误：\(message)")
+}
+
+func showPermissionAlert(for mediaType: AVMediaType) {
+    let message = mediaType == .video
+        ? "请在「设置 > 隐私 > 摄像头」中允许本应用访问摄像头"
+        : "请在「设置 > 隐私 > 麦克风」中允许本应用访问麦克风"
+    // 业务自行展示 Alert + 跳转设置
+    if let url = URL(string: UIApplication.openSettingsURLString) {
+        UIApplication.shared.open(url)
+    }
+}
+```
+
+**App 生命周期处理（后台暂停/前台恢复）**：
+```swift
+import Combine
+
+var cancellables = Set<AnyCancellable>()
+
+func observeAppLifecycle() {
+    NotificationCenter.default.publisher(for: UIApplication.didEnterBackgroundNotification)
+        .sink { [weak self] _ in
+            // 进后台时释放设备，避免摄像头指示灯常亮
+            DeviceStore.shared.closeLocalCamera()
+            DeviceStore.shared.closeLocalMicrophone()
+        }
+        .store(in: &cancellables)
+
+    NotificationCenter.default.publisher(for: UIApplication.didBecomeActiveNotification)
+        .sink { [weak self] _ in
+            // 回到前台时重新打开（注意：需要重新检查权限）
+            openCameraAndMic()
+        }
+        .store(in: &cancellables)
+}
+```
+
+## 调用时序
+
+```
+进入预览界面
+        │
+        ▼
+checkCameraPermission()
+        │
+        ├─ denied  → showPermissionAlert → 用户跳转系统设置
+        │
+        └─ authorized
+                │
+                ▼
+        DeviceStore.shared.openLocalCamera(isFront: true, completion:)
+                │
+                ├─ .failure(errorInfo) → handleDeviceError（显示错误提示）
+                │
+                └─ .success
+                        │
+                        ▼
+                DeviceStore.shared.openLocalMicrophone(completion:)
+                        │
+                        ├─ .failure(errorInfo) → handleDeviceError
+                        │
+                        └─ .success → 预览画面出现，等待用户点击「开始直播」
+                                │
+                        [用户点击开始直播]
+                                │
+                                ▼
+                        导航到房间配置页
+                        由配置页调用 createLive（参见 anchor-room-config）
+        │
+退出预览界面
+        │
+        ▼
+DeviceStore.shared.closeLocalCamera()
+DeviceStore.shared.closeLocalMicrophone()   ← 退出预览时释放设备
+```
+
+## 平台特有注意事项
+
+### 1. openLocalCamera 有 completion 参数，不可忽略
+`DeviceStore.shared.openLocalCamera(isFront: Bool, completion: CompletionClosure?)` 包含 completion 参数。必须在 `.success` 回调中再打开麦克风，避免设备尚未就绪时即执行后续逻辑。
+
+### 2. iOS 模拟器不支持摄像头
+所有摄像头相关功能必须在**真实设备**上测试。模拟器调用 `openLocalCamera` 会返回 code `-1103`。
+
+### 3. 进入后台时摄像头自动暂停
+iOS 系统在 App 进入后台时会自动挂起摄像头采集。监听 `UIApplication.didEnterBackgroundNotification` 主动关闭设备，再在 `didBecomeActiveNotification` 时重新打开，避免 `-1102` 被占用错误。
+
+### 4. 前后摄像头切换（不中断预览）
+预览阶段可直接调用 `DeviceStore.shared.switchCamera(isFront:)` 切换前后摄像头，无需重新调用 `openLocalCamera`，画面切换无黑屏。
+
+### 5. ErrorInfo 不是 Swift Error
+设备回调的 `.failure` 分支中，错误对象是 `ErrorInfo` 结构体（`.code: Int` + `.message: String`），不是 `Swift.Error`，不可调用 `localizedDescription`。