17 KiB
17 KiB
流程文档总览
本文档按用户流程组织，将 SDK 技术行为拆分为七个主流程文件和一个独立的状态同步流程文件。 依据：
docs/sdk-bridge-api.mdSDK：github.com/honeybbq/teamspeak-go→ gomobile AAR →TSBridge.kt应用层桥接
一、完整用户流程
进入应用
│
├─ 已有最近服务器？ ──是──→ 显示最近服务器列表 ──→ 选择服务器
│ │
└─ 否 ──→ 输入服务器地址 ──→ 输入昵称 ──→ 输入密码（可选） ──→┘
│
点击"进入服务器"
│
┌─────────────────────┘
▼
连接中（显示进度）
│
┌───────────────┼───────────────┐
▼ ▼ ▼
连接成功 连接失败 超时
│ │ │
│ 显示错误原因 显示超时提示
│ 允许重试 允许重试
│ │ │
│ └───────→ 返回输入页面
▼
分配到默认频道（首次同步 ①）
│
▼
浏览频道列表 ──→ 浏览频道中的人员分布
│ │
│ poke 服务器内成员
│ │
▼ ▼
┌──→ 进入/切换频道 ←──────────┘
│ │ ← 自身状态同步 ④
│ │ ← 增量同步 ② / 补偿同步 ③
│ │
│ ├─ 频道有密码？ ──是──→ 输入密码
│ │
│ ├─ 收听语音 ──→ 发送语音（PTT）
│ │
│ ├─ 收到文本消息 ──→ 消息归档同步 ⑤ ──→ 发送文本消息
│ │
│ ├─ 浏览频道文件 ──→ 上传文件 ──→ 下载文件
│ │
│ ├─ poke 服务器内成员 ──→ 被 poke
│ │
│ ▼
│ 切换频道 / 留在当前频道
│ │
└────┘
│
▼
┌─── 离开原因 ───┐
│ │ │
▼ ▼ ▼
主动断开 网络异常 被踢出
│ │ │
▼ ▼ ▼
发送 显示错误 显示被踢原因
disconnect 允许重连 允许重连
│ │ │
│ 重连后全量同步 ⑥
│ │ │
└────────┼─────────┘
▼
清理会话状态
│
▼
返回应用主页
① 首次同步 ② 增量同步 ③ 补偿同步 ④ 自身状态同步 ⑤ 消息归档同步 ⑥ 重连后全量同步 详见 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 | 输入信息 → 建立连接 → 首次同步 | 生命周期、初始化配置、构造连接时序、状态树、事件依赖 |
| 02_浏览频道.md | 浏览频道列表 → 查看成员 → Poke | 同步状态、成员状态、成员事件时序、成员实体状态树 |
| 03_切换频道.md | 选择频道 → 输入密码 → 等待确认 | 频道切换时序、切换状态机 |
| 04_文本消息.md | 发送消息 → 接收消息 → 消息归档 | 文本消息时序、聊天状态树 |
| 05_语音通信.md | PTT 按下 → 发送语音帧 → 松开 | 语音发送时序、语音状态树 |
| 06_文件传输.md | 初始化 → TCP 连接 → 数据传输 | 文件传输时序、文件状态树 |
| 07_断开连接.md | 主动断开 / 被动断开 / 被踢 | 断开时序、清理流程 |
| 09_EventBus架构.md | TS 事件与渲染线程分离 | 事件定义、合并策略、线程模型 |
注：流程文档中的 API 调用通过
TSBridge单例，事件通过EventBus接收。 底层通过 gomobile AAR 调用 Go SDK。详见 sdk-bridge-api.md 和 09_EventBus架构.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 内部与上层应用的运行关系
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
三条核心运行通道
命令通道
TSBridge → gomobile → Go SDK API → CommandMiddleware → 协议命令 → UDP → 服务器响应
适用：TSBridge.getChannelsJSON()、TSBridge.getClientsJSON()、TSBridge.moveToChannel()、TSBridge.sendChannelMessage()、TSBridge.sendVoice()。
事件通道
服务器 notify* → UDP → Go SDK 解析 → EventMiddleware → gomobile 回调 → TSBridge EventCallback → EventBus → ViewModel → StateFlow → UI
适用：Connected、Disconnected、ClientEnter、ClientLeave、ClientMoved、TextMessage、Poked、Kicked。
语音通道（绕过 EventBus）
Go 语音包 → JNI OnVoiceData → VoiceService (Dispatchers.IO) → Opus 解码 → AudioTrack 播放
语音数据延迟敏感，不经过 EventBus，由 VoiceService 在 IO 线程直接处理。
文件传输通道
初始化命令 → 获得 host/port/key → DialFileTransfer → TCP 数据传输
文件内容不直接复用普通命令通道，初始化结果是建立 TCP 传输连接的前置条件。
中间件执行方向
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]
六、统一实现原则
- 先注册事件，再连接。 避免握手完成后的首批推送无人处理。
- 先等待连接就绪，再发送业务命令。
Connect不代替WaitConnected。 - 列表命令建立基线，服务端事件维护增量。 两者缺一不可。
- 成员表按 ClientID 幂等更新。 不使用独立
+1/-1长期维护频道人数。 - 命令响应和事件事实分离。 尤其是频道移动，必须等待
OnClientMoved。 - 当前用户通过 ClientID 识别。 不依赖昵称或 UI 当前页面判断自己。
- 未知实体引用触发补偿同步。 不静默忽略移动或离开事件。
- 消息按 TargetMode 和 Target 归档。 不使用当前页面频道代替真实目标。
- 语音只在连接和频道前置条件满足时发送。 断开或被踢必须立即停止。
- 文件传输严格遵守"初始化 → TCP 连接 → 数据传输"。 三个阶段不能跳过。
- 中间件必须正确调用下一层。 吞掉命令会导致请求不发送，吞掉事件会导致状态缺失。
- 断开时统一清理当前会话资源。 防止旧成员、频道和 Pending 污染下一次连接。
- 事件通过 EventBus 分发，不在 JNI 回调中直接更新 UI 状态。 JNI 回调只负责
emit()，ViewModel 通过collect()响应。高频成员变化事件 debounce 合并，避免事件风暴。