# UI 架构设计

> 依据：`docs/流程/00_总览.md` 及 `docs/流程/01~08` 各流程文件  
> 范围：页面布局、卡片设计、全局交互、状态处理、流程映射

---

## 一、架构总览

### 1.1 整体结构：3 页 3 卡

```
页面（Page）                          卡片（Card）
┌─────────────────────┐              ┌─────────────────────┐
│  服务器配置页        │              │  服务器详情卡        │
│  ServerConfigPage    │              │  ServerDetailCard    │
├─────────────────────┤              │  （底部弹出）         │
│  频道列表页          │              ├─────────────────────┤
│  ChannelListPage     │              │  频道详情卡          │
├─────────────────────┤              │  ChannelDetailCard   │
│  聊天页              │              │  （底部弹出）         │
│  ChatPage            │              ├─────────────────────┤
└─────────────────────┘              │  语音卡              │
                                     │  VoiceCard           │
                                     │  （底部弹出）         │
                                     └─────────────────────┘
```

### 1.2 页面导航关系

```
                    ┌──────────────────────┐
                    │   服务器配置页        │
                    │   (应用启动首屏)      │
                    └──────────┬───────────┘
                               │ 连接成功
                               ▼
                    ┌──────────────────────┐
              ┌────→│   频道列表页          │──────┐
              │     │   (主页面)            │      │
              │     └──────────────────────┘      │
              │            │                       │
              │            │ 点击"中部-底部"当前频道 │
              │            ▼                       │
              │     ┌──────────────────────┐      │
              │     │   聊天页              │      │
              │     │   (当前频道消息)      │      │
              │     └──────────┬───────────┘      │
              │                │ 返回按钮          │
              └────────────────┘                  │
                                                  │
              ┌───────────────────────────────────┘
              │  头部左侧按钮
              ▼
        服务器详情卡（弹出）

              频道列表页 / 聊天页
              │ 头部右侧按钮
              ▼
        频道详情卡（弹出）

              任意页面（服务器配置页除外）
              │ 底部语音控制区 "展开" 按钮
              ▼
        语音卡（弹出）
```

### 1.3 卡片弹出规则

| 卡片 | 可弹出页面 | 弹出方式 | 关闭方式 |
| --- | --- | --- | --- |
| 服务器详情卡 | 频道列表页 | 底部弹出（BottomSheet） | 点击外部 / 下滑 / 断开后自动关闭 |
| 频道详情卡 | 频道列表页、聊天页 | 底部弹出（BottomSheet） | 点击外部 / 下滑 |
| 语音卡 | 频道列表页、聊天页 | 底部弹出（BottomSheet），可拖拽为半屏 | 点击外部 / 下滑 / 点击展开按钮 |

---

## 二、页面详细设计

### 2.1 服务器配置页

> 对应流程：01 连接服务器

#### 布局

```
┌──────────────────────────────┐
│           上：品牌区          │
│   [Logo]                     │
│   TeamSpeak Mobile           │
│   连接到你的 TeamSpeak 服务器 │
│                    [🌙 主题] │  ← 右上角主题切换图标
├──────────────────────────────┤
│           中：输入区          │
│                              │
│  服务器地址                   │
│  ┌──────────────────────────┐│
│  │ ts.example.com           ││
│  └──────────────────────────┘│
│                              │
│  昵称                        │
│  ┌──────────────────────────┐│
│  │ 我的昵称                  ││
│  └──────────────────────────┘│
│                              │
│  密码（可选）                 │
│  ┌──────────────────────────┐│
│  │ ••••••                   ││
│  └──────────────────────────┘│
│                              │
│  ┌──────────────────────────┐│
│  │      连接服务器           ││  ← 按钮状态见 5.1
│  └──────────────────────────┘│
├──────────────────────────────┤
│           下：最近连接        │
│                              │
│  最近连接                     │
│  ┌──────────────────────────┐│
│  │ 🟢 ts.myserver.com       ││  ← 点击快速连接
│  │    上次连接：2小时前      ││
│  ├──────────────────────────┤│
│  │ 🔴 ts.other.com          ││
│  │    上次连接：昨天         ││
│  └──────────────────────────┘│
│                              │
│  [清空最近记录]               │  ← 长按或编辑模式删除单条
└──────────────────────────────┘
```

#### 三段式结构说明

| 段落 | 内容 | 说明 |
| --- | --- | --- |
| 上（品牌区） | Logo + 描述文本 + 主题切换 | 仅展示，不可交互（主题图标除外） |
| 中（输入区） | 地址/昵称/密码输入 + 连接按钮 | 核心交互区，连接成功跳转频道列表页 |
| 下（最近连接） | 历史服务器列表 | 点击直接快速连接（复用已保存的昵称和密码） |

#### 输入验证规则

| 字段 | 必填 | 验证规则 | 错误提示 |
| --- | --- | --- | --- |
| 服务器地址 | 是 | 非空，格式合法（域名/IP/TSDNS） | "请输入有效的服务器地址" |
| 昵称 | 是 | 非空，满足服务器命名规则 | "请输入昵称" |
| 密码 | 否 | 仅当服务器需要密码时必填 | "该服务器需要密码" |

#### 最近连接列表

- 点击列表项 → 自动填充地址/昵称/密码 → 触发连接
- 最多保存 10 条历史记录
- 按最近连接时间倒序排列
- 连接成功的服务器标记为绿色，失败的标记为红色（短暂）
- 长按可删除单条记录

---

### 2.2 频道列表页

> 对应流程：02 浏览频道 + 03 切换频道 + 08 状态同步

#### 布局

```
┌──────────────────────────────────────┐
│ 头部（三段）                          │
│ ┌────┐ ┌──────────────────┐ ┌─────┐ │
│ │ ☰  │ │ MyServer         │ │ 🟢  │ │
│ │服务│ │ 192.168.1.1:9987 │ │连接 │ │  ← 连接状态指示
│ │器卡│ │ 42人在线          │ │状态 │ │
│ └────┘ └──────────────────┘ └─────┘ │
├──────────────────────────────────────┤
│ 中部：频道树 + 成员                   │
│                                      │
│ ▼ 📁 默认频道                        │  ← 展开/折叠
│   ▼ 📁 大厅                          │
│     👤 Alice                         │  ← 点击弹出成员操作菜单
│     👤 Bob 🔇                        │  ← 🔇 = 正在发言
│     👤 Charlie 🎤                   │  ← 🎤 = 正在发言
│   ▶ 📁 游戏区 🔒                     │  ← 🔒 = 有密码
│     (3人)                            │  ← 折叠时显示人数
│   ▶ 📁 音乐区                        │
│     (1人)                            │
│ ▼ 📁 VIP 频道 🔒                     │
│   👤 Admin                           │
│                                      │
│  （频道列表支持滚动）                  │
├──────────────────────────────────────┤
│ 中部-底部：当前频道栏                 │
│ ┌──────────────────────────────────┐ │
│ │ 💬 大厅 (5人)  Alice🎤 Bob      │ │  ← 点击跳转到聊天页
│ └──────────────────────────────────┘ │
├──────────────────────────────────────┤
│ 底部：语音控制                        │
│ ┌──────┐ ┌────────────────┐ ┌─────┐ │
│ │ 🎤   │ │   PTT 按住发言  │ │ ⬆  │ │
│ │静音  │ │                │ │语音 │ │  ← 展开语音卡
│ └──────┘ └────────────────┘ └─────┘ │
└──────────────────────────────────────┘
```

#### 频道树交互

| 操作 | 行为 |
| --- | --- |
| 点击频道名 | 无密码 → 直接切换（发送 ClientMove） |
| 点击有密码频道 🔒 | 弹出频道密码对话框（见 4.2） |
| 点击折叠频道 ▶ | 展开显示子频道 |
| 点击展开频道 ▼ | 折叠子频道 |
| 长按频道 | 弹出频道操作菜单（频道信息） |
| 点击成员 👤 | 弹出成员操作菜单（见 4.3） |
| 点击当前频道栏 | 跳转到聊天页 |

#### 未读消息指示

| 状态 | 显示 | 说明 |
| --- | --- | --- |
| 无未读 | 正常显示 | — |
| 有未读消息 | 频道名右侧显示红点 ● | 弱未读提示 |
| 有未读 @提及 | 频道名右侧显示数字 badge | 强未读提示 |
| 当前所在频道 | 不显示未读标记 | 已在该频道 |

#### 初始同步加载态

连接成功进入频道列表页时，如果首次同步尚未完成：

```
┌──────────────────────────────┐
│          头部（正常）         │
├──────────────────────────────┤
│                              │
│     ⟳ 正在同步服务器数据...   │  ← 居中加载指示器
│                              │
├──────────────────────────────┤
│         底部（正常）          │
└──────────────────────────────┘
```

同步完成后自动切换为正常频道树视图。

---

### 2.3 聊天页

> 对应流程：04 文本消息

#### 布局

```
┌──────────────────────────────────────┐
│ 头部                                  │
│ ┌────┐ ┌──────────────────┐ ┌─────┐ │
│ │ ←  │ │ 大厅              │ │ ⋮  │ │
│ │返回│ │ 5人               │ │频道 │ │  ← 右侧弹出频道详情卡
│ │    │ │                  │ │详情 │ │
│ └────┘ └──────────────────┘ └─────┘ │
├──────────────────────────────────────┤
│ 中部：消息列表                        │
│                                      │
│ ┌──────────────────────────────────┐ │
│ │ Alice                     14:30  │ │
│ │ 大家好！                         │ │
│ ├──────────────────────────────────┤ │
│ │ Bob                        14:31 │ │
│ │ 你好 Alice！                      │ │
│ ├──────────────────────────────────┤ │
│ │ Charlie                   14:32  │ │
│ │ 有人一起打游戏吗？                │ │
│ ├──────────────────────────────────┤ │
│ │ 我                        14:33  │ │
│ │ 我来！                          │ │  ← 自己的消息靠右 / 不同颜色
│ └──────────────────────────────────┘ │
│                                      │
│  （消息列表支持滚动，新消息自动滚到底） │
├──────────────────────────────────────┤
│ 中部-底部：消息输入区                 │
│ ┌──────────────────────────┐ ┌────┐ │
│ │ 输入消息...               │ │ 发送│ │  ← 随输入法上抬
│ └──────────────────────────┘ └────┘ │
├──────────────────────────────────────┤
│ 底部：语音控制                        │
│ ┌──────┐ ┌────────────────┐ ┌─────┐ │
│ │ 🎤   │ │   PTT 按住发言  │ │ ⬆  │ │
│ │静音  │ │                │ │语音 │ │
│ └──────┘ └────────────────┘ └─────┘ │
└──────────────────────────────────────┘
```

#### 消息显示格式

```
发送者名称                   发送时间
消息内容
```

- 自己的消息靠右对齐或使用不同背景色区分
- 支持长按消息弹出操作菜单（复制 / Poke 发送者）
- 新消息到达时自动滚动到底部
- 如果用户正在查看历史消息，新消息到达时显示 "↓ 新消息" 提示条

#### 消息输入区与键盘联动

- 点击输入框 → 唤起输入法 → 输入区 + 发送按钮随键盘上抬
- 语音控制栏保持固定在底部，不受键盘影响
- 发送消息后输入框清空，保持键盘打开状态
- 输入框为空时发送按钮置灰不可点击

---

## 三、卡片详细设计

### 3.1 服务器详情卡

> 弹出方式：频道列表页头部左侧按钮触发，底部弹出 BottomSheet

```
┌──────────────────────────────┐
│        服务器详情         ✕   │
├──────────────────────────────┤
│                              │
│  服务器名                     │
│  My TeamSpeak Server         │
│                              │
│  服务器地址                   │
│  192.168.1.1:9987           │
│                              │
│  在线人数                     │
│  42 / 100                   │
│                              │
│  ┌──────────────────────────┐│
│  │     断开服务器            ││  ← 确认弹窗后执行 Disconnect
│  └──────────────────────────┘│
│                              │
└──────────────────────────────┘
```

#### 行为

- 断开服务器 → 弹出确认对话框 "确定要断开连接吗？" → 确认后执行断开 → 关闭卡片 → 返回服务器配置页
- 卡片数据来自首次同步结果和实时事件更新

---

### 3.2 频道详情卡

> 弹出方式：聊天页头部右侧按钮触发，底部弹出 BottomSheet

```
┌──────────────────────────────┐
│        频道详情          ✕   │
├──────────────────────────────┤
│                              │
│  频道名                      │
│  大厅                        │
│                              │
│  频道描述                     │
│  欢迎来到大厅频道，请遵守规则  │
│                              │
│  频道人数                     │
│  5人                         │
│                              │
└──────────────────────────────┘
```

#### 行为

- 如果频道无描述，显示 "暂无描述"
- 有密码频道在频道名旁显示 🔒 图标

---

### 3.3 语音卡

> 弹出方式：频道列表页 / 聊天页底部语音控制区 "展开" 按钮  
> 激活时机：进入频道后即激活，除服务器配置页外任意页面可弹出

```
┌──────────────────────────────┐
│        语音控制          ✕   │
├──────────────────────────────┤
│                              │
│  正在发言                     │
│  ┌──────────────────────────┐│
│  │ 🎤 Charlie  ▓▓▓▓░░ -12dB││  ← 音量波形指示
│  │ 🎤 Alice    ▓▓░░░░ -24dB││
│  └──────────────────────────┘│
│  （无人在发言时显示 "暂无发言"）│
│                              │
├──────────────────────────────┤
│                              │
│  频道内人员 (5)               │
│  ┌──────────────────────────┐│
│  │ 👤 Alice                 ││  ← 长按弹出操作菜单（Poke）
│  │ 👤 Bob                   ││
│  │ 👤 Charlie  🎤 发言中    ││  ← 发言中高亮
│  │ 👤 David                 ││
│  │ 👤 Eve                   ││
│  └──────────────────────────┘│
│  （人员超出时可滚动）          │
│                              │
├──────────────────────────────┤
│ 控制                          │
│ ┌──────────┐ ┌──────────────┐│
│ │ 🔊 扬声器 │ │ 🎙️ 降噪     ││
│ │  开 / 关  │ │  开 / 关     ││
│ └──────────┘ └──────────────┘│
│                              │
└──────────────────────────────┘
```

#### 行为

- 发言人栏实时显示正在发送语音帧的成员，附带音量波形指示
- 频道内人员列表支持滚动
- 长按成员 → 弹出操作菜单（Poke）
- 扬声器控制：切换本地音频输出开/关
- 降噪控制：切换本地降噪算法开/关

---

## 四、全局交互

### 4.1 Poke 交互

> 对应流程：02 浏览频道中的 "poke 服务器内成员" 和 "被 poke"

#### 发送 Poke

| 入口 | 操作 |
| --- | --- |
| 频道列表页成员列表 | 长按成员 → 弹出菜单 → Poke |
| 语音卡成员列表 | 长按成员 → 弹出菜单 → Poke |
| 聊天页消息列表 | 长按消息 → 弹出菜单 → Poke 发送者 |

发送后调用 SDK 的 Poke 方法，无需等待服务端确认。

#### 接收 Poke 通知

收到 `OnPoked` 事件时：

```
┌──────────────────────────────┐
│ ┌──────────────────────────┐ │
│ │ 🫴 Alice poke 了你       │ │  ← 顶部 Toast，3秒自动消失
│ │ "起床啦！"               │ │
│ └──────────────────────────┘ │
└──────────────────────────────┘
```

- Toast 从顶部滑入，3 秒后自动消失
- 如果在聊天页收到 Poke，同样显示 Toast（不自动跳转）

---

### 4.2 频道密码弹窗

> 对应流程：03 切换频道中的密码检查分支

点击有密码频道 🔒 时弹出：

```
┌──────────────────────────────┐
│                              │
│   该频道需要密码              │
│                              │
│   ┌────────────────────────┐ │
│   │ 输入频道密码            │ │
│   └────────────────────────┘ │
│                              │
│   ┌──────────┐ ┌──────────┐ │
│   │   取消    │ │   进入    │ │
│   └──────────┘ └──────────┘ │
│                              │
└──────────────────────────────┘
```

- 密码错误 → 按钮变为 "密码错误，重试" → 清空输入框 → 允许重新输入
- 点击取消 → 关闭弹窗，不发送 ClientMove
- 点击进入 → 发送 `ClientMove(selfID, targetID, password)`

---

### 4.3 成员点击行为

在频道列表页和语音卡中，点击/长按成员时弹出操作菜单：

```
┌──────────────────────────────┐
│  👤 Alice                    │
│  频道：大厅                   │
├──────────────────────────────┤
│  🫴 Poke                    │  → 发送 Poke
│  📋 复制昵称                 │  → 复制到剪贴板
└──────────────────────────────┘
```

---

### 4.4 主题切换

- 入口位置：服务器配置页右上角 🌙 图标
- 切换方式：点击在亮色/暗色主题间切换
- 持久化：选择保存到本地配置，下次启动自动应用
- 影响范围：全局所有页面和卡片

---

## 五、状态处理

### 5.1 连接状态

> 对应流程：01 连接服务器

#### 服务器配置页按钮状态

| 状态 | 按钮外观 | 说明 |
| --- | --- | --- |
| 空闲 | "连接服务器"（正常样式） | 等待用户输入并点击 |
| 连接中 | ⟳ "连接中..."（加载动画 + 禁用） | Connect + WaitConnected 进行中 |
| 连接失败 | "连接失败，点击重试"（红色 + 错误信息） | 显示具体失败原因（密码错误/超时/网络不可达） |
| 超时 | "连接超时，点击重试"（橙色） | WaitConnected 超时 |

#### 错误信息分类

| 错误类型 | 提示信息 | 建议操作 |
| --- | --- | --- |
| 密码错误 | "服务器密码错误" | 重新输入密码 |
| 昵称冲突 | "昵称已被使用，请更换" | 修改昵称 |
| 网络不可达 | "无法连接到服务器，请检查网络" | 检查网络后重试 |
| 地址无效 | "服务器地址无法解析" | 检查地址格式 |
| 超时 | "连接超时" | 检查网络后重试 |
| 服务器满 | "服务器已满" | 稍后重试 |

---

### 5.2 初始同步加载态

> 对应流程：08 状态同步 ① 首次同步

连接成功后进入频道列表页，首次同步期间：

- 频道树区域显示居中加载指示器 + "正在同步服务器数据..."
- 头部正常显示（但在线人数可能显示为 "--"）
- 底部语音控制区正常显示
- 同步完成后自动切换到正常频道树视图
- 同步失败 → 显示 "同步失败" + 重试按钮

---

### 5.3 被踢处理

> 对应流程：07 断开连接

被服务器踢出时（`OnKicked` 触发）：

```
┌──────────────────────────────┐
│                              │
│         你已被踢出            │
│                              │
│     原因：违反服务器规则       │  ← 显示踢出原因
│                              │
│     ┌────────────────────┐   │
│     │     重新连接        │   │
│     └────────────────────┘   │
│                              │
│     ┌────────────────────┐   │
│     │    返回主页         │   │
│     └────────────────────┘   │
│                              │
└──────────────────────────────┘
```

- 全屏覆盖提示，不可通过点击外部关闭
- "重新连接" → 使用相同参数重新连接
- "返回主页" → 回到服务器配置页
- 清理当前会话状态（频道、成员、消息）

---

### 5.4 断线重连

> 对应流程：07 断开连接

网络异常断开时（`OnDisconnected(error)` 触发）：

```
┌──────────────────────────────────────┐
│ ┌──────────────────────────────────┐ │
│ │ ⚠️ 连接已断开                    │ │  ← 顶部横幅
│ │ 正在尝试重连... (3/5)           │ │  ← 自动重连尝试计数
│ │              [手动重连] [放弃]   │ │
│ └──────────────────────────────────┘ │
└──────────────────────────────────────┘
```

- 顶部横幅提示，不阻塞底层页面（页面数据冻结）
- 自动重连：最多尝试 5 次，间隔递增（2s → 4s → 8s → 16s → 30s）
- 手动重连：用户主动触发立即重连
- 放弃：停止重连 → 显示完整断线提示（类似被踢处理） → 返回主页
- 重连成功 → 执行全量同步（08 状态同步 ⑥）→ 横幅消失 → 恢复正常

---

### 5.5 未读消息指示

> 对应流程：04 文本消息

#### 频道列表页

| 场景 | 显示 | 说明 |
| --- | --- | --- |
| 频道有新消息 | 频道名右侧显示红点 ● | 弱未读（用户不在该频道时） |
| 频道有 @提及 | 频道名右侧显示数字（如 3） | 强未读 |
| 当前所在频道 | 不显示 | 已在该频道，消息直接可见 |
| 用户进入频道后 | 清除该频道的未读标记 | 已读即清 |

---

## 六、页面与流程的对应关系

| 流程文件 | 主要承载页面 | 承载卡片 | 关键交互 |
| --- | --- | --- | --- |
| 01 连接服务器 | 服务器配置页 | — | 输入验证、连接按钮状态、最近连接快速连接 |
| 02 浏览频道 | 频道列表页 | 语音卡 | 频道树展开/折叠、成员列表、Poke、未读指示 |
| 03 切换频道 | 频道列表页 | — | 点击频道切换、密码弹窗、ClientMove 等待确认 |
| 04 文本消息 | 聊天页 | — | 消息列表、发送消息、未读归档 |
| 05 语音通信 | 频道列表页 + 聊天页 | 语音卡 | PTT 按钮、静音控制、发言人指示 |
| 06 文件传输 | — | — | 本应用不实现 |
| 07 断开连接 | 全屏覆盖 | 服务器详情卡 | 断开确认、被踢提示、断线重连横幅 |
| 08 状态同步 | 所有页面 | — | 首次同步加载、增量更新、补偿同步、重连全量同步 |