1.1.sdk-core-architecture.md 6.9 KB
Story 1.1: SDK核心架构和基础封装
Status
Draft
Story
As a TypeScript开发者， I want 将现有的stt-demo应用中的语音转文字功能封装成通用的TypeScript SDK， so that 我可以在任何TypeScript项目中轻松使用语音转文字功能，而不依赖特定框架。
Acceptance Criteria
- 在项目根目录创建
packages/目录结构，采用monorepo模式管理SDK - 初始化
stt-sdk-core包的基础配置，包括package.json、tsconfig.json、vite.config.ts - 封装现有的SttManager和RtmManager类，提供适配器接口
- 实现基础的事件系统和错误处理机制
- 提供完整的TypeScript类型定义
- 确保现有stt-demo应用功能不受影响，保持向后兼容
Tasks / Subtasks
- Task 1: 创建packages目录结构和monorepo配置 (AC: 1)
- 在项目根目录创建packages/目录
- 配置根package.json的workspaces字段
- 创建stt-sdk-core包目录结构
- Task 2: 初始化stt-sdk-core包基础配置 (AC: 2)
- 创建stt-sdk-core/package.json配置
- 配置TypeScript编译选项
- 设置Vite构建配置
- 配置ESLint和Prettier规则
- Task 3: 封装现有管理器类 (AC: 3)
- 创建SttManagerAdapter类，封装现有SttManager功能
- 创建RtmManagerAdapter类，封装现有RtmManager功能
- 保持现有API接口不变，确保向后兼容
- Task 4: 实现事件系统和错误处理 (AC: 4)
- 创建通用EventEmitter类
- 实现事件类型定义和监听机制
- 创建错误处理类和错误类型定义
- Task 5: 提供完整类型定义 (AC: 5)
- 创建核心类型定义文件
- 定义配置接口和事件接口
- 导出完整的类型声明
- Task 6: 配置测试环境和编写测试 (AC: 5,6)
- 配置Vitest测试环境
- 编写核心类的单元测试
- 编写事件系统和错误处理的测试
- 配置测试覆盖率报告
- Task 7: 验证现有功能兼容性 (AC: 6)
- 确保现有stt-demo应用编译通过
- 验证语音转文字功能正常工作
- 测试多语言转录和翻译功能
- 运行Playwright E2E测试验证回归
Dev Notes
技术栈信息 [Source: architecture/tech-stack.md]
- 前端框架: React 18.2.0 + TypeScript 5.2.2
- 状态管理: Redux Toolkit 1.6.2
- 构建工具: Vite 5.0.8
- Agora服务: RTC SDK 4.20.0, RTM 2.1.9
- 包管理: npm/yarn，支持workspaces
现有管理器架构 [Source: architecture.md#核心架构模式]
- 管理器模式: 将复杂业务逻辑封装在独立的管理器中
- RtcManager: 音视频通信管理
- RtmManager: 实时消息管理
- SttManager: 语音转文字管理
- 事件驱动: 管理器间通过自定义事件系统通信
源码结构信息 [Source: architecture/source-tree.md]
- 管理器位置:
src/manager/stt/stt.ts(SttManager) - 管理器位置:
src/manager/rtm/rtm.ts(RtmManager) - 事件系统:
src/manager/events.ts(AGEventEmitter) - 类型定义:
src/manager/stt/types.ts,src/manager/rtm/types.ts
编码规范 [Source: architecture/coding-standards.md]
- 类型定义: 使用接口定义数据模型，优先使用interface而非type
- 导入导出: 使用绝对路径导入(@/)，按类型分组导入
- 命名约定: 文件kebab-case，组件PascalCase，变量camelCase
- 错误处理: 使用try-catch处理异步错误，提供有意义的错误消息
包结构设计 [Source: docs/prd/epic-1-stt-sdk-package-structure.md]
- 核心包路径:
packages/stt-sdk-core/ - 源码结构: src/core/, src/managers/, src/types/, src/utils/
- 构建输出: dist/目录，支持CommonJS和ES Module
- 依赖管理: 外部依赖agora-rtm，peerDependencies配置
API规范参考 [Source: docs/prd/epic-1-stt-sdk-api-spec.md]
- SDK初始化接口: SttSdkConfig, SttSdk.initialize()
- 管理器接口: SttManager.init(), startTranscription(), stopTranscription()
- 客户端接口: SttClient, RtmClient的通用API设计
- 事件系统: 转录开始、停止、结果、错误等事件定义
架构设计原则 [Source: docs/prd/epic-1-stt-sdk-architecture.md]
- 框架无关性: SDK核心不依赖任何前端框架
- 模块化设计: 核心包 + 框架适配器包
- 类型安全: 完整的TypeScript类型定义
- 性能优化: 连接复用、事件去重、懒加载
项目结构对齐
- 新增文件位置: 所有SDK相关代码放在packages/目录下
- 现有代码保持: src/目录下的现有代码保持不变
- 集成方式: SDK作为独立包，主应用通过workspace引用
Testing
测试策略 [Source: architecture/testing-strategy.md]
- 测试框架: Vitest 3.2.4 (已集成) [Source: architecture/testing-strategy.md#单元测试]
- 测试库: Testing Library 16.3.0 [Source: architecture/testing-strategy.md#单元测试]
- E2E测试: Playwright 1.55.0 [Source: architecture/testing-strategy.md#端到端测试]
- 测试位置:
packages/stt-sdk-core/tests/目录 - 单元测试: 针对核心类和工具函数 [Source: architecture/testing-strategy.md#单元测试]
- 集成测试: 验证与现有管理器的集成 [Source: architecture/testing-strategy.md#集成测试]
- 测试覆盖率目标: 核心功能80%以上 [Source: architecture/testing-strategy.md#测试覆盖率目标]
测试要求 [Source: architecture/testing-strategy.md]
- 所有核心类必须有单元测试（使用Vitest + Testing Library）
- 事件系统和错误处理需要测试覆盖
- 类型定义需要通过TypeScript编译检查
- 现有功能回归测试必须通过（使用Playwright E2E测试）
- 测试覆盖率目标：核心功能80%以上 [Source: architecture/testing-strategy.md#测试覆盖率目标]
- 测试命名规范：使用描述性测试名称 [Source: architecture/testing-strategy.md#测试命名规范]
- 测试结构：遵循AAA模式（Arrange-Act-Assert） [Source: architecture/testing-strategy.md#测试结构]
- 异步测试处理：正确使用async/await [Source: architecture/testing-strategy.md#异步测试处理]
Change Log
| Date | Version | Description | Author |
|---|---|---|---|
| 2025-09-25 | 1.0 | 初始故事创建 | Claude Code |
| 2025-09-25 | 1.1 | 更新测试框架信息：Vitest 3.2.4, Testing Library 16.3.0, Playwright 1.55.0 | Claude Code |
| 2025-09-25 | 1.2 | 更新测试策略引用：使用architecture/testing-strategy.md文档 | Claude Code |