blank/docs/stories/1.1.sdk-core-architecture.md

Story 1.1: SDK核心架构和基础封装

Status

Draft

Story

As a TypeScript开发者， I want 将现有的stt-demo应用中的语音转文字功能封装成通用的TypeScript SDK， so that 我可以在任何TypeScript项目中轻松使用语音转文字功能，而不依赖特定框架。

Acceptance Criteria

1. 在项目根目录创建 packages/ 目录结构，采用monorepo模式管理SDK
2. 初始化 stt-sdk-core 包的基础配置，包括package.json、tsconfig.json、vite.config.ts
3. 封装现有的SttManager和RtmManager类，提供适配器接口
4. 实现基础的事件系统和错误处理机制
5. 提供完整的TypeScript类型定义
6. 确保现有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/tech-stack.md#测试工具]

• 测试框架: Vitest 3.2.4 (已集成)
• 测试库: Testing Library 16.3.0
• E2E测试: Playwright 1.55.0
• 测试位置: packages/stt-sdk-core/tests/目录
• 单元测试: 针对核心类和工具函数
• 集成测试: 验证与现有管理器的集成

测试要求

• 所有核心类必须有单元测试（使用Vitest + Testing Library）
• 事件系统和错误处理需要测试覆盖
• 类型定义需要通过TypeScript编译检查
• 现有功能回归测试必须通过（使用Playwright E2E测试）
• 测试覆盖率目标：核心功能80%以上

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

Dev Agent Record

Agent Model Used

Debug Log References

Completion Notes List

File List

QA Results