# 技术栈介绍

<cite>
**本文引用的文件**
- [my-uniapp-vue3/package.json](file://my-uniapp-vue3/package.json)
- [my-uniapp-vue3/vite.config.ts](file://my-uniapp-vue3/vite.config.ts)
- [my-uniapp-vue3/src/main.ts](file://my-uniapp-vue3/src/main.ts)
- [my-uniapp-vue3/src/App.vue](file://my-uniapp-vue3/src/App.vue)
- [server/package.json](file://server/package.json)
- [server/src/app.ts](file://server/src/app.ts)
- [server/src/config/index.ts](file://server/src/config/index.ts)
- [server/src/modules/tts/tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [server/src/modules/tts/aliyun.provider.ts](file://server/src/modules/tts/aliyun.provider.ts)
- [server/src/modules/tts/minimax.provider.ts](file://server/src/modules/tts/minimax.provider.ts)
- [server/src/services/ffmpeg.processor.ts](file://server/src/services/ffmpeg.processor.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [docs/database-structure.md](file://docs/database-structure.md)
</cite>

## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖分析](#依赖分析)
7. [性能考虑](#性能考虑)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)

## 简介
本文件面向AI有声书生成平台，系统性梳理前后端技术栈与架构选型，重点覆盖：
- 前端：uniapp + Vue3 + TypeScript 的跨平台开发能力，统一支撑H5与微信小程序
- 后端：Node.js 18 + Koa 2.x 的现代化服务端架构，Prisma + MySQL 的持久层
- 音频处理：FFmpeg 的本地/云端音频处理与合并能力
- 语音合成：阿里云TTS（DashScope）与MiniMax双通道，提供高音质与高可用
- 设计原则：在性能、可扩展性与可维护性之间取得平衡

## 项目结构
项目采用“前端工程 + 后端工程”双工程布局，配合 Prisma 数据库模型与文档，形成清晰的职责边界。

```mermaid
graph TB
subgraph "前端(uniapp + Vue3 + TS)"
FE_PKG["my-uniapp-vue3/package.json"]
FE_MAIN["my-uniapp-vue3/src/main.ts"]
FE_APP["my-uniapp-vue3/src/App.vue"]
FE_VITE["my-uniapp-vue3/vite.config.ts"]
end
subgraph "后端(Node.js 18 + Koa 2.x)"
BE_PKG["server/package.json"]
BE_APP["server/src/app.ts"]
BE_CFG["server/src/config/index.ts"]
BE_PRISMA["server/prisma/schema.prisma"]
end
subgraph "模块与服务"
TTS_SVC["server/src/modules/tts/tts.service.ts"]
ALIYUN["server/src/modules/tts/aliyun.provider.ts"]
MINIMAX["server/src/modules/tts/minimax.provider.ts"]
FFMPEG["server/src/services/ffmpeg.processor.ts"]
end
FE_VITE --> BE_APP
FE_MAIN --> FE_APP
FE_PKG --> FE_MAIN
BE_PKG --> BE_APP
BE_APP --> TTS_SVC
TTS_SVC --> ALIYUN
TTS_SVC --> MINIMAX
TTS_SVC --> FFMPEG
BE_APP --> BE_CFG
BE_APP --> BE_PRISMA
```

**图表来源**
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [my-uniapp-vue3/src/main.ts:1-32](file://my-uniapp-vue3/src/main.ts#L1-L32)
- [my-uniapp-vue3/src/App.vue:1-134](file://my-uniapp-vue3/src/App.vue#L1-L134)
- [my-uniapp-vue3/vite.config.ts:1-24](file://my-uniapp-vue3/vite.config.ts#L1-L24)
- [server/package.json:1-60](file://server/package.json#L1-L60)
- [server/src/app.ts:1-194](file://server/src/app.ts#L1-L194)
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)

**章节来源**
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [my-uniapp-vue3/vite.config.ts:1-24](file://my-uniapp-vue3/vite.config.ts#L1-L24)
- [server/package.json:1-60](file://server/package.json#L1-L60)
- [server/src/app.ts:1-194](file://server/src/app.ts#L1-L194)

## 核心组件
- 前端框架：uniapp 3.x + Vue 3 + TypeScript，通过 Vite 插件实现多端构建与代理
- 后端框架：Koa 2.x + 路由 + 中间件，统一处理CORS、日志、安全、限流与静态资源
- 数据层：Prisma + MySQL，提供强类型ORM与迁移能力
- 音频处理：FFmpeg 处理器，支持下载、合并、转码、裁剪、音量调节与时长探测
- 语音合成：阿里云 DashScope TTS 与 MiniMax 异步长文本TTS，提供多音色与高可用降级
- 存储：本地文件系统或阿里云 OSS（通过统一 storageService 抽象）

**章节来源**
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [server/src/modules/tts/tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [server/src/services/ffmpeg.processor.ts:1-379](file://server/src/services/ffmpeg.processor.ts#L1-L379)
- [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)

## 架构总览
整体采用“前端多端统一 + 后端REST/WS + 模块化服务”的分层架构。前端通过Vite代理访问后端API；后端以Koa为核心，集中注册路由与中间件，并通过模块化控制器/服务解耦业务；TTS与FFmpeg作为独立服务被TTS模块复用；数据库通过Prisma抽象统一访问。

```mermaid
graph TB
Client["浏览器/H5<br/>微信小程序"] --> Proxy["Vite 代理(/api,/uploads,/videos)"]
Proxy --> Koa["Koa 应用(app.ts)"]
Koa --> Cfg["配置(config/index.ts)"]
Koa --> Routes["路由注册(app.ts)"]
Routes --> TTS["TTS服务(tts.service.ts)"]
TTS --> Aliyun["阿里云TTS(aliyun.provider.ts)"]
TTS --> Minimax["MiniMax(异步)(minimax.provider.ts)"]
TTS --> FFmpeg["FFmpeg处理器(ffmpeg.processor.ts)"]
Koa --> DB["Prisma(Prisma Client)"]
DB --> MySQL["MySQL(通过DATABASE_URL)"]
```

**图表来源**
- [my-uniapp-vue3/vite.config.ts:7-22](file://my-uniapp-vue3/vite.config.ts#L7-L22)
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [server/src/modules/tts/tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [server/src/modules/tts/aliyun.provider.ts:1-152](file://server/src/modules/tts/aliyun.provider.ts#L1-L152)
- [server/src/modules/tts/minimax.provider.ts:1-280](file://server/src/modules/tts/minimax.provider.ts#L1-L280)
- [server/src/services/ffmpeg.processor.ts:1-379](file://server/src/services/ffmpeg.processor.ts#L1-L379)
- [server/prisma/schema.prisma:1-8](file://server/prisma/schema.prisma#L1-L8)

## 详细组件分析

### 前端技术栈：uniapp + Vue3 + TypeScript
- 跨平台能力：通过 uni-app 3.x 的多端编译与运行时，一次开发同时适配 H5 与微信小程序等多端
- 开发体验：Vite 作为构建工具，提供快速热更新与代理能力；脚本命令覆盖多端开发与构建
- 状态管理：Pinia 简洁直观的状态管理模式
- 类型安全：TypeScript 提供完善的类型约束，降低运行时风险
- 调试与初始化：App 生命周期钩子中进行用户状态初始化与主题应用；H5 环境可选调试工具

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant Vite as "Vite(开发服务器)"
participant Uni as "uni-app(多端编译)"
participant App as "App.vue(main.ts)"
Dev->>Vite : 启动 dev : h5 或 dev : mp-weixin
Vite->>Uni : 调用 uni 命令进行多端构建
Uni->>App : 初始化应用(createApp)
App->>App : Pinia初始化/用户状态初始化
App-->>Dev : 多端运行结果(H5/小程序)
```

**图表来源**
- [my-uniapp-vue3/package.json:4-37](file://my-uniapp-vue3/package.json#L4-L37)
- [my-uniapp-vue3/vite.config.ts:1-24](file://my-uniapp-vue3/vite.config.ts#L1-L24)
- [my-uniapp-vue3/src/main.ts:10-31](file://my-uniapp-vue3/src/main.ts#L10-L31)
- [my-uniapp-vue3/src/App.vue:10-25](file://my-uniapp-vue3/src/App.vue#L10-L25)

**章节来源**
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [my-uniapp-vue3/vite.config.ts:1-24](file://my-uniapp-vue3/vite.config.ts#L1-L24)
- [my-uniapp-vue3/src/main.ts:1-32](file://my-uniapp-vue3/src/main.ts#L1-L32)
- [my-uniapp-vue3/src/App.vue:1-134](file://my-uniapp-vue3/src/App.vue#L1-L134)

### 后端技术栈：Node.js 18 + Koa 2.x + Prisma + MySQL
- 服务启动：Koa 应用集中注册中间件（错误处理、性能监控、日志、安全、CORS、限流）、静态资源挂载与路由注册
- 配置中心：统一加载环境变量与模型配置，支持多供应商模型切换
- 数据层：Prisma 作为 ORM，提供强类型查询与迁移；MySQL 作为持久化存储
- 模块化：控制器/服务分离，TTS、视频生成、播放器、支付等模块清晰解耦

```mermaid
flowchart TD
Start(["启动 Koa 应用"]) --> InitSentry["初始化 Sentry"]
InitSentry --> ConnectDB["连接 MySQL(Prisma)"]
ConnectDB --> TestRedis["测试 Redis 连接"]
TestRedis --> TestStorage["测试存储连接(OSS/本地)"]
TestStorage --> InitWS["初始化 WebSocket 服务"]
InitWS --> MountStatic["挂载静态资源(/uploads,/videos)"]
MountStatic --> RegisterRoutes["注册业务路由"]
RegisterRoutes --> Listen["监听端口并启动服务"]
Listen --> Queue["初始化任务队列(书籍生成)"]
Queue --> Graceful["注册优雅关闭(SIGTERM/SIGINT)"]
```

**图表来源**
- [server/src/app.ts:133-192](file://server/src/app.ts#L133-L192)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [server/prisma/schema.prisma:1-8](file://server/prisma/schema.prisma#L1-L8)

**章节来源**
- [server/src/app.ts:1-194](file://server/src/app.ts#L1-L194)
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)

### 音频处理：FFmpeg 处理器
- 能力范围：下载远程文件、合并音频、合并音视频、获取时长、格式转换、裁剪、音量调节
- 存储抽象：统一通过 storageService 上传至本地或 OSS，屏蔽底层差异
- 临时文件：集中管理 temp 目录，完成后清理，避免磁盘污染

```mermaid
flowchart TD
In(["输入URL/本地路径"]) --> Download["下载到本地临时目录"]
Download --> BuildList["生成 FFmpeg 列表文件"]
BuildList --> Merge["执行 FFmpeg 合并"]
Merge --> Upload["上传到存储(OSS/本地)"]
Upload --> Out(["输出最终URL"])
Download -.-> Cleanup["清理临时文件"]
Merge -.-> Cleanup
```

**图表来源**
- [server/src/services/ffmpeg.processor.ts:29-122](file://server/src/services/ffmpeg.processor.ts#L29-L122)

**章节来源**
- [server/src/services/ffmpeg.processor.ts:1-379](file://server/src/services/ffmpeg.processor.ts#L1-L379)

### 语音合成：阿里云TTS 与 MiniMax
- 多通道策略：优先使用 MiniMax（异步长文本），其次阿里云 HTTP，最后模拟降级
- 文本分段：针对阿里云限制进行安全分段，避免超长文本导致失败
- 并发与降级：不同提供商采用不同并发策略；额度受限时自动切换下一通道
- LRC歌词：根据时长与字数估算生成歌词时间轴
- 预览与回调：支持预览音频生成与完成回调，便于前端交互

```mermaid
sequenceDiagram
participant FE as "前端"
participant API as "TTS 控制器"
participant SVC as "TTS 服务"
participant PM as "提供商工厂"
participant ALI as "阿里云 Provider"
participant MM as "MiniMax Provider"
participant FFM as "FFmpeg 处理器"
FE->>API : 请求生成音频
API->>SVC : generateAudio(...)
SVC->>PM : 选择提供商(minimax/aliyun/mock)
alt MiniMax
PM->>MM : synthesize(长文本, 异步轮询)
else 阿里云
PM->>ALI : synthesize(HTTP, 分段)
else 模拟
PM->>SVC : 生成占位音频
end
SVC->>FFM : 合并/上传/时长探测
SVC-->>API : 返回音频URL/时长
API-->>FE : 返回结果
```

**图表来源**
- [server/src/modules/tts/tts.service.ts:200-542](file://server/src/modules/tts/tts.service.ts#L200-L542)
- [server/src/modules/tts/aliyun.provider.ts:21-150](file://server/src/modules/tts/aliyun.provider.ts#L21-L150)
- [server/src/modules/tts/minimax.provider.ts:53-278](file://server/src/modules/tts/minimax.provider.ts#L53-L278)
- [server/src/services/ffmpeg.processor.ts:69-122](file://server/src/services/ffmpeg.processor.ts#L69-L122)

**章节来源**
- [server/src/modules/tts/tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [server/src/modules/tts/aliyun.provider.ts:1-152](file://server/src/modules/tts/aliyun.provider.ts#L1-L152)
- [server/src/modules/tts/minimax.provider.ts:1-280](file://server/src/modules/tts/minimax.provider.ts#L1-L280)

### 数据模型与关系
- 书籍体系：Book → BookChapter → AudioRecord（含播放记录、收藏、专辑等扩展）
- 学习路径体系：LearningPath → Subject → Chapter → Section → ContentBlock
- 关键状态：draft/generating/completed/failed 等贯穿多表
- 索引设计：围绕用户、时间、唯一组合建立索引，提升查询效率

```mermaid
erDiagram
USER {
int id PK
string phone
string openid
string nickname
string avatar
int memberLevel
datetime memberExpireAt
}
BOOK {
int id PK
int userId
string title
string status
int totalChapters
int estimatedWords
}
BOOKCHAPTER {
int id PK
int bookId FK
int number
string title
string status
string audioUrl
int audioDuration
}
AUDIORECORD {
int id PK
int userId
string audioId
string title
string audioUrl
int audioDuration
string status
}
USER ||--o{ BOOK : "拥有"
BOOK ||--o{ BOOKCHAPTER : "包含"
BOOKCHAPTER ||--o{ AUDIORECORD : "生成"
```

**图表来源**
- [server/prisma/schema.prisma:10-194](file://server/prisma/schema.prisma#L10-L194)
- [docs/database-structure.md:1-402](file://docs/database-structure.md#L1-L402)

**章节来源**
- [server/prisma/schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)
- [docs/database-structure.md:1-402](file://docs/database-structure.md#L1-L402)

## 依赖分析
- 前端依赖：uni-app 生态、Vue3、Pinia、vconsole、marked、katex 等
- 后端依赖：Koa 生态、Prisma、LangChain/LangGraph、Bull 队列、Axios、Fluent-FFmpeg、ioredis、Sentry、Winston 等
- 关键耦合点：TTS 服务对提供商与存储的抽象依赖；FFmpeg 处理器对存储上传的依赖；应用启动对数据库/缓存/存储的健康检查

```mermaid
graph LR
FE["前端(uniapp)"] --> API["后端(Koa)"]
API --> PRISMA["Prisma(ORM)"]
API --> PROVIDERS["TTS提供商(Aliyun/MiniMax)"]
API --> FFMPEG["FFmpeg 处理器"]
API --> STORAGE["存储服务(OSS/本地)"]
API --> REDIS["Redis(缓存/队列)"]
API --> MYSQL["MySQL(持久化)"]
```

**图表来源**
- [my-uniapp-vue3/package.json:39-63](file://my-uniapp-vue3/package.json#L39-L63)
- [server/package.json:11-44](file://server/package.json#L11-L44)
- [server/src/app.ts:133-192](file://server/src/app.ts#L133-L192)

**章节来源**
- [my-uniapp-vue3/package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [server/package.json:1-60](file://server/package.json#L1-L60)
- [server/src/app.ts:1-194](file://server/src/app.ts#L1-L194)

## 性能考虑
- 并发策略：不同提供商采用不同并发度，兼顾吞吐与稳定性
- 降级与重试：提供商额度受限或服务异常时自动切换与指数退避重试
- 临时文件管理：FFmpeg 处理完成后清理，避免磁盘占用
- 存储抽象：统一通过 storageService 上传，支持 OSS 与本地切换
- 中间件：性能监控、日志、安全与限流中间件在请求链路中提供可观测性与稳定性

[本节为通用性能讨论，无需特定文件引用]

## 故障排查指南
- 健康检查：后端提供 /health 与 /metrics 接口，便于容器化部署与监控
- 日志与错误：Winston 日志与 Sentry 错误上报，结合中间件统一处理
- TTS 状态：通过文件系统标记与数据库状态联动，定位失败与僵尸任务
- 存储与缓存：启动阶段对 Redis 与存储进行连通性测试，失败时给出明确提示
- 代理与端口：Vite 代理指向后端 3000 端口，确保开发环境联调畅通

**章节来源**
- [server/src/app.ts:91-98](file://server/src/app.ts#L91-L98)
- [server/src/app.ts:142-151](file://server/src/app.ts#L142-L151)
- [server/src/modules/tts/tts.service.ts:547-597](file://server/src/modules/tts/tts.service.ts#L547-L597)

## 结论
本项目在技术选型上实现了“前端跨平台统一、后端模块化可扩展、音频处理与语音合成高可用”的目标。通过 uniapp + Vue3 + TypeScript 的前端组合，配合 Koa + Prisma 的后端架构，以及 FFmpeg 与阿里云/MiniMax 的音频能力，形成了从内容生成到播放消费的完整闭环。在性能、可扩展性与可维护性之间取得了良好平衡，适合持续演进与规模化运营。