453 lines
17 KiB
Markdown
453 lines
17 KiB
Markdown
# 流程文档总览
|
||
|
||
> 本文档按用户流程组织，将 SDK 技术行为拆分为七个主流程文件和一个独立的状态同步流程文件。
|
||
> 依据：`docs/sdk-bridge-api.md`
|
||
> SDK：`github.com/honeybbq/teamspeak-go` → gomobile AAR → `TSBridge.kt` 应用层桥接
|
||
|
||
---
|
||
|
||
## 一、完整用户流程
|
||
|
||
```
|
||
进入应用
|
||
│
|
||
├─ 已有最近服务器？ ──是──→ 显示最近服务器列表 ──→ 选择服务器
|
||
│ │
|
||
└─ 否 ──→ 输入服务器地址 ──→ 输入昵称 ──→ 输入密码（可选） ──→┘
|
||
│
|
||
点击"进入服务器"
|
||
│
|
||
┌─────────────────────┘
|
||
▼
|
||
连接中（显示进度）
|
||
│
|
||
┌───────────────┼───────────────┐
|
||
▼ ▼ ▼
|
||
连接成功 连接失败 超时
|
||
│ │ │
|
||
│ 显示错误原因 显示超时提示
|
||
│ 允许重试 允许重试
|
||
│ │ │
|
||
│ └───────→ 返回输入页面
|
||
▼
|
||
分配到默认频道（首次同步 ①）
|
||
│
|
||
▼
|
||
浏览频道列表 ──→ 浏览频道中的人员分布
|
||
│ │
|
||
│ poke 服务器内成员
|
||
│ │
|
||
▼ ▼
|
||
┌──→ 进入/切换频道 ←──────────┘
|
||
│ │ ← 自身状态同步 ④
|
||
│ │ ← 增量同步 ② / 补偿同步 ③
|
||
│ │
|
||
│ ├─ 频道有密码？ ──是──→ 输入密码
|
||
│ │
|
||
│ ├─ 收听语音 ──→ 发送语音（PTT）
|
||
│ │
|
||
│ ├─ 收到文本消息 ──→ 消息归档同步 ⑤ ──→ 发送文本消息
|
||
│ │
|
||
│ ├─ 浏览频道文件 ──→ 上传文件 ──→ 下载文件
|
||
│ │
|
||
│ ├─ poke 服务器内成员 ──→ 被 poke
|
||
│ │
|
||
│ ▼
|
||
│ 切换频道 / 留在当前频道
|
||
│ │
|
||
└────┘
|
||
│
|
||
▼
|
||
┌─── 离开原因 ───┐
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
主动断开 网络异常 被踢出
|
||
│ │ │
|
||
▼ ▼ ▼
|
||
发送 显示错误 显示被踢原因
|
||
disconnect 允许重连 允许重连
|
||
│ │ │
|
||
│ 重连后全量同步 ⑥
|
||
│ │ │
|
||
└────────┼─────────┘
|
||
▼
|
||
清理会话状态
|
||
│
|
||
▼
|
||
返回应用主页
|
||
```
|
||
|
||
> **① 首次同步** ② **增量同步** ③ **补偿同步** ④ **自身状态同步** ⑤ **消息归档同步** ⑥ **重连后全量同步**
|
||
> 详见 [08_状态同步.md](08_状态同步.md)
|
||
|
||
---
|
||
|
||
## 二、用户流程对应的程序流程概览
|
||
|
||
### 2.1 连接服务器
|
||
|
||
```
|
||
读取本地配置
|
||
│
|
||
检查输入是否合法
|
||
│
|
||
创建 Identity（首次生成，后续读取）
|
||
│
|
||
TSBridge.connect(host, nickname, password, defaultChannel, defaultChannelPassword, callbacks)
|
||
│
|
||
callbacks 内部注册 EventBus.emit()（将 JNI 回调转为 EventBus 事件）
|
||
│
|
||
TSClient.connect() → 建立 UDP 连接 → 身份认证 → 服务器密码验证
|
||
│
|
||
├── 失败 → 连接失败处理 → 显示错误
|
||
│
|
||
└── 成功 →
|
||
│
|
||
EventBus 收到 Connected 事件
|
||
│
|
||
开始同步服务器数据
|
||
│
|
||
├── 获取频道列表 TSBridge.getChannelsJSON()
|
||
├── 获取成员列表 TSBridge.getClientsJSON()
|
||
└── 获取自身 ID TSBridge.getClientID()
|
||
│
|
||
建立本地状态（频道基线 + 成员基线）
|
||
│
|
||
UI 切换到服务器页面
|
||
```
|
||
|
||
### 2.2 浏览频道与成员
|
||
|
||
```
|
||
已同步的频道列表 → 构建树形结构 → 渲染频道树
|
||
│
|
||
已同步的成员列表 → 按 channelID 索引 → 派生每个频道的成员列表
|
||
│
|
||
持续接收 EventBus 事件（debounce 合并后处理）：
|
||
├── ClientEnter → 新增成员到成员表
|
||
├── ClientMoved → 更新成员所在频道
|
||
├── ClientLeave → 从成员表移除
|
||
└── Poked → 显示 Poke 通知
|
||
│
|
||
未知 clientID → 触发 TSBridge.getClientsJSON() 补偿同步
|
||
未知 channelID → 触发 TSBridge.getChannelsJSON() 补偿同步
|
||
```
|
||
|
||
### 2.3 切换频道
|
||
|
||
```
|
||
用户选择目标频道
|
||
│
|
||
├── 频道有密码？ → 弹出密码输入
|
||
│
|
||
├── TsClient.clientMove(selfID, targetID, password)
|
||
│
|
||
├── 命令被拒绝 → 显示失败原因 → 允许重试
|
||
│
|
||
└── 命令成功 → 等待 onClientMoved 服务端事实
|
||
│
|
||
比对 clientID == selfID
|
||
│
|
||
提交新频道事实 → UI 导航到目标频道
|
||
```
|
||
|
||
### 2.4 发送与接收文本消息
|
||
|
||
```
|
||
发送：
|
||
用户输入消息 → 选择目标模式（频道/私聊/服务器）
|
||
│
|
||
TSBridge.sendTextMessage(targetMode, targetId, message)
|
||
│
|
||
├── 失败 → 标记消息发送失败 → 允许重试
|
||
│
|
||
└── 成功 → 标记发送完成
|
||
|
||
接收：
|
||
服务器推送 notifytextmessage
|
||
│
|
||
EventBus 收到 TextMessage 事件（立即分发，不合并）
|
||
│
|
||
按 targetMode 与 target 归档（不用当前页面猜测）
|
||
│
|
||
更新目标会话和未读状态
|
||
```
|
||
|
||
### 2.5 语音通信
|
||
|
||
```
|
||
用户按下 PTT 按钮
|
||
│
|
||
├── 前置条件检查（已连接 + 已在频道中）
|
||
│ └── 不满足 → 显示无法发言原因
|
||
│
|
||
└── 满足 → 启动麦克风采集 + Opus 编码（Dispatchers.IO）
|
||
│
|
||
循环发送：
|
||
└── 每帧 → TSBridge.sendVoice(data, codec)
|
||
│
|
||
├── 用户松开 → StopCapture → 恢复静默
|
||
│
|
||
└── 连接断开 → StopCapture → 进入 Blocked
|
||
|
||
接收语音（绕过 EventBus，延迟敏感）：
|
||
VoiceService.handleVoiceData() → Opus 解码 → AudioTrack 播放
|
||
```
|
||
|
||
### 2.6 文件传输
|
||
|
||
```
|
||
上传：
|
||
选择文件 → FileTransferInitUpload(channelID, path, size, overwrite)
|
||
│
|
||
获得 host/port/key
|
||
│
|
||
DialFileTransfer(host, port, key) → 建立 TCP 连接
|
||
│
|
||
UploadFileData(host, info, reader) → 传输文件字节流
|
||
|
||
下载：
|
||
选择文件 → FileTransferInitDownload(channelID, path, password)
|
||
│
|
||
获得 host/port/key
|
||
│
|
||
DialFileTransfer(host, port, key) → 建立 TCP 连接
|
||
│
|
||
DownloadFileData(host, info, writer) → 接收文件字节流
|
||
```
|
||
|
||
### 2.7 断开连接
|
||
|
||
```
|
||
主动断开：
|
||
用户点击离开 → 状态改为 disconnecting → 阻止新操作
|
||
│
|
||
TSBridge.disconnect() → 通知服务器客户端主动离开
|
||
│
|
||
EventBus 收到 Disconnected 事件 → 停止语音和文件传输 → 清理会话状态 → 返回主页
|
||
|
||
被动断开：
|
||
UDP 会话中断 → EventBus 收到 Disconnected(error) → 显示错误原因 → 允许重连
|
||
|
||
被踢出：
|
||
notifyclientleftview reasonid=4/5 → EventBus 收到 Kicked(reason) → 显示被踢原因 → 允许重连
|
||
```
|
||
|
||
### 2.8 状态同步（独立于主流程的横切关注点）
|
||
|
||
```
|
||
贯穿所有主流程的同步机制：
|
||
|
||
① 首次同步（连接建立后）
|
||
触发：EventBus 收到 Connected 事件
|
||
动作：TSBridge.getChannelsJSON() + TSBridge.getClientsJSON() + TSBridge.getClientID()
|
||
目标：建立完整的频道基线和成员基线
|
||
|
||
② 增量同步（事件驱动）
|
||
触发：EventBus 收到 ClientEnter / ClientMoved / ClientLeave 事件
|
||
动作：debounce 合并后 refreshClientList() 全量刷新
|
||
目标：维护实时成员位置和频道人数
|
||
|
||
③ 补偿同步（数据不一致时）
|
||
触发：事件引用了未知的 clientID 或 channelID
|
||
动作：重新调用 TSBridge.getClientsJSON() 或 TSBridge.getChannelsJSON()
|
||
目标：用完整列表修复丢失的基线数据
|
||
|
||
④ 自身状态同步（频道切换后）
|
||
触发：EventBus 收到自己的 ClientMoved 事件
|
||
动作：比对 clientID == selfID → 更新自身所在频道
|
||
目标：确认当前用户的实际频道位置
|
||
|
||
⑤ 消息归档同步（收到消息时）
|
||
触发：EventBus 收到 TextMessage 事件
|
||
动作：按 targetMode + target 归档到正确的会话
|
||
目标：维护消息与目标频道的对应关系
|
||
|
||
⑥ 重连后全量同步（断开重连后）
|
||
触发：重新收到 Connected 事件
|
||
动作：清空旧会话状态 → 重新执行首次同步
|
||
目标：确保重连后数据与服务器完全一致
|
||
|
||
⑦ 同步失败处理
|
||
触发：TSBridge.getChannelsJSON() / TSBridge.getClientsJSON() 请求失败
|
||
动作：标记同步失败 → 不进入业务就绪 → 允许重试
|
||
目标：防止在不完整数据上执行业务操作
|
||
```
|
||
|
||
---
|
||
|
||
## 三、文件索引
|
||
|
||
### 主流程
|
||
|
||
| 文件 | 用户流程 | 主要内容 |
|
||
| --- | --- | --- |
|
||
| [01_连接服务器.md](01_连接服务器.md) | 输入信息 → 建立连接 → 首次同步 | 生命周期、初始化配置、构造连接时序、状态树、事件依赖 |
|
||
| [02_浏览频道.md](02_浏览频道.md) | 浏览频道列表 → 查看成员 → Poke | 同步状态、成员状态、成员事件时序、成员实体状态树 |
|
||
| [03_切换频道.md](03_切换频道.md) | 选择频道 → 输入密码 → 等待确认 | 频道切换时序、切换状态机 |
|
||
| [04_文本消息.md](04_文本消息.md) | 发送消息 → 接收消息 → 消息归档 | 文本消息时序、聊天状态树 |
|
||
| [05_语音通信.md](05_语音通信.md) | PTT 按下 → 发送语音帧 → 松开 | 语音发送时序、语音状态树 |
|
||
| [06_文件传输.md](06_文件传输.md) | 初始化 → TCP 连接 → 数据传输 | 文件传输时序、文件状态树 |
|
||
| [07_断开连接.md](07_断开连接.md) | 主动断开 / 被动断开 / 被踢 | 断开时序、清理流程 |
|
||
| [09_EventBus架构.md](09_EventBus架构.md) | TS 事件与渲染线程分离 | 事件定义、合并策略、线程模型 |
|
||
|
||
> **注**：流程文档中的 API 调用通过 `TSBridge` 单例，事件通过 `EventBus` 接收。
|
||
> 底层通过 gomobile AAR 调用 Go SDK。详见 [sdk-bridge-api.md](../sdk-bridge-api.md) 和 [09_EventBus架构.md](09_EventBus架构.md)。
|
||
|
||
### 横切流程
|
||
|
||
| 文件 | 说明 | 触发时机 |
|
||
| --- | --- | --- |
|
||
| [08_状态同步.md](08_状态同步.md) | 独立于主流程之外的频道/成员/消息状态同步 | 连接建立、事件到达、数据不一致、重新连接时触发 |
|
||
|
||
> 所有流程文档中的 API 调用通过 `TSBridge` 单例，事件通过 `EventBus` 接收。
|
||
> 底层通过 gomobile AAR 调用 Go SDK。
|
||
|
||
---
|
||
|
||
## 四、图例
|
||
|
||
本文将 SDK 行为分成三类：
|
||
|
||
| 类型 | 含义 | Kotlin API 示例 |
|
||
| --- | --- | --- |
|
||
| 本地调用 | 只在客户端进程内执行，不直接产生网络通信 | `TsClient.getClientId()`、`TsClient.getSelf()` |
|
||
| 客户端请求 | 客户端主动向 TeamSpeak 服务器发送命令并等待响应 | `TsClient.connect()`、`TsClient.getChannelList()`、`TsClient.clientMove()` |
|
||
| 服务端推送 | TeamSpeak 服务器主动下发通知，由 SDK 转换成 EventBus 事件 | `ClientEnter`、`ClientMoved`、`TextMessage` |
|
||
|
||
所有 Mermaid 图块均使用"技术名称 + 中文注释"的形式。箭头表示调用、数据流或前置依赖，不表示所有步骤都能互换顺序。
|
||
|
||
---
|
||
|
||
## 五、运行架构
|
||
|
||
### SDK 内部与上层应用的运行关系
|
||
|
||
```mermaid
|
||
flowchart TB
|
||
subgraph APP[上层应用层<br/>负责 UI、业务状态和用户意图]
|
||
UI[界面与交互<br/>发起连接、切换、聊天和 PTT]
|
||
SM[业务状态机<br/>管理连接、同步、成员和语音状态]
|
||
STORE[实体与消息存储<br/>保存频道、客户端和聊天事实]
|
||
end
|
||
|
||
subgraph BRIDGE[桥接层<br/>TSBridge 单例<br/>负责 Kotlin 友好封装与生命周期管理]
|
||
TSB[TSBridge<br/>connect、getChannelsJSON、moveToChannel 等 API]
|
||
CB[JNI EventCallback<br/>Go 回调转 EventBus 事件]
|
||
end
|
||
|
||
subgraph EB[事件总线层<br/>EventBus<br/>负责事件收集、合并与分发]
|
||
BUS[EventBus<br/>SharedFlow 事件流]
|
||
MERGE[事件合并器<br/>debounce 高频成员变化]
|
||
THREAD[线程调度<br/>JNI 线程 → Main 线程]
|
||
end
|
||
|
||
subgraph SDK[teamspeak-go SDK (gomobile AAR)<br/>负责协议、连接和事件转换]
|
||
API[Go 公开方法<br/>Connect、GetChannelsJSON、SendVoice 等]
|
||
CMDMW[命令中间件链<br/>拦截发送前的客户端请求]
|
||
CMDBUS[命令通道<br/>构建、转义并发送协议命令]
|
||
EVTBUS[事件分发器<br/>接收并解析 notify* 通知]
|
||
EVTMW[事件中间件链<br/>拦截分发前的服务端事件]
|
||
HANDLER[Go 回调 → gomobile 转换<br/>将 Go 结构体转为 Java 对象]
|
||
VOICE[语音通道<br/>发送原始 Opus 语音帧]
|
||
FILE[文件传输协调器<br/>初始化上传或下载会话]
|
||
end
|
||
|
||
subgraph NET[网络与服务器层<br/>负责 TeamSpeak 实际通信]
|
||
UDP[UDP 协议连接<br/>承载握手、命令、事件和语音]
|
||
TCP[文件传输 TCP 连接<br/>承载上传和下载数据]
|
||
SERVER[TeamSpeak 服务器<br/>提供频道、成员、消息和权限]
|
||
end
|
||
|
||
UI --> SM
|
||
SM --> TSB
|
||
TSB --> API
|
||
API --> CMDMW
|
||
CMDMW --> CMDBUS
|
||
CMDBUS --> UDP
|
||
UDP <--> SERVER
|
||
SERVER --> UDP
|
||
UDP --> EVTBUS
|
||
EVTBUS --> EVTMW
|
||
EVTMW --> HANDLER
|
||
HANDLER --> CB
|
||
CB --> BUS
|
||
BUS --> MERGE
|
||
MERGE --> THREAD
|
||
THREAD --> SM
|
||
SM --> STORE
|
||
API --> VOICE
|
||
VOICE --> UDP
|
||
API --> FILE
|
||
FILE --> TCP
|
||
TCP <--> SERVER
|
||
```
|
||
|
||
### 三条核心运行通道
|
||
|
||
**命令通道**
|
||
|
||
```text
|
||
TSBridge → gomobile → Go SDK API → CommandMiddleware → 协议命令 → UDP → 服务器响应
|
||
```
|
||
|
||
适用：`TSBridge.getChannelsJSON()`、`TSBridge.getClientsJSON()`、`TSBridge.moveToChannel()`、`TSBridge.sendChannelMessage()`、`TSBridge.sendVoice()`。
|
||
|
||
**事件通道**
|
||
|
||
```text
|
||
服务器 notify* → UDP → Go SDK 解析 → EventMiddleware → gomobile 回调 → TSBridge EventCallback → EventBus → ViewModel → StateFlow → UI
|
||
```
|
||
|
||
适用：`Connected`、`Disconnected`、`ClientEnter`、`ClientLeave`、`ClientMoved`、`TextMessage`、`Poked`、`Kicked`。
|
||
|
||
**语音通道（绕过 EventBus）**
|
||
|
||
```text
|
||
Go 语音包 → JNI OnVoiceData → VoiceService (Dispatchers.IO) → Opus 解码 → AudioTrack 播放
|
||
```
|
||
|
||
语音数据延迟敏感，不经过 EventBus，由 VoiceService 在 IO 线程直接处理。
|
||
|
||
**文件传输通道**
|
||
|
||
```text
|
||
初始化命令 → 获得 host/port/key → DialFileTransfer → TCP 数据传输
|
||
```
|
||
|
||
文件内容不直接复用普通命令通道，初始化结果是建立 TCP 传输连接的前置条件。
|
||
|
||
### 中间件执行方向
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
A[上层业务命令<br/>通过 TSBridge 调用 API] --> B[CommandMiddleware 外层<br/>执行日志、鉴权或限流]
|
||
B --> C[CommandMiddleware 内层<br/>修改或检查协议命令]
|
||
C --> D[SDK 命令发送器<br/>编码并发送 TeamSpeak 命令]
|
||
D --> E[TeamSpeak 服务器<br/>执行命令并返回响应]
|
||
|
||
E --> F[SDK 事件解析器<br/>解析 notify* 服务端通知]
|
||
F --> G[EventMiddleware 内层<br/>检查或转换原始事件]
|
||
G --> H[EventMiddleware 外层<br/>记录事件或统一过滤]
|
||
H --> I[gomobile 回调 → TSBridge<br/>JNI 回调转 EventBus 事件]
|
||
I --> J[EventBus<br/>合并/节流后分发给 ViewModel]
|
||
```
|
||
|
||
---
|
||
|
||
## 六、统一实现原则
|
||
|
||
1. **先注册事件，再连接。** 避免握手完成后的首批推送无人处理。
|
||
2. **先等待连接就绪，再发送业务命令。** `Connect` 不代替 `WaitConnected`。
|
||
3. **列表命令建立基线，服务端事件维护增量。** 两者缺一不可。
|
||
4. **成员表按 ClientID 幂等更新。** 不使用独立 `+1/-1` 长期维护频道人数。
|
||
5. **命令响应和事件事实分离。** 尤其是频道移动，必须等待 `OnClientMoved`。
|
||
6. **当前用户通过 ClientID 识别。** 不依赖昵称或 UI 当前页面判断自己。
|
||
7. **未知实体引用触发补偿同步。** 不静默忽略移动或离开事件。
|
||
8. **消息按 TargetMode 和 Target 归档。** 不使用当前页面频道代替真实目标。
|
||
9. **语音只在连接和频道前置条件满足时发送。** 断开或被踢必须立即停止。
|
||
10. **文件传输严格遵守"初始化 → TCP 连接 → 数据传输"。** 三个阶段不能跳过。
|
||
11. **中间件必须正确调用下一层。** 吞掉命令会导致请求不发送，吞掉事件会导致状态缺失。
|
||
12. **断开时统一清理当前会话资源。** 防止旧成员、频道和 Pending 污染下一次连接。
|
||
13. **事件通过 EventBus 分发，不在 JNI 回调中直接更新 UI 状态。** JNI 回调只负责 `emit()`，ViewModel 通过 `collect()` 响应。高频成员变化事件 debounce 合并，避免事件风暴。
|