# STT SDK 通用架构设计

## 概述

本文档描述了语音转文字数据流SDK的通用TypeScript架构设计，确保SDK可以在任何TypeScript项目中使用，不依赖特定框架。

## 架构设计原则

### 1. 框架无关性

- SDK核心不依赖任何前端框架（React、Vue、Angular等）
- 提供通用的类式API接口
- 框架适配器作为可选包提供

### 2. 模块化设计

- 核心SDK包：`@agora/stt-sdk`
- React适配器：`@agora/stt-sdk/react`
- Vue适配器：`@agora/stt-sdk/vue`
- Angular适配器：`@agora/stt-sdk/angular`

### 3. 类型安全

- 完整的TypeScript类型定义
- 编译时类型检查
- 智能代码提示

## 核心架构

### SDK 层次结构

```
┌─────────────────────────────────────────┐
│           应用层 (Application)           │
├─────────────────────────────────────────┤
│         框架适配器 (可选)                │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐    │
│  │ React   │ │  Vue    │ │ Angular │    │
│  │ Adapter │ │ Adapter │ │ Adapter │    │
│  └─────────┘ └─────────┘ └─────────┘    │
├─────────────────────────────────────────┤
│           核心SDK层                      │
│  ┌─────────┐ ┌─────────┐                │
│  │ SttClient│ │ RtmClient│               │
│  └─────────┘ └─────────┘                │
├─────────────────────────────────────────┤
│           管理器层                       │
│  ┌─────────┐ ┌─────────┐                │
│  │SttManager│ │RtmManager│               │
│  └─────────┘ └─────────┘                │
├─────────────────────────────────────────┤
│           服务层                         │
│  ┌─────────┐ ┌─────────┐                │
│  │ STT API │ │ RTM API │                │
│  └─────────┘ └─────────┘                │
└─────────────────────────────────────────┘
```

### 核心组件设计

#### 1. SttSdk (主入口)

```typescript
class SttSdk {
  // 单例模式，全局配置管理
  private static instance: SttSdk
  private config: SttSdkConfig

  // 管理器实例池
  private sttManagers: Map<string, SttManager>
  private rtmManagers: Map<string, RtmManager>

  // 客户端实例池
  private sttClients: Map<string, SttClient>
  private rtmClients: Map<string, RtmClient>

  // 公共方法
  initialize(config: SttSdkConfig): Promise<void>
  createSttClient(options: SttClientOptions): SttClient
  createRtmClient(options: RtmClientOptions): RtmClient
  destroy(): Promise<void>
}
```

#### 2. SttClient (通用客户端)

```typescript
class SttClient {
  // 状态管理
  private state: SttClientState

  // 事件系统
  private eventEmitter: EventEmitter

  // 依赖注入
  private sttManager: SttManager
  private rtmManager: RtmManager

  // 公共API
  initialize(options: SttInitOptions): Promise<void>
  startTranscription(options: StartOptions): Promise<void>
  stopTranscription(): Promise<void>

  // 事件监听
  on(event: string, callback: Function): void
  off(event: string, callback: Function): void
}
```

#### 3. 事件系统设计

```typescript
interface SttClientEvents {
  initialized: () => void
  transcriptionStart: () => void
  transcriptionStop: () => void
  transcriptionResult: (result: TranscriptionResult) => void
  error: (error: SttError) => void
}

interface RtmClientEvents {
  connected: () => void
  disconnected: () => void
  userListChanged: (users: ISimpleUserInfo[]) => void
  messageReceived: (message: any) => void
}
```

## 包结构设计

### 1. 核心包 (@agora/stt-sdk)

```
stt-sdk/
├── src/
│   ├── core/
│   │   ├── SttSdk.ts          # 主SDK类
│   │   ├── SttClient.ts       # STT客户端
│   │   ├── RtmClient.ts       # RTM客户端
│   │   └── EventEmitter.ts    # 事件系统
│   ├── managers/
│   │   ├── SttManager.ts      # STT管理器封装
│   │   └── RtmManager.ts      # RTM管理器封装
│   ├── types/
│   │   ├── index.ts           # 类型定义
│   │   ├── events.ts          # 事件类型
│   │   └── errors.ts          # 错误类型
│   └── utils/
│       ├── config.ts          # 配置工具
│       └── validation.ts      # 验证工具
├── dist/                      # 构建输出
├── package.json
└── README.md
```

### 2. React适配器包 (@agora/stt-sdk/react)

```
stt-sdk-react/
├── src/
│   ├── hooks/
│   │   ├── useSttClient.ts    # React Hook
│   │   └── useRtmClient.ts    # React Hook
│   ├── components/
│   │   ├── SttProvider.tsx    # Context Provider
│   │   └── Transcription.tsx  # 示例组件
│   └── types/
│       └── index.ts           # React特定类型
├── dist/
├── package.json
└── README.md
```

### 3. Vue适配器包 (@agora/stt-sdk/vue)

```
stt-sdk-vue/
├── src/
│   ├── composables/
│   │   ├── useSttClient.ts    # Vue Composable
│   │   └── useRtmClient.ts    # Vue Composable
│   ├── components/
│   │   ├── SttProvider.vue    # Provide/Inject
│   │   └── Transcription.vue  # 示例组件
│   └── types/
│       └── index.ts           # Vue特定类型
├── dist/
├── package.json
└── README.md
```

## 集成模式

### 1. 纯TypeScript项目

```typescript
import { createSttSdk } from "@agora/stt-sdk"

const sdk = createSttSdk()
await sdk.initialize(config)

const sttClient = sdk.createSttClient(options)
sttClient.on("transcriptionResult", handleResult)
await sttClient.initialize()
```

### 2. Node.js后端项目

```typescript
import { createSttSdk } from "@agora/stt-sdk"

// 可用于服务端的语音处理
const sdk = createSttSdk()
await sdk.initialize(config)

// 处理音频文件转录
const result = await processAudioFile(audioBuffer)
```

### 3. 浏览器扩展

```typescript
// 在Chrome扩展中使用
const sdk = createSttSdk()
await sdk.initialize(config)

// 捕获标签页音频进行转录
chrome.tabs.captureVisibleTab((audio) => {
  // 处理音频转录
})
```

## 性能优化策略

### 1. 懒加载

- 按需加载SDK模块
- 动态导入大型依赖
- 减少初始包大小

### 2. 连接复用

- RTM连接池管理
- 避免重复建立连接
- 智能连接保持

### 3. 事件优化

- 事件去重机制
- 批量事件处理
- 内存泄漏防护

### 4. 资源管理

- 自动垃圾回收
- 连接超时处理
- 错误恢复机制

## 兼容性考虑

### 1. 浏览器支持

- 现代浏览器（Chrome 80+, Firefox 75+, Safari 13+）
- ES2018+ 特性支持
- Module 和 CommonJS 双模式

### 2. TypeScript版本

- TypeScript 4.0+
- 严格的类型检查
- 完整的类型定义

### 3. 构建工具

- Webpack 4+
- Vite 2+
- Rollup 2+
- 支持Tree Shaking

## 扩展性设计

### 1. 插件系统

```typescript
interface SttPlugin {
  name: string
  install(sdk: SttSdk): void
}

// 自定义插件示例
class AnalyticsPlugin implements SttPlugin {
  install(sdk: SttSdk) {
    sdk.on("transcriptionResult", this.trackAnalytics)
  }

  private trackAnalytics(result: TranscriptionResult) {
    // 发送分析数据
  }
}
```

### 2. 自定义适配器

```typescript
// 为其他框架创建适配器
class CustomFrameworkAdapter {
  static createSttClient(sdk: SttSdk, options: any) {
    // 返回框架特定的客户端实例
  }
}
```

这个架构设计确保了SDK的通用性、可扩展性和高性能，同时保持了与现有代码的兼容性。