blank/docs/prd/epic-1-stt-sdk-package-structure.md

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配置

{
  "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

{
  "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

{
  "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

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. 本地开发

# 安装所有包依赖
npm install

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

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

2. 构建发布

# 构建所有包
npm run build:all

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

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

3. 主应用集成

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

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

优势

1. 代码隔离

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

2. 开发效率

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

3. 发布灵活

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

4. 团队协作

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

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