Browse Source

📝 docs(architecture): 完善SDK测试页面实施细节和测试场景

- 细化Task 8任务清单,明确页面组件、路由配置和E2E测试的具体子任务
- 添加SDK集成示例代码,包括主应用集成和路由配置示例
- 补充SDK测试页面E2E测试场景,覆盖初始化、转录功能、事件系统和错误处理
- 更新Change Log,记录版本1.8的实施细节完善
yourname 2 months ago
parent
commit
7444bf05e6
1 changed files with 94 additions and 2 deletions
  1. 94 2
      docs/stories/1.1.sdk-core-architecture.md

+ 94 - 2
docs/stories/1.1.sdk-core-architecture.md

@@ -64,10 +64,24 @@
   - [ ] 运行Playwright E2E测试验证回归(主应用暂未集成SDK)
 - [ ] Task 8: **主应用集成SDK测试页面** (AC: 8,9)
   - [ ] 在src/pages/目录下创建sdk-test页面
-  - [ ] 实现SDK初始化、连接、转录功能演示界面
-  - [ ] 添加实时转录结果显示和事件监听
+    - [ ] 创建sdk-test/index.tsx页面组件
+    - [ ] 实现SDK初始化界面:App ID输入、Token配置
+    - [ ] 添加连接状态显示和连接/断开按钮
+    - [ ] 实现转录功能控制:开始/停止转录按钮
+    - [ ] 添加实时转录结果显示区域,支持多语言显示
+    - [ ] 实现事件监听面板,显示SDK事件日志
+    - [ ] 添加错误处理和状态提示
   - [ ] 配置路由,添加/sdk-test路径访问
+    - [ ] 在src/router/index.tsx中添加sdk-test路由
+    - [ ] 配置懒加载导入sdk-test页面
+    - [ ] 更新路由配置,确保/sdk-test路径可访问
   - [ ] 编写Playwright E2E测试验证SDK功能
+    - [ ] 创建e2e/sdk-test.spec.ts测试文件
+    - [ ] 测试SDK初始化流程:输入App ID、连接成功
+    - [ ] 测试转录功能:开始转录、接收转录结果
+    - [ ] 测试多语言支持:切换语言、验证转录结果
+    - [ ] 测试错误处理:无效配置、连接失败场景
+    - [ ] 验证事件系统:监听和显示SDK事件
   - [ ] 运行E2E测试确保SDK在实际应用中正常工作
 
 ## Dev Notes
@@ -135,6 +149,48 @@
 - **现有代码保持**: src/目录下的现有代码保持不变
 - **集成方式**: SDK作为独立包,主应用通过workspace引用
 
+### SDK集成示例代码
+
+**主应用集成SDK示例**:
+
+```typescript
+// 在sdk-test页面中集成SDK
+import { createSttSdk } from "@stt-demo/stt-sdk-core"
+
+// SDK初始化配置
+const sdkConfig = {
+  appId: "your-app-id",
+  token: "your-token",
+}
+
+// 创建SDK实例
+const sttSdk = createSttSdk(sdkConfig)
+
+// 监听SDK事件
+sttSdk.on("connected", () => {
+  console.log("SDK连接成功")
+})
+
+sttSdk.on("transcriptionResult", (result) => {
+  console.log("转录结果:", result)
+})
+```
+
+**路由配置示例**:
+
+```typescript
+// src/router/index.tsx 中添加sdk-test路由
+const SdkTestPage = lazy(() => import('../pages/sdk-test'))
+
+const routerItems = [
+  <Route path="/" element={<LoginPage />} />,
+  <Route path="/home" element={<HomePage />} />,
+  <Route path="/login" element={<LoginPage />} />,
+  <Route path="/sdk-test" element={<SdkTestPage />} />, // 新增路由
+  <Route path="*" element={<NotFoundPage />} />,
+]
+```
+
 ## Testing
 
 ### 测试策略 [Source: architecture/testing-strategy.md]
@@ -158,6 +214,41 @@
 - 测试结构:遵循AAA模式(Arrange-Act-Assert) [Source: architecture/testing-strategy.md#测试结构]
 - 异步测试处理:正确使用async/await [Source: architecture/testing-strategy.md#异步测试处理]
 
+### SDK测试页面E2E测试场景
+
+**测试文件位置**: `e2e/sdk-test.spec.ts`
+
+**主要测试场景**:
+
+1. **SDK初始化测试**
+   - 验证App ID输入和配置保存
+   - 测试连接建立和状态更新
+   - 验证Token验证机制
+
+2. **转录功能测试**
+   - 测试开始/停止转录按钮功能
+   - 验证实时转录结果显示
+   - 测试多语言转录切换
+
+3. **事件系统测试**
+   - 验证SDK事件监听和显示
+   - 测试错误事件处理
+   - 验证连接状态变化事件
+
+4. **错误处理测试**
+   - 测试无效App ID的错误处理
+   - 验证网络连接失败场景
+   - 测试转录任务异常处理
+
+**测试数据示例**:
+
+```typescript
+// e2e/fixtures/sdk-test-data.ts
+export const validAppId = "test-app-id"
+export const invalidAppId = "invalid-app-id"
+export const testLanguages = ["zh-CN", "en-US", "ja-JP"]
+```
+
 ## Change Log
 
 | Date       | Version | Description                                                                       | Author      |
@@ -170,6 +261,7 @@
 | 2025-09-25 | 1.5     | **重大纠正**:发现SDK实现为模拟功能而非真实封装,需要重新实现真实Agora SDK集成    | Bob (SM)    |
 | 2025-09-25 | 1.6     | **完成真实功能集成**:重新实现管理器适配器类,集成真实Agora SDK功能,修复所有测试 | Claude Code |
 | 2025-09-25 | 1.7     | **更新故事状态**:添加主应用集成SDK测试页面需求,将状态改为进行中                 | Bob (SM)    |
+| 2025-09-25 | 1.8     | **完善实施细节**:根据PO建议细化Task 8任务、添加SDK集成示例和E2E测试场景          | Bob (SM)    |
 
 ## Dev Agent Record