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)

源码树和模块组织

项目结构（实际）

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() - 更新任务配置

技术债务和已知问题

关键技术债务

全局状态管理: src/store/reducers/global.ts 包含过多状态，可能需要拆分
管理器依赖: RTC、RTM、STT管理器之间存在循环依赖关系
事件监听: 事件监听器在组件卸载时清理不够完善
错误处理: 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进行页面导航

开发和部署

本地开发设置

环境要求: Node.js 18+，npm或yarn
安装依赖: npm install 或 yarn install
环境配置: 复制 .env 文件并配置Agora App ID和Certificate
启动开发: npm run dev 或 yarn dev
访问应用: 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方法

运行测试

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

附录 - 有用命令和脚本

常用命令

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服务权限已开通，环境变量配置正确

系统特性总结

核心功能

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

技术特点

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

扩展性考虑

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

brownfield-architecture.md 9.2 KB Pysyvä linkki Historia Raaka

stt-demo 现有系统架构文档

介绍

文档范围

变更日志

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

理解系统的关键文件

高层架构

技术总结

实际技术栈

仓库结构实际情况

源码树和模块组织

项目结构（实际）

关键模块及其用途

数据模型和API

数据模型

API规范

技术债务和已知问题

关键技术债务

工作变通方案和注意事项

集成点和外部依赖

外部服务

内部集成点

开发和部署

本地开发设置

构建和部署流程

测试现状

当前测试覆盖

运行测试

附录 - 有用命令和脚本

常用命令

调试和故障排除

系统特性总结

核心功能

技术特点

扩展性考虑

brownfield-architecture.md 9.2 KB

Pysyvä linkki Historia Raaka