# 文本消息

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

---

## 一、状态树

### 聊天状态

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

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

---

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

```mermaid
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 |

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

```mermaid
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` |