📝 docs(story): 更新Agora实时语音转录翻译集成需求文档

- 修改Story标题，明确包含前端组件和后端Token路由
- 更新角色和目标描述，从仅前端扩展为完整解决方案
- 新增3项验收标准，包括Token路由实现、前端集成和安全认证
- 添加后端开发任务和子任务，完善项目结构指导
- 补充Token集成详细说明，包括实现步骤和代码示例
- 增加安全考虑和测试场景，覆盖前后端完整流程
- 更新变更日志和开发记录，反映最新需求变更

docs/stories/005.001.story.md

@@ -1,4 +1,4 @@
-# Story 005.001: Agora实时语音转录翻译前端组件集成
+# Story 005.001: Agora实时语音转录翻译完整集成（前端组件 + 后端Token路由）
 
 **父史诗**: 史诗005 - Agora实时语音转录翻译集成
 docs/prd/epic-005-agora-real-time-speech-transcription.md
@@ -10,9 +10,9 @@ In Development
 High - 新功能实现，增强用户体验
 
 ## Story
-**As a** 前端开发者
-**I want** 集成Agora实时语音转文字前端组件
-**so that** 我可以在管理后台中提供语音输入转文字功能，增强用户体验和多媒体处理能力
+**As a** 系统开发者
+**I want** 集成Agora实时语音转文字完整解决方案
+**so that** 我可以在管理后台中提供安全的语音输入转文字功能，包括前端组件和后端Token动态获取能力
 
 ## Acceptance Criteria
 1. 实现Agora STT React组件 - 组件功能完整，支持加入/离开频道操作，符合前端规范设计
@@ -22,6 +22,9 @@ High - 新功能实现，增强用户体验
 5. 响应式设计实现 - 移动端单列、平板两列、桌面端三列布局适配
 6. 无障碍功能支持 - 键盘导航、屏幕阅读器兼容、色彩对比度符合WCAG 2.1 AA
 7. 测试覆盖和性能验证 - 组件测试覆盖率>80%，响应延迟<2秒，动画流畅60fps
+8. 实现Agora Token动态获取后端路由 - 提供安全的Token生成API，支持RTC和RTM两种类型
+9. 前端集成Token动态获取 - 组件自动从后端获取Token，避免硬编码敏感信息
+10. 安全认证集成 - Token路由集成现有JWT认证系统，确保只有授权用户可访问
 
 ## Tasks / Subtasks
 - [x] 创建Agora STT React组件 (AC: #1)
@@ -53,6 +56,22 @@ High - 新功能实现，增强用户体验
   - [x] 验证转录延迟和准确率
   - [x] 性能基准测试和优化
   - [ ] 创建E2E测试文件
+- [ ] 实现Agora Token动态获取后端路由 (AC: #8)
+  - [ ] 创建Agora Token生成服务模块
+  - [ ] 实现RTC Token生成路由（用于STT功能）
+  - [ ] 实现RTM Token生成路由（用于实时消息）
+  - [ ] 集成现有JWT认证中间件
+  - [ ] 实现参数验证和错误处理
+  - [ ] 编写路由单元测试和集成测试
+- [ ] 前端集成Token动态获取 (AC: #9)
+  - [ ] 修改前端组件使用动态Token获取
+  - [ ] 实现Token过期自动刷新机制
+  - [ ] 更新前端配置管理
+  - [ ] 测试Token获取和刷新流程
+- [ ] 安全认证集成 (AC: #10)
+  - [ ] 验证Token路由的认证保护
+  - [ ] 测试权限控制机制
+  - [ ] 确保敏感配置安全存储
 
 ## Dev Notes
 
@@ -62,58 +81,81 @@ High - 新功能实现，增强用户体验
 - **WebSocket**: 浏览器原生WebSocket API
 - **音频处理**: MediaRecorder API
 - **测试框架**: Vitest + Testing Library
+- **后端框架**: Hono 4.8.5 + TypeORM
+- **认证系统**: JWT Bearer Token
+- **API设计**: OpenAPI规范，RESTful风格
 
 ### 项目结构指导 [Source: architecture/source-tree.md]
-- **组件位置**: `src/client/admin/components/agora-stt/` (管理后台专用组件 - 基于架构文档分析)
-- **测试位置**: `src/client/admin/components/agora-stt/__tests__/`
-- **类型定义**: `src/client/types/agora-stt.ts`
-- **工具函数**: `src/client/utils/agora-stt.ts`
+- **前端组件位置**: `src/client/admin/components/agora-stt/` (管理后台专用组件)
+- **后端路由位置**: `src/server/api/agora/` (Agora相关API路由)
+- **服务模块位置**: `src/server/modules/agora/` (Agora业务逻辑模块)
+- **测试位置**: `src/client/admin/components/agora-stt/__tests__/` 和 `src/server/api/agora/__tests__/`
+- **类型定义**: `src/client/types/agora-stt.ts` 和 `src/server/types/agora.ts`
+- **工具函数**: `src/client/utils/agora-stt.ts` 和 `src/server/utils/agora-token.ts`
 
 ### Agora配置参数 [Source: docs/agora实时语音转录翻译参考文档.md]
 ```typescript
-// 使用全局配置安全访问（通过服务器端注入）
+// 前端配置 - 使用全局配置安全访问（通过服务器端注入）
 import { getGlobalConfig } from '@/client/utils/utils';
 
 const AGORA_CONFIG = {
   appId: getGlobalConfig('AGORA_APP_ID'),
-  primaryCert: getGlobalConfig('AGORA_PRIMARY_CERT'),
-  token: getGlobalConfig('AGORA_TOKEN'),
   channel: getGlobalConfig('AGORA_CHANNEL') || '123',
-  key: getGlobalConfig('AGORA_KEY'),
-  secret: getGlobalConfig('AGORA_SECRET'),
   sttJoinUrl: getGlobalConfig('AGORA_STT_JOIN_URL') || 'https://api.agora.io/v7/rtm/stt/join',
-  sttWsUrl: getGlobalConfig('AGORA_STT_WS_URL') || 'wss://api.agora.io/v7/rtm/stt/connect'
+  sttWsUrl: getGlobalConfig('AGORA_STT_WS_URL') || 'wss://api.agora.io/v7/rtm/stt/connect',
+  tokenEndpoint: '/api/v1/agora/token' // 动态Token获取端点
+};
+
+// 后端配置 - 使用环境变量安全存储
+const AGORA_SERVER_CONFIG = {
+  appId: process.env.AGORA_APP_ID || '',
+  appSecret: process.env.AGORA_APP_SECRET || '',
+  tokenExpiry: parseInt(process.env.AGORA_TOKEN_EXPIRY || '3600'),
+  primaryCert: process.env.AGORA_PRIMARY_CERT || ''
 };
 ```
 
 ### 核心功能流程
 1. **初始化阶段**: 组件挂载，准备Agora配置
-2. **加入频道**: 调用Agora STT API加入语音转文字频道
-3. **WebSocket连接**: 建立WebSocket连接接收实时转录结果
-4. **麦克风激活**: 申请浏览器麦克风权限并开始录制
-5. **实时转录**: 发送音频流，接收并显示转录结果
-6. **离开频道**: 清理资源，关闭连接
+2. **Token获取**: 调用后端API动态获取Agora Token
+3. **加入频道**: 使用动态Token调用Agora STT API加入语音转文字频道
+4. **WebSocket连接**: 建立WebSocket连接接收实时转录结果
+5. **麦克风激活**: 申请浏览器麦克风权限并开始录制
+6. **实时转录**: 发送音频流，接收并显示转录结果
+7. **Token刷新**: 监听Token过期，自动刷新Token
+8. **离开频道**: 清理资源，关闭连接
 
 ### 技术约束和要求
 - **兼容性**: 支持Chrome、Edge等现代浏览器
 - **HTTPS要求**: 生产环境需要HTTPS协议
 - **性能要求**: 转录延迟<2秒，准确率>90%
 - **用户体验**: 响应式设计，支持移动端
+- **安全性**: Token动态生成，敏感配置服务器端存储
+- **认证要求**: 所有API端点需要JWT认证保护
 
 ### 集成点
 - **现有UI系统**: 集成到shadcn/ui组件库
 - **认证系统**: 使用现有JWT认证机制
 - **状态管理**: 与现有React状态管理集成
 - **错误处理**: 统一错误处理机制
+- **API路由架构**: 遵循现有Hono + OpenAPI路由模式
+- **配置管理**: 使用环境变量和服务器端配置
 
 ### E2E测试要求
-- **测试文件位置**: `tests/e2e/specs/admin/agora-stt.spec.ts`
-- **测试场景**:
+- **前端测试文件位置**: `tests/e2e/specs/admin/agora-stt.spec.ts`
+- **后端测试文件位置**: `src/server/api/agora/__tests__/agora-token.integration.test.ts`
+- **前端测试场景**:
   - 管理员登录后访问Agora STT功能页面
   - 验证组件初始状态显示正确
+  - 测试Token动态获取流程
   - 测试加入/离开频道功能
   - 测试麦克风权限申请流程
   - 验证转录结果显示
+- **后端测试场景**:
+  - 测试Token生成API认证保护
+  - 验证RTC和RTM Token生成功能
+  - 测试参数验证和错误处理
+  - 验证Token有效期管理
 - **测试数据**: 使用模拟音频数据和转录结果
 - **浏览器兼容性**: Chrome、Edge等现代浏览器
 
@@ -125,9 +167,53 @@ const AGORA_CONFIG = {
 - **核心组件**: 转录控制按钮、实时转录文本显示、音频波形可视化
 - **动画规范**: 状态切换300ms ease-out，音频波形实时更新
 
+### 前端组件Token集成详细说明 [Source: docs/agora实时语音转录翻译参考文档.md]
+前端组件需要修改以支持动态Token获取，主要变更包括：
+
+1. **移除硬编码Token配置**
+   - 删除AGORA_CONFIG中的硬编码token字段
+   - 添加tokenEndpoint配置指向后端API
+
+2. **实现Token获取函数**
+```typescript
+// 使用项目现有的API客户端配置获取Token
+import { hc } from 'hono/client';
+import type { AgoraRoutes } from '@/server/api'; // 需要创建AgoraRoutes类型
+
+// 创建Agora客户端，使用现有的axiosFetch适配器
+const agoraClient = hc<AgoraRoutes>('/', {
+  fetch: axiosFetch, // 使用项目现有的axiosFetch适配器
+}).api.v1.agora;
+
+const fetchAgoraToken = async (type: 'rtc' | 'rtm', channel?: string, userId?: string) => {
+  // 使用项目标准的API客户端调用方式
+  const response = await agoraClient.token.$get({
+    query: { type, channel, userId }
+  });
+
+  if (!response.ok) {
+    throw new Error('Token获取失败');
+  }
+
+  const data = await response.json();
+  return data.data.token;
+};
+```
+
+3. **修改组件初始化流程**
+   - 在加入频道前先获取Token
+   - 处理Token过期自动刷新
+   - 更新错误处理机制
+
+4. **Token刷新机制**
+   - 监听Token过期时间
+   - 在过期前自动刷新Token
+   - 处理刷新过程中的连接状态
+
 ### 安全考虑
 #### 认证与授权
 - 使用环境变量存储敏感配置信息
+- Token路由集成JWT认证，确保只有授权用户可访问
 - 实现适当的令牌刷新机制
 - 通过认证保护WebSocket连接安全
 
@@ -135,11 +221,13 @@ const AGORA_CONFIG = {
 - 确保用户对麦克风使用的明确同意
 - 实施适当的错误处理，避免敏感数据泄露
 - 遵循语音数据处理的隐私法规
+- Token生成API不暴露敏感配置信息
 
 #### 合规要求
 - GDPR合规的语音数据处理
 - 麦克风访问的用户同意机制
 - 数据保留和删除策略
+- API访问日志和审计跟踪
 
 ## Testing
 
@@ -166,22 +254,32 @@ const AGORA_CONFIG = {
 - **Playwright**: E2E测试
 
 ### E2E测试用例设计
-- **测试文件**: `tests/e2e/specs/admin/agora-stt.spec.ts`
+- **前端测试文件**: `tests/e2e/specs/admin/agora-stt.spec.ts`
+- **后端测试文件**: `src/server/api/agora/__tests__/agora-token.integration.test.ts`
 - **前置条件**: 管理员用户已登录
-- **测试步骤**:
+- **前端测试步骤**:
   1. 导航到Agora STT功能页面
   2. 验证组件初始状态（未连接、未录制）
-  3. 测试加入频道功能
-  4. 验证连接状态更新
-  5. 测试麦克风权限申请
-  6. 测试开始/停止录音功能
-  7. 验证转录结果显示
-  8. 测试离开频道功能
+  3. 测试Token动态获取流程
+  4. 测试加入频道功能
+  5. 验证连接状态更新
+  6. 测试麦克风权限申请
+  7. 测试开始/停止录音功能
+  8. 验证转录结果显示
+  9. 测试离开频道功能
+- **后端测试步骤**:
+  1. 测试未认证用户访问Token API
+  2. 测试认证用户生成RTC Token
+  3. 测试认证用户生成RTM Token
+  4. 测试参数验证错误处理
+  5. 验证Token有效期和格式
 - **断言验证**:
   - 组件各状态正确显示
+  - Token获取和刷新流程正常
   - 按钮交互功能正常
   - 转录结果正确展示
   - 错误处理机制有效
+  - API认证保护正常工作
 
 ## Change Log
 | Date | Version | Description | Author |
@@ -193,6 +291,7 @@ const AGORA_CONFIG = {
 | 2025-09-23 | 1.2 | 整合前端规范文档，添加UX设计要求 | Bob (SM) |
 | 2025-09-23 | 1.3 | 组件实现验证和代码修复，状态更新为Ready for Review | James (Dev) |
 | 2025-09-23 | 1.4 | 发现缺少E2E测试文件，状态回退为In Development | Bob (SM) |
+| 2025-09-23 | 1.5 | 补充Token动态获取后端路由和前端集成需求 | Bob (SM) |
 
 ## Dev Agent Record
 
@@ -203,6 +302,7 @@ const AGORA_CONFIG = {
 - 组件已存在并完整实现，无需重新开发
 - 已验证功能完整性、无障碍功能和响应式设计
 - 已修复代码检查问题（console语句和未使用变量）
+- 需要修改前端组件以支持动态Token获取
 
 ### Completion Notes List
 - ✅ Agora STT组件已完整实现并符合所有验收标准
@@ -214,14 +314,22 @@ const AGORA_CONFIG = {
 - ✅ 组件测试已通过（8个测试用例全部通过）
 - ✅ 代码检查已通过（修复了console语句和未使用变量）
 - ⚠️ E2E测试文件待创建 - 需要创建完整的端到端测试
+- ⚠️ 前端组件需要修改以支持动态Token获取
+- ⚠️ 需要实现后端Token生成路由
 
 ### File List
-- `src/client/admin/components/agora-stt/AgoraSTTComponent.tsx` - 主组件文件（已存在）
-- `src/client/admin/components/agora-stt/__tests__/AgoraSTTComponent.test.tsx` - 组件测试（已存在）
-- `src/client/types/agora-stt.ts` - 类型定义（已存在）
-- `src/client/utils/agora-stt.ts` - 工具函数（已存在）
-- `src/client/hooks/useAgoraSTT.ts` - 自定义Hook（已存在）
+- `src/client/admin/components/agora-stt/AgoraSTTComponent.tsx` - 主组件文件（已存在，需要修改）
+- `src/client/admin/components/agora-stt/__tests__/AgoraSTTComponent.test.tsx` - 组件测试（已存在，需要更新）
+- `src/client/types/agora-stt.ts` - 类型定义（已存在，需要扩展）
+- `src/client/utils/agora-stt.ts` - 工具函数（已存在，需要更新）
+- `src/client/hooks/useAgoraSTT.ts` - 自定义Hook（已存在，需要更新）
 - `src/client/admin/components/agora-stt/index.ts` - 组件导出文件（已存在）
+- `src/server/api/agora/token/get.ts` - Token生成路由（待创建）
+- `src/server/modules/agora/agora-token.service.ts` - Token生成服务（待创建）
+- `src/server/types/agora.ts` - 后端类型定义（待创建）
+- `src/server/api/agora/__tests__/agora-token.integration.test.ts` - Token路由集成测试（待创建）
+- `src/server/api/index.ts` - 需要导出AgoraRoutes类型（需要更新）
+- `src/client/api.ts` - 需要添加Agora客户端导出（需要更新）
 - `tests/e2e/specs/admin/agora-stt.spec.ts` - E2E测试文件（待创建）
 
 ## QA Results