ts-mobile-go/docs/流程/04_文本消息.md

文本消息

用户流程：收到文本消息 → 发送文本消息 → 消息按目标归档 对应程序流程：TsClient.sendTextMessage(targetMode, targetID, text) → 等待命令响应 → onTextMessage 按 targetMode/target 归档

---

一、状态树

聊天状态

flowchart TD
    CHAT[聊天状态<br/>维护发送与接收消息]

    CHAT --> T0[空闲 Idle<br/>没有正在发送的文本消息]
    CHAT --> T1[发送中 Sending<br/>sendTextMessage 等待响应]
    CHAT --> T2[发送失败 Failed<br/>命令返回错误]
    CHAT --> T3[收到消息 Received<br/>OnTextMessage 归档服务端推送]

---

二、时序：发送与接收文本消息

sequenceDiagram
    participant UI as 聊天 UI<br/>输入消息并展示会话
    participant CHAT as 聊天状态机<br/>管理发送 Pending 和失败
    participant BRIDGE as TSBridge<br/>调用 TsClient API
    participant SDK as Go SDK (gomobile)<br/>发送并解析文本消息
    participant TS as TeamSpeak 服务器<br/>路由私聊、频道或服务器消息
    participant STORE as 消息仓库<br/>按真实目标会话归档

    UI->>CHAT: MessageSendRequested(targetMode, targetID, text)
    CHAT->>CHAT: 创建 requestId 与 sending 状态
    CHAT->>BRIDGE: sendTextMessage(targetMode, targetID, text)
    BRIDGE->>SDK: gomobile SendTextMessage
    SDK->>TS: sendtextmessage

    alt 发送失败
        TS-->>SDK: error
        SDK-->>BRIDGE: 命令失败
        BRIDGE-->>CHAT: 返回错误
        CHAT-->>UI: 标记消息发送失败
    else 发送成功
        TS-->>SDK: command ok
        SDK-->>BRIDGE: 命令成功
        BRIDGE-->>CHAT: 返回成功
        CHAT-->>UI: 标记发送完成
    end

    TS-->>SDK: notifytextmessage
    SDK->>CHAT: onTextMessage(TsTextMessage)
    CHAT->>STORE: 按 targetMode 与 target 归档
    STORE-->>UI: 更新目标会话和未读状态

---

三、事件依赖

文本消息前置依赖矩阵

操作或事件	必须依赖	建议依赖	依赖失败时的处理
TsClient.sendTextMessage	已连接、合法 targetMode 和 target	已建立目标会话上下文	失败保留可重试消息状态
onTextMessage 归档	targetMode、target、发送者信息	已有频道或私聊实体	不得使用当前页面猜测目标

服务端通知映射

服务端通知	TSBridge 回调 → EventBus 事件	上层状态依赖	中文说明
notifytextmessage	OnTextMessage → TextMessage	消息归档、未读	立即分发，必须读取 targetMode 和 target

命令响应与事件事实的区别

flowchart LR
    INTENT[用户意图<br/>发送文本消息] --> COMMAND[客户端请求<br/>SendTextMessage]
    COMMAND --> RESPONSE{命令响应<br/>判断服务器是否接受请求}
    RESPONSE -- 失败 --> FAILED[请求失败<br/>保留原事实并展示原因]
    RESPONSE -- 成功 --> WAITFACT[等待事实事件<br/>适用于有对应推送的操作]
    WAITFACT --> EVENT[服务端推送事件<br/>OnTextMessage]
    EVENT --> COMMIT[提交服务器事实<br/>归档消息实体]

    RESPONSE -- 无对应事实事件 --> LOCALDONE[完成本次调用<br/>仅记录调用结果]

关键区分：

• TsClient.sendTextMessage 返回成功：发送命令成功；如果服务器会向自己回推消息，可再用 onTextMessage 归档权威消息。
• 消息归档必须依据 targetMode 和 target，不能使用当前页面频道代替真实目标。

权威性划分

数据	推荐权威来源	原因
文本消息	onTextMessage	来源是 notifytextmessage