432 lines
18 KiB
Markdown
432 lines
18 KiB
Markdown
# 状态控制设计
|
||
|
||
## 1. 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ Go Bridge (TSBridge) │
|
||
│ onConnected / onDisconnected / onTextMessage / onClientEnter │
|
||
│ onClientLeave / onClientMoved / onKicked / onVoiceData / onPoked│
|
||
└──────────────────────────────┬──────────────────────────────────┘
|
||
│ JNI 回调
|
||
▼
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ ServerViewModel (协调者) │
|
||
│ connectionState / serverInfo / kickReason / pokeNotification │
|
||
│ 拥有其他 ViewModel 引用，分发事件 │
|
||
└──────┬────────────┬────────────┬────────────┬────────────────────┘
|
||
│ │ │ │
|
||
▼ ▼ ▼ ▼
|
||
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
|
||
│ ChannelVM │ │ ChatVM │ │ VoiceVM │ │ Repository│
|
||
│ 频道列表 │ │ 文字聊天 │ │ 语音通信 │ │ (单例) │
|
||
│ 频道切换 │ │ 消息归档 │ │ PTT控制 │ │ 数据仓库 │
|
||
│ 未读状态 │ │ 送达确认 │ │ 说话检测 │ │ │
|
||
└───────────┘ └───────────┘ └───────────┘ └───────────┘
|
||
│ │ │ │
|
||
▼ ▼ ▼ ▼
|
||
┌──────────────────────────────────────────────────────────────────┐
|
||
│ Compose UI (StateFlow collectAsState) │
|
||
│ NavGraph → ChannelListScreen / ChatScreen / KickedScreen │
|
||
└──────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 2. Repository（单例数据仓库）
|
||
|
||
所有 ViewModel 共享的底层数据源。ViewModel 读取 Repository 的 StateFlow，事件处理通过 Repository 方法更新。
|
||
|
||
```
|
||
Repository (object)
|
||
├── channels: StateFlow<List<ChannelInfo>> // 频道列表（低频，按需请求）
|
||
├── clients: StateFlow<List<ClientInfo>> // 客户端列表（高频，人员变动全量刷新）
|
||
├── channelClients: StateFlow<Map<String, List<ClientInfo>>> // 按频道索引（由 clients 派生）
|
||
├── selfClientId: StateFlow<Int> // 自身客户端 ID
|
||
├── currentChannelId: StateFlow<String> // 当前频道 ID
|
||
├── serverInfo: StateFlow<ServerInfo?> // 服务器信息
|
||
├── unreadCounts: StateFlow<Map<String, Int>> // 未读消息计数
|
||
├── activeChatKey: String? // 当前查看的会话
|
||
└── messageArchives: ConcurrentHashMap // 消息归档
|
||
```
|
||
|
||
**数据更新频率设计原则**：
|
||
|
||
| 数据 | 变动频率 | SDK 事件支持 | 更新策略 |
|
||
|------|---------|-------------|---------|
|
||
| 频道列表 | 极低频 | 无事件 | 连接时全量请求一次，之后按需刷新（超5分钟过期检测） |
|
||
| 客户端列表 | 高频 | Enter/Leave/Move | 每次事件全量刷新 `refreshClientList()` |
|
||
| 频道树 | — | — | 不维护中间状态，UI 层直接从 channels + clients 实时计算 |
|
||
|
||
**关键方法**：
|
||
- `performInitialSync()` — 首次同步（串行请求频道列表、客户端列表、自身 ID）
|
||
- `refreshClientList()` — 全量刷新客户端列表（人员变动时调用，高频）
|
||
- `updateBaseline()` — 原子提交基线数据
|
||
- `clearSession()` — 清理会话（断开连接时调用）
|
||
- `archiveMessage()` — 归档消息
|
||
- `confirmMessageDelivery()` — 匹配回显确认送达
|
||
|
||
## 3. ViewModel 状态明细
|
||
|
||
### 3.1 ServerViewModel — 连接与事件协调
|
||
|
||
**职责**：管理连接生命周期、接收 Go Bridge 回调并分发给其他 ViewModel。
|
||
|
||
```
|
||
ServerViewModel
|
||
├── state: StateFlow<ServerScreenState>
|
||
│ ├── address / nickname / password // 输入字段
|
||
│ ├── connectState: ConnectState // 连接按钮状态
|
||
│ │ ├── IDLE 空闲，等待用户输入
|
||
│ │ ├── CONNECTING 连接中
|
||
│ │ ├── SUCCESS 连接成功（触发导航）
|
||
│ │ ├── FAILED 连接失败
|
||
│ │ └── TIMEOUT 连接超时
|
||
│ └── errorMessage / validationErrors
|
||
│
|
||
├── connectionState: StateFlow<ConnectionState?>
|
||
│ ├── null 未进入频道列表页
|
||
│ ├── Connected 已连接
|
||
│ ├── Disconnecting 断开中
|
||
│ ├── Reconnecting 重连中（attempt, reason）
|
||
│ └── Disconnected 已断开（reason, wasKicked）
|
||
│
|
||
├── serverInfo: StateFlow<ServerInfo?>
|
||
├── kickReason: StateFlow<String>
|
||
├── pokeNotification / showPokeNotification
|
||
├── themeMode: StateFlow<ThemeMode>
|
||
└── recents: StateFlow<List<RecentConnection>>
|
||
```
|
||
|
||
**Bridge 回调分发**：
|
||
|
||
| 回调 | 分发目标 |
|
||
|------|---------|
|
||
| `onConnected` | `channelViewModel.performInitialSync()` → 导航到频道列表 |
|
||
| `onDisconnected` | `Repository.clearSession()` + `channelViewModel.clearChannels()` + `chatViewModel.clearMessages()` |
|
||
| `onTextMessage` | `chatViewModel.handleTextMessage()` + `channelViewModel.onTextMessage()` |
|
||
| `onClientEnter` | `channelViewModel.handleClientEnter()` |
|
||
| `onClientLeave` | `channelViewModel.handleClientLeave()` |
|
||
| `onClientMoved` | `channelViewModel.handleClientMoved()` |
|
||
| `onKicked` | `Repository.clearSession()` + 所有 ViewModel 清理 → 导航到 KickedScreen |
|
||
| `onVoiceData` | `voiceViewModel.handleVoiceData()` |
|
||
| `onPoked` | `serverViewModel.handlePoked()` |
|
||
|
||
**ViewModel 引用**（由 NavGraph LaunchedEffect 设置）：
|
||
```
|
||
serverViewModel.channelViewModel = channelViewModel
|
||
serverViewModel.chatViewModel = chatViewModel
|
||
serverViewModel.voiceViewModel = voiceViewModel
|
||
```
|
||
|
||
### 3.2 ChannelViewModel — 频道列表与切换
|
||
|
||
**职责**：管理同步状态、频道切换状态机、展开状态、未读指示。频道树不在 ViewModel 中维护，由 UI 层实时计算。
|
||
|
||
```
|
||
ChannelViewModel
|
||
├── syncState: StateFlow<SyncState>
|
||
│ ├── Unsynced 已连接但尚无完整数据（初始状态）
|
||
│ ├── Syncing 正在调用 ListChannels / ListClients
|
||
│ ├── Synchronized 列表基线可供 UI 使用
|
||
│ └── SyncFailed 同步失败
|
||
│
|
||
├── channels: StateFlow<List<ChannelInfo>> // Repository 引用（低频）
|
||
├── clients: StateFlow<List<ClientInfo>> // Repository 引用（高频）
|
||
├── channelClients: StateFlow<Map<String, List<ClientInfo>>> // Repository 引用
|
||
├── selfClientId: StateFlow<Int> // Repository 引用
|
||
├── currentChannelId: StateFlow<String> // Repository 引用
|
||
│
|
||
├── expandedChannelIds: StateFlow<Set<String>> // 本地状态（初始同步时自动展开有成员的频道）
|
||
├── hasUnreadMessage: StateFlow<Boolean> // 本地状态（当前频道外有新消息）
|
||
│
|
||
├── switchState: StateFlow<ChannelSwitchState>
|
||
│ ├── Idle 空闲
|
||
│ ├── Requesting 正在发送 ClientMove
|
||
│ ├── WaitingServerEvent 等待 OnClientMoved 确认
|
||
│ └── Failed 切换失败
|
||
│
|
||
├── showPasswordDialog / pendingSwitchChannel
|
||
└── channelDetailInfo / showChannelDetailCard
|
||
```
|
||
|
||
**频道树构建（UI 层）**：
|
||
UI 直接从源 StateFlow 实时计算，不维护中间状态：
|
||
```kotlin
|
||
// ChannelListScreen
|
||
val tree = remember(channels, clients, expandedChannelIds) {
|
||
channelViewModel.buildChannelTree(channels, clients, expandedChannelIds, unreadStates)
|
||
}
|
||
```
|
||
|
||
**频道数据更新策略**：
|
||
- 频道列表是静态数据，SDK 不提供频道增删改事件
|
||
- 连接时全量请求一次（`performInitialSync`），之后按需刷新（超5分钟过期检测）
|
||
- 人员变动事件（Enter/Leave/Move）只刷新客户端列表，不碰频道列表
|
||
- 如果管理员创建/删除了频道，用户下次切换频道时自动检测过期并刷新
|
||
|
||
**频道切换状态机**：
|
||
```
|
||
用户点击频道
|
||
│
|
||
▼
|
||
Idle ──→ Requesting ──→ WaitingServerEvent ──→ Idle
|
||
│ │ │
|
||
│ ▼ ▼
|
||
│ Failed 超时 → Failed
|
||
│ │
|
||
└───────────┘
|
||
用户重试/取消
|
||
```
|
||
|
||
**事件处理**：
|
||
|
||
| 事件 | 处理 |
|
||
|------|------|
|
||
| `handleClientEnter()` | `Repository.refreshClientList()` 全量刷新（高频） |
|
||
| `handleClientLeave()` | `Repository.refreshClientList()` 全量刷新（高频） |
|
||
| `handleClientMoved()` | 区分自己/他人，全量刷新 + 更新 currentChannelId（高频） |
|
||
| `onTextMessage()` | 设置 hasUnreadMessage 标记（仅当 targetId != currentChannelId） |
|
||
|
||
### 3.3 ChatViewModel — 文字聊天
|
||
|
||
**职责**：管理消息列表、发送状态、送达确认。
|
||
|
||
```
|
||
ChatViewModel
|
||
├── messages: StateFlow<List<ChatMessage>> // 当前会话消息
|
||
├── sendState: StateFlow<MessageSendState>
|
||
│ ├── Idle 空闲
|
||
│ ├── Sending 发送中
|
||
│ └── Failed 发送失败
|
||
│
|
||
├── currentTargetMode: Int // 1=私聊, 2=频道, 3=服务器
|
||
├── currentTargetId: Long // 目标 ID
|
||
└── deliveryTimeoutJob // 送达确认超时
|
||
```
|
||
|
||
**消息生命周期**：
|
||
```
|
||
用户输入
|
||
│
|
||
▼
|
||
sendMessage()
|
||
│
|
||
├── 1. 创建 PENDING 消息 → Repository.archiveMessage()
|
||
├── 2. TSBridge.sendTextMessage()
|
||
│ ├── 成功 → 等待回显（10秒超时）
|
||
│ └── 失败 → 标记 FAILED
|
||
│
|
||
▼
|
||
收到 OnTextMessage 回显
|
||
│
|
||
├── Repository.confirmMessageDelivery() 匹配 PENDING
|
||
│ ├── 匹配 → 标记 SENT（送达确认）
|
||
│ └── 不匹配 → 正常归档（他人消息）
|
||
│
|
||
▼
|
||
超时未确认 → 标记 FAILED
|
||
```
|
||
|
||
**会话管理**：
|
||
- `enterChat()` — 设置 activeChatKey，加载消息，清除未读
|
||
- `leaveChat()` — 清除 activeChatKey，重置发送状态
|
||
- `clearMessages()` — 清空消息列表（断开连接时）
|
||
|
||
### 3.4 VoiceViewModel — 语音通信
|
||
|
||
**职责**：管理 PTT、静音、语音状态、说话检测。
|
||
|
||
```
|
||
VoiceViewModel
|
||
├── voiceState: StateFlow<VoiceState>
|
||
│ ├── Idle 空闲（可 PTT）
|
||
│ ├── Transmitting 发送中（PTT 按下）
|
||
│ └── Blocked 受阻（原因：未连接/未入频道/权限/断开）
|
||
│
|
||
├── isMuted: StateFlow<Boolean> // 默认 true
|
||
├── isTransmitting: StateFlow<Boolean>
|
||
├── speakerEnabled: StateFlow<Boolean>
|
||
├── denoiseEnabled: StateFlow<Boolean>
|
||
├── showVoiceCard: StateFlow<Boolean>
|
||
├── outputDevice: StateFlow<VoiceOutputDevice>
|
||
├── inputVolume / outputVolume: StateFlow<Float>
|
||
├── isSelfSpeaking: StateFlow<Boolean>
|
||
└── speakingClients: StateFlow<Map<Int, Long>>
|
||
```
|
||
|
||
**PTT 状态机**：
|
||
```
|
||
Idle ──→ startTransmit() ──→ Transmitting ──→ stopTransmit() ──→ Idle
|
||
│ │
|
||
│ 前置检查失败 │ 异常
|
||
▼ ▼
|
||
Blocked ←──────────────────────────┘
|
||
│
|
||
└── clearBlocked() ──→ Idle
|
||
```
|
||
|
||
## 4. 状态生命周期
|
||
|
||
### 4.1 连接建立
|
||
|
||
```
|
||
用户点击连接
|
||
│
|
||
▼
|
||
ServerViewModel.connect()
|
||
│ connectState = CONNECTING
|
||
▼
|
||
TSBridge.connect() (IO 线程)
|
||
│
|
||
▼
|
||
onConnected 回调
|
||
│
|
||
├── Repository 记录连接
|
||
├── ChannelVM.performInitialSync()
|
||
│ ├── syncState = Syncing
|
||
│ ├── Repository.performInitialSync() (串行请求)
|
||
│ ├── syncState = Synchronized
|
||
│ └── autoExpandChannelsWithClients()
|
||
│
|
||
├── ConnectionService.start() (前台服务保活)
|
||
├── connectState = SUCCESS
|
||
└── connectionState = Connected
|
||
│
|
||
▼
|
||
NavGraph 导航到 CHANNEL_LIST
|
||
```
|
||
|
||
### 4.2 正常断开
|
||
|
||
```
|
||
用户点击断开
|
||
│
|
||
▼
|
||
ServerViewModel.disconnect()
|
||
│
|
||
├── ConnectionService.stop()
|
||
├── reconnectJob?.cancel()
|
||
├── connectionState = Disconnecting
|
||
├── voiceViewModel.stopVoice()
|
||
├── TSBridge.disconnect()
|
||
│
|
||
├── Repository.clearSession()
|
||
│ ├── channels/clients = empty
|
||
│ ├── selfClientId = 0
|
||
│ ├── currentChannelId = "0"
|
||
│ ├── channelClients = empty
|
||
│ └── messageArchives.clear()
|
||
│
|
||
├── channelViewModel.clearChannels()
|
||
│ ├── syncState = Unsynced
|
||
│ ├── expandedChannelIds = empty
|
||
│ ├── unreadStates = empty
|
||
│ └── switchState = Idle
|
||
│
|
||
├── chatViewModel.clearMessages()
|
||
│ ├── messages = empty
|
||
│ └── sendState = Idle
|
||
│
|
||
├── connectionState = null
|
||
└── connectState = IDLE
|
||
│
|
||
▼
|
||
NavGraph 导航到 SERVER_CONFIG
|
||
```
|
||
|
||
### 4.3 被踢出
|
||
|
||
```
|
||
onKicked 回调
|
||
│
|
||
├── ConnectionService.stop()
|
||
├── reconnectJob?.cancel()
|
||
├── voiceViewModel.stopVoice()
|
||
├── Repository.clearSession()
|
||
├── channelViewModel.clearChannels()
|
||
│
|
||
├── kickReason = reason
|
||
└── connectionState = Disconnected(wasKicked=true)
|
||
│
|
||
▼
|
||
NavGraph 导航到 KICKED
|
||
```
|
||
|
||
### 4.4 网络断开（自动重连已禁用）
|
||
|
||
```
|
||
onDisconnected 回调
|
||
│
|
||
├── 检查 connectionState
|
||
│ ├── Disconnecting → 忽略（主动断开）
|
||
│ └── 其他 → 继续
|
||
│
|
||
├── voiceViewModel.onDisconnected()
|
||
│ └── voiceState = Blocked("连接已断开")
|
||
│
|
||
├── ConnectionService.stop()
|
||
├── Repository.clearSession()
|
||
├── channelViewModel.clearChannels()
|
||
│
|
||
└── connectionState = Disconnected(wasKicked=false)
|
||
│
|
||
▼
|
||
NavGraph 导航到 SERVER_CONFIG
|
||
```
|
||
|
||
## 5. 状态流向图
|
||
|
||
```
|
||
┌──────────────────────────────┐
|
||
│ Repository │
|
||
│ channels (低频) / clients (高频) │
|
||
└──────┬───────────────────────┘
|
||
│ StateFlow（只读引用）
|
||
┌────────────┼────────────────┐
|
||
▼ ▼ ▼
|
||
┌────────────┐ ┌──────────┐ ┌──────────┐
|
||
│ ChannelVM │ │ ChatVM │ │ VoiceVM │
|
||
│ 同步状态 │ │ 消息管理 │ │ 语音控制 │
|
||
│ 切换状态机 │ │ 送达确认 │ │ PTT │
|
||
│ 展开/未读 │ │ │ │ │
|
||
└─────┬──────┘ └────┬─────┘ └────┬─────┘
|
||
│ StateFlow │ StateFlow │ StateFlow
|
||
▼ ▼ ▼
|
||
┌─────────────────────────────────────────┐
|
||
│ Compose UI Layer │
|
||
│ collectAsState() → remember 派生计算 │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
**数据流规则**：
|
||
1. **Repository** 持有底层数据。`channels` 低频更新（连接时请求），`clients` 高频更新（每次人员变动全量刷新）
|
||
2. **ViewModel** 读取 Repository 的 StateFlow 引用，仅管理本地 UI 状态（expandedChannelIds、hasUnreadMessage、switchState 等）
|
||
3. **UI** 通过 `collectAsState()` 订阅 StateFlow，使用 `remember` 实时派生计算（频道树）。不维护中间 combine 状态
|
||
4. **事件** 从 ServerViewModel（Bridge 回调）→ ViewModel 方法 → Repository 更新 → StateFlow 自动通知 UI
|
||
|
||
## 6. 导航状态控制
|
||
|
||
NavGraph 监听 `connectionState` 变化，自动处理导航：
|
||
|
||
```
|
||
connectionState 变化
|
||
│
|
||
├── Disconnected(wasKicked=true) → navigate(KICKED)
|
||
├── Disconnected(wasKicked=false) → navigate(SERVER_CONFIG)
|
||
├── Connected (当前在 KICKED) → navigate(CHANNEL_LIST)
|
||
└── 其他 → 不处理
|
||
```
|
||
|
||
**页面与 ViewModel 生命周期**：
|
||
- ViewModel 作用域绑定到 NavBackStackEntry
|
||
- 从 CHANNEL_LIST 导航到 CHAT 时，ChannelVM 不销毁（在返回栈中）
|
||
- 从 CHAT 返回 CHANNEL_LIST 时，ChannelVM 状态保持
|
||
- 如果系统回收 ViewModel（内存不足），`LaunchedEffect` 检测 `syncState != Synchronized` 并重新触发同步
|
||
|
||
## 7. 已知状态问题与防护
|
||
|
||
| 问题 | 防护措施 |
|
||
|------|---------|
|
||
| ViewModel 被系统回收后 syncState 回到 Unsynced | ChannelListScreen 的 `LaunchedEffect` 自动重新同步 |
|
||
| 详情按钮快速连点 | ViewModel 层 500ms 防抖 |
|
||
| `leaveChat()` 被调用多次（Compose 重组） | `leaveChat()` 本身是幂等操作，无副作用 |
|