112 lines
6.1 KiB
Markdown
112 lines
6.1 KiB
Markdown
|
# 实施总览
|
|||
|
|
|
|||
|
|
> 本文档是 TeamSpeak Android 客户端实施计划的主索引，将设计文档拆分为可执行的实施步骤。
|
|||
|
|
> 依据：`docs/sdk-bridge-api.md`、`docs/UI架构设计.md`、`docs/流程/`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 〇、已完成工作
|
|||
|
|
|
|||
|
|
| 阶段 | 状态 | 说明 |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| Go 层能力封装 | ✅ 完成 | `go/teamspeak/bridge.go` 已封装全部 SDK 能力，gomobile 编译为 AAR |
|
|||
|
|
| Bridge 层实现 | ✅ 完成 | `TSBridge.kt` 单例直接包装 gomobile 导出的 `TSClient`，提供 Kotlin 友好 API |
|
|||
|
|
|
|||
|
|
**当前架构**：
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
Go SDK (teamspeak-go) → gomobile → AAR → TSBridge.kt (应用层桥接，单例)
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
**事件流**：Go goroutine → JNI callback（Go goroutine 线程）→ TSBridge → ViewModel → StateFlow → UI
|
|||
|
|
|
|||
|
|
详见 [sdk-bridge-api.md](../sdk-bridge-api.md)。
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 一、实施步骤索引
|
|||
|
|
|
|||
|
|
| 步骤 | 文档 | 主要内容 | 对应流程 | 依赖步骤 | 状态 |
|
|||
|
|
| --- | --- | --- | --- | --- | --- |
|
|||
|
|
| 01 | [项目基础设施](01_项目基础设施.md) | 项目结构、构建系统、依赖配置 | — | — | ✅ |
|
|||
|
|
| 02 | [Bridge 层实现](02_Bridge层实现.md) | TSBridge → TsClient 桥接、事件监听 | — | 01 | ✅ |
|
|||
|
|
| 03 | [服务器配置页](03_服务器配置页.md) | 连接 UI、输入验证、最近连接 | 01 连接服务器 | 02 | ⬚ |
|
|||
|
|
| 04 | [连接与首次同步](04_连接与首次同步.md) | 连接流程、Identity、首次同步 | 01 + 08① | 03 | ⬚ |
|
|||
|
|
| 05 | [频道列表页](05_频道列表页.md) | 频道树渲染、成员列表、未读指示 | 02 浏览频道 | 04 | ⬚ |
|
|||
|
|
| 06 | [频道切换](06_频道切换.md) | 频道切换流程、密码弹窗、ClientMove | 03 切换频道 | 05 | ⬚ |
|
|||
|
|
| 07 | [聊天页](07_聊天页.md) | 消息列表、发送消息、消息归档 | 04 文本消息 | 06 | ⬚ |
|
|||
|
|
| 08 | [语音通信](08_语音通信.md) | PTT 按钮、Opus 编码、语音发送/接收 | 05 语音通信 | 06 | ⬚ |
|
|||
|
|
| 09 | [断开连接](09_断开连接.md) | 主动断开、被动断开、被踢处理 | 07 断开连接 | 08 | ⬚ |
|
|||
|
|
| 10 | [状态同步进阶](10_状态同步进阶.md) | 增量同步、补偿同步、重连全量同步 | 08 状态同步 ②③⑥ | 09 | ⬚ |
|
|||
|
|
| 11 | [卡片与全局交互](11_卡片与全局交互.md) | 服务器详情卡、频道详情卡、语音卡、Poke | UI架构 三、四 | 10 | ⬚ |
|
|||
|
|
| 12 | [主题与收尾](12_主题与收尾.md) | 暗色主题、边缘情况、稳定性 | — | 11 | ⬚ |
|
|||
|
|
| 13 | [EventBus 架构](../流程/09_EventBus架构.md) | TS 事件与渲染线程分离、事件合并/节流 | — | 02 | ⬚ |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 二、实施原则
|
|||
|
|
|
|||
|
|
1. **先跑通最小闭环**：连接 → 同步 → 显示频道 → 切换频道 → 发消息 → 断开
|
|||
|
|
2. **每步可验证**：每个步骤完成后应能在真机或模拟器上运行并验证核心功能
|
|||
|
|
3. **Bridge 层已完成**：Go ↔ Kotlin 通信已通过 `TsClient` 封装，后续步骤直接调用
|
|||
|
|
4. **状态管理清晰**：严格遵循流程文档中的状态树和事件依赖
|
|||
|
|
5. **UI 后于逻辑**：先确保数据流正确，再打磨 UI 细节
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 三、技术栈确认
|
|||
|
|
|
|||
|
|
| 层级 | 技术 | 说明 |
|
|||
|
|
| --- | --- | --- |
|
|||
|
|
| 协议层 | Go + teamspeak-go | 编译为 AAR，通过 gomobile 绑定 |
|
|||
|
|
| Kotlin 封装层 | TSBridge (单例) | 直接包装 gomobile TSClient，JSON 传递复杂数据 |
|
|||
|
|
| 桥接层 | TSBridge (单例) | 直接包装 gomobile TSClient，JNI 回调转 EventBus 事件 |
|
|||
|
|
| 事件总线 | EventBus (单例) | 事件收集、合并、节流，TS 线程与渲染线程分离 |
|
|||
|
|
| UI 层 | Kotlin + Jetpack Compose | Material Design 3 主题 |
|
|||
|
|
| 状态管理 | ViewModel + StateFlow | 单向数据流，通过 EventBus 接收 TS 事件 |
|
|||
|
|
| 音频 | Opus 编解码 | Android MediaCodec 或第三方库 |
|
|||
|
|
| 网络 | UDP (SDK) + TCP (文件传输) | SDK 内部处理 |
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 四、文件结构预期
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
android/app/src/main/java/com/tsmobile/app/
|
|||
|
|
├── MainActivity.kt # 入口
|
|||
|
|
├── TSBridge.kt # 应用层桥接（直接包装 gomobile TSClient）
|
|||
|
|
├── EventBus.kt # 事件总线（TS 事件收集、合并、分发）
|
|||
|
|
├── data/ # 数据模型
|
|||
|
|
│ ├── Models.kt # 频道、成员、消息等数据类
|
|||
|
|
│ └── Repository.kt # 状态仓库
|
|||
|
|
├── voice/ # 语音服务
|
|||
|
|
│ ├── VoiceService.kt # 音频管线（采集、编码、解码、播放）
|
|||
|
|
│ ├── OpusEncoder.kt # Opus 编码器
|
|||
|
|
│ └── OpusDecoder.kt # Opus 解码器
|
|||
|
|
├── ui/
|
|||
|
|
│ ├── theme/ # Material 3 主题
|
|||
|
|
│ ├── components/ # 可复用组件
|
|||
|
|
│ └── screens/
|
|||
|
|
│ ├── ServerConfigScreen.kt
|
|||
|
|
│ ├── ChannelListScreen.kt
|
|||
|
|
│ └── ChatScreen.kt
|
|||
|
|
└── viewmodel/
|
|||
|
|
├── ServerViewModel.kt # 连接生命周期（监听 Connected/Disconnected/Kicked）
|
|||
|
|
├── ChannelViewModel.kt # 频道列表（监听 ClientEnter/Leave/Moved，debounce 刷新）
|
|||
|
|
├── ChatViewModel.kt # 消息归档（监听 TextMessage）
|
|||
|
|
└── VoiceViewModel.kt # 语音控制（VoiceService 直接处理，不经 EventBus）
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## 五、风险与注意事项
|
|||
|
|
|
|||
|
|
1. **gomobile 限制已解决**：`TSBridge.kt` 直接包装 gomobile 导出的 `TSClient`，通过 JSON 字符串传递复杂数据
|
|||
|
|
2. **线程安全**：Go JNI 回调在 Go goroutine 线程上执行（非 Android 主线程），通过 `EventBus.emit()` 统一投递，ViewModel 在 `Dispatchers.Main` 上消费事件
|
|||
|
|
3. **事件合并**：高频成员变化事件（ClientEnter/Leave/Moved）通过 debounce 合并，避免事件风暴导致频繁 refreshClientList
|
|||
|
|
4. **Opus 编解码**：SDK 不内置，需应用层集成（`voice/OpusEncoder.kt`、`voice/OpusDecoder.kt`）
|
|||
|
|
5. **语音延迟敏感**：VoiceData 不经过 EventBus，由 VoiceService 在 Dispatchers.IO 上直接处理
|
|||
|
|
6. **文件传输**：本文档范围暂不实现（见流程 06 说明）
|
|||
|
|
7. **Identity 管理**：首次生成后需持久化存储
|
|||
|
|
8. **TSBridge 是全局单例**：同一时间只能有一个活跃连接
|