# stt-demo 现有系统架构文档

## 介绍

本文档记录了 stt-demo 项目的当前状态，包括技术债务、工作变通方案和实际使用模式。它作为AI代理进行增强开发的参考文档。

### 文档范围

全面记录整个系统的文档化

### 变更日志

| 日期       | 版本 | 描述             | 作者    |
| ---------- | ---- | ---------------- | ------- |
| 2025-09-25 | 1.0  | 初始现有系统分析 | Winston |

## 快速参考 - 关键文件和入口点

### 理解系统的关键文件

- **主入口**: `src/main.tsx` - React应用启动文件
- **应用入口**: `src/App.tsx` - 根组件
- **路由配置**: `src/router/index.tsx` - 路由定义
- **状态管理**: `src/store/index.ts` - Redux store配置
- **全局状态**: `src/store/reducers/global.ts` - 全局状态管理
- **核心管理器**: `src/manager/` - RTC、RTM、STT管理器
- **页面组件**: `src/pages/` - 主要页面组件
- **通用工具**: `src/common/` - 工具函数和hooks
- **类型定义**: `src/types/index.ts` - TypeScript类型定义

## 高层架构

### 技术总结

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

### 实际技术栈

| 类别     | 技术             | 版本   | 备注               |
| -------- | ---------------- | ------ | ------------------ |
| 运行时   | Node.js          | 18+    | 开发环境要求       |
| 前端框架 | React            | 18.2.0 | 函数式组件 + Hooks |
| 状态管理 | Redux Toolkit    | 1.6.2  | 简化Redux使用      |
| 构建工具 | Vite             | 5.0.8  | 快速开发构建       |
| UI组件库 | Ant Design       | 5.15.3 | 企业级UI组件       |
| 实时通信 | Agora RTC SDK    | 4.20.0 | 音视频通信         |
| 实时消息 | Agora RTM        | 2.1.9  | 实时消息传递       |
| 国际化   | i18next          | 23.8.2 | 多语言支持         |
| 路由     | React Router DOM | 6.21.3 | 单页面应用路由     |
| 类型系统 | TypeScript       | 5.2.2  | 类型安全           |

### 仓库结构实际情况

- 类型: 单仓库前端应用
- 包管理器: npm (package.json中显示yarn，但实际使用npm)
- 构建系统: Vite + TypeScript
- 开发服务器: Vite dev server (端口8080)

## 源码树和模块组织

### 项目结构（实际）

```text
stt-demo/
├── src/
│   ├── components/          # 可复用UI组件
│   │   ├── avatar/         # 用户头像组件
│   │   ├── caption/        # 字幕显示组件
│   │   ├── center-area/    # 主视频区域
│   │   ├── dialog/         # 对话框组件
│   │   ├── footer/         # 底部控制栏
│   │   ├── header/         # 顶部导航栏
│   │   ├── icons/          # 图标组件
│   │   ├── menu/           # 侧边菜单
│   │   ├── stream-player/  # 视频流播放器
│   │   └── user-list/      # 用户列表
│   ├── pages/              # 页面组件
│   │   ├── 404/           # 404页面
│   │   ├── home/          # 主页面（音视频通话）
│   │   └── login/         # 登录页面
│   ├── manager/            # 核心业务逻辑管理器
│   │   ├── events.ts      # 事件系统
│   │   ├── parser/        # 数据解析器
│   │   ├── rtc/           # RTC音视频管理
│   │   ├── rtm/           # RTM实时消息管理
│   │   └── stt/           # 语音转文字管理
│   ├── store/             # 状态管理
│   │   └── reducers/      # Redux reducers
│   ├── common/            # 通用工具
│   │   ├── hooks.ts       # 自定义React Hooks
│   │   ├── request.ts     # API请求封装
│   │   ├── utils.ts       # 工具函数
│   │   └── storage.ts     # 本地存储
│   ├── i18n/              # 国际化配置
│   ├── router/            # 路由配置
│   ├── types/             # TypeScript类型定义
│   ├── protobuf/          # Protobuf定义
│   └── styles/            # 样式文件
├── public/                # 静态资源
├── docs/                  # 文档目录（新创建）
└── 配置文件...
```

### 关键模块及其用途

- **RTC管理器**: `src/manager/rtc/rtc.ts` - 处理音视频通话连接、发布/订阅流
- **RTM管理器**: `src/manager/rtm/rtm.ts` - 处理实时消息、用户状态同步
- **STT管理器**: `src/manager/stt/stt.ts` - 语音转文字任务管理
- **全局状态**: `src/store/reducers/global.ts` - 管理用户信息、UI状态、STT数据
- **主页面**: `src/pages/home/index.tsx` - 音视频通话主界面，集成所有管理器
- **登录页面**: `src/pages/login/index.tsx` - 用户登录和频道加入

## 数据模型和API

### 数据模型

参考实际类型定义文件：

- **用户信息**: 参见 `src/types/index.ts` 中的 `IUserInfo` 接口
- **STT数据**: 参见 `src/types/index.ts` 中的 `ISttData` 接口
- **字幕项**: 参见 `src/types/index.ts` 中的 `ITextItem` 接口
- **选项配置**: 参见 `src/types/index.ts` 中的 `IOptions` 接口

### API规范

项目使用Agora的REST API进行语音转文字服务：

- **Token获取**: `apiGetAgoraToken()` - 获取Agora RTC token
- **STT启动**: `apiSTTStartTranscription()` - 启动语音转文字任务
- **STT停止**: `apiSTTStopTranscription()` - 停止语音转文字任务
- **STT查询**: `apiSTTQueryTranscription()` - 查询任务状态
- **STT更新**: `apiSTTUpdateTranscription()` - 更新任务配置

## 技术债务和已知问题

### 关键技术债务

1. **全局状态管理**: `src/store/reducers/global.ts` 包含过多状态，可能需要拆分
2. **管理器依赖**: RTC、RTM、STT管理器之间存在循环依赖关系
3. **事件监听**: 事件监听器在组件卸载时清理不够完善
4. **错误处理**: API错误处理较为简单，需要增强

### 工作变通方案和注意事项

- **环境变量**: 必须设置正确的Agora App ID和Certificate才能正常运行
- **端口配置**: 开发服务器使用8080端口，需要确保端口可用
- **浏览器兼容**: 依赖现代浏览器特性，需要Chrome/Firefox/Safari较新版本
- **Agora服务**: 需要开通Agora RTC、RTM和语音转文字服务权限

## 集成点和外部依赖

### 外部服务

| 服务      | 用途       | 集成类型 | 关键文件                |
| --------- | ---------- | -------- | ----------------------- |
| Agora RTC | 音视频通信 | SDK      | `src/manager/rtc/`      |
| Agora RTM | 实时消息   | SDK      | `src/manager/rtm/`      |
| Agora STT | 语音转文字 | REST API | `src/common/request.ts` |

### 内部集成点

- **组件通信**: 通过Redux store进行状态共享
- **事件系统**: 使用自定义事件系统进行管理器间通信
- **国际化**: 通过i18next进行多语言支持
- **路由导航**: React Router进行页面导航

## 开发和部署

### 本地开发设置

1. **环境要求**: Node.js 18+，npm或yarn
2. **安装依赖**: `npm install` 或 `yarn install`
3. **环境配置**: 复制 `.env` 文件并配置Agora App ID和Certificate
4. **启动开发**: `npm run dev` 或 `yarn dev`
5. **访问应用**: http://localhost:8080

### 构建和部署流程

- **构建命令**: `npm run build` (Vite构建配置在 `vite.config.ts`)
- **测试构建**: `npm run build:test`
- **预览**: `npm run preview`
- **代码检查**: `npm run lint`
- **代码格式化**: `npm run prettier`

## 测试现状

### 当前测试覆盖

- **单元测试**: 未发现测试文件，需要补充
- **集成测试**: 无
- **E2E测试**: 无
- **手动测试**: 主要QA方法

### 运行测试

```bash
npm run lint    # 代码检查
# 需要添加测试脚本
```

## 附录 - 有用命令和脚本

### 常用命令

```bash
npm run dev         # 启动开发服务器
npm run build       # 生产构建
npm run preview     # 预览生产构建
npm run lint        # 代码检查
npm run lint:fix    # 自动修复代码问题
npm run prettier    # 代码格式化
```

### 调试和故障排除

- **开发工具**: 使用浏览器开发者工具进行调试
- **日志输出**: 控制台输出调试信息，使用 `console.log`
- **网络检查**: 检查Agora API调用和WebSocket连接
- **常见问题**: 确保Agora服务权限已开通，环境变量配置正确

## 系统特性总结

### 核心功能

1. **实时音视频通话**: 基于Agora RTC的多用户音视频通信
2. **语音转文字**: 实时语音识别和文字转录
3. **多语言翻译**: 支持实时语音翻译
4. **字幕显示**: 实时显示语音转文字结果
5. **用户管理**: 多用户在线状态管理
6. **国际化**: 中英文界面支持

### 技术特点

- **模块化设计**: 管理器模式分离业务逻辑
- **事件驱动**: 自定义事件系统处理组件通信
- **状态集中**: Redux管理全局应用状态
- **类型安全**: TypeScript提供类型检查
- **现代构建**: Vite提供快速开发和构建体验

### 扩展性考虑

- **组件化**: React组件便于复用和扩展
- **管理器模式**: 新功能可以通过添加管理器实现
- **配置驱动**: 环境变量和配置支持不同环境
- **API封装**: 统一的API请求封装便于维护