# 步骤 02：Bridge 层实现（✅ 已完成）

> 实现 Go ↔ Kotlin 桥接层，包括 Go 侧 TSClient 导出、Kotlin 友好封装（TsClient.kt + TsModels.kt）、应用层桥接（TSBridge.kt）。

---

## 一、目标

- [x] Go 侧 TSClient 结构体及方法导出（`go/teamspeak/bridge.go`）
- [x] gomobile 编译为 AAR（`android/app/libs/teamspeak.aar`）
- [x] Kotlin 友好封装层（`TsClient.kt` + `TsModels.kt`）
- [x] 应用层桥接（`TSBridge.kt`）

---

## 二、架构总览

```
┌─────────────────────────────────────────────────────────────┐
│  Kotlin 应用层                                               │
│                                                             │
│  ViewModel ──→ TSBridge (object) ──→ TsClient (object)      │
│                    │                       │                 │
│                    │ TsListener 回调        │ Kotlin 友好 API  │
│                    ↑                       │                 │
│                    └── TsListener ─────────┘                 │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  gomobile 自动生成层                                         │
│                                                             │
│  teamspeak.TSClient (Java) ← Go TSClient struct             │
│  teamspeak.EventCallback (Java) ← Go EventCallback interface│
│  teamspeak.* 数据类 (Java) ← Go 导出结构体                   │
│                                                             │
├─────────────────────────────────────────────────────────────┤
│  Go 层                                                      │
│                                                             │
│  bridge.go (TSClient + EventCallback) ──→ teamspeak-go SDK  │
│       │                                         │           │
│       │ 事件队列 + 单消费者 goroutine              │ On* 回调  │
│       └──→ JNI 回调 ──→ EventCallback            │           │
│                                                             │
└─────────────────────────────────────────────────────────────┘
```

**数据流**：

| 方向 | 路径 | 说明 |
| --- | --- | --- |
| Kotlin → Go | `TSBridge` → `TsClient` → gomobile `TSClient` → Go `Client` | 用户操作 |
| Go → Kotlin | Go `On*` → 事件队列 → JNI → `EventCallback` → `TsClient` 转换 → `TsListener` → `TSBridge` | 事件推送 |

---

## 三、三层架构详解

### 3.1 Go 层（bridge.go）

**文件**：`go/teamspeak/bridge.go`

Go 侧 Bridge 是 gomobile 导出的核心，将 teamspeak-go SDK 封装为可供 Kotlin 调用的 `TSClient` 类。

#### 导出的接口与结构

```go
// EventCallback — gomobile 导出的回调接口
type EventCallback interface {
    OnConnected()
    OnDisconnected(message string)
    OnTextMessage(msg *TextMsg)
    OnClientEnter(client *ServerClientView)
    OnClientLeave(client *ServerClientView)
    OnClientMoved(client *ClientMoved)
    OnKicked(reason *ServerError)
    OnTalkStatusChanged(talker *TalkStatusChange)
    OnClientIDsDone()
    OnServerError(error *ServerError)
}

// TSClient — gomobile 导出的桥接客户端
type TSClient struct {
    client   *teamspeak.Client
    callback EventCallback
}

// 导出的数据结构（适配 gomobile 限制）
type ServerClientView struct { ... }  // 频道成员视图
type ClientInfo struct { ... }        // 完整客户端信息
type ChannelListItem struct { ... }   // 频道列表项
type TextMsg struct { ... }           // 文本消息
type ClientMoved struct { ... }       // 客户端移动事件
type ServerError struct { ... }       // 服务器错误
type TalkStatusChange struct { ... }  // 说话状态变化
type ChannelListResult struct { ... } // 频道列表结果（含数组）
```

#### 关键设计决策

1. **字符串传递 ID**：gomobile 不支持 `uint64` → Kotlin Long 的安全映射，统一用 `string`
2. **结构体包装**：gomobile 不支持 `[]*T`，用 `ChannelListResult` 包装 `ChannelListItem[]`
3. **错误用字符串**：gomobile 不支持 `error` 返回值，用空串=成功
4. **事件队列**：SDK 内部 `evtQueue` + 单消费者 goroutine 串行分发，JNI 回调线程安全

### 3.2 Kotlin 友好封装层（TsClient.kt + TsModels.kt）

**文件**：`android/app/src/main/java/com/tsmobile/app/TsClient.kt`、`TsModels.kt`

这一层将 gomobile 生成的 Java 对象转为 Kotlin 友好接口，解决：
- 所有 API 为 getter/setter 而非属性
- `ChannelListItem[]` 需要手动转 `List<TsChannel>`
- 事件回调参数是 `Object` 类型需要强转
- group 类型是 `Int` 需要映射为 `ChanGroupType` 枚举

#### TsClient 对象

```kotlin
object TsClient {
    // 连接
    fun connect(identity, host, nickname, password, defaultChannel): Boolean
    fun disconnect()

    // 事件监听
    fun setListener(listener: TsListener?)

    // 查询（返回 Kotlin 友好类型）
    fun getChannelList(): List<TsChannel>
    fun getClientList(): List<TsClientInfo>
    fun getClientId(): Long
    fun getClientInfo(clientId: Long): TsClientInfo?
    fun getChannelInfo(channelId: Long): TsChannel?
    fun getSelf(): TsSelf
    fun getChannelIdsByUid(uid: String, maxDepth: Int): List<Long>

    // 属性
    val serverVersion: String
    val serverIp: String
    val serverPlatform: String
    val serverName: String
    val serverCreated: Long
    val serverUptime: Long
    val maxClients: Int
    val clientsOnline: Int
    val channelsOnline: Int

    // 操作
    fun sendTextMessage(targetMode: Int, targetId: Long, msg: String): Boolean
    fun clientMove(clientId: Long, channelId: Long, password: String): Boolean
    fun clientPoke(clientId: Long, msg: String): Boolean
    fun kickClient(clientId: Long, reasonId: Int, reasonMsg: String): Boolean
    fun banClient(uid: String, timeInSeconds: Long, reasonMsg: String): Boolean
    fun channelCreate(name: String, properties: Map<String, String>, permissions: List<TSPermission>): Long
    fun channelUpdate(channelId: Long, properties: Map<String, String>): Boolean
    fun channelDelete(channelId: Long, force: Boolean): Boolean
    fun sendVoice(clientId: Long, codec: Int, data: ByteArray): Boolean
}
```

#### TsListener 接口

```kotlin
interface TsListener {
    fun onConnected()
    fun onDisconnected(error: String?)
    fun onClientEnter(client: TsClientInfo)
    fun onClientMoved(moved: TsClientMoved)
    fun onClientLeave(client: ServerClientView)
    fun onTalkStatusChanged(talker: TsTalker)
    fun onClientIDsDone()
    fun onTextMessage(msg: TsTextMessage)
    fun onPoked(msg: TsTextMessage)
    fun onKicked(reason: ServerError?)
    fun onServerError(error: ServerError)
    fun onChannelListChanged()
}
```

#### TsModels 数据类

```kotlin
// 频道
data class TsChannel(val channelListItem: ChannelListItem) {
    val channelId get() = channelListItem.getChannelID()
    val parentId get() = channelListItem.getParentChannelID()
    val name get() = channelListItem.getName()
    val order get() = channelListItem.getOrder()
    val isPermanent get() = channelListItem.getIsPermanent()
    val totalClients get() = channelListItem.getTotalClients()
    // ... 更多属性
}

// 客户端
data class TsClientInfo(val serverClientView: ServerClientView) {
    val clientId get() = serverClientView.getID()
    val channelId get() = serverClientView.getChannelID()
    val nickname get() = serverClientView.getNickname()
    val uid get() = serverClientView.getUid()
    val isTalker get() = serverClientView.getIsTalker()
    // ... 更多属性
}

// 自身信息（可写）
class TsSelf internal constructor(
    private val view: ServerClientView,
    private val info: ClientInfo?
) {
    var nickname
        get() = view.getNickname()
        set(value) { info?.setNickname(value) }
    var isTalker
        get() = view.getIsTalker()
        set(value) { info?.setIsTalker(value) }
    var inputMuted
        get() = info?.getInputMuted() ?: false
        set(value) { info?.setInputMuted(value) }
    var outputMuted
        get() = info?.getOutputMuted() ?: false
        set(value) { info?.setOutputMuted(value) }
    // ... 更多可写属性
}

// 移动事件
data class TsClientMoved(
    val theClient: ServerClientView?,
    val oldChannel: ChannelListItem?,
    val newChannel: ChannelListItem?,
    val visibility: Int
)

// 说话状态
data class TsTalker(
    val client: ServerClientView?,
    val isTalking: Boolean
)

// 文本消息
data class TsTextMessage(
    val message: String,
    val invokerUid: String,
    val invokerName: String,
    val invokerId: Long,
    val targetMode: Int,
    val targetClientId: Long,
    val targetChannelId: Long
)

// 频道组/服务器组类型
enum class ChanGroupType(val value: Int) { ... }
enum class ChannelGroupType(val value: Int) { ... }
```

### 3.3 应用层桥接（TSBridge.kt）

**文件**：`android/app/src/main/java/com/tsmobile/app/TSBridge.kt`

TSBridge 是 ViewModel 层访问 Go 桥接的唯一入口，采用 `object` 单例模式。

#### 核心职责

1. **连接管理**：封装 `TsClient.connect()` / `disconnect()`
2. **监听注册**：在 `connect()` 时自动设置 `TsListener`
3. **查询转发**：所有查询方法委托给 `TsClient`
4. **操作转发**：所有操作方法委托给 `TsClient`

#### 完整 API

```kotlin
object TSBridge {
    // === 连接管理 ===
    fun connect(identity: Any, host: String, nickname: String,
                password: String = "", defaultChannel: String = "",
                listener: TSBridgeListener? = null): Boolean
    fun disconnect()

    // === 查询 ===
    fun getChannelList(): List<TsChannel>
    fun getClientList(): List<TsClientInfo>
    fun getClientId(): Long
    fun getSelf(): TsSelf
    fun getChannelInfo(channelId: Long): TsChannel?
    fun getClientInfo(clientId: Long): TsClientInfo?
    fun getChannelIdsByUid(uid: String): List<Long>

    // === 操作 ===
    fun sendTextMessage(targetMode: Int, targetId: Long, msg: String): Boolean
    fun clientMove(clientId: Long, channelId: Long, password: String = ""): Boolean
    fun clientPoke(clientId: Long, msg: String): Boolean
    fun kickClient(clientId: Long, reasonId: Int, reasonMsg: String): Boolean
    fun banClient(uid: String, timeInSeconds: Long, reasonMsg: String): Boolean
    fun channelCreate(name: String, properties: Map<String, String> = emptyMap(),
                      permissions: List<TSPermission> = emptyList()): Long
    fun channelUpdate(channelId: Long, properties: Map<String, String>): Boolean
    fun channelDelete(channelId: Long, force: Boolean = false): Boolean
    fun sendVoice(clientId: Long, codec: Int, data: ByteArray): Boolean

    // === 服务器属性 ===
    val serverVersion: String
    val serverIp: String
    val serverPlatform: String
    val serverName: String
    // ...
}

// 回调接口（简化版，供 ViewModel 使用）
interface TSBridgeListener {
    fun onConnected()
    fun onDisconnected(error: String?)
    fun onClientEnter(client: TsClientInfo)
    fun onClientMoved(moved: TsClientMoved)
    fun onClientLeave(client: ServerClientView)
    fun onTalkStatusChanged(talker: TsTalker)
    fun onClientIDsDone()
    fun onTextMessage(msg: TsTextMessage)
    fun onPoked(msg: TsTextMessage)
    fun onKicked(reason: ServerError?)
    fun onServerError(error: ServerError)
}
```

---

## 四、数据流转详解

### 4.1 连接流程

```
ViewModel: TSBridge.connect(identity, host, nickname, password)
    ↓
TSBridge: TsClient.connect(identity, host, nickname, password)
    ↓
TsClient: TSClient.connect(...)  // gomobile Java 对象
    ↓
Go: TSClient.Connect() → NewClient → registerHandlers → Connect → WaitConnected
    ↓
Go SDK: 收到 welcome → 触发 OnConnected
    ↓
Go Bridge: EventCallback.OnConnected()  // JNI
    ↓
TsClient: listener?.onConnected()  // Kotlin 友好回调
    ↓
TSBridge: listener?.onConnected()
    ↓
ViewModel: _state.update { it.copy(connected = true) }
```

### 4.2 查询流程

```
ViewModel: TSBridge.getChannelList()
    ↓
TSBridge: TsClient.getChannelList()
    ↓
TsClient: TSClient.requestChannelList()  // gomobile
    ↓
TsClient: result.getChannels().map { TsChannel(it) }  // 转为 Kotlin 类型
    ↓
TSBridge: 返回 List<TsChannel>
    ↓
ViewModel: _state.update { it.copy(channels = list) }
```

### 4.3 事件推送流程

```
TeamSpeak 服务器: notifyclientmoved
    ↓
Go SDK: handleNotification → evtQueue → startEventLoop
    ↓
Go Bridge: EventCallback.OnClientMoved(clientMoved)
    ↓ JNI
TsClient: TsListener.onClientMoved(TsClientMoved(view, old, new, vis))
    ↓
TSBridge: listener?.onClientMoved(moved)
    ↓
ViewModel: 处理移动事件，更新状态
```

---

## 五、gomobile 约束与应对

| 约束 | 影响 | 应对方案 |
| --- | --- | --- |
| 不能导出 `[]string` | 服务器组列表无法直接传递 | `TsClientInfo` 封装为逗号分隔字符串 |
| 不能导出 `[]*T` | 频道/客户端列表无法返回切片 | `ChannelListResult` 包装 + `TsClient` 转 `List` |
| 不能导出 `map[string]string` | 属性列表无法传递 | `channelCreate`/`channelUpdate` 接受 `Map`，内部转 gomobile 类型 |
| 不能导出 `error` | 方法无法返回错误 | `Boolean` 返回值（true=成功） |
| `uint64` 映射为 `long` | 频道 ID 可能溢出 | 统一用 `string` 传递 ID |
| 回调在 JNI 线程 | 不能直接操作 UI | `TsListener` 回调 → ViewModel + StateFlow 中转 |
| 所有字段为 getter/setter | Kotlin 不友好 | `TsModels` 包装为 `val`/`var` 属性 |

---

## 六、文件清单

| 文件 | 说明 |
| --- | --- |
| `go/teamspeak/bridge.go` | Go 侧桥接，导出 TSClient + EventCallback |
| `android/app/libs/teamspeak.aar` | gomobile 编译产物 |
| `android/app/src/main/java/com/tsmobile/app/TsClient.kt` | Kotlin 友好封装（TsClient 对象） |
| `android/app/src/main/java/com/tsmobile/app/TsModels.kt` | Kotlin 数据类（TsChannel, TsClientInfo 等） |
| `android/app/src/main/java/com/tsmobile/app/TSBridge.kt` | 应用层桥接（单例） |

---

## 七、验收标准

| # | 验证项 | 验证方法 |
| --- | --- | --- |
| 1 | bridge.go 可编译 | `cd go && go build ./teamspeak` 无报错 |
| 2 | gomobile 生成 AAR | `gomobile bind ...` 成功 |
| 3 | TsClient.connect() 可调用 | 编译通过，连接测试服务器成功 |
| 4 | TsListener 回调正常 | 连接后收到 `onConnected`、`onClientEnter` 等 |
| 5 | 查询返回 Kotlin 类型 | `getChannelList()` 返回 `List<TsChannel>` |
| 6 | 操作方法正常 | `sendTextMessage`、`clientMove` 等返回 true |
| 7 | 断开连接无崩溃 | `disconnect()` 后应用正常退出 |

---

## 八、参考文档

- `docs/sdk-bridge-api.md` — TsClient API 完整参考
- `docs/流程/00_总览.md` — 运行架构、三条核心通道
- `docs/流程/01_连接服务器.md` — 连接时序、事件依赖
- `CLAUDE.md` — gomobile 限制说明、JNI 线程注意事项