ts-mobile-go/docs/bridge-contract.md

Go ↔ Kotlin Bridge 契约

状态：权威 ｜ 最后核对：2026-09-10 ｜ 契约版本：1

单一事实来源：go/teamspeak/contract.go（字段名常量 + BridgeContractVersion） Kotlin 侧守卫：android/app/src/main/java/com/tsmobile/app/data/BridgeContract.kt 契约测试：go/teamspeak/contract_test.go、contract_golden_test.go、 android/app/src/test/java/com/tsmobile/app/data/BridgeContractTest.kt

---

为什么需要这份文档

gomobile 有三条硬限制（CLAUDE.md 已记录）：不能导出 []string、[]*T、Go error。 项目用 JSON 字符串绕过它们，代价是：

Go 侧改一个字段名，Kotlin 侧不会编译失败，只会在运行时静默拿到默认值。

叠加 Repository.kt 的 Json { ignoreUnknownKeys = true }，字段对不上时 ChannelInfo 直接填 "" / 0 / false：频道列表看起来是空的， 或者密码频道显示成公开频道，而日志里什么都没有。

本契约用三道机制钉住这个边界：

机制	防止的问题
contract.go 字段名常量	集中声明，marshal 处不写字面量
contract_test.go 反射断言	常量与 struct tag 漂移 → 测试红
golden 样本（Go/Kotlin 共用）	样本与 tag 漂移 → 两侧测试都红
BridgeContract.verifyOrDescribeError()	AAR 与 App 版本不匹配 → 连接前明确报错

---

边界数据类型分级

不是所有跨边界数据都同样脆弱。改代码前先确认属于哪一类：

类别	保护强度	类型	说明
A 类	编译期检查	TextMsg、PokeEvent、Channel、Client	gomobile 导出的 struct，字段是真实属性。Go 改名 → Kotlin 编译失败。无需常量保护。
B 类	无（靠契约测试）	channelJSON、clientJSON、serverInfoJSON、文件下载 JSON	JSON 字符串。本契约的主要保护对象。
C 类	无（无消费方）	channelDetailedJSON、clientDetailedInfoJSON、initialSyncJSON	已导出但 Kotlin 未解析。字段名已声明以钉住形状；将来要消费时先跑契约测试。

---

B 类契约明细

图例：✓ = 已有 Kotlin 消费方 ｜ — = 当前未消费

1. 频道列表 — GetChannelsJSON() → Repository.fetchChannels()

Go：channelJSON（bridge.go）｜ Kotlin：ChannelInfo（Models.kt）

Go 字段	JSON 字段	Kotlin 字段	类型	可空	默认值语义
ID	id	id	String	否	"" — 字符串化数字，见下方注意
Name	name	name	String	否	""
ParentID	parentId	parentId	String	否	"0" — 顶级频道的约定值
Description	description	description	String	否	""（Go 侧实际不填充）
IsPassword	isPassword	isPassword	Boolean	否	false

⚠️ id / parentId 是字符串不是数字。 TeamSpeak 的频道 ID 是无符号 64 位， 超出 Kotlin Int 范围。contract_test.go 的 TestChannelJSON_IDIsStringType 钉住了这一点——改成数值类型会让 Kotlin 在运行时抛序列化异常。

⚠️ ChannelInfo.order（Int）在 Go 侧不存在。 channelJSON 没有 order 字段， 所以该值恒为默认 0，ChannelViewModel.buildChannelTree 的 .sortedBy { it.order } 实际是不产生效果的 no-op（sortedBy 稳定，全等值等于保持原序）。

频道顺序目前由服务器返回顺序决定，且这是正确的——TS3 的 channellist 响应按频道树顺序返回，子频道紧跟父频道。显示顺序经真机验证与响应顺序一致。

📌 不要"按 order 排序"：channel_order 不是排序权重，而是 前驱频道的 ID（链表指针，0 = 排在本层最前）。见 docs/teamspeak-sdk-3.5.2/doc/client/channel-sort.html：

The channel order is the ID of the predecessor channel after which the given channel should be sorted. An order of 0 means the channel is sorted on the top of its hirarchy.

官方示例：Subsubchannel_2 ( ID = 7 , order = 6 ) 表示"排在 ID=6 之后"， Subchannel_2 ( ID = 5 , order = 4 ) 表示"排在 ID=4 之后"。 若按该值数值排序会得到 1,4,6,2,3,5,7，正好把树结构打乱。

若将来确实需要在客户端重建顺序（例如不再依赖响应顺序）， 正确做法是消费 channelDetailedJSON.order 后按前驱指针串链， 而不是排序。注意 API 侧 ChannelDetailInfo 里 pid 取自 item["channel_order"]（api.go:265），该处取值可疑，使用前需先核实。

2. 客户端列表 — GetClientsJSON() → Repository.fetchClients()

Go：clientJSON ｜ Kotlin：ClientInfo

Go 字段	JSON 字段	Kotlin 字段	类型	可空	默认值语义
ID	id	id	Int	否	0
Nickname	nickname	nickname	String	否	""
UID	uid	uid	String	否	"" — 永久身份标识，等同账号 ID
ChannelID	channelId	channelId	String	否	"0" — 字符串化
ServerGroups	serverGroups	serverGroups	List<String>	否	[]
IsSelf	isSelf	isSelf	Boolean	否	false

uid 是敏感数据：Repository.performInitialSync 中的全量 dump 已改为 BuildConfig.DEBUG 保护 + proguard-rules.pro 剥离 Log.d。

3. 服务器信息 — GetServerInfoJSON() → ServerViewModel / Repository

Go：serverInfoJSON ｜ Kotlin：ServerInfo

Go 字段	JSON 字段	Kotlin 字段	类型	可空	默认值语义
Name	name	name	String	否	""
WelcomeMessage	welcomeMessage	welcomeMessage	String	否	""
MaxClients	maxClients	maxClients	Int	否	0
ClientsOnline	clientsOnline	clientsOnline	Int	否	0
ChannelsOnline	channelsOnline	channelsOnline	Int	否	0
Uptime	uptime	uptime	String	否	"" — 字符串化秒数
Version	version	version	String	否	""
Platform	platform	platform	String	否	""
Created	created	created	String	否	"" — 字符串化秒级时间戳
IconID	iconId	iconId	String	否	""
DefaultServerGroup	defaultServerGroup	defaultServerGroup	Int	否	0
DefaultChannelGroup	defaultChannelGroup	defaultChannelGroup	Int	否	0

⚠️ uptime / created 是字符串。TestGolden_ServerInfoTypes 钉住了类型—— 改成数值会让 Kotlin 的 String 字段静默变空。

4. 文件下载 — DownloadFileBytesJSON() → FileDownloadManager

Go：kotlin_api.go（内联 map）｜ Kotlin：TSBridge.downloadFileBytes()

JSON 字段	类型	说明
data	String	base64 编码的文件内容
size	Int	解码后字节数

失败约定与其它接口不同：失败返回 "{}"（而非 "[]"），消费方以 data 为空判定失败。 空字符串返回表示「未连接」，"{}" 表示「连接正常但下载失败」——两者不可混为一谈。

---

事件契约（A 类，编译期检查）

这些类型由 gomobile 直接导出为 Java 类，字段访问经编译器校验，不需要也不应该 为它们添加 JSON 字段常量。

TextMsg（EventCallback.OnTextMessage）

字段	类型	说明
TargetMode	Int	见下方 targetMode 表
TargetID	String	目标 ID（字符串化）
InvokerID	Int	发送者 clid；旧 AAR 可能为 0
InvokerName	String	发送者昵称
InvokerUID	String	发送者 UID
Message	String	消息内容（纯文本或文件消息 JSON）

PokeEvent（EventCallback.OnPoked）

字段	类型
InvokerID	Int
InvokerName	String
InvokerUID	String
Message	String

---

targetMode 收发能力对照（重要）

TargetMode 的接收与发送能力不对称，读代码时极易误判为「三种都支持」：

值	含义	接收	发送
1	私聊	✅ 支持	❌ 未实现
2	频道	✅ 支持	✅ 支持
3	服务器	✅ 支持	❌ 未实现

TSBridge.sendTextMessage 仅实现 mode=2；其余分支返回显式错误串 "暂不支持该消息类型"（按桥接约定：非空 = 错误），由 ChatViewModel 映射为 MessageSendState.Failed 并将消息标记为 FAILED。

当前状态：接收侧支持三种会话（通知 deep link 可跳转到指定会话），发送侧只有频道消息。 私聊能收到、能弹通知，但无法在 App 内回复。

---

版本升级流程

任何不兼容变更（字段改名、类型变更、字段删除）必须：

1. 递增 go/teamspeak/contract.go 的 BridgeContractVersion
2. 同步 BridgeContract.kt 的 EXPECTED_VERSION
3. 更新本文档
4. 重编 AAR（build.bat 第 1 步）

只新增可选字段（Kotlin 侧有默认值）不需要递增版本。

版本校验不匹配时，ServerViewModel.connect() 会以 ConnectState.FAILED 明确报错并阻止连接——而不是带着错配的字段名继续跑。 旧 AAR（未导出 getContractVersion()）不阻断，仅记录 warning。

---

跑契约测试

# Go 侧：字段名常量 + golden 样本一致性
cd go && go test ./teamspeak/ -run "Contract|Golden" -v

# Kotlin 侧：反序列化 + 失效模式
cd android && ./gradlew testDebugUnitTest --tests '*BridgeContractTest*'

golden 样本位于 android/app/src/test/resources/contract/， 由 Go 与 Kotlin 共用：Go 测试断言样本字段集合 == struct tag， Kotlin 测试断言样本能正确反序列化。 字段漂移时两侧都会变红——这是「改了字段名却无人发现」的兜底。