📝 docs(architecture): 创建stt-demo现有系统架构文档

- 记录系统当前状态，包括技术债务、工作变通方案和实际使用模式
- 详细列出关键文件和入口点，便于AI代理理解系统结构
- 总结高层架构、技术栈和源码组织结构
- 记录数据模型、API规范、技术债务和已知问题
- 提供开发部署流程、测试现状和常用命令参考

docs/brownfield-architecture.md

@@ -0,0 +1,245 @@
+# 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请求封装便于维护