@tencent-rtc/trtc-agent-skills 0.1.0

package/knowledge-base/slices/live/ios/gift.md

@@ -0,0 +1,315 @@
+---
+id: live/gift
+platform: ios
+---
+
+# 礼物 — iOS 实现
+
+## 前置条件
+
+**依赖安装（Podfile）**
+```ruby
+pod 'AtomicXCore', '~> 4.0'
+```
+
+**前置状态**：
+- `LoginStore.shared.isLogin == true`（礼物功能依赖登录态）
+- 已成功加入直播间（liveID 与进房 ID 一致）
+- 服务端已配置礼物系统及扣费回调
+
+## API 调用
+
+```swift
+// 创建礼物实例（与直播间绑定）
+let giftStore = GiftStore.create(liveID: liveID)
+
+// （可选）设置语言，须在 refreshUsableGifts 前调用
+// ⚠️ 首个参数无标签（unnamed），直接传值
+giftStore.setLanguage("zh-CN")
+
+// 拉取礼物列表
+giftStore.refreshUsableGifts(completion: CompletionClosure?)
+// CompletionClosure = (Result<Void, ErrorInfo>) -> Void
+
+// 发送礼物
+// ⚠️ count 类型为 UInt，不是 Int
+giftStore.sendGift(
+    giftID: String,
+    count: UInt,
+    completion: CompletionClosure?
+)
+
+// 订阅礼物事件
+giftStore.giftEventPublisher  // PassthroughSubject<GiftEvent, Never>
+// GiftEvent 枚举：
+// case .onReceiveGift(liveID: String, gift: Gift, count: UInt, sender: LiveUserInfo)
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `liveID` | `String` | 直播间唯一标识 |
+| `giftID` | `String` | 礼物唯一 ID，来自 `GiftState.usableGifts` |
+| `count` | `UInt` | 发送数量，最小为 1 |
+
+## 代码示例
+
+### 完整礼物集成
+
+```swift
+import AtomicXCore
+import Combine
+
+final class GiftManager {
+
+    // MARK: - 属性
+
+    private let giftStore: GiftStore
+    private var cancellables = Set<AnyCancellable>()
+
+    /// 礼物分类列表（供 UI 面板使用）
+    @Published private(set) var giftCategories: [GiftCategory] = []
+
+    // MARK: - 初始化
+
+    init(liveID: String, language: String = "zh-CN") {
+        // 步骤1: 创建 GiftStore 实例
+        self.giftStore = GiftStore.create(liveID: liveID)
+
+        // 步骤2: 多语言场景先设置语言（首个参数无标签）
+        giftStore.setLanguage(language)
+
+        // 步骤3: 订阅礼物事件（进房后立即订阅，避免遗漏）
+        subscribeGiftEvents()
+
+        // 步骤4: 订阅礼物列表状态
+        subscribeGiftState()
+    }
+
+    // MARK: - 礼物列表
+
+    /// 拉取可用礼物列表（面板打开前调用）
+    func loadGifts(completion: ((Result<Void, ErrorInfo>) -> Void)? = nil) {
+        giftStore.refreshUsableGifts { result in
+            switch result {
+            case .success:
+                print("[Gift] 礼物列表拉取成功")
+                completion?(.success(()))
+            case .failure(let error):
+                print("[Gift] 礼物列表拉取失败 code=\(error.code) msg=\(error.message)")
+                completion?(.failure(error))
+            }
+        }
+    }
+
+    private func subscribeGiftState() {
+        giftStore.state
+            .map(\.usableGifts)
+            .receive(on: DispatchQueue.main)
+            .assign(to: &$giftCategories)
+    }
+
+    // MARK: - 礼物事件订阅
+
+    private func subscribeGiftEvents() {
+        // 步骤5: 通过 giftEventPublisher 处理所有礼物 UI
+        giftStore.giftEventPublisher
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] event in
+                switch event {
+                case .onReceiveGift(let liveID, let gift, let count, let sender):
+                    self?.handleReceiveGift(liveID: liveID, gift: gift, count: count, sender: sender)
+                }
+            }
+            .store(in: &cancellables)
+    }
+
+    private func handleReceiveGift(liveID: String, gift: Gift, count: UInt, sender: LiveUserInfo) {
+        print("[Gift] 收到礼物: \(gift.name) ×\(count) from \(sender.userName)")
+
+        // 播放礼物动画
+        // GiftAnimationPlayer.shared.play(resourceURL: gift.resourceURL, ...)
+
+        // 在弹幕区插入礼物通知（通过 BarrageStore.appendLocalTip）
+        // 见 live/barrage slice
+    }
+
+    // MARK: - 发送礼物
+
+    /// 发送礼物（从礼物面板调用）
+    /// - Parameter count: UInt 类型，最小值为 1
+    func sendGift(giftID: String,
+                  count: UInt = 1,
+                  completion: ((Result<Void, ErrorInfo>) -> Void)? = nil) {
+        // 步骤6: 发送礼物
+        giftStore.sendGift(giftID: giftID, count: count) { result in
+            switch result {
+            case .success:
+                // ✅ 成功后不在此处展示动画！
+                // 动画由 giftEventPublisher 统一驱动（发送方也会收到 onReceiveGift）
+                completion?(.success(()))
+
+            case .failure(let error):
+                // ❌ 仅在失败时处理
+                print("[Gift] 发送失败 code=\(error.code) msg=\(error.message)")
+                completion?(.failure(error))
+            }
+        }
+    }
+
+    // MARK: - 资源清理
+
+    func cleanup() {
+        cancellables.removeAll()
+    }
+}
+```
+
+### 礼物面板示例
+
+```swift
+final class GiftPanelViewController: UIViewController {
+
+    private var giftManager: GiftManager!
+    private var cancellables = Set<AnyCancellable>()
+
+    @IBOutlet weak var collectionView: UICollectionView!
+    @IBOutlet weak var loadingIndicator: UIActivityIndicatorView!
+
+    override func viewDidLoad() {
+        super.viewDidLoad()
+
+        // 绑定礼物列表数据
+        giftManager.$giftCategories
+            .receive(on: DispatchQueue.main)
+            .sink { [weak self] categories in
+                guard !categories.isEmpty else { return }
+                self?.collectionView.reloadData()
+                self?.loadingIndicator.stopAnimating()
+            }
+            .store(in: &cancellables)
+
+        // 面板出现时拉取礼物列表
+        loadingIndicator.startAnimating()
+        giftManager.loadGifts { [weak self] result in
+            if case .failure(let error) = result {
+                self?.showErrorToast(message: error.message)
+                self?.loadingIndicator.stopAnimating()
+            }
+        }
+    }
+
+    // 用户点击礼物（count 为 UInt）
+    func didSelectGift(_ gift: Gift, count: UInt) {
+        giftManager.sendGift(giftID: gift.giftID, count: count) { [weak self] result in
+            DispatchQueue.main.async {
+                switch result {
+                case .success:
+                    break // 动画由 giftEventPublisher 驱动，此处无需操作
+                case .failure(let error):
+                    self?.handleSendError(error)
+                }
+            }
+        }
+    }
+
+    private func handleSendError(_ error: ErrorInfo) {
+        switch error.code {
+        case -4001:
+            showRechargeAlert()   // 余额不足，引导充值
+        case -4002:
+            // 礼物不存在，刷新列表
+            giftManager.loadGifts()
+        default:
+            showErrorToast(message: error.message)
+        }
+    }
+
+    private func showRechargeAlert() {
+        let alert = UIAlertController(
+            title: "余额不足",
+            message: "当前金币不足，是否前往充值？",
+            preferredStyle: .alert
+        )
+        alert.addAction(UIAlertAction(title: "去充值", style: .default) { _ in
+            // 跳转充值页面
+        })
+        alert.addAction(UIAlertAction(title: "取消", style: .cancel))
+        present(alert, animated: true)
+    }
+}
+```
+
+### 多语言礼物列表
+
+```swift
+// 根据系统语言自动选择
+func makeGiftManager(liveID: String) -> GiftManager {
+    let languageCode: String
+    if let preferred = Locale.preferredLanguages.first {
+        languageCode = preferred.hasPrefix("zh") ? "zh-CN" : "en"
+    } else {
+        languageCode = "zh-CN"
+    }
+    return GiftManager(liveID: liveID, language: languageCode)
+}
+```
+
+## 调用时序
+
+```
+进房成功
+    │
+    ▼
+GiftStore.create(liveID:)              // 创建实例
+    │
+    ├─ setLanguage("zh-CN")            // （可选）多语言设置，首个参数无标签
+    │
+    ▼
+订阅 giftEventPublisher                // ⚠️ 进房后立即订阅，避免遗漏礼物
+    │
+    ├─ 用户打开礼物面板
+    │       │
+    │       ▼
+    │   refreshUsableGifts()           // 拉取礼物分类+列表
+    │       │
+    │       ├─ .failure(ErrorInfo) → 展示 error.message，提供重试
+    │       └─ .success → GiftState.usableGifts 更新 → 渲染面板
+    │
+    ├─ 用户点击发送礼物（count: UInt）
+    │       │
+    │       ▼
+    │   sendGift(giftID:count:)
+    │       ├─ .failure(code: -4001) → 引导充值
+    │       ├─ .failure(code: -4002) → 刷新礼物列表
+    │       └─ .success → （无需额外操作）
+    │
+    ├─ 收到 giftEventPublisher 事件
+    │       │
+    │       ▼
+    │   .onReceiveGift(liveID:gift:count:sender:)
+    │       ├─ count 类型为 UInt
+    │       ├─ 播放礼物动画（gift.resourceURL）
+    │       └─ 弹幕区插入礼物提示
+    │
+    └─ 退出直播间
+            │
+            ▼
+        cancellables.removeAll()
+```
+
+## 平台特有注意事项
+
+### 1. count 类型为 UInt
+`sendGift` 的 `count` 参数及 `onReceiveGift` 事件的 `count` 都是 `UInt`，不是 `Int`。UI 层的计数变量应使用 `UInt` 或在传入时做显式转换。
+
+### 2. setLanguage 参数无标签
+`giftStore.setLanguage("zh-CN")` 中首个参数没有外部标签（unnamed），直接传字符串值。不要写 `giftStore.setLanguage(language: "zh-CN")`。
+
+### 3. 礼物动画资源预加载
+`Gift.resourceURL` 指向动画文件（如 SVGA、MP4）。建议在 `refreshUsableGifts` 成功后异步预下载高频礼物动画文件到本地缓存，避免发送时实时下载导致动画延迟。
+
+### 4. 连击礼物（连续发送相同礼物）
+iOS 上实现连击需在 UI 层维护连击计数和防抖 Timer（建议 800ms 间隔）。收到 `onReceiveGift` 后判断是否与上一条礼物来自同一发送者且礼物相同，若是则累计数量更新 UI，否则重新播放动画。
+
+### 5. 内存管理
+礼物动画（SVGA/Lottie）占用内存较高。建议同时最多播放 3 个礼物动画，超出时将旧动画排队等待完成后再播放，使用动画队列管理器控制并发数。

package/knowledge-base/slices/live/ios/live-list.md

@@ -0,0 +1,269 @@
+---
+id: live/live-list
+platform: ios
+---
+
+# 直播列表 — iOS 实现
+
+## 前置条件
+
+**依赖安装（Podfile）**
+```ruby
+pod 'AtomicXCore', '~> 4.0'
+```
+
+**最低系统要求**：iOS 13.0+，Xcode 14.0+
+
+**前置登录**：必须在 `LoginStore.shared.login` 成功回调后才可调用 `fetchLiveList`。
+
+## API 调用（真实签名）
+
+```swift
+// 拉取直播列表（分页）
+// ⚠️ completion 是 CompletionClosure（Result<Void, ErrorInfo>），列表通过 state 读取
+LiveListStore.shared.fetchLiveList(
+    cursor: String,            // 首次传 ""，后续传 liveListCursor
+    count: Int,                // 每页数量，推荐 20
+    completion: CompletionClosure?  // (Result<Void, ErrorInfo>) -> Void
+)
+
+// 读取状态快照（Combine）
+LiveListStore.shared.state  // StatePublisher<LiveListState>
+
+// 订阅异步事件
+LiveListStore.shared.liveListEventPublisher  // PassthroughSubject<LiveListEvent, Never>
+
+// 加入直播间（观众）
+// ⚠️ completion 返回 LiveInfo（不是 Void）
+LiveListStore.shared.joinLive(liveID: String,
+                              completion: LiveInfoCompletionClosure?)
+// LiveInfoCompletionClosure = (Result<LiveInfo, ErrorInfo>) -> Void
+```
+
+**LiveListState 关键字段**
+```swift
+struct LiveListState {
+    var liveList: [LiveInfo]        // 当前已拉取的直播列表
+    var liveListCursor: String      // 下一页游标；"" 表示已到末页
+    var currentLive: LiveInfo       // 当前所在直播间的信息
+}
+```
+
+**LiveListEvent 完整签名**
+```swift
+enum LiveListEvent {
+    case onLiveEnded(liveID: String, reason: LiveEndedReason, message: String)
+    case onKickedOutOfLive(liveID: String, reason: LiveKickedOutReason, message: String)
+}
+```
+
+| 参数 | 类型 | 说明 |
+|------|------|------|
+| `cursor` | `String` | 分页游标；首次传 `""`，末页时 `liveListCursor` 返回 `""` |
+| `count` | `Int` | 单次返回条数，建议 20，最大 50 |
+
+**LiveInfo 关键字段**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `liveID` | `String` | 直播间唯一 ID |
+| `liveName` | `String` | 直播间名称 |
+| `coverURL` | `String` | 封面 URL |
+| `liveOwner` | `LiveUserInfo` | 主播信息 |
+| `seatTemplate` | `SeatLayoutTemplate` | 座位布局模板 |
+| `categoryList` | `[NSNumber]` | 分类标签（NSNumber，不是 String） |
+| `metaData` | `[String: String]` | 自定义扩展数据 |
+| `totalViewerCount` | `Int` | 当前观看人数 |
+| `isEmpty` | `Bool` | 直播间是否为空（可用于过滤） |
+
+## 代码示例
+
+```swift
+import AtomicXCore
+import Combine
+
+var cancellables = Set<AnyCancellable>()
+
+// MARK: - 分页拉取直播列表
+// ⚠️ fetchLiveList completion 是 Result<Void, ErrorInfo>
+//    列表数据通过 state 读取，不是通过 completion 参数返回
+
+func fetchFirstPage() {
+    LiveListStore.shared.fetchLiveList(cursor: "", count: 20) { result in
+        switch result {
+        case .success:
+            // ✅ 拉取成功后，从 state 读取列表
+            // （state 是 StatePublisher，可订阅也可直接读当前值）
+            observeLiveListState()
+
+        case .failure(let errorInfo):
+            print("[LiveList] 拉取失败, code: \(errorInfo.code), msg: \(errorInfo.message)")
+        }
+    }
+}
+
+func fetchMorePages() {
+    // 通过 state 读取当前 cursor
+    // （StatePublisher 读当前值的方式取决于具体 SDK 实现，此处以 .value 示意）
+    // TODO: 待验证 — StatePublisher 读取当前值的具体方式
+    let currentCursor = "..." // 从 state.liveListCursor 获取
+    guard !currentCursor.isEmpty else {
+        print("[LiveList] 已到末页")
+        return
+    }
+
+    LiveListStore.shared.fetchLiveList(cursor: currentCursor, count: 20) { result in
+        switch result {
+        case .success:
+            print("[LiveList] 更多页拉取成功")
+        case .failure(let errorInfo):
+            print("[LiveList] 拉取更多失败, code: \(errorInfo.code)")
+        }
+    }
+}
+
+// MARK: - 订阅状态（Combine）
+
+func observeLiveListState() {
+    LiveListStore.shared.state
+        .receive(on: DispatchQueue.main)
+        .sink { liveListState in
+            let list   = liveListState.liveList       // [LiveInfo]
+            let cursor = liveListState.liveListCursor // String（"" = 末页）
+            print("[LiveList] 当前列表数量: \(list.count), 下一页 cursor: \(cursor)")
+            // 刷新 UI
+        }
+        .store(in: &cancellables)
+}
+
+// MARK: - 订阅直播事件
+
+func subscribeLiveListEvents() {
+    LiveListStore.shared.liveListEventPublisher
+        .receive(on: DispatchQueue.main)
+        .sink { event in
+            switch event {
+            // ⚠️ onLiveEnded 三个关联值
+            case .onLiveEnded(let liveID, _, _):
+                print("[LiveList] 直播 \(liveID) 已结束，从列表移除")
+
+            // ⚠️ onKickedOutOfLive 三个关联值
+            case .onKickedOutOfLive(let liveID, let reason, let message):
+                print("[LiveList] 被踢出 \(liveID), reason: \(reason), msg: \(message)")
+            }
+        }
+        .store(in: &cancellables)
+}
+
+// MARK: - 加入直播间（joinLive 返回 LiveInfo，不是 Void）
+
+func joinLive(liveID: String) {
+    // ⚠️ joinLive completion 是 LiveInfoCompletionClosure，返回 LiveInfo
+    LiveListStore.shared.joinLive(liveID: liveID) { result in
+        switch result {
+        case .success(let liveInfo):
+            // 成功时回调携带完整 LiveInfo
+            print("[LiveList] 进房成功")
+            print("[LiveList] 直播间名称: \(liveInfo.liveName)")
+            print("[LiveList] 主播: \(liveInfo.liveOwner.userID)")
+            // 进房成功后启用弹幕/礼物等功能
+
+        case .failure(let errorInfo):
+            print("[LiveList] 进房失败, code: \(errorInfo.code)")
+            handleJoinError(errorInfo)
+        }
+    }
+}
+
+// MARK: - 进房错误处理
+
+func handleJoinError(_ errorInfo: ErrorInfo) {
+    switch errorInfo.code {
+    case -1002: print("请先登录")
+    case -2001: print("直播间不存在或已结束")
+    default:    print("进房失败（code: \(errorInfo.code)）: \(errorInfo.message)")
+    }
+}
+```
+
+## 调用时序
+
+```
+LoginStore.login 成功
+    │
+    ▼
+LiveListStore.shared.fetchLiveList(cursor: "", count: 20) { result in ... }
+    │
+    ├─ .failure(errorInfo) → 检查登录态 / 网络
+    │
+    └─ .success
+            │
+            ▼
+    LiveListStore.shared.state 订阅
+    读取 liveListState.liveList        ← [LiveInfo]
+    读取 liveListState.liveListCursor  ← 下一页游标
+            │
+            ├─ 渲染列表（reloadData）
+            │
+            ▼
+        用户滑动到底部 → fetchLiveList(cursor: cursor, count: 20)
+            │
+            └─ .success → state 更新 liveList 和 liveListCursor
+            │
+            ▼
+        用户点击某个直播间
+            │
+            ▼
+        LiveListStore.shared.joinLive(liveID:) { result in ... }
+            │
+            ├─ .failure(errorInfo) → 展示错误
+            └─ .success(liveInfo)  → 进入直播间（启用弹幕/礼物等）
+```
+
+## 平台特有注意事项
+
+### 1. fetchLiveList completion 是 `Result<Void, ErrorInfo>`，列表从 state 读取
+`fetchLiveList` 的 completion 只表示「请求是否成功」，实际列表数据通过 `LiveListStore.shared.state` 订阅获取：
+```swift
+// ✅ 正确流程
+LiveListStore.shared.fetchLiveList(cursor: "", count: 20) { result in
+    if case .success = result {
+        // 从 state 读取列表
+        subscribeToState()
+    }
+}
+
+// ❌ 错误：completion 没有 list 参数
+LiveListStore.shared.fetchLiveList(cursor: "", count: 20) { result in
+    if case .success(let list) = result { ... }  // 编译错误
+}
+```
+
+### 2. joinLive completion 返回 LiveInfo，不是 Void
+`joinLive` 的回调类型是 `LiveInfoCompletionClosure = (Result<LiveInfo, ErrorInfo>) -> Void`，成功时携带直播间完整信息：
+```swift
+case .success(let liveInfo):  // ✅ liveInfo: LiveInfo
+    let ownerID = liveInfo.liveOwner.userID
+```
+
+### 3. LiveListEvent 关联值有三个字段
+```swift
+// ✅ 正确（三个关联值）
+case .onLiveEnded(let liveID, let reason, let message):
+case .onKickedOutOfLive(let liveID, let reason, let message):
+
+// ❌ 错误（缺少 reason 和 message）
+case .onLiveEnded(let liveID):
+```
+
+### 4. categoryList 类型是 `[NSNumber]`，不是 `[String]`
+```swift
+// ✅ 正确
+let categories: [NSNumber] = liveInfo.categoryList
+
+// ❌ 错误
+let categories: [String] = liveInfo.categoryList  // 类型不匹配
+```
+
+### 5. 内存管理：Cell 离屏必须退出直播间
+iOS UICollectionView 会缓存离屏 Cell，若不在 `didEndDisplaying` 中调用 `leaveLive`，旧 Cell 的 `LiveCoreView` 会继续解码、占用解码器硬件资源，在直播列表页快速滑动时极易触发内存警告甚至 OOM。