132 lines
5.6 KiB
Markdown
132 lines
5.6 KiB
Markdown
|
# 浏览频道与成员
|
||
|
|
|
||
|
|
> 用户流程：分配到默认频道 → 浏览频道列表 → 浏览频道中的人员分布 → poke 服务器内成员
|
||
|
|
> 对应程序流程：TsClient.getChannelList() 建立频道基线 → TsClient.getClientList() 建立成员基线 → 持续接收 onClient* 事件增量更新
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 一、状态树
|
||
|
|
|
||
|
|
### 同步状态
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
flowchart TD
|
||
|
|
SYNC[同步状态<br/>建立服务器数据基线]
|
||
|
|
|
||
|
|
SYNC --> S0[未同步 Unsynced<br/>已连接但尚无完整数据]
|
||
|
|
SYNC --> S1[同步中 Syncing<br/>调用 getChannelList 和 getClientList]
|
||
|
|
SYNC --> S2[已同步 Synchronized<br/>列表基线可供 UI 使用]
|
||
|
|
SYNC --> S3[同步失败 SyncFailed<br/>列表请求失败或上下文失效]
|
||
|
|
```
|
||
|
|
|
||
|
|
### 成员状态
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
flowchart TD
|
||
|
|
MEMBER[成员状态<br/>维护在线用户及频道位置]
|
||
|
|
|
||
|
|
MEMBER --> M0[空基线 Empty<br/>尚未执行 ListClients]
|
||
|
|
MEMBER --> M1[已有基线 Loaded<br/>getClientList 已建立成员表]
|
||
|
|
MEMBER --> M2[增量更新 Updating<br/>OnClientEnter/Leave/Moved 正在归并]
|
||
|
|
MEMBER --> M3[不一致 Inconsistent<br/>事件引用未知成员或频道]
|
||
|
|
```
|
||
|
|
|
||
|
|
### 成员实体状态树
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
flowchart TD
|
||
|
|
ENTITY[成员实体状态树<br/>描述 ListClients 基线与实时事件如何协同]
|
||
|
|
|
||
|
|
ENTITY --> BASE[基线分支<br/>由客户端请求建立完整成员集合]
|
||
|
|
ENTITY --> DELTA[增量分支<br/>由服务端推送维护实时变化]
|
||
|
|
ENTITY --> SELF[当前用户分支<br/>通过 ClientID 识别自己的事件]
|
||
|
|
ENTITY --> REPAIR[修复分支<br/>处理事件缺失或引用不一致]
|
||
|
|
|
||
|
|
BASE --> B1[getClientList 请求<br/>获取服务器当前全部在线客户端]
|
||
|
|
B1 --> B2[按 clientID 建表<br/>使用客户端 ID 去重保存]
|
||
|
|
B2 --> B3[按 channelID 建索引<br/>派生每个频道的成员列表]
|
||
|
|
|
||
|
|
DELTA --> D1[onClientEnter<br/>新增或覆盖进入视野的成员]
|
||
|
|
DELTA --> D2[onClientMoved<br/>覆盖成员的 channelID]
|
||
|
|
DELTA --> D3[onClientLeave<br/>按 clientID 幂等删除成员]
|
||
|
|
|
||
|
|
SELF --> S1[getClientId 本地调用<br/>读取服务器分配的自身 ID]
|
||
|
|
S1 --> S2[事件 clientID 比对<br/>判断移动或离开事件是否属于自己]
|
||
|
|
S2 --> S3[更新自身频道事实<br/>自己的移动决定实际所在频道]
|
||
|
|
|
||
|
|
REPAIR --> R1[检测未知 clientID<br/>移动或离开事件找不到实体]
|
||
|
|
R1 --> R2[重新调用 getClientList<br/>用完整列表修复成员基线]
|
||
|
|
REPAIR --> R3[检测未知 channelID<br/>成员引用本地不存在的频道]
|
||
|
|
R3 --> R4[重新调用 getChannelList<br/>用完整列表修复频道基线]
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 二、时序：成员进入、移动与离开
|
||
|
|
|
||
|
|
```mermaid
|
||
|
|
sequenceDiagram
|
||
|
|
participant TS as TeamSpeak 服务器<br/>产生在线成员变化
|
||
|
|
participant SDK as Go SDK (gomobile)<br/>解析 notify* 通知
|
||
|
|
participant BRIDGE as TSBridge<br/>JNI 回调转 EventBus
|
||
|
|
participant EB as EventBus<br/>事件合并与分发
|
||
|
|
participant REDUCER as ViewModel<br/>debounce 后刷新成员
|
||
|
|
participant STORE as 成员实体仓库<br/>以 clientID 保存唯一成员
|
||
|
|
participant UI as 频道树 UI<br/>派生人数和成员预览
|
||
|
|
|
||
|
|
TS-->>SDK: notifycliententerview
|
||
|
|
SDK->>BRIDGE: OnClientEnter(Client)
|
||
|
|
BRIDGE->>EB: emit(ClientEnter)
|
||
|
|
|
||
|
|
TS-->>SDK: notifyclientmoved
|
||
|
|
SDK->>BRIDGE: OnClientMoved(id, channelID)
|
||
|
|
BRIDGE->>EB: emit(ClientMoved)
|
||
|
|
|
||
|
|
TS-->>SDK: notifyclientleftview
|
||
|
|
SDK->>BRIDGE: OnClientLeave(id, reason)
|
||
|
|
BRIDGE->>EB: emit(ClientLeave)
|
||
|
|
|
||
|
|
Note over EB: debounce 300ms 合并
|
||
|
|
|
||
|
|
EB->>REDUCER: collect → refreshClientList()
|
||
|
|
REDUCER->>STORE: TSBridge.getClientsJSON() → 全量刷新
|
||
|
|
STORE-->>UI: 实体引用变化
|
||
|
|
```
|
||
|
|
|
||
|
|
---
|
||
|
|
|
||
|
|
## 三、事件依赖
|
||
|
|
|
||
|
|
### 成员相关前置依赖矩阵
|
||
|
|
|
||
|
|
| 操作或事件 | 必须依赖 | 建议依赖 | 依赖失败时的处理 |
|
||
|
|
| --- | --- | --- | --- |
|
||
|
|
| `getClientsJSON` 增量归并 | 已有频道基线更易校验 | 与 `getChannelsJSON` 同一同步批次 | 未知频道触发频道补偿读取 |
|
||
|
|
| `ClientEnter` 事件 | 已注册 EventBus 事件收集 | 已有成员基线 | debounce 后全量刷新 |
|
||
|
|
| `ClientMoved` 事件 | 已注册 EventBus 事件收集 | 已有成员基线和自身 ID | debounce 后全量刷新 |
|
||
|
|
| `ClientLeave` 事件 | 已注册 EventBus 事件收集 | 已有成员基线 | debounce 后全量刷新 |
|
||
|
|
|
||
|
|
### 服务端通知映射
|
||
|
|
|
||
|
|
| 服务端通知 | TSBridge 回调 → EventBus 事件 | 上层状态依赖 | 中文说明 |
|
||
|
|
| --- | --- | --- | --- |
|
||
|
|
| `notifycliententerview` | `OnClientEnter` → `ClientEnter` | 成员实体表、频道成员 Selector | 新成员进入视野后 debounce 合并刷新 |
|
||
|
|
| `notifyclientleftview` | `OnClientLeave` → `ClientLeave` | 成员实体表、离开原因 | debounce 合并刷新 |
|
||
|
|
| `notifyclientmoved` | `OnClientMoved` → `ClientMoved` | 成员位置、当前用户频道 | debounce 合并刷新 |
|
||
|
|
| `notifyclientpoke` | `OnPoked` → `Poked` | Poke 通知或成员卡 | 立即分发，展示发送者和 Poke 内容 |
|
||
|
|
|
||
|
|
### 缺失事件能力带来的依赖限制
|
||
|
|
|
||
|
|
根据 SDK 文档，当前公开事件不包含频道创建、频道更新和频道删除。因此：
|
||
|
|
|
||
|
|
1. `TsClient.getChannelList()` 是频道目录的主要权威来源。
|
||
|
|
2. 不能假设频道列表会依靠 `onClient*` 事件永久保持最新。
|
||
|
|
3. 发现成员引用未知频道时，应重新调用 `TsClient.getChannelList()`。
|
||
|
|
4. 如果产品需要实时频道管理，应扩展 SDK 对相应 `notify*` 通知的支持。
|
||
|
|
|
||
|
|
### 权威性划分
|
||
|
|
|
||
|
|
| 数据 | 推荐权威来源 | 原因 |
|
||
|
|
| --- | --- | --- |
|
||
|
|
| 成员实时变化 | EventBus `ClientEnter/Leave/Moved` 事件 | 服务端主动推送实时事实，debounce 后全量刷新 |
|