# 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/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 |

## Dev Agent Record

### Agent Model Used

### Debug Log References

### Completion Notes List

### File List

## QA Results