@tencent-rtc/trtc-agent-skills 0.1.0

package/knowledge-base/slices/live/ios/audience-manage.md

@@ -0,0 +1,381 @@
+---
+id: live/audience-manage
+platform: ios
+---
+
+# 观众管理 — iOS 实现
+
+## 前置条件
+
+**依赖安装（Podfile）**
+```ruby
+pod 'AtomicXCore', '~> 4.0'
+```
+
+**前置状态**：
+- `LoginStore.shared.isLogin == true`
+- 已成功进入直播间
+- 当前用户为房主（执行 `setAdministrator` / `revokeAdministrator`）或管理员（执行 `kickUserOutOfRoom`）
+
+## API 调用
+
+```swift
+// 创建观众管理模块（通过 LiveAudienceStore 工厂方法）
+let liveAudienceStore = LiveAudienceStore.create(liveID: liveID)
+
+// 踢出观众（需房主或管理员权限）
+liveAudienceStore.kickUserOutOfRoom(
+    userID: String,
+    completion: CompletionClosure?
+)
+// CompletionClosure = (Result<Void, ErrorInfo>) -> Void
+
+// 设置管理员（仅房主）
+liveAudienceStore.setAdministrator(
+    userID: String,
+    completion: CompletionClosure?
+)
+
+// 撤销管理员（仅房主）
+liveAudienceStore.revokeAdministrator(
+    userID: String,
+    completion: CompletionClosure?
+)
+
+// 禁言 / 解除禁言（需房主或管理员权限）
+liveAudienceStore.disableSendMessage(
+    userID: String,
+    isDisable: Bool,
+    completion: CompletionClosure?
+)
+
+// 订阅观众管理事件
+liveAudienceStore.liveAudienceEventPublisher  // PassthroughSubject<LiveAudienceEvent, Never>
+// 包含：
+// .onAudienceMessageDisabled(audience: LiveUserInfo, isDisable: Bool)
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `userID` | `String` | 目标用户的唯一标识 |
+| `isDisable` | `Bool` | `true` = 禁言，`false` = 解除禁言 |
+| `completion` | `CompletionClosure?` | `(Result<Void, ErrorInfo>) -> Void`，`ErrorInfo` 含 `.code` 和 `.message` |
+
+## 代码示例
+
+### 完整管理操作集成
+
+```swift
+import AtomicXCore
+import Combine
+
+final class AudienceManageManager {
+
+    // MARK: - 属性
+
+    private let audienceStore: LiveAudienceStore
+    private var cancellables = Set<AnyCancellable>()
+
+    /// 当前用户角色（从 LiveStore 获取）
+    private var currentUserRole: UserRole = .audience
+
+    // MARK: - 初始化
+
+    init(liveID: String) {
+        // 通过工厂方法创建，确保每个直播间独立实例
+        self.audienceStore = LiveAudienceStore.create(liveID: liveID)
+        subscribeAudienceEvents()
+    }
+
+    // MARK: - 监听观众管理事件
+
+    private func subscribeAudienceEvents() {
+        audienceStore.liveAudienceEventPublisher
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] event in
+                guard let self else { return }
+                switch event {
+                case .onAudienceMessageDisabled(let audience, let isDisable):
+                    // 某用户禁言状态变更，刷新列表 UI
+                    print("[Manage] 用户 \(audience.userID) 禁言状态: \(isDisable)")
+                case .onAudienceJoined, .onAudienceLeft:
+                    break
+                }
+            }
+            .store(in: &cancellables)
+    }
+
+    // MARK: - 权限校验
+
+    /// 校验是否有踢人权限
+    private func canKick(targetRole: UserRole) -> Bool {
+        switch currentUserRole {
+        case .owner:
+            // 房主可以踢任何人
+            return true
+        case .admin:
+            // 管理员只能踢普通观众，不能踢其他管理员或房主
+            return targetRole == .audience
+        case .audience:
+            return false
+        }
+    }
+
+    /// 校验是否有设置/撤销管理员权限
+    private func canManageAdmin() -> Bool {
+        return currentUserRole == .owner
+    }
+
+    // MARK: - 踢出观众
+
+    func kickUser(_ userID: String,
+                  targetRole: UserRole,
+                  completion: ((Result<Void, ErrorInfo>) -> Void)? = nil) {
+        // 步骤1: 调用前校验权限
+        guard canKick(targetRole: targetRole) else {
+            print("[Manage] 权限不足，无法踢出用户: \(userID)")
+            completion?(.failure(ErrorInfo(code: -1, message: "权限不足，无法执行此操作")))
+            return
+        }
+
+        // 步骤2: 踢出用户
+        audienceStore.kickUserOutOfRoom(userID: userID) { result in
+            DispatchQueue.main.async {
+                switch result {
+                case .success:
+                    print("[Manage] 已踢出用户: \(userID)")
+                    completion?(.success(()))
+                case .failure(let error):
+                    print("[Manage] 踢出失败 code=\(error.code) msg=\(error.message)")
+                    completion?(.failure(error))
+                }
+            }
+        }
+    }
+
+    // MARK: - 管理员设置（仅房主）
+
+    func setAdministrator(_ userID: String,
+                          completion: ((Result<Void, ErrorInfo>) -> Void)? = nil) {
+        // 步骤3: 校验房主权限
+        guard canManageAdmin() else {
+            completion?(.failure(ErrorInfo(code: -1, message: "权限不足，无法执行此操作")))
+            return
+        }
+
+        audienceStore.setAdministrator(userID: userID) { result in
+            DispatchQueue.main.async {
+                switch result {
+                case .success:
+                    print("[Manage] 已设置管理员: \(userID)")
+                    completion?(.success(()))
+                case .failure(let error):
+                    print("[Manage] 设置管理员失败 code=\(error.code) msg=\(error.message)")
+                    completion?(.failure(error))
+                }
+            }
+        }
+    }
+
+    func revokeAdministrator(_ userID: String,
+                             completion: ((Result<Void, ErrorInfo>) -> Void)? = nil) {
+        guard canManageAdmin() else {
+            completion?(.failure(ErrorInfo(code: -1, message: "权限不足，无法执行此操作")))
+            return
+        }
+
+        audienceStore.revokeAdministrator(userID: userID) { result in
+            DispatchQueue.main.async {
+                switch result {
+                case .success:
+                    print("[Manage] 已撤销管理员: \(userID)")
+                    completion?(.success(()))
+                case .failure(let error):
+                    print("[Manage] 撤销管理员失败 code=\(error.code) msg=\(error.message)")
+                    completion?(.failure(error))
+                }
+            }
+        }
+    }
+
+    // MARK: - 禁言管理
+
+    func muteUser(_ userID: String,
+                  completion: ((Result<Void, ErrorInfo>) -> Void)? = nil) {
+        audienceStore.disableSendMessage(userID: userID, isDisable: true) { result in
+            DispatchQueue.main.async {
+                switch result {
+                case .success:
+                    print("[Manage] 已禁言用户: \(userID)")
+                    completion?(.success(()))
+                case .failure(let error):
+                    print("[Manage] 禁言失败 code=\(error.code) msg=\(error.message)")
+                    completion?(.failure(error))
+                }
+            }
+        }
+    }
+
+    func unmuteUser(_ userID: String,
+                    completion: ((Result<Void, ErrorInfo>) -> Void)? = nil) {
+        audienceStore.disableSendMessage(userID: userID, isDisable: false) { result in
+            DispatchQueue.main.async {
+                completion?(result)
+            }
+        }
+    }
+
+    // MARK: - 错误处理
+
+    func handleManageError(_ error: ErrorInfo, for operation: String) {
+        switch error.code {
+        case -2300:
+            showAlert(title: "权限不足", message: "该操作仅房主可执行")
+        case -2301:
+            showAlert(title: "权限不足", message: "该操作需要管理员或房主权限")
+        case -2302:
+            showToast("该用户已不在直播间")
+        default:
+            showToast("\(operation)失败：\(error.message)")
+        }
+    }
+}
+
+// MARK: - 用户角色
+
+enum UserRole {
+    case owner      // 房主
+    case admin      // 管理员
+    case audience   // 普通观众
+}
+```
+
+### 观众列表操作菜单
+
+```swift
+// 观众列表 Cell 上的操作菜单（权限判断）
+func showAudienceActionMenu(for audience: LiveUserInfo,
+                            audienceRole: UserRole,
+                            currentRole: UserRole) {
+    var actions: [UIAlertAction] = []
+
+    // 仅房主或管理员可踢人（管理员只能踢普通观众）
+    let canKick = (currentRole == .owner) ||
+                  (currentRole == .admin && audienceRole == .audience)
+    if canKick {
+        actions.append(UIAlertAction(title: "踢出直播间", style: .destructive) { [weak self] _ in
+            self?.confirmKick(userID: audience.userID)
+        })
+    }
+
+    // 仅房主可禁言/设置管理员
+    if currentRole == .owner {
+        actions.append(UIAlertAction(title: "禁言", style: .default) { [weak self] _ in
+            self?.manageManager.muteUser(audience.userID) { result in
+                if case .failure(let error) = result {
+                    self?.manageManager.handleManageError(error, for: "禁言")
+                }
+            }
+        })
+
+        if audienceRole == .audience {
+            actions.append(UIAlertAction(title: "设为管理员", style: .default) { [weak self] _ in
+                self?.manageManager.setAdministrator(audience.userID) { result in
+                    if case .failure(let error) = result {
+                        self?.manageManager.handleManageError(error, for: "设为管理员")
+                    }
+                }
+            })
+        } else if audienceRole == .admin {
+            actions.append(UIAlertAction(title: "撤销管理员", style: .default) { [weak self] _ in
+                self?.manageManager.revokeAdministrator(audience.userID) { result in
+                    if case .failure(let error) = result {
+                        self?.manageManager.handleManageError(error, for: "撤销管理员")
+                    }
+                }
+            })
+        }
+    }
+
+    guard !actions.isEmpty else { return }
+
+    let sheet = UIAlertController(
+        title: audience.userName,
+        message: nil,
+        preferredStyle: .actionSheet
+    )
+    actions.forEach { sheet.addAction($0) }
+    sheet.addAction(UIAlertAction(title: "取消", style: .cancel))
+    present(sheet, animated: true)
+}
+
+private func confirmKick(userID: String) {
+    let alert = UIAlertController(
+        title: "踢出直播间",
+        message: "确定要将该用户移出直播间吗？",
+        preferredStyle: .alert
+    )
+    alert.addAction(UIAlertAction(title: "确定", style: .destructive) { [weak self] _ in
+        self?.manageManager.kickUser(userID, targetRole: .audience) { result in
+            if case .failure(let error) = result {
+                self?.manageManager.handleManageError(error, for: "踢出用户")
+            }
+        }
+    })
+    alert.addAction(UIAlertAction(title: "取消", style: .cancel))
+    present(alert, animated: true)
+}
+```
+
+## 调用时序
+
+```
+进入直播间
+    │
+    ▼
+LiveAudienceStore.create(liveID:)
+    │
+    ▼
+订阅 liveAudienceEventPublisher        // 监听禁言状态变更等事件
+    │
+    ├─ 房主操作流程
+    │       │
+    │       ├─ setAdministrator(userID:)
+    │       │       ├─ .success → 更新观众列表角色标记
+    │       │       └─ .failure(code: -2300) → 非房主，隐藏入口
+    │       │
+    │       ├─ revokeAdministrator(userID:)
+    │       │       ├─ .success → 更新观众列表角色标记
+    │       │       └─ .failure(code: -2300) → 非房主，隐藏入口
+    │       │
+    │       └─ disableSendMessage(userID:isDisable:)
+    │               ├─ .success → onAudienceMessageDisabled 事件推送
+    │               └─ .failure(ErrorInfo) → 展示 error.message
+    │
+    └─ 房主/管理员踢人流程
+            │
+            ├─ 权限校验（canKick）
+            ├─ 二次确认弹窗
+            └─ kickUserOutOfRoom(userID:)
+                    ├─ .success → 刷新观众列表
+                    ├─ .failure(code: -2301) → 权限不足
+                    └─ .failure(code: -2302) → 用户已离开，刷新列表
+```
+
+## 平台特有注意事项
+
+### 1. ErrorInfo 替代 Error
+所有 completion 使用 `(Result<Void, ErrorInfo>) -> Void`，不是 `Result<Void, Error>`。错误信息通过 `error.code`（Int）和 `error.message`（String）访问，不要调用 `localizedDescription`。
+
+### 2. 管理员权限 UI 实时刷新
+当房主撤销某用户的管理员权限时，该用户应立即看到操作按钮的变化（如隐藏踢人按钮）。通过订阅观众列表状态变化来驱动 UI 更新，不要依赖本地缓存的角色信息。
+
+### 3. iPad 上的 ActionSheet
+在 iPad 上，`UIAlertController` 的 `.actionSheet` 样式需要设置 `popoverPresentationController` 的 `sourceView` 和 `sourceRect`，否则会崩溃。
+
+```swift
+if let popover = sheet.popoverPresentationController {
+    popover.sourceView = cell
+    popover.sourceRect = cell.bounds
+}
+```

package/knowledge-base/slices/live/ios/audience-watch.md

@@ -0,0 +1,286 @@
+---
+id: live/audience-watch
+platform: ios
+---
+
+# 观众观看 — iOS 实现
+
+## 前置条件
+
+**依赖安装（Podfile）**
+```ruby
+pod 'AtomicXCore', '~> 4.0'
+```
+
+**最低系统要求**：iOS 13.0+，Xcode 14.0+
+
+**前置登录**：必须在 `LoginStore.shared.login` 成功后才可调用 `joinLive`。
+
+**权限说明**：观众使用 `.playView` 仅拉流，**无需**申请摄像头/麦克风权限。若观众发起连麦则需相机与麦克风权限（参见 live/device-control）。
+
+## API 调用（真实签名）
+
+```swift
+// LiveCoreView 初始化：观众端用 .playView（拉流模式）
+// 参数名是 viewType（不是 liveScene）
+LiveCoreView(viewType: .playView, frame: CGRect = .zero)
+
+// 加入直播间并开始拉流
+// ⚠️ completion 返回 LiveInfo（不是 Void）
+LiveListStore.shared.joinLive(liveID: String,
+                              completion: LiveInfoCompletionClosure?)
+// LiveInfoCompletionClosure = (Result<LiveInfo, ErrorInfo>) -> Void
+
+// 离开直播间并释放媒体资源
+LiveListStore.shared.leaveLive(completion: CompletionClosure?)
+// CompletionClosure = (Result<Void, ErrorInfo>) -> Void
+
+// 订阅直播事件（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
+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 isInLive = false
+
+// MARK: - 进入直播间（joinLive）
+
+func joinLive(liveID: String) {
+    // ⚠️ joinLive completion 是 LiveInfoCompletionClosure，成功时返回 LiveInfo
+    LiveListStore.shared.joinLive(liveID: liveID) { result in
+        switch result {
+        case .success(let liveInfo):
+            isInLive = true
+            print("[AudienceWatch] 进房成功: \(liveID)")
+            print("[AudienceWatch] 直播间名称: \(liveInfo.liveName)")
+            print("[AudienceWatch] 主播: \(liveInfo.liveOwner.userID)")
+            // 进房成功后启用弹幕/礼物等功能
+
+        case .failure(let errorInfo):
+            // errorInfo: ErrorInfo（.code + .message）
+            print("[AudienceWatch] 进房失败, code: \(errorInfo.code), msg: \(errorInfo.message)")
+            handleJoinError(errorInfo)
+        }
+    }
+}
+
+// MARK: - 离开直播间（leaveLive）
+
+func leaveLive() {
+    guard isInLive else { return }
+    isInLive = false
+
+    // ⚠️ leaveLive completion 是 CompletionClosure（Result<Void, ErrorInfo>）
+    LiveListStore.shared.leaveLive { result in
+        switch result {
+        case .success:
+            print("[AudienceWatch] 退出直播间成功")
+        case .failure(let errorInfo):
+            // 即使失败也清理本地状态，避免残留
+            print("[AudienceWatch] 退出直播间失败, code: \(errorInfo.code)")
+        }
+        cleanupSubscriptions()
+    }
+}
+
+// MARK: - 订阅直播事件（先订阅再 joinLive，防止事件丢失）
+
+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 message)
+                where liveID == currentLiveID:
+                print("[AudienceWatch] 直播已结束: \(message)")
+                handleLiveEnded()
+
+            // ⚠️ onKickedOutOfLive 有三个关联值：liveID, reason, message
+            case .onKickedOutOfLive(let liveID, _, let message)
+                where liveID == currentLiveID:
+                print("[AudienceWatch] 被踢出直播间: \(message)")
+                handleKickedOut()
+
+            default:
+                break
+            }
+        }
+        .store(in: &cancellables)
+}
+
+// MARK: - 事件处理
+
+func handleLiveEnded() {
+    isInLive = false
+    cleanupSubscriptions()
+    print("[AudienceWatch] 直播已结束，返回列表")
+}
+
+func handleKickedOut() {
+    isInLive = false
+    cleanupSubscriptions()
+    print("[AudienceWatch] 您已被移出直播间")
+}
+
+// MARK: - 进房错误处理
+
+func handleJoinError(_ errorInfo: ErrorInfo) {
+    switch errorInfo.code {
+    case -1002: print("请先登录后再进入直播间")
+    case -2001: print("直播间不存在或已结束")
+    default:    print("进房失败（code: \(errorInfo.code)）: \(errorInfo.message)")
+    }
+}
+
+// MARK: - 清理订阅
+
+func cleanupSubscriptions() {
+    cancellables.removeAll()
+}
+```
+
+**完整进房 + 退房流程**：
+```swift
+// ① 先订阅事件（防止进房前的事件丢失）
+subscribeLiveEvents(currentLiveID: liveID)
+
+// ② 进入直播间
+joinLive(liveID: liveID)
+
+// ③ 退出时（页面消失、收到 onLiveEnded / onKickedOutOfLive）
+leaveLive()
+```
+
+**App 生命周期处理**：
+```swift
+import Combine
+
+func observeAppLifecycle(liveID: String) {
+    // 进入后台：停止拉流，避免后台占用解码资源
+    NotificationCenter.default.publisher(for: UIApplication.didEnterBackgroundNotification)
+        .sink { _ in
+            // 若业务要求后台不能播放，调用 leaveLive 并在前台重新 joinLive
+            // leaveLive()
+        }
+        .store(in: &cancellables)
+
+    // 回到前台：恢复播放
+    NotificationCenter.default.publisher(for: UIApplication.willEnterForegroundNotification)
+        .sink { _ in
+            // 如已调用 leaveLive，需重新 joinLive
+            // joinLive(liveID: liveID)
+        }
+        .store(in: &cancellables)
+}
+```
+
+## 调用时序
+
+```
+LoginStore.login 成功
+    │
+    ▼
+subscribeLiveEvents(currentLiveID:)    ← ① 先订阅，防止事件丢失
+    │
+    ▼
+LiveListStore.shared.joinLive(liveID: String, completion: LiveInfoCompletionClosure?)
+    │
+    ├─ .failure(errorInfo)
+    │       ├─ code -1002 → 先登录
+    │       ├─ code -2001 → 直播已结束 → 返回列表
+    │       └─ 其他       → showAlert（code + message）
+    │
+    └─ .success(liveInfo)   ← 携带完整 LiveInfo
+            │
+            isInLive = true
+            启用弹幕/礼物功能
+            │
+            ▼
+        ┌──────────────────────────────────┐
+        │         直播进行中               │
+        │  onLiveEnded(liveID,reason,msg)  │
+        │  onKickedOutOfLive(liveID,r,msg) │
+        └──────────────────────────────────┘
+            │
+            [用户退出 / 收到事件]
+            │
+            ▼
+LiveListStore.shared.leaveLive(completion: CompletionClosure?)
+    │
+    ├─ .success / .failure  → 清理本地状态（无论成功失败都 cleanup）
+    │
+    ▼
+cancellables.removeAll()
+```
+
+## 平台特有注意事项
+
+### 1. joinLive completion 返回 LiveInfo，不是 Void
+```swift
+// ✅ 正确
+LiveListStore.shared.joinLive(liveID: liveID) { result in
+    if case .success(let liveInfo) = result {
+        print(liveInfo.liveName)  // 使用服务端返回的 LiveInfo
+    }
+}
+
+// ❌ 错误：completion 没有直接的 list/room 参数
+```
+
+### 2. leaveLive completion 是 `Result<Void, ErrorInfo>`
+`leaveLive` 回调是 `CompletionClosure`（`Result<Void, ErrorInfo>`），即使失败也应清理本地状态：
+```swift
+LiveListStore.shared.leaveLive { result in
+    // 无论 .success 还是 .failure，都需要清理本地状态
+    isInLive = false
+    cancellables.removeAll()
+}
+```
+
+### 3. LiveListEvent 关联值有三个字段
+```swift
+// ✅ 正确
+case .onLiveEnded(let liveID, let reason, let message):
+case .onKickedOutOfLive(let liveID, let reason, let message):
+
+// ❌ 错误（只有一个关联值）
+case .onLiveEnded(let liveID):
+case .onKickedOutOfLive(let liveID):
+```
+
+### 4. viewDidDisappear vs deinit 中调用 leaveLive
+建议在 `viewDidDisappear` 中调用而非 `deinit`，原因：iOS push/pop 导航栈时，上级页面不会被销毁（`deinit` 不调用），但 `viewDidDisappear` 会触发。如在 `deinit` 中释放，可能导致用户返回列表后资源未释放直到页面从栈中弹出。
+
+### 5. 强引用导致 LiveCoreView 无法释放
+若闭包中捕获 `self` 导致循环引用，`leaveLive` 的回调永远不执行。始终使用 `[weak self]` 捕获 ViewController 引用。
+
+### 6. 后台播放与 App Store 合规
+若 App 允许后台音频播放，需在 `Info.plist` 的 `UIBackgroundModes` 中声明 `audio`，否则 App 进入后台后音频会被系统静音，且审核可能被拒。若不支持后台播放，进后台时调用 `leaveLive` 是更安全的选择。