`RoomStore`  专职负责  `AtomicXCore`  中的房间事务管理，提供从房间创建到解散的完整流程控制接口。通过 `RoomStore` 提供的接口（如获取及更新房间信息），可高效开发出一套成熟的房间管理体系。

## 核心功能
- **创建并加入房间**：房主通过调用该接口可以直接创建并进入房间。

- **加入房间**：参与者通过调用该接口可以直接进入已存在的房间。

- **离开房间**：参与者通过调用该接口可以退出已进入的房间。

- **结束房间**：房主通过调用该接口可以结束当前房间，如果房间内还有其他参与者，此时他们会收到 `onRoomEnded` 事件。

- **更新房间信息**：房主或管理员通过调用该接口可以更新房间信息，目前支持更新房间名称，房间密码。

- **获取房间信息**：通过调用该接口可以获取房间的详细信息。

## 核心概念

在开始集成之前，需要通过下表了解一下`RoomStore`相关的几个核心概念：
| **核心概念** | **类型** | **核心职责与描述** |
| --- | --- | --- |
| [RoomInfo](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roominfo) | `struct` | 代表房间信息的核心数据模型，封装了房间的完整信息和状态管理能力。<br>核心功能包括：<br>- 房间基本信息管理（房间 ID、名称、创建者）。<br>- 实时状态跟踪（参与者数量、房间状态、创建时间）。<br>- 房间调度功能（预约时间、参会者列表、提醒设置）。<br>- 权限控制（密码保护、设备管控、消息管理）。 |
| [RoomState](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomstate) | `struct` | 代表房间状态管理的核心数据结构，负责维护用户的房间相关状态信息。<br>核心属性：<br>- `scheduledRoomList`存储了当前账号下所有预约的房间列表信息。<br>- `scheduledRoomListCursor` 则代表预约房间列表的分页快照。<br>- `currentRoom`则代表当前所在房间的状态信息。 |
| [RoomEvent](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomevent) | `enum` | 代表房间动态的实时事件。主要事件分为三大类：预约房间事件，房间结束事件，房间呼叫事件。 |
| [RoomStore](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomstore) | `class` | 这是与房间全生命周期相关的核心类。功能包含：获取预约房间列表快照、执行房间管理操作，并通过订阅其 `roomEventPublisher` 来接收实时动态事件。 |

## 实现步骤

### 步骤1：组件集成

请参考 接入概览 集成 **AtomicXCore SDK **，并已完成 实现登录逻辑 部分接入。

### 步骤2：**创建并加入房间**

##### 实现方式：
1. **配置房间初始化参数：**初始化`CreateRoomOptions`来设置房间名称，房间密码。

2. **房间权限预设：**设置房间内全场成员权限，例如全体静音，全体禁画等。

3. **创建并加入房间：**调用`RoomStore`的`createAndJoinRoom`接口执行核心操作。

##### 示例代码：
``` swift
import Foundation
import AtomicXCore

func createAndJoinRoom() {
    // 1. 配置房间创建参数
    // CreateRoomOptions 定义房间的基础属性和初始权限设置
    var options = CreateRoomOptions()
    options.roomName = "团队会议室"           // 房间显示名称
    options.password = ""                   // 房间密码（可选）

    // 2. 房间权限预设
    options.isAllCameraDisabled = false     // 是否禁用所有成员摄像头
    options.isAllMessageDisabled = false    // 是否禁言所有成员
    options.isAllMicrophoneDisabled = false // 是否静音所有成员
    options.isAllScreenShareDisabled = false // 是否禁止所有成员屏幕分享

    // 3. 创建并加入房间
    // 该方法会自动处理房间创建（如果不存在）和加入逻辑
    RoomStore.shared.createAndJoinRoom(roomID: "roomID", roomType: .standard, options: options) { result in
        switch result {
        case .success():
            print("成功创建并加入房间")
        case .failure(let error):
            print("创建并加入房间失败 [错误码: \(error.code)]: \(error.message)")
        }
    }
}
```

##### createAndJoinRoom 接口参数详细说明
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roomID` | `String` | 是 | - 字符串类型的房间唯一标识符。<br>- 限制长度为 0-48 字节。<br>- 建议仅包含数字、英文字母（区分大小写）、下划线（_）和连字符（-）。避免使用空格和中文字符。 |
| `roomType` | `RoomType` | 是 | 房间类型。<br>- standard：标准房间，所有成员可自由音视频互动。<br>- webinar：大型研讨会房间，区分嘉宾和观众角色，观众默认无上麦权限。 |
| `options` | `CreateRoomOptions` | 是 | - 创建房间配置对象。<br>- 详细用法请参考：CreateRoomOptions 结构体详细说明。 |
| `completion` | `CompletionClosure` | 否 | 操作完成回调，用于返回创建和加入房间的结果。若创建失败则会返回错误码和错误信息。 |

##### CreateRoomOptions 结构体详细说明
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roomName` | `String` | 否 | - 房间名称，可以不设置，默认为空字符串。<br>- 限制长度为 0-60 字节。<br>- 支持中英文、数字、特殊字符。 |
| `password` | `String` | 否 | - 房间密码，空字符串 "" 通常表示该房间不设密码。<br>- 限制长度为 0-32 字节。<br>- 推荐使用 4-8 位纯数字，方便移动端输入。设置后，其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 |
| `isAllMicrophoneDisabled` | `Bool` | 否 | 是否全员禁止打开麦克风。开启后，除房主/管理员外，普通参与者默认禁止打开麦克风。<br>- true：禁止。<br>- false：取消禁止 （默认值）。 |
| `isAllCameraDisabled` | `Bool` | 否 | 是否全员禁止打开摄像头。开启后，除房主/管理员外，普通参与者默认禁止打开摄像头。<br>- true：禁止。<br>- false：取消禁止（默认值）。 |
| `isAllScreenShareDisabled` | `Bool` | 否 | 是否全员禁止发起屏幕共享。开启后，仅房主/管理员可进行屏幕共享。<br>- true：禁止。<br>- false：取消禁止（默认值）。 |
| `isAllMessageDisabled` | `Bool` | 否 | 是否全员禁止发送聊天消息（禁言）。开启后，普通参与者无法在房间内发送文字消息。<br>- true：禁止。<br>- false：取消禁止（默认值）。 |

### 步骤3：**加入房间**

参与者需要加入房间时，调用 `RoomStore` 的 `joinRoom` 接口，即可加入房间，此时房间内其他参与者会收到参与者加入房间事件通知。
``` swift
import Foundation
import AtomicXCore

func joinRoom() {
    // 1. 准备加入房间参数
    // joinRoom 适用于加入一个已知且正在进行的房间
    let roomPassword = "" // 房间密码，若房间未设置密码则传空字符串或 nil

    // 2. 调用 RoomStore 加入房间接口
    // 该操作会验证房间是否存在、用户是否被禁入以及密码是否正确
    RoomStore.shared.joinRoom(roomID: "roomID", roomType: .standard, password: roomPassword) { result in
        switch result {
        case .success():
            print("加入房间成功")
        case .failure(let error):
            print("加入房间失败 [错误码: \(error.code)]: \(error.message)")
        }
    }
}
```

##### joinRoom 接口参数详细说明
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roomID` | `String` | 是 | - 字符串类型的房间唯一标识符。<br>- 限制长度为 0-48 字节。<br>- 建议仅包含数字、英文字母（区分大小写）、下划线（_）和连字符（-）。避免使用空格和中文字符。 |
| `roomType` | `RoomType` | 是 | 房间类型<br>- standard：标准房间，所有成员可自由音视频互动。<br>- webinar：大型研讨会房间，区分嘉宾和观众角色，观众默认无上麦权限。 |
| `password` | `String` | 是 | - 房间密码，空字符串 "" 通常表示该房间不设密码。<br>- 限制长度为 0-32 字节。<br>- 推荐使用 4-8 位纯数字，方便移动端输入。设置后，其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 |
| `completion` | `CompletionClosure` | 否 | 操作完成回调，用于返回加入房间的结果。若创建失败则会返回错误码和错误信息。 |

### **步骤4：离开房间**

当参与者要离开房间时，通过调用 `RoomStore` 的 `leaveRoom` 接口即可离开房间，此时房间内其他参与者都会收到参与者离开房间事件通知。
``` swift
import Foundation
import AtomicXCore

func leaveRoom() {
    // 1. 业务逻辑说明
    // leaveRoom 接口用于普通成员或房主主动退出房间
    // 与 endRoom 不同，房主调用 leaveRoom 只会让自己离开，房间依然存在

    // 2. 调用 RoomStore 离开房间接口
    // 该操作会停止音视频流传输，并通知服务器将当前用户移出房间
    RoomStore.shared.leaveRoom { result in
        switch result {
        case .success():
            print("离开房间成功")
        case .failure(let error):
            print("离开房间失败 [错误码: \(error.code)]: \(error.message)")
        }
    }
}
```

### 步骤5：**结束房间**

当房主期望结束房间时，调用 `RoomStore` 的 `endRoom` 接口即可结束当前房间。结束房间后，房间内的所有参与者都会收到房间结束事件。
``` swift
import Foundation
import AtomicXCore

func endRoom() {
    // 1. 业务逻辑说明
    // endRoom 接口用于永久解散当前房间
    // 注意：该操作通常仅限房主（Owner）执行，解散后所有成员将被强制退出

    // 2. 调用 RoomStore 解散房间接口
    // 该方法会向服务器发送解散指令，并通知所有在线参与者房间已结束
    RoomStore.shared.endRoom { result in
        switch result {
        case .success():
            print("解散房间成功")
        case .failure(let error):
            print("解散房间失败 [错误码: \(error.code)]: \(error.message)")
        }
    }
}
```

### **步骤6：更新房间信息**

当房主期望更新房间名称或者更改房间密码时，调用 `RoomStore` 的 `updateRoomInfo` 接口即可更新房间信息。更新后房间内的参与者会收到房间状态变更通知。
``` swift
import Foundation
import AtomicXCore

func updateRoomInfo() {
    // 1. 配置房间更新参数
    // UpdateRoomOptions 用于定义需要更新的房间属性
    var options = UpdateRoomOptions()
    options.roomName = "新的会议室名称"  // 更新房间显示名称

    // 2. 设置修改标志位
    // ModifyFlag 用于指定具体要更新哪些字段
    var modifyFlag: UpdateRoomOptions.ModifyFlag = []
    modifyFlag.insert(.roomName)       // 标记需要更新房间名称

    // 3. 调用 RoomStore 更新房间信息接口
    // 该方法会向服务器提交更新请求，并同步给所有房间成员
    RoomStore.shared.updateRoomInfo(roomID: "roomID", options: options, modifyFlag: modifyFlag) { result in
        switch result {
        case .success():
            print("更新房间信息成功")
        case .failure(let error):
            print("更新房间信息失败 [错误码: \(error.code)]: \(error.message)")
        }
    }
}
```

##### updateRoomInfo 接口参数详细说明
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roomID` | `String` | 是 | - 字符串类型的房间唯一标识符。<br>- 限制长度为 0-48 字节。<br>- 建议仅包含数字、英文字母（区分大小写）、下划线（_）和连字符（-）。避免使用空格和中文字符。 |
| `options` | `UpdateRoomOptions` | 是 | - 更新房间属性配置对象。<br>- 详细用法请参考：UpdateRoomOptions 结构体详细说明 |
| `modifyFlag` | `UpdateRoomOptions.ModifyFlag` | 是 | - 更新房间属性修改标志位。目前支持更新**房间名称**、**房间密码**。<br>- 详细用法请参考：UpdateRoomOptions.ModifyFlag 详细说明。 |
| `completion` | `CompletionClosure` | 否 | 操作完成回调，用于返回更新房间信息的结果。若更新失败则会返回错误码和错误信息。 |

**UpdateRoomOptions 结构体详细说明**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roomName` | `String` | 否 | - 房间名称，可以不设置，默认为空字符串。<br>- 限制长度为 0-60 字节。<br>- 支持中英文、数字、特殊字符。 |
| `password` | `String` | 否 | - 房间密码，空字符串 "" 通常表示该房间不设密码。<br>- 限制长度为 0-32 字节。<br>- 推荐使用 4-8 位纯数字，方便移动端输入。设置后，其他用户加入房间时需输入密码。建议不要存储明文敏感信息。 |

**UpdateRoomOptions.ModifyFlag 详细说明**
| 参数名 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `roomName` | `UInt` | 否 | - 修改房间名称时的标识位。<br>- 当修改`UpdateRoomOptions`中的`roomName`后，需要同步设置`ModifyFlag`的`roomName`标识位。 |
| `password` | `UInt` | 否 | - 修改房间密码时的标识位。<br>- 当修改`UpdateRoomOptions`中的`password`后，需要同步设置`ModifyFlag`的`password`标识位。 |

### 步骤7：获取房间信息

进入房间成功后调用`RoomStore`的`getRoomInfo`接口即可获取到房间详细信息。
``` swift
import Foundation
import AtomicXCore

func getRoomInfo() {
    // 1. 业务逻辑说明
    // getRoomInfo 接口用于获取指定房间的详细信息
    // 可以获取房间名称、创建者、参与者数量、权限设置等完整信息

    // 2. 调用 RoomStore 获取房间信息接口
    // 该操作会从服务器获取最新的房间状态和配置信息
    RoomStore.shared.getRoomInfo(roomID: "roomID") { result in
        switch result {
        case .success(let roomInfo):
            print("获取房间信息成功，roomInfo: \(roomInfo)")
        case .failure(let error):
            print("获取房间信息失败 [错误码: \(error.code)]: \(error.message)")
        }
    }
}
```

### 步骤8：监听房间实时事件及状态变化

订阅`RoomEvent`房间内的被动事件。以订阅房间结束事件为例，示例代码如下：
``` swift
import Foundation
import AtomicXCore
import Combine

private var cancellableSet = Set<AnyCancellable>()

/// 设置房间事件监听器
private func subscribeRoomEvent() {
    RoomStore.shared.roomEventPublisher
        .receive(on: DispatchQueue.main) // 确保在主线程处理 UI 逻辑
        .sink { event in
            switch event {
            case .onRoomEnded(let roomInfo):
                print("当前所在房间已结束")
            default: break
            }
        }
        .store(in: &cancellableSet)
}
```

订阅`RoomState`房间属性状态变化。以订阅当前所在房间信息变化为例，示例代码如下：
``` swift
import Foundation
import AtomicXCore
import Combine

private var cancellableSet = Set<AnyCancellable>()

private func subscribeRoomState() {
    /// 设置当前房间状态监听器
    RoomStore.shared.state
        .subscribe(StatePublisherSelector(keyPath: \.currentRoom))
        .receive(on: DispatchQueue.main) // 确保在主线程处理 UI 逻辑
        .sink { roomInfo in
            if let newRoomInfo = roomInfo {
                print("房间信息更新 新的房间信息: \(newRoomInfo)")
            }
        }
        .store(in: &cancellableSet)
}
```

## API 文档
| **Store/Component** | **功能描述** | **API文档** |
| --- | --- | --- |
| **RoomStore** | 房间全生命周期管理：创建并加入 / 加入 / 离开 / 结束房间 / 更新、获取房间信息 / 房间预定 / 呼叫房间外成员 / 监听房间内被动事件（如房间解散，房间信息更新等）。 | [API 文档](https://tencent-rtc.github.io/TUIKit_iOS/documentation/atomicxcore/roomstore) |

## 常见问题

### `RoomInfo` 中的参与人数（`participantCount`）是如何更新的？时机和频率是怎样的？

`participantCount` 的更新并非总是实时的，其机制如下：
- **主动进出房间**：当用户主动加入或正常退出房间时，参与人数的变更通知会即时触发。您会很快在 `RoomState` 中的`currentRoom`观察到 `participantCount` 的变化。

- **异常掉线**：当用户因网络问题、应用崩溃等原因异常掉线时，系统需要通过心跳机制来判断其真实状态。只有当该用户连续 90 秒没有心跳后，系统才会判定其为离线，并触发人数变更通知。

- **更新机制与频率控制：**

  - 无论是即时触发还是延迟触发，所有的人数变更通知都是以消息的形式在房间内广播的。

  - 房间内每秒的消息总量有上限，单房间消息频控是**每秒 40 条消息**。

  - **关键点：**在“弹幕风暴”消息流量极高的场景下，如果房间内的消息速率超过了 40条/秒 的阈值，为了保证核心消息（例如弹幕）的送达，**人数变更的消息可能会被频控策略丢弃**。

      **这对开发者意味着什么？**

      `participantCount` 是一个非常接近实时的**高精度估算值**，但在极端高并发场景下，它可能存在短暂的延迟或数据丢失。因此，我们建议您将其用于 **UI 展示**，而不应作为计费、统计等需要绝对精准场景的唯一依据。