# 步骤 06：频道切换

> 实现频道切换流程：频道点击处理、密码弹窗、ClientMove 命令发送、等待 OnClientMoved 服务端确认、自身频道状态更新。
> 对应流程：`docs/流程/03_切换频道.md`
> 依赖步骤：05（频道列表页）

---

## 一、目标

- [ ] 频道点击事件处理（区分有密码/无密码频道）
- [ ] 密码输入弹窗组件
- [ ] ChannelSwitchState 状态机（idle → requesting → waitingServerEvent → idle/failed）
- [ ] ClientMove 命令发送（通过 TSBridge.MoveToChannel）
- [ ] 等待 OnClientMoved 服务端事实确认
- [ ] 自身频道状态更新（④ 自身状态同步）
- [ ] 错误处理与用户反馈

---

## 二、任务清单

### 6.1 频道点击处理

**目标**：在频道列表页中处理频道点击事件，区分有密码和无密码频道。

**前置条件**：
- 步骤 05 的 ChannelListScreen 已实现
- ChannelRow 组件已支持点击事件

**任务**：

1. **频道点击入口**
   ```kotlin
   // ChannelListScreen.kt - ChannelTreeContent 中的 onChannelClick 回调
   @Composable
   fun ChannelTreeContent(
       channelViewModel: ChannelViewModel,
       onChannelClick: (ChannelInfo) -> Unit,
       onClientClick: (ClientInfo) -> Unit,
       onNavigateToChat: () -> Unit
   ) {
       // ... 已有实现 ...
   }
   ```

2. **频道点击逻辑（ChannelViewModel）**
   ```kotlin
   // ChannelViewModel.kt
   
   // 密码弹窗状态
   private val _showPasswordDialog = MutableStateFlow(false)
   val showPasswordDialog: StateFlow<Boolean> = _showPasswordDialog
   
   // 待切换的目标频道
   private val _pendingSwitchChannel = MutableStateFlow<ChannelInfo?>(null)
   val pendingSwitchChannel: StateFlow<ChannelInfo?> = _pendingSwitchChannel
   
   /**
    * 处理频道点击事件
    * 对应 UI架构设计.md 频道树交互规则
    */
   fun onChannelClicked(channel: ChannelInfo) {
       // 如果是当前频道，忽略
       if (channel.id == repository.selfChannelId.value) {
           Log.d(TAG, "Already in channel ${channel.id}, ignoring click")
           return
       }
       
       // 检查是否正在切换中
       if (_switchState.value != ChannelSwitchState.Idle) {
           Log.w(TAG, "Channel switch already in progress, ignoring click")
           return
       }
       
       if (channel.isPassword) {
           // 有密码频道：弹出密码输入框
           _pendingSwitchChannel.value = channel
           _showPasswordDialog.value = true
       } else {
           // 无密码频道：直接发起切换
           viewModelScope.launch {
               performChannelSwitch(channel.id, "")
           }
       }
   }
   ```

### 6.2 密码弹窗组件

**目标**：实现频道密码输入弹窗，支持密码错误重试。

**任务**：

1. **密码弹窗 Composable**
   ```kotlin
   // ui/components/ChannelPasswordDialog.kt
   
   @Composable
   fun ChannelPasswordDialog(
       channelName: String,
       onConfirm: (password: String) -> Unit,
       onDismiss: () -> Unit,
       isError: Boolean = false,
       errorMessage: String = "密码错误，请重试"
   ) {
       var password by remember { mutableStateOf("") }
       var showError by remember { mutableStateOf(isError) }
       
       // 当 isError 变化时更新本地状态
       LaunchedEffect(isError) {
           showError = isError
           if (isError) {
               password = "" // 清空输入框
           }
       }
       
       AlertDialog(
           onDismissRequest = onDismiss,
           title = {
               Text(
                   text = "该频道需要密码",
                   style = MaterialTheme.typography.titleMedium
               )
           },
           text = {
               Column {
                   Text(
                       text = "频道：$channelName",
                       style = MaterialTheme.typography.bodyMedium,
                       color = MaterialTheme.colorScheme.onSurfaceVariant
                   )
                   
                   Spacer(modifier = Modifier.height(16.dp))
                   
                   OutlinedTextField(
                       value = password,
                       onValueChange = { 
                           password = it
                           showError = false
                       },
                       label = { Text("输入频道密码") },
                       singleLine = true,
                       visualTransformation = PasswordVisualTransformation(),
                       keyboardOptions = KeyboardOptions(keyboardType = KeyboardType.Password),
                       isError = showError,
                       supportingText = if (showError) {
                           { Text(errorMessage, color = MaterialTheme.colorScheme.error) }
                       } else null,
                       modifier = Modifier.fillMaxWidth()
                   )
               }
           },
           confirmButton = {
               TextButton(
                   onClick = { onConfirm(password) },
                   enabled = password.isNotEmpty()
               ) {
                   Text("进入")
               }
           },
           dismissButton = {
               TextButton(onClick = onDismiss) {
                   Text("取消")
               }
           }
       )
   }
   ```

2. **在 ChannelListScreen 中集成密码弹窗**
   ```kotlin
   // ChannelListScreen.kt
   
   @Composable
   fun ChannelListScreen(
       channelViewModel: ChannelViewModel,
       serverViewModel: ServerViewModel,
       voiceViewModel: VoiceViewModel,
       onNavigateToChat: () -> Unit,
       onNavigateToServerConfig: () -> Unit,
       onOpenServerDetail: () -> Unit,
       onOpenChannelDetail: (channelId: Long) -> Unit,
       onOpenVoiceCard: () -> Unit
   ) {
       val showPasswordDialog by channelViewModel.showPasswordDialog.collectAsState()
       val pendingChannel by channelViewModel.pendingSwitchChannel.collectAsState()
       val switchState by channelViewModel.switchState.collectAsState()
       
       Column(modifier = Modifier.fillMaxSize()) {
           // ... 已有布局 ...
       }
       
       // 密码弹窗
       if (showPasswordDialog && pendingChannel != null) {
           ChannelPasswordDialog(
               channelName = pendingChannel!!.name,
               onConfirm = { password ->
                   channelViewModel.confirmPasswordAndSwitch(password)
               },
               onDismiss = {
                   channelViewModel.dismissPasswordDialog()
               },
               isError = switchState is ChannelSwitchState.Failed,
               errorMessage = (switchState as? ChannelSwitchState.Failed)?.error ?: "密码错误，请重试"
           )
       }
   }
   ```

3. **密码确认与取消逻辑**
   ```kotlin
   // ChannelViewModel.kt
   
   /**
    * 用户确认密码，发起切换
    */
   fun confirmPasswordAndSwitch(password: String) {
       val channel = _pendingSwitchChannel.value ?: return
       _showPasswordDialog.value = false
       
       viewModelScope.launch {
           performChannelSwitch(channel.id, password)
       }
   }
   
   /**
    * 用户取消密码输入
    */
   fun dismissPasswordDialog() {
       _showPasswordDialog.value = false
       _pendingSwitchChannel.value = null
       _switchState.value = ChannelSwitchState.Idle
   }
   ```

### 6.3 ChannelSwitchState 状态机

**目标**：实现频道切换的状态管理，确保命令响应与事件事实分离。

**状态定义**：
```kotlin
// data/Models.kt 或 ChannelViewModel.kt

/**
 * 频道切换状态机
 * 对应 docs/流程/03_切换频道.md 中的状态转换
 * 
 * 状态转换：
 *   Idle → Requesting：用户发起切换请求
 *   Requesting → WaitingServerEvent：ClientMove 命令成功
 *   Requesting → Failed：ClientMove 命令失败
 *   WaitingServerEvent → Idle：收到自己的 OnClientMoved 事件
 *   Failed → Idle：用户重试或取消
 */
sealed class ChannelSwitchState {
    /** 空闲状态，可以发起新的切换 */
    object Idle : ChannelSwitchState()
    
    /** 正在发送 ClientMove 命令 */
    object Requesting : ChannelSwitchState()
    
    /** ClientMove 命令成功，等待服务端 OnClientMoved 事件确认 */
    data class WaitingServerEvent(val targetChannelId: Long) : ChannelSwitchState()
    
    /** 切换失败（命令被拒绝或超时） */
    data class Failed(val error: String) : ChannelSwitchState()
}
```

**状态机实现**：
```kotlin
// ChannelViewModel.kt

// 切换状态
private val _switchState = MutableStateFlow<ChannelSwitchState>(ChannelSwitchState.Idle)
val switchState: StateFlow<ChannelSwitchState> = _switchState

// 等待服务端确认的超时 Job
private var switchTimeoutJob: Job? = null

/**
 * 执行频道切换
 * 对应 docs/流程/03_切换频道.md 时序图
 */
private suspend fun performChannelSwitch(targetChannelId: Long, password: String) {
    Log.d(TAG, "Requesting channel switch to $targetChannelId")
    
    // 状态改为 requesting
    _switchState.value = ChannelSwitchState.Requesting
    
    try {
        // 发送 ClientMove 命令
        // TSBridge.MoveToChannel 返回空串表示成功，否则返回错误信息
        val error = TSBridge.moveSelfToChannel(targetChannelId.toString(), password)
        
        if (error.isEmpty()) {
            // 命令成功，等待服务端事件确认
            _switchState.value = ChannelSwitchState.WaitingServerEvent(targetChannelId)
            
            // 启动超时检测（10秒）
            switchTimeoutJob?.cancel()
            switchTimeoutJob = viewModelScope.launch {
                delay(10_000)
                // 超时：如果还在等待状态，视为失败
                if (_switchState.value is ChannelSwitchState.WaitingServerEvent) {
                    Log.w(TAG, "Channel switch timeout waiting for server event")
                    _switchState.value = ChannelSwitchState.Failed("等待服务端确认超时")
                }
            }
            
            Log.d(TAG, "ClientMove command accepted, waiting for server event")
        } else {
            // 命令被拒绝
            Log.w(TAG, "ClientMove command rejected: $error")
            _switchState.value = ChannelSwitchState.Failed(mapMoveError(error))
        }
    } catch (e: Exception) {
        Log.e(TAG, "ClientMove command failed", e)
        _switchState.value = ChannelSwitchState.Failed("切换失败：${e.message}")
    }
}

/**
 * 映射 MoveToChannel 错误信息为用户友好的提示
 */
private fun mapMoveError(error: String): String {
    return when {
        error.contains("password", ignoreCase = true) -> "密码错误"
        error.contains("permission", ignoreCase = true) -> "权限不足"
        error.contains("full", ignoreCase = true) -> "频道已满"
        error.contains("banned", ignoreCase = true) -> "你已被该频道封禁"
        else -> "切换失败：$error"
    }
}
```

### 6.4 自身状态同步（④）

**目标**：处理自己的 OnClientMoved 事件，确认频道切换完成。

**关键原则**：
- 命令响应（ClientMove nil）不等于状态已提交
- 必须等待服务端推送的 OnClientMoved 事件才能更新本地频道事实
- 通过比对 ClientID == selfID 识别自己的移动事件

**任务**：

1. **处理 OnClientMoved 事件（区分自己和他人）**
   ```kotlin
   // ChannelViewModel.kt
   
   /**
    * 处理客户端移动事件
    * 对应 docs/流程/08_状态同步.md ② 增量同步 + ④ 自身状态同步
    * 
    * @param clientId 移动的客户端 ID
    * @param targetChannelId 目标频道 ID（字符串形式）
    */
   fun handleClientMoved(clientId: Int, targetChannelId: Long) {
       Log.d(TAG, "Client moved: $clientId -> channel $targetChannelId")
       
       val selfId = repository.selfClientId.value
       
       if (clientId == selfId) {
           // ④ 自身状态同步：这是自己的移动事件
           handleSelfMoved(targetChannelId)
       } else {
           // ② 增量同步：这是其他用户的移动事件
           handleOtherClientMoved(clientId, targetChannelId)
       }
   }
   
   /**
    * 处理自己的移动事件
    * 对应 docs/流程/03_切换频道.md 中等待 OnClientMoved 确认的分支
    */
   private fun handleSelfMoved(targetChannelId: Long) {
       val currentState = _switchState.value
       
       // 更新自身频道事实
       repository.updateSelfChannel(targetChannelId)
       
       // 清除目标频道的未读标记
       clearUnread(targetChannelId)
       
       when (currentState) {
           is ChannelSwitchState.WaitingServerEvent -> {
               // 正常流程：确认切换完成
               Log.d(TAG, "Channel switch confirmed by server: target=$targetChannelId")
               switchTimeoutJob?.cancel()
               _switchState.value = ChannelSwitchState.Idle
               _pendingSwitchChannel.value = null
           }
           is ChannelSwitchState.Requesting -> {
               // 罕见情况：事件先于命令响应到达
               Log.d(TAG, "Server event arrived before command response")
               switchTimeoutJob?.cancel()
               _switchState.value = ChannelSwitchState.Idle
               _pendingSwitchChannel.value = null
           }
           else -> {
               // 非切换流程中的移动（例如被管理员移动）
               Log.d(TAG, "Self moved by external action to channel $targetChannelId")
               _switchState.value = ChannelSwitchState.Idle
           }
       }
   }
   
   /**
    * 处理其他用户的移动事件（增量同步）
    */
   private fun handleOtherClientMoved(clientId: Int, targetChannelId: Long) {
       val existingClient = repository.getClientById(clientId)
       
       if (existingClient != null) {
           // 成员存在：更新频道位置
           repository.updateClientChannel(clientId, targetChannelId)
       } else {
           // 成员不存在：触发补偿同步
           Log.w(TAG, "Unknown client $clientId, triggering compensation sync")
           viewModelScope.launch { compensateClientList() }
       }
   }
   ```

2. **切换超时处理**
   ```kotlin
   // ChannelViewModel.kt
   
   /**
    * 重试频道切换（失败后）
    */
   fun retryChannelSwitch() {
       val channel = _pendingSwitchChannel.value ?: return
       _switchState.value = ChannelSwitchState.Idle
       
       viewModelScope.launch {
           performChannelSwitch(channel.id, "")
       }
   }
   
   /**
    * 取消频道切换
    */
   fun cancelChannelSwitch() {
       switchTimeoutJob?.cancel()
       _switchState.value = ChannelSwitchState.Idle
       _pendingSwitchChannel.value = null
       _showPasswordDialog.value = false
   }
   ```

### 6.5 切换状态 UI 反馈

**目标**：在频道列表页显示切换状态，提供用户反馈。

**任务**：

1. **切换中指示器**
   ```kotlin
   // ui/components/SwitchingIndicator.kt
   
   @Composable
   fun ChannelSwitchingIndicator(
       state: ChannelSwitchState,
       onRetry: () -> Unit,
       onCancel: () -> Unit
   ) {
       when (state) {
           is ChannelSwitchState.Requesting -> {
               LinearProgressIndicator(
                   modifier = Modifier.fillMaxWidth()
               )
           }
           is ChannelSwitchState.WaitingServerEvent -> {
               LinearProgressIndicator(
                   modifier = Modifier.fillMaxWidth()
               )
           }
           is ChannelSwitchState.Failed -> {
               Snackbar(
                   action = {
                       TextButton(onClick = onRetry) {
                           Text("重试")
                       }
                       TextButton(onClick = onCancel) {
                           Text("取消")
                       }
                   }
               ) {
                   Text(state.error)
               }
           }
           else -> { /* Idle: 不显示任何指示 */ }
       }
   }
   ```

2. **在 ChannelListScreen 中集成**
   ```kotlin
   // ChannelListScreen.kt
   
   @Composable
   fun ChannelListScreen(
       // ... 参数 ...
   ) {
       val switchState by channelViewModel.switchState.collectAsState()
       
       Column(modifier = Modifier.fillMaxSize()) {
           // 头部
           ChannelListHeader(/* ... */)
           
           // 切换状态指示器
           if (switchState != ChannelSwitchState.Idle) {
               ChannelSwitchingIndicator(
                   state = switchState,
                   onRetry = { channelViewModel.retryChannelSwitch() },
                   onCancel = { channelViewModel.cancelChannelSwitch() }
               )
           }
           
           // 中部：频道树
           Box(modifier = Modifier.weight(1f)) {
               // ... 已有实现 ...
           }
           
           // ... 其余布局 ...
       }
   }
   ```

### 6.6 事件处理器注册

**目标**：确保 ChannelViewModel 的事件处理方法被 ServerViewModel 正确调用。

**任务**：

```kotlin
// ServerViewModel.kt - 在 registerEventHandlers 中添加

fun registerEventHandlers() {
    TSBridge.setCallbacks(object : TSBridge.Callbacks {
        // ... 已有回调 ...
        
        override fun onClientMoved(id: Int, targetChannelID: String) {
            val targetId = targetChannelID.toLongOrNull() ?: return
            channelViewModel.handleClientMoved(id, targetId)
        }
        
        // ... 其他回调 ...
    })
}
```

---

## 三、状态与数据流

### 3.1 频道切换状态机

```
                    ┌──────────────────────────────────────┐
                    │                                      │
                    ▼                                      │
               ┌─────────┐                                │
               │  Idle    │◄───────────────────────────────┤
               └────┬────┘                                │
                    │ 用户点击频道                          │
                    ▼                                      │
               ┌─────────────┐                            │
               │  Requesting │                            │
               └──────┬──────┘                            │
                      │                                   │
          ┌───────────┴───────────┐                       │
          │                       │                       │
          ▼                       ▼                       │
    ┌───────────┐          ┌──────────┐                   │
    │  Failed   │          │ Waiting  │                   │
    │           │          │ Server   │                   │
    └─────┬─────┘          │ Event    │                   │
          │                └────┬─────┘                   │
          │                     │                         │
          │   ┌─────────────────┤                         │
          │   │                 │                         │
          │   ▼                 ▼                         │
          │  超时          OnClientMoved                  │
          │   │           (selfID match)                  │
          │   │                 │                         │
          └───┴─────────────────┴─────────────────────────┘
```

### 3.2 数据流向

```
用户操作           ChannelViewModel              TSBridge/Go          服务端
    │                    │                           │                  │
    │ 点击频道           │                           │                  │
    ├───────────────────→│                           │                  │
    │                    │                           │                  │
    │                    │ 有密码？                   │                  │
    │                    ├─→ 显示密码弹窗             │                  │
    │ 输入密码           │                           │                  │
    ├───────────────────→│                           │                  │
    │                    │                           │                  │
    │                    │ MoveToChannel(id, pwd)    │                  │
    │                    ├──────────────────────────→│  clientmove      │
    │                    │                           ├─────────────────→│
    │                    │                           │                  │
    │                    │                           │  命令响应         │
    │                    │                           │←─────────────────┤
    │                    │  error == "" ?             │                  │
    │                    │←──────────────────────────┤                  │
    │                    │                           │                  │
    │                    │ 状态 → WaitingServerEvent  │                  │
    │                    │                           │                  │
    │                    │                           │  notifyclientmoved│
    │                    │                           │←─────────────────┤
    │                    │  OnClientMoved(selfID)    │                  │
    │                    │←──────────────────────────┤                  │
    │                    │                           │                  │
    │                    │ 更新自身频道               │                  │
    │                    │ 状态 → Idle               │                  │
    │                    │                           │                  │
```

### 3.3 命令响应与事件事实的区分

**关键原则**（对应 `docs/流程/03_切换频道.md`）：

| 概念 | 含义 | 处理方式 |
|------|------|----------|
| ClientMove 返回 error | 命令被服务器拒绝 | 立即显示错误，状态 → Failed |
| ClientMove 返回 nil | 命令被服务器接受 | 状态 → WaitingServerEvent，继续等待 |
| OnClientMoved(selfID) | 服务器确认移动完成 | 更新本地频道事实，状态 → Idle |

**为什么不能用命令响应直接更新频道？**

- 命令响应只表示服务器接受了请求
- 实际移动可能因权限、密码、容量等原因被延迟拒绝
- 只有服务端推送的 `notifyclientmoved` 事件才是最终事实

---

## 四、验收标准

### 功能验收

- [ ] **无密码频道切换**
  - 点击无密码频道 → 直接发送 ClientMove
  - 显示切换中进度指示
  - 收到 OnClientMoved 后切换完成
  - 当前频道栏更新为目标频道

- [ ] **有密码频道切换**
  - 点击有密码频道 → 弹出密码输入框
  - 输入密码后发送 ClientMove
  - 密码错误 → 显示错误提示，清空输入框，允许重试
  - 点击取消 → 关闭弹窗，不发送命令

- [ ] **切换状态管理**
  - 切换中禁止发起新的切换
  - 切换超时（10秒）显示失败提示
  - 失败后可重试或取消
  - 被管理员移动时正确更新状态

- [ ] **自身状态同步**
  - 只有匹配 selfID 的 OnClientMoved 才更新自身频道
  - 命令响应不直接提交频道事实
  - 切换完成后清除目标频道的未读标记

### 错误处理验收

| 错误场景 | 预期行为 |
|----------|----------|
| 密码错误 | 弹窗显示错误，清空输入框 |
| 频道已满 | Snackbar 提示"频道已满" |
| 权限不足 | Snackbar 提示"权限不足" |
| 网络超时 | 10秒后显示超时提示，可重试 |
| 被管理员移动 | 静默更新当前频道 |

### 性能验收

- [ ] 切换响应时间 < 100ms（UI 反馈）
- [ ] 服务端确认时间 < 3s（正常网络）
- [ ] 密码弹窗弹出/关闭动画流畅

### 测试用例

| 场景 | 操作 | 预期结果 |
|------|------|----------|
| 无密码切换 | 点击无密码频道 | 进度条 → 切换完成 → 当前频道更新 |
| 有密码切换 | 点击有密码频道 → 输入密码 → 点击进入 | 密码弹窗 → 进度条 → 切换完成 |
| 密码错误 | 输入错误密码 | 弹窗显示错误，清空输入框 |
| 取消密码 | 点击取消 | 弹窗关闭，无网络请求 |
| 切换超时 | 断网后切换 | 10秒后显示超时提示 |
| 重试切换 | 失败后点击重试 | 重新发送 ClientMove |
| 被管理员移动 | 管理员移动你到其他频道 | 当前频道静默更新 |
| 重复点击 | 快速点击多个频道 | 只处理第一次点击 |
| 切换中点击 | 切换进行中点击其他频道 | 忽略点击 |

---

## 五、参考文档

- `docs/流程/03_切换频道.md` - 时序图、状态机、事件依赖
- `docs/流程/08_状态同步.md` - ④ 自身状态同步
- `docs/UI架构设计.md` - 2.2 频道列表页交互、4.2 密码弹窗
- `docs/sdk文档-go.md` - ClientMove API、OnClientMoved 事件
- `docs/implementation/02_Bridge层实现.md` - MoveToChannel、onClientMoved 回调
- `docs/implementation/05_频道列表页.md` - ChannelViewModel、ChannelListScreen