- tscore: Protocol implementation (packets, crypto, connection handshake)
- tsaudio: Audio engine (capture, playback, codec, VAD, jitter buffer)
- tsdb: SQLite database (identities, bookmarks, messages, settings)
- shared: Core types and events
- tauri-app: Tauri v2 desktop application with React frontend
- docs: SRS, SAD, SDD documentation
- CI/CD: GitHub Actions workflow
- 32 unit tests passing

2026-05-12 14:41:54 +09:00

12 KiB

Raw Blame History

需求分析文档 (SRS)

1. 概述

本文档定义 TeamSpeak 3 客户端系统的功能需求和非功能需求，基于对参考代码库的分析和 TeamSpeak 3 协议规范。

2. 系统目标

2.1 主要目标

实现一个功能完整的 TeamSpeak 3 客户端
支持跨平台运行 (Windows, Linux, macOS, Android, Web)
提供现代化的用户界面
保持与官方 TeamSpeak 服务器的兼容性
支持音频通信和文本聊天

2.2 次要目标

支持插件扩展机制
提供统计和分析功能
支持多服务器同时连接
提供机器人开发框架

3. 功能需求

3.1 连接管理

FR-3.1.1 服务器连接

描述: 用户能够连接到 TeamSpeak 3 服务器

需求:

支持通过 IP 地址连接
支持通过域名连接
支持通过服务器昵称连接
支持 DNS SRV 和 TSDNS 解析
支持服务器密码验证
支持身份选择和管理
支持默认频道设置
支持频道密码

输入:

服务器地址 (IP/域名/昵称)
服务器密码 (可选)
身份 (可选)
昵称
默认频道 (可选)
频道密码 (可选)

输出:

连接成功/失败状态
服务器信息
客户端 ID

FR-3.1.2 连接状态管理

描述: 管理连接的生命周期状态

状态:

Uninitialized: 未初始化
Connecting: 连接中
IdentityLevelIncreasing: 身份等级提升中
Connected: 已连接
ChannelListFinished: 频道列表接收完成
DisconnectedTemporarily: 临时断开
Disconnected: 已断开
Error: 错误

需求:

状态转换应有明确的触发条件
状态变化应通知前端
支持自动重连（临时断开时）
支持手动断开连接

FR-3.1.3 多服务器连接

描述: 支持同时连接多个 TeamSpeak 服务器

需求:

每个连接独立管理
连接间互不影响
支持连接切换
支持连接列表管理

3.2 频道管理

FR-3.2.1 频道浏览

描述: 浏览服务器的频道结构

需求:

显示频道树状结构
显示频道名称、主题、编解码器
显示频道最大客户端数
显示频道类型（永久/半永久/临时）
显示频道密码状态
支持频道搜索

FR-3.2.2 频道操作

描述: 执行频道相关操作

需求:

加入频道
离开频道
创建频道（需要权限）
编辑频道（需要权限）
删除频道（需要权限）
移动频道（需要权限）
设置频道密码
设置频道排序

FR-3.2.3 频道订阅

描述: 订阅频道以接收通知

需求:

订阅频道
取消订阅频道
接收频道事件通知
显示订阅状态

3.3 客户端管理

FR-3.3.1 客户端列表

描述: 显示在线客户端列表

需求:

显示客户端昵称
显示客户端状态（离开/录音/静音等）
显示客户端所在频道
显示客户端服务器组
显示客户端频道组
支持客户端搜索

FR-3.3.2 客户端操作

描述: 执行客户端相关操作

需求:

发送私聊消息
发送戳一戳
移动客户端（需要权限）
踢出客户端（需要权限）
封禁客户端（需要权限）
设置客户端音量
设置客户端静音

FR-3.3.3 客户端信息

描述: 查看客户端详细信息

需求:

显示客户端唯一标识符
显示客户端数据库 ID
显示客户端版本信息
显示客户端平台
显示客户端连接信息
显示客户端权限

3.4 文本聊天

FR-3.4.1 消息发送

描述: 发送文本消息

需求:

发送服务器消息
发送频道消息
发送私聊消息
支持 BBCode 格式
支持消息历史
支持消息撤回（如果服务器支持）

FR-3.4.2 消息接收

描述: 接收和显示文本消息

需求:

显示服务器消息
显示频道消息
显示私聊消息
显示系统通知
支持消息通知
支持消息过滤

FR-3.4.3 消息存储

描述: 存储聊天历史

需求:

本地存储消息历史
支持消息搜索
支持消息导出
支持消息清理

3.5 音频通信

FR-3.5.1 音频输入

描述: 捕获和处理麦克风音频

需求:

支持音频设备选择
支持音频编码 (Opus)
支持语音活动检测 (VAD)
支持推按说话 (PTT)
支持输入音量调节
支持输入静音
支持噪声抑制
支持回声消除

FR-3.5.2 音频输出

描述: 播放接收到的音频

需求:

支持音频设备选择
支持音频解码 (Opus)
支持输出音量调节
支持输出静音
支持每客户端音量
支持音频混音
支持抖动缓冲
支持丢包隐藏

FR-3.5.3 音频路由

描述: 管理音频数据的路由

需求:

支持频道音频
支持私语
支持组私语
支持频道指挥官
支持优先发言者
支持音频编码质量设置

3.6 文件传输

FR-3.6.1 文件浏览

描述: 浏览频道文件

需求:

显示文件列表
显示文件大小
显示文件修改时间
支持文件搜索
支持目录创建

FR-3.6.2 文件上传

描述: 上传文件到频道

需求:

支持单文件上传
支持多文件上传
支持断点续传
支持上传进度显示
支持上传取消

FR-3.6.3 文件下载

描述: 下载频道文件

需求:

支持单文件下载
支持多文件下载
支持断点续传
支持下载进度显示
支持下载取消

3.7 身份管理

FR-3.7.1 身份创建

描述: 创建新的 TeamSpeak 身份

需求:

自动生成 ECC 密钥对
支持身份命名
支持身份导出
支持身份导入

FR-3.7.2 身份存储

描述: 安全存储身份信息

需求:

加密存储私钥
支持多身份管理
支持身份备份
支持身份恢复

FR-3.7.3 身份验证

描述: 使用身份进行验证

需求:

支持 Hashcash 计算
支持身份等级提升
支持权限令牌
支持身份唯一标识符计算

3.8 权限管理

FR-3.8.1 权限查看

描述: 查看权限信息

需求:

显示服务器组权限
显示频道组权限
显示客户端权限
显示权限值
显示权限描述

FR-3.8.2 权限操作

描述: 执行权限相关操作

需求:

添加权限（需要权限）
删除权限（需要权限）
修改权限（需要权限）
添加服务器组客户端
删除服务器组客户端

3.9 服务器管理

FR-3.9.1 服务器信息

描述: 查看服务器信息

需求:

显示服务器名称
显示服务器版本
显示服务器平台
显示在线客户端数
显示频道数
显示服务器运行时间
显示服务器加密模式

FR-3.9.2 服务器操作

描述: 执行服务器相关操作

需求:

修改服务器密码（需要权限）
修改服务器名称（需要权限）
查看服务器日志（需要权限）
发送服务器消息（需要权限）

3.10 热键管理

FR-3.10.1 热键配置

描述: 配置全局热键

需求:

支持输入静音切换
支持输出静音切换
支持离开状态切换
支持推按说话
支持自定义热键

FR-3.10.2 热键执行

描述: 执行热键绑定的操作

需求:

全局热键支持
应用内热键支持
热键冲突检测
热键状态反馈

3.11 设置管理

FR-3.11.1 应用设置

描述: 管理应用程序设置

需求:

用户界面设置
音频设备设置
热键设置
通知设置
语言设置
主题设置

FR-3.11.2 连接设置

描述: 管理连接相关设置

需求:

默认昵称
默认身份
默认频道
自动重连设置
音频编码设置

3.12 插件系统

FR-3.12.1 插件加载

描述: 加载和管理插件

需求:

支持动态加载插件
支持插件启用/禁用
支持插件配置
支持插件更新

FR-3.12.2 插件接口

描述: 提供插件开发接口

需求:

事件监听接口
命令注册接口
UI 扩展接口
数据访问接口

4. 非功能需求

4.1 性能需求

NFR-4.1.1 连接性能

连接建立时间 < 3 秒
消息延迟 < 100ms
音频延迟 < 200ms
支持 1000+ 客户端的服务器

NFR-4.1.2 资源使用

CPU 使用率 < 10% (空闲时)
内存使用 < 200MB
网络带宽 < 1Mbps (语音通信时)
磁盘空间 < 100MB (应用程序)

NFR-4.1.3 并发性能

支持 10+ 同时连接
支持 100+ 消息/秒
支持 50+ 音频流同时播放

4.2 可靠性需求

NFR-4.2.1 连接可靠性

支持自动重连
支持断点续传
支持数据包重传
支持拥塞控制

NFR-4.2.2 数据可靠性

消息不丢失
文件传输完整性
身份数据安全
配置数据备份

4.3 安全性需求

NFR-4.3.1 传输安全

使用 AES-128-EAX 加密
使用 ECDH 密钥交换
支持证书验证
防止中间人攻击

NFR-4.3.2 数据安全

私钥加密存储
敏感数据不落盘
安全内存处理
防止内存泄露

NFR-4.3.3 访问控制

身份验证
权限检查
操作审计
防止未授权访问

4.4 可用性需求

NFR-4.4.1 用户界面

响应式设计
键盘导航支持
屏幕阅读器支持
高对比度模式

NFR-4.4.2 国际化

支持多语言
支持 RTL 布局
支持本地化日期格式
支持本地化数字格式

NFR-4.4.3 可访问性

支持字体大小调整
支持颜色主题切换
支持快捷键自定义
支持语音反馈

4.5 可维护性需求

NFR-4.5.1 代码质量

模块化设计
清晰的接口定义
完整的文档
单元测试覆盖

NFR-4.5.2 日志和监控

详细的日志记录
错误报告机制
性能监控
使用统计

4.6 可扩展性需求

NFR-4.6.1 架构扩展

支持插件系统
支持自定义主题
支持自定义命令
支持自定义通知

NFR-4.6.2 协议扩展

支持协议版本协商
支持功能特性检测
支持向后兼容
支持向前兼容

5. 约束条件

5.1 技术约束

使用 Rust 作为主要开发语言
使用 Tauri v2 作为桌面框架
使用 Svelte 5 作为前端框架
使用 Actix 作为 Actor 框架
使用 SQLite 作为本地数据库

5.2 协议约束

兼容 TeamSpeak 3 协议
支持 IPv4 和 IPv6
使用 UDP 传输
最大数据包大小 500 字节

5.3 法律约束

不得侵犯 TeamSpeak 商标
不得用于商业用途（除非获得许可）
遵守相关法律法规
尊重用户隐私

6. 验收标准

6.1 功能验收

能够连接到官方 TeamSpeak 服务器
能够发送和接收文本消息
能够进行语音通信
能够浏览和管理频道
能够管理客户端

6.2 性能验收

连接建立时间 < 3 秒
消息延迟 < 100ms
音频延迟 < 200ms
CPU 使用率 < 10% (空闲时)

6.3 安全验收

通过安全审计
无已知漏洞
数据加密存储
传输加密验证

6.4 兼容性验收

Windows 10/11 兼容
Linux (Ubuntu 20.04+) 兼容
macOS 11+ 兼容
Android 10+ 兼容
Chrome/Firefox/Safari 兼容

7. 术语表

术语	定义
TeamSpeak	一种 VoIP 应用程序，用于语音通信
Channel	语音/文本通信的房间
Client	连接到服务器的用户或机器人
Server	TeamSpeak 服务器实例
Identity	用户的唯一标识符
Permission	用户的操作权限
Codec	音频编码格式
Opus	现代音频编解码器
ECDH	椭圆曲线 Diffie-Hellman 密钥交换
AES	高级加密标准
EAX	认证加密模式
Hashcash	工作量证明系统
VAD	语音活动检测
PTT	推按说话
TSDNS	TeamSpeak DNS 服务
SRV	DNS 服务记录

8. 参考文献

TeamSpeak 3 协议规范 (ts3protocol.md)
tsdeclarations 项目文档
tsclientlib 项目文档
Qint 项目文档
SimpleBot 项目文档
ts3stats 项目文档

12 KiB Raw Blame History