# STT SDK 包结构设计

## 概述

本文档详细描述了在项目根目录创建 `packages/` 目录来管理STT SDK的monorepo结构设计。

## 整体目录结构

```
stt-demo/
├── packages/                    # SDK包目录
│   ├── stt-sdk-core/           # 核心SDK包
│   ├── stt-sdk-react/          # React适配器
│   ├── stt-sdk-vue/            # Vue适配器
│   └── stt-sdk-angular/        # Angular适配器
├── src/                        # 主应用代码（保持不变）
├── docs/                       # 文档目录
├── public/                     # 静态资源
└── package.json               # 根package.json
```

## 包详细结构

### 1. stt-sdk-core (核心包)

```
packages/stt-sdk-core/
├── src/
│   ├── core/
│   │   ├── SttSdk.ts              # 主SDK类
│   │   ├── SttClient.ts           # STT客户端
│   │   ├── RtmClient.ts           # RTM客户端
│   │   └── EventEmitter.ts        # 事件系统
│   ├── managers/
│   │   ├── SttManagerAdapter.ts   # STT管理器适配器
│   │   ├── RtmManagerAdapter.ts   # RTM管理器适配器
│   │   └── index.ts
│   ├── types/
│   │   ├── index.ts               # 主类型定义
│   │   ├── events.ts              # 事件类型
│   │   ├── config.ts              # 配置类型
│   │   └── errors.ts              # 错误类型
│   ├── utils/
│   │   ├── config.ts              # 配置工具
│   │   ├── validation.ts          # 验证工具
│   │   └── logger.ts              # 日志工具
│   └── index.ts                   # 包入口
├── tests/
│   ├── unit/
│   ├── integration/
│   └── fixtures/
├── dist/                         # 构建输出
│   ├── index.js                  # CommonJS
│   ├── index.mjs                 # ES Module
│   └── types/                    # 类型声明
├── package.json
├── tsconfig.json
├── vite.config.ts               # 构建配置
└── README.md
```

### 2. stt-sdk-react (React适配器)

```
packages/stt-sdk-react/
├── src/
│   ├── hooks/
│   │   ├── useSttClient.ts       # React Hook for STT
│   │   ├── useRtmClient.ts       # React Hook for RTM
│   │   └── index.ts
│   ├── components/
│   │   ├── SttProvider.tsx       # Context Provider
│   │   ├── Transcription.tsx     # 转录组件
│   │   └── index.ts
│   ├── context/
│   │   ├── SttContext.tsx        # React Context
│   │   └── index.ts
│   ├── types/
│   │   ├── react.ts              # React特定类型
│   │   └── index.ts
│   └── index.ts
├── examples/
│   ├── basic-usage/
│   └── advanced-usage/
├── package.json
├── tsconfig.json
└── README.md
```

### 3. stt-sdk-vue (Vue适配器)

```
packages/stt-sdk-vue/
├── src/
│   ├── composables/
│   │   ├── useSttClient.ts       # Vue Composable for STT
│   │   ├── useRtmClient.ts       # Vue Composable for RTM
│   │   └── index.ts
│   ├── components/
│   │   ├── SttProvider.vue       # Provide/Inject
│   │   ├── Transcription.vue     # 转录组件
│   │   └── index.ts
│   ├── types/
│   │   ├── vue.ts                # Vue特定类型
│   │   └── index.ts
│   └── index.ts
├── examples/
│   └── basic-usage/
├── package.json
├── tsconfig.json
└── README.md
```

## 包配置设计

### 根package.json配置

```json
{
  "name": "stt-demo",
  "private": true,
  "workspaces": ["packages/*"],
  "scripts": {
    "build:sdk": "npm run build -w packages/stt-sdk-core",
    "build:react": "npm run build -w packages/stt-sdk-react",
    "build:all": "npm run build:sdk && npm run build:react",
    "test:sdk": "npm run test -w packages/stt-sdk-core",
    "lint:sdk": "npm run lint -w packages/stt-sdk-core"
  },
  "devDependencies": {
    "@types/node": "^20.0.0",
    "typescript": "^5.0.0"
  }
}
```

### stt-sdk-core/package.json

```json
{
  "name": "@stt-demo/sdk-core",
  "version": "1.0.0",
  "type": "module",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/types/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.mjs",
      "require": "./dist/index.js",
      "types": "./dist/types/index.d.ts"
    }
  },
  "scripts": {
    "build": "vite build",
    "dev": "vite build --watch",
    "test": "vitest",
    "lint": "eslint src --ext .ts,.tsx"
  },
  "dependencies": {
    "agora-rtm": "^1.5.0"
  },
  "peerDependencies": {
    "typescript": "^5.0.0"
  }
}
```

### stt-sdk-react/package.json

```json
{
  "name": "@stt-demo/sdk-react",
  "version": "1.0.0",
  "main": "./dist/index.js",
  "module": "./dist/index.mjs",
  "types": "./dist/types/index.d.ts",
  "peerDependencies": {
    "@stt-demo/sdk-core": "^1.0.0",
    "react": "^18.0.0",
    "react-dom": "^18.0.0"
  },
  "devDependencies": {
    "@stt-demo/sdk-core": "*",
    "@types/react": "^18.0.0",
    "@types/react-dom": "^18.0.0"
  }
}
```

## 构建配置

### stt-sdk-core/vite.config.ts

```typescript
import { defineConfig } from "vite"
import { resolve } from "path"

export default defineConfig({
  build: {
    lib: {
      entry: resolve(__dirname, "src/index.ts"),
      name: "SttSdkCore",
      fileName: (format) => `index.${format === "es" ? "mjs" : "js"}`,
    },
    rollupOptions: {
      external: ["agora-rtm"],
      output: {
        globals: {
          "agora-rtm": "AgoraRTM",
        },
      },
    },
  },
  test: {
    environment: "jsdom",
  },
})
```

## 开发工作流

### 1. 本地开发

```bash
# 安装所有包依赖
npm install

# 开发模式构建SDK
npm run dev -w packages/stt-sdk-core

# 运行SDK测试
npm run test -w packages/stt-sdk-core
```

### 2. 构建发布

```bash
# 构建所有包
npm run build:all

# 只构建核心包
npm run build:sdk

# 发布到npm（需要配置）
npm publish -w packages/stt-sdk-core
```

### 3. 主应用集成

```typescript
// 在stt-demo主应用中引用本地包
import { createSttSdk } from "../../packages/stt-sdk-core"

// 或者发布后从npm安装
import { createSttSdk } from "@stt-demo/sdk-core"
```

## 优势

### 1. 代码隔离

- SDK代码与主应用代码完全分离
- 便于独立维护和版本管理

### 2. 开发效率

- 热重载支持，修改SDK代码立即生效
- 统一的构建和测试流程

### 3. 发布灵活

- 可以独立发布核心包或适配器包
- 支持语义化版本管理

### 4. 团队协作

- 不同团队可以并行开发不同包
- 清晰的依赖关系和接口定义

这个包结构设计确保了SDK的可维护性、可扩展性和易用性，同时与现有项目完美集成。