# 步骤 10：状态同步进阶

> 实现高级状态同步：增量同步完善、补偿同步触发、重连全量同步、同步失败处理、数据一致性校验。
> 依赖：步骤 09（断开连接）已完成，首次同步（①）已在步骤 04 实现。

---

## 一、目标

- [ ] 增量同步（②）完善 — OnClientEnter / OnClientMoved / OnClientLeave 幂等归并
- [ ] 补偿同步（③）触发机制 — 未知实体引用时自动修复基线
- [ ] 重连全量同步（⑥） — 清理旧状态 → 重新执行首次同步
- [ ] 同步失败处理（⑦） — 状态机流转、重试、降级
- [ ] 数据一致性校验 — 周期性校验与频道列表刷新

---

## 二、任务清单

### 10.1 增量同步完善

**目标**：将步骤 04 中注册的事件处理器补全为完整的幂等归并逻辑，确保成员实体表在持续事件流中保持一致。

**前置条件**：
- 步骤 04 已实现首次同步（ListChannels + ListClients + ClientID）
- 步骤 04 已注册 OnClientEnter / OnClientLeave / OnClientMoved 事件处理器
- `ChannelRepository` 已有 `_clients: MutableStateFlow<List<ClientInfo>>` 和 `_channelClients: MutableStateFlow<Map<Long, List<ClientInfo>>>`

**任务**：

1. **成员实体表改造为 Map 结构**

   将成员存储从 `List<ClientInfo>` 改为 `Map<Int, ClientInfo>`，以 ClientID 为 key 实现 O(1) 查询和幂等更新。

   ```kotlin
   // data/Repository.kt
   class ChannelRepository {
       // 成员实体表：ClientID → ClientInfo
       private val _clientMap = MutableStateFlow<Map<Int, ClientInfo>>(emptyMap())
       val clientMap: StateFlow<Map<Int, ClientInfo>> = _clientMap

       // 派生：按频道 ID 索引的成员列表（由 clientMap 自动计算）
       val channelClients: StateFlow<Map<Long, List<ClientInfo>>> =
           _clientMap.map { map ->
               map.values.groupBy { it.channelId }
           }.stateIn(scope, SharingStarted.WhileSubscribed(), emptyMap())

       // 派生：成员列表（兼容旧接口）
       val clients: StateFlow<List<ClientInfo>> =
           _clientMap.map { it.values.toList() }
               .stateIn(scope, SharingStarted.WhileSubscribed(), emptyList())

       /** 首次同步：原子替换整个成员表 */
       fun setClientBaseline(clients: List<ClientInfo>) {
           _clientMap.value = clients.associateBy { it.id }
       }

       /** 增量更新：按 ID 幂等插入或覆盖 */
       fun upsertClient(client: ClientInfo) {
           _clientMap.update { it + (client.id to client) }
       }

       /** 增量更新：按 ID 幂等删除（重复删除为 no-op） */
       fun removeClient(clientId: Int) {
           _clientMap.update { it - clientId }
       }

       /** 增量更新：移动成员到目标频道 */
       fun moveClient(clientId: Int, targetChannelId: Long) {
           _clientMap.update { map ->
               val existing = map[clientId] ?: return@update map // 不存在则 no-op
               if (existing.channelId == targetChannelId) return@update map // 相同频道则 no-op
               map + (clientId to existing.copy(channelId = targetChannelId))
           }
       }

       /** 查询成员是否存在 */
       fun hasClient(clientId: Int): Boolean = _clientMap.value.containsKey(clientId)

       /** 查询频道是否存在 */
       fun hasChannel(channelId: Long): Boolean = _channels.value.any { it.id == channelId }

       /** 清理会话数据 */
       fun clearSession() {
           _clientMap.value = emptyMap()
           _channels.value = emptyList()
           _selfClientId.value = null
       }
   }
   ```

2. **OnClientEnter 归并逻辑**

   ```kotlin
   // ChannelViewModel.kt
   fun handleClientEnter(data: String) {
       val client = Json.decodeFromString<ClientInfo>(data)
       // 按 ID 覆盖，重复事件不会重复计数
       repository.upsertClient(client)
   }
   ```

   **关键约束**：
   - 按 ClientInfo.ID 覆盖，**禁止**使用 `+1` 增量累加频道人数
   - 频道人数由 `channelClients[channelId].size` 实时派生
   - 已有基线时，进入事件覆盖旧数据；无基线时，插入新条目

3. **OnClientMoved 归并逻辑**

   ```kotlin
   // ChannelViewModel.kt
   fun handleClientMoved(data: String) {
       val event = Json.decodeFromString<ClientMovedEvent>(data)

       // 判断是否为自己
       if (event.clientId == repository.selfClientId.value) {
           repository.updateSelfChannel(event.targetChannelId)
       }

       // 更新成员位置
       if (repository.hasClient(event.clientId)) {
           repository.moveClient(event.clientId, event.targetChannelId)
       } else {
           // 成员不存在 → 触发补偿同步（见 10.2）
           triggerClientCompensationSync()
       }
   }
   ```

   **关键约束**：
   - 目标频道 ID 是移动后的服务器事实，直接覆盖旧的 ChannelID
   - 相同目标频道视为 no-op
   - 未知成员**不得**静默忽略，必须触发补偿同步

4. **OnClientLeave 归并逻辑**

   ```kotlin
   // ChannelViewModel.kt
   fun handleClientLeave(data: String) {
       val event = Json.decodeFromString<ClientLeftViewEvent>(data)

       if (event.isSelf) {
           // 自己被踢出或离开 → 由步骤 09 处理
           handleKicked(event.reasonMessage)
           return
       }

       // 按 ID 删除，重复删除安全地保持 no-op
       repository.removeClient(event.clientId)
   }
   ```

   **关键约束**：
   - 重复删除必须为 no-op（Map.remove 天然满足）
   - 不使用 `-1` 减量维护频道人数
   - `IsSelf` 为 true 时走踢出/断开流程，不从成员表删除

5. **ClientMovedEvent / ClientLeftViewEvent 数据类**

   ```kotlin
   // data/Models.kt
   data class ClientMovedEvent(
       val clientId: Int,
       val targetChannelId: Long,
       val reasonId: Int = 0,
       val invokerId: Int = 0,
       val invokerName: String = "",
       val invokerUid: String = ""
   )

   data class ClientLeftViewEvent(
       val clientId: Int,
       val reasonId: Int = 0,       // 0=正常离开, 4=频道踢, 5=服务器踢
       val reasonMessage: String = "",
       val isSelf: Boolean = false
   )
   ```

### 10.2 补偿同步机制

**目标**：当增量事件引用了本地不存在的实体（ClientID 或 ChannelID），自动触发完整列表请求修复基线。

**触发条件**：

| 场景 | 检测方式 | 补偿动作 |
|------|----------|----------|
| OnClientMoved 引用未知 ClientID | `!repository.hasClient(event.clientId)` | 重新调用 ListClients |
| OnClientLeave 引用未知 ClientID | `!repository.hasClient(event.clientId)` | 重新调用 ListClients（可选，删除本身是 no-op） |
| 成员引用未知 ChannelID | `!repository.hasChannel(member.channelId)` | 重新调用 ListChannels |

**任务**：

1. **补偿同步触发器**

   ```kotlin
   // ChannelViewModel.kt
   private var compensationSyncJob: Job? = null

   /**
    * 触发成员基线补偿同步。
    * 使用防抖：连续多个未知实体事件只触发一次 ListClients。
    */
   private fun triggerClientCompensationSync() {
       compensationSyncJob?.cancel()
       compensationSyncJob = viewModelScope.launch {
           delay(300) // 防抖 300ms
           performCompensationSync()
       }
   }

   private suspend fun performCompensationSync() {
       try {
           Log.w(TAG, "Compensation sync: rebuilding client baseline")
           val clients = TSBridge.listClients()
           repository.setClientBaseline(clients)
           Log.i(TAG, "Compensation sync completed: ${clients.size} clients")
       } catch (e: Exception) {
           Log.e(TAG, "Compensation sync failed", e)
           // 补偿同步失败不阻塞业务，等待下次触发
       }
   }
   ```

2. **频道基线补偿同步**

   ```kotlin
   // ChannelViewModel.kt
   private fun triggerChannelCompensationSync() {
       viewModelScope.launch {
           try {
               Log.w(TAG, "Compensation sync: rebuilding channel baseline")
               val channels = TSBridge.listChannels()
               repository.setChannelBaseline(channels)
               Log.i(TAG, "Compensation sync completed: ${channels.size} channels")
           } catch (e: Exception) {
               Log.e(TAG, "Channel compensation sync failed", e)
           }
       }
   }
   ```

3. **补偿同步与增量事件的协调**

   ```kotlin
   // 在 handleClientMoved 中集成
   fun handleClientMoved(data: String) {
       val event = Json.decodeFromString<ClientMovedEvent>(data)

       if (event.clientId == repository.selfClientId.value) {
           repository.updateSelfChannel(event.targetChannelId)
       }

       if (repository.hasClient(event.clientId)) {
           repository.moveClient(event.clientId, event.targetChannelId)
       } else {
           // 检测到未知成员，触发补偿同步
           Log.w(TAG, "Unknown client ${event.clientId} in move event, triggering compensation")
           triggerClientCompensationSync()
       }
   }
   ```

**关键约束**：
- 补偿同步使用**完整列表替换**，不是增量合并
- 使用防抖避免事件风暴时重复调用 ListClients
- 补偿同步失败不阻塞业务，等待下次事件触发重试
- 补偿同步完成后，UI 通过 StateFlow 自动刷新

**时序**（对应流程文档 §六）：

```
OnClientMoved(未知 ClientID)
  → 检测到不一致
  → 调用 ListClients()
  → 完整成员列表返回
  → 替换成员基线（setClientBaseline）
  → UI 自动刷新
```

### 10.3 重连流程

**目标**：断开重连后，清空旧会话状态，重新执行完整首次同步，确保数据与服务器完全一致。

**触发条件**：
- 网络恢复后自动重连
- 用户手动触发重连
- 被踢出后重新连接

**任务**：

1. **重连状态机**

   ```kotlin
   // ServerViewModel.kt
   sealed class ReconnectState {
       object Idle : ReconnectState()
       object Detecting : ReconnectState()      // 检测到断开
       object Cleaning : ReconnectState()       // 清理旧会话
       object Reconnecting : ReconnectState()   // 重新连接中
       object Syncing : ReconnectState()        // 首次同步中
       object Ready : ReconnectState()          // 恢复就绪
       data class Failed(val error: Throwable) : ReconnectState()
   }
   ```

2. **重连流程实现**

   ```kotlin
   // ServerViewModel.kt
   private suspend fun performReconnect(config: ConnectionConfig) {
       _reconnectState.value = ReconnectState.Cleaning

       // 1. 清理旧会话数据（频道、成员、Pending 全部移除）
       repository.clearSession()
       _connectionState.value = ConnectionState.Disconnected

       // 2. 断开旧连接（确保资源释放）
       try { TSBridge.disconnect() } catch (_: Exception) {}

       _reconnectState.value = ReconnectState.Reconnecting

       // 3. 重新执行连接流程（参见步骤 04）
       registerEventHandlers()
       val connectResult = TSBridge.connect(config)
       if (connectResult.isFailure) {
           _reconnectState.value = ReconnectState.Failed(connectResult.exceptionOrNull()!!)
           return
       }

       val waitResult = TSBridge.waitConnected()
       if (waitResult.isFailure) {
           _reconnectState.value = ReconnectState.Failed(waitResult.exceptionOrNull()!!)
           return
       }

       // 4. OnConnected 事件将自动触发首次同步（步骤 04 已实现）
       _reconnectState.value = ReconnectState.Syncing
   }
   ```

3. **断开事件处理中的重连触发**

   ```kotlin
   // ServerViewModel.kt
   fun handleDisconnected(data: String) {
       val error = Json.decodeFromString<DisconnectedEvent>(data)

       when {
           error.isKicked -> {
               // 被踢出：显示原因，不自动重连
               _kickReason.value = error.reasonMessage
               repository.clearSession()
               _connectionState.value = ConnectionState.Disconnected
           }
           isAutoReconnectEnabled -> {
               // 网络断开：尝试自动重连
               viewModelScope.launch {
                   delay(RECONNECT_DELAY) // 等待网络恢复
                   performReconnect(lastConfig)
               }
           }
           else -> {
               // 手动断开或不自动重连
               repository.clearSession()
               _connectionState.value = ConnectionState.Disconnected
           }
       }
   }
   ```

4. **清理会话数据的完整性**

   ```kotlin
   // data/Repository.kt
   fun clearSession() {
       _clientMap.value = emptyMap()
       _channels.value = emptyList()
       _selfClientId.value = null
       _currentChannelId.value = null
       // 清除所有待确认状态
       _pendingChannelMove.value = null
   }
   ```

**关键约束**：
- 重连前**必须**清空旧会话状态，防止旧成员、频道和 Pending 污染新连接
- 清理操作在连接断开后执行，避免竞态
- 重连后的首次同步复用步骤 04 的 `performInitialSync()` 逻辑
- 被踢出不自动重连，由用户决定

**时序**（对应流程文档 §七）：

```
检测到断开
  → 状态改为 Cleaning
  → 清理旧会话数据（频道、成员、Pending）
  → 断开旧连接
  → 重新 Connect + WaitConnected
  → OnConnected 触发首次同步
  → ListChannels + ListClients + ClientID
  → 原子提交新基线
  → 恢复业务就绪
```

### 10.4 同步失败处理

**目标**：当 ListChannels 或 ListClients 请求失败时，正确流转同步状态，允许重试，防止在不完整数据上执行业务操作。

**任务**：

1. **同步状态机完善**

   ```kotlin
   // data/Models.kt
   sealed class SyncState {
       object Unsynced : SyncState()                          // 已连接但尚无完整数据
       object Syncing : SyncState()                           // 调用 ListChannels 和 ListClients
       object Synchronized : SyncState()                      // 列表基线可供 UI 使用
       data class SyncFailed(val error: Throwable) : SyncState()  // 同步失败
   }
   ```

   **状态流转**：
   ```
   Unsynced → Syncing → Synchronized（正常路径）
   Syncing → SyncFailed → Syncing（重试路径）
   Synchronized → Syncing（补偿同步或重连）
   ```

2. **首次同步失败处理**

   ```kotlin
   // ServerViewModel.kt
   private suspend fun performInitialSync() {
       _syncState.value = SyncState.Syncing

       try {
           // 并行请求
           val channelsDeferred = async { TSBridge.listChannels() }
           val clientsDeferred = async { TSBridge.listClients() }
           val selfIdDeferred = async { TSBridge.getClientId() }

           val channels = channelsDeferred.await()
           val clients = clientsDeferred.await()
           val selfId = selfIdDeferred.await()

           // 原子提交
           repository.setChannelBaseline(channels)
           repository.setClientBaseline(clients)
           repository.setSelfClientId(selfId)

           _syncState.value = SyncState.Synchronized
           _connectionState.value = ConnectionState.Ready
       } catch (e: Exception) {
           Log.e(TAG, "Initial sync failed", e)
           _syncState.value = SyncState.SyncFailed(e)
           // 不进入业务就绪，允许重试
       }
   }
   ```

3. **重试机制**

   ```kotlin
   // ServerViewModel.kt
   private suspend fun performSyncWithRetry(maxRetries: Int = 3) {
       var retryCount = 0

       while (retryCount < maxRetries) {
           performInitialSync()

           if (_syncState.value is SyncState.Synchronized) {
               return // 成功
           }

           retryCount++
           if (retryCount < maxRetries) {
               Log.w(TAG, "Sync retry $retryCount/$maxRetries")
               delay(1000L * retryCount) // 递增延迟
           }
       }

       Log.e(TAG, "Sync failed after $maxRetries retries")
       // 保持 SyncFailed 状态，UI 显示重试按钮
   }
   ```

4. **手动重试入口**

   ```kotlin
   // ServerViewModel.kt
   fun retrySync() {
       viewModelScope.launch {
           performSyncWithRetry()
       }
   }
   ```

5. **同步失败时的 UI 保护**

   ```kotlin
   // 在业务操作前检查同步状态
   fun switchChannel(channelId: Long, password: String? = null) {
       if (_syncState.value !is SyncState.Synchronized) {
           _error.value = "数据未同步，请等待同步完成或点击重试"
           return
       }
       // 执行频道切换...
   }
   ```

**关键约束**：
- 任一核心请求（ListChannels / ListClients / ClientID）失败则不标记业务就绪
- 允许重试，避免在不完整数据上执行业务操作
- 同步失败期间，业务操作（切换频道、发消息等）应被阻止
- 补偿同步失败不进入 SyncFailed，仅记录日志等待下次触发

### 10.5 数据一致性

**目标**：在长期运行中，检测并修复可能的数据不一致（如频道列表过期、成员数据漂移）。

**任务**：

1. **频道列表过期检测**

   SDK 不提供频道创建/更新/删除事件，因此频道列表可能随时间过期。

   ```kotlin
   // ChannelViewModel.kt
   private var lastChannelRefreshTime: Long = 0

   /** 检查频道列表是否需要刷新 */
   private fun isChannelListStale(): Boolean {
       val elapsed = System.currentTimeMillis() - lastChannelRefreshTime
       return elapsed > CHANNEL_LIST_STALE_THRESHOLD // 建议 5 分钟
   }

   companion object {
       const val CHANNEL_LIST_STALE_THRESHOLD = 5 * 60 * 1000L // 5 分钟
   }
   ```

2. **被动刷新策略**

   在用户执行关键操作时，检查并刷新过期数据：

   ```kotlin
   // ChannelViewModel.kt
   suspend fun refreshChannelsIfNeeded() {
       if (isChannelListStale()) {
           try {
               val channels = TSBridge.listChannels()
               repository.setChannelBaseline(channels)
               lastChannelRefreshTime = System.currentTimeMillis()
           } catch (e: Exception) {
               Log.e(TAG, "Channel refresh failed", e)
               // 不阻塞业务，使用旧数据
           }
       }
   }

   /** 浏览频道时刷新 */
   fun onChannelListVisible() {
       viewModelScope.launch { refreshChannelsIfNeeded() }
   }

   /** 切换频道前刷新 */
   suspend fun beforeChannelSwitch() {
       refreshChannelsIfNeeded()
   }
   ```

3. **成员数据校验**

   当成员引用了本地不存在的频道时，触发频道基线刷新：

   ```kotlin
   // ChannelViewModel.kt
   fun validateMemberData() {
       val channels = repository.channels.value.map { it.id }.toSet()
       val clients = repository.clientMap.value.values

       val unknownChannelIds = clients
           .map { it.channelId }
           .filter { it !in channels }
           .toSet()

       if (unknownChannelIds.isNotEmpty()) {
           Log.w(TAG, "Found clients referencing unknown channels: $unknownChannelIds")
           triggerChannelCompensationSync()
       }
   }
   ```

4. **后台一致性检查（可选）**

   ```kotlin
   // ServerViewModel.kt
   private var consistencyCheckJob: Job? = null

   fun startConsistencyCheck() {
       consistencyCheckJob = viewModelScope.launch {
           while (isActive) {
               delay(CONSISTENCY_CHECK_INTERVAL)
               if (_syncState.value is SyncState.Synchronized) {
                   channelViewModel.validateMemberData()
               }
           }
       }
   }

   fun stopConsistencyCheck() {
       consistencyCheckJob?.cancel()
       consistencyCheckJob = null
   }

   companion object {
       const val CONSISTENCY_CHECK_INTERVAL = 60 * 1000L // 1 分钟
   }
   ```

**关键约束**：
- `ListChannels` 是频道目录的**唯一权威来源**（SDK 无频道变更事件）
- 不能假设频道列表依靠 `On*` 事件永久保持最新
- 刷新失败时使用旧数据，不阻塞业务操作
- 一致性检查为低优先级，不影响正常事件流的实时性

---

## 三、验收标准

### 功能验收

- [ ] **增量同步**
  - OnClientEnter 事件正确添加成员到基线，重复事件不重复计数
  - OnClientMoved 事件正确更新成员频道位置，相同目标频道为 no-op
  - OnClientLeave 事件正确删除成员，重复删除为 no-op
  - 自己的移动事件正确更新自身频道位置
  - 频道人数由成员实体表实时派生，不使用独立计数器

- [ ] **补偿同步**
  - OnClientMoved 引用未知 ClientID 时自动触发 ListClients
  - 补偿同步使用完整列表替换成员基线
  - 连续多个未知实体事件只触发一次补偿同步（防抖）
  - 补偿同步失败不阻塞业务

- [ ] **重连全量同步**
  - 重连前清空旧会话数据（频道、成员、Pending）
  - 重连后自动执行首次同步
  - 同步完成后恢复业务就绪
  - 被踢出不自动重连

- [ ] **同步失败处理**
  - 首次同步失败进入 SyncFailed 状态
  - 同步失败期间业务操作被阻止
  - 提供手动重试入口
  - 重试最多 3 次，递增延迟

- [ ] **数据一致性**
  - 频道列表超过 5 分钟未刷新时，关键操作前自动刷新
  - 成员引用未知频道时触发频道基线补偿同步
  - 刷新失败时使用旧数据，不阻塞业务

### 性能验收

- [ ] 增量同步单次事件处理 < 10ms
- [ ] 补偿同步（ListClients）在 3 秒内完成
- [ ] 重连全量同步在 5 秒内完成
- [ ] 防抖机制避免事件风暴时的重复请求

### 代码质量验收

- [ ] 成员实体表操作线程安全（StateFlow + immutable Map）
- [ ] 补偿同步防抖使用协程取消，无泄漏
- [ ] 所有网络操作在 IO 线程执行
- [ ] 日志覆盖关键状态转换和异常

### 测试用例

| 场景 | 操作 | 预期结果 |
|------|------|----------|
| 正常增量流 | 其他用户进入/移动/离开 | 成员表实时更新，频道人数正确 |
| 重复进入事件 | 同一用户连续两次 OnClientEnter | 成员表只有一条记录，无重复计数 |
| 未知成员移动 | OnClientMoved 引用不存在的 ClientID | 自动触发 ListClients 补偿同步 |
| 补偿同步防抖 | 连续 5 个未知实体事件 | 只触发 1 次 ListClients |
| 正常重连 | 网络断开后恢复 | 清理旧数据 → 重连 → 同步 → 就绪 |
| 被踢后重连 | 被服务器踢出后手动重连 | 显示踢出原因 → 清理 → 重连 → 同步 |
| 同步失败重试 | 首次同步网络超时 | 进入 SyncFailed → 点击重试 → 成功 |
| 同步失败阻塞 | 同步失败时切换频道 | 显示"数据未同步"提示 |
| 频道列表过期 | 5 分钟后切换频道 | 自动刷新频道列表再切换 |
| 成员引用未知频道 | 成员的 ChannelID 在本地不存在 | 触发频道基线补偿同步 |

---

## 四、参考文档

- `docs/流程/08_状态同步.md` - 完整同步机制（②③⑥⑦）
- `docs/流程/02_浏览频道.md` - 成员实体状态树、事件依赖矩阵
- `docs/sdk文档-go.md` - OnClientEnter / OnClientLeave / OnClientMoved 事件处理器、ListClients / ListChannels API
- `docs/implementation/04_连接与首次同步.md` - 首次同步实现、SyncState 状态机
- `docs/implementation/09_断开连接.md` - 断开连接清理逻辑