# stt-demo 系统架构文档 v4

## 概述

stt-demo 是一个基于 Agora RTC/RTM 的实时语音转文字 Web 应用，支持多语言实时转录和翻译功能。

### 系统目标

- 提供高质量的实时音视频通信
- 实现准确的语音转文字功能
- 支持多语言实时翻译
- 提供友好的用户界面和交互体验

### 架构原则

- **模块化**: 采用管理器模式分离关注点
- **事件驱动**: 基于事件系统实现松耦合通信
- **状态集中**: 使用 Redux 管理全局状态
- **类型安全**: 全面使用 TypeScript
- **性能优先**: 优化音视频流处理和渲染

## 技术架构

### 前端架构

#### 技术栈

- **框架**: React 18 + TypeScript
- **状态管理**: Redux Toolkit
- **构建工具**: Vite
- **UI组件**: Ant Design
- **路由**: React Router DOM
- **国际化**: i18next

#### 核心架构模式

**管理器模式**: 将复杂业务逻辑封装在独立的管理器中

- RtcManager: 音视频通信管理
- RtmManager: 实时消息管理
- SttManager: 语音转文字管理

**事件驱动**: 管理器间通过自定义事件系统通信
**组件分层**: 页面组件 → 业务组件 → 基础组件

### 后端集成架构

#### Agora 服务集成

- **Agora RTC**: 实时音视频通信
- **Agora RTM**: 实时消息传递
- **Agora STT**: 语音转文字服务

#### API 设计

- RESTful API 设计
- Token 认证机制
- 错误处理标准化

## 数据流架构

### 音视频数据流

```
麦克风/摄像头 → RTC SDK → 网络传输 → 远端用户
```

### 语音转文字数据流

```
音频流 → STT 服务 → 文字结果 → RTM 通道 → 界面显示
```

### 状态数据流

```
用户操作 → Redux Action → Reducer → Store → 组件更新
```

## 部署架构

### 开发环境

- Vite 开发服务器 (端口 8080)
- 热重载支持
- TypeScript 类型检查

### 生产环境

- Vite 构建优化
- 静态资源 CDN
- 环境变量配置

## 测试策略

### 测试框架

- **单元测试**: Vitest 3.2.4 + Testing Library 16.3.0
- **端到端测试**: Playwright 1.55.0
- **测试覆盖**: 核心功能80%以上覆盖率目标

### 测试层级

- **单元测试**: 管理器类、工具函数、自定义Hooks
- **集成测试**: 组件与状态管理集成、管理器协作
- **E2E测试**: 完整用户流程、音视频功能验证

详细测试策略参见: [测试策略文档](architecture/testing-strategy.md)

## 扩展性设计

### 水平扩展

- 组件化设计支持功能模块添加
- 管理器模式便于新业务逻辑集成
- 配置驱动支持不同部署环境

### 性能优化

- 音视频流优化处理
- 虚拟滚动支持大量字幕显示
- 懒加载优化首屏性能

---

_本文档为架构文档主文件，详细的分片文档请参考 docs/architecture/ 目录_