# 系统架构

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [my-uniapp-vue3/package.json](file://my-uniapp-vue3/package.json)
- [server/package.json](file://server/package.json)
- [server/src/app.ts](file://server/src/app.ts)
- [deploy-package/server/app.js](file://deploy-package/server/app.js)
- [server/src/modules/auth/auth.controller.ts](file://server/src/modules/auth/auth.controller.ts)
- [server/src/modules/tts/tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [server/src/modules/member/member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [server/src/modules/book-generator/book-generator.controller.ts](file://server/src/modules/book-generator/book-generator.controller.ts)
- [server/src/modules/video-generator/video-generator.controller.ts](file://server/src/modules/video-generator/video-generator.controller.ts)
- [server/src/services/ffmpeg.processor.ts](file://server/src/services/ffmpeg.processor.ts)
- [server/src/config/index.ts](file://server/src/config/index.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [my-uniapp-vue3/src/main.ts](file://my-uniapp-vue3/src/main.ts)
- [my-uniapp-vue3/src/utils/request.ts](file://my-uniapp-vue3/src/utils/request.ts)
- [docker-nginx/docker-compose.yml](file://docker-nginx/docker-compose.yml)
- [docker-nginx/bookapi.conf](file://docker-nginx/bookapi.conf)
</cite>

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

## 引言
本系统是一个“AI有声书生成平台”，采用前后端分离架构：前端基于 uniapp + Vue 3 + TypeScript，后端基于 Koa.js，数据库采用 Prisma + MySQL，音频处理通过 FFmpeg 与对象存储结合。系统支持 TTS 文本转音频、会员体系、书籍批量生成（内容-音频-视频）、视频生成与合并、播放器与播放列表、搜索与偏好设置等能力。

## 项目结构
- 前端（uniapp + Vue 3 + TypeScript）
  - 应用入口与状态管理：src/main.ts、store/
  - 页面与组件：src/pages、src/components
  - 工具与网络请求：src/utils/request.ts、config.ts 等
  - 构建脚本：my-uniapp-vue3/package.json
- 后端（Koa.js + TypeScript）
  - 应用入口与中间件：server/src/app.ts
  - 模块化路由：server/src/modules/*/*.controller.ts
  - 服务层与工具：server/src/services/*
  - 配置与模型：server/src/config、server/prisma/schema.prisma
  - 构建脚本：server/package.json
- 部署与反向代理
  - Nginx 反代：docker-nginx/bookapi.conf、docker-compose.yml
- 文档与说明
  - README.md 展示技术栈、API 与快速开始

```mermaid
graph TB
subgraph "前端(uniapp)"
FE_App["应用入口<br/>src/main.ts"]
FE_Utils["网络请求<br/>src/utils/request.ts"]
FE_Router["页面与组件<br/>src/pages/*, src/components/*"]
end
subgraph "后端(Koa.js)"
BE_App["应用入口<br/>server/src/app.ts"]
BE_Modules["业务模块路由<br/>modules/*/*.controller.ts"]
BE_Services["服务与工具<br/>services/*"]
BE_DB["数据模型<br/>prisma/schema.prisma"]
BE_Config["配置<br/>src/config/index.ts"]
end
subgraph "基础设施"
Nginx["Nginx 反向代理<br/>docker-nginx/bookapi.conf"]
Docker["Docker Compose<br/>docker-compose.yml"]
Storage["对象存储/本地存储"]
FFmpeg["FFmpeg 处理器<br/>services/ffmpeg.processor.ts"]
end
FE_App --> FE_Utils
FE_Router --> FE_Utils
FE_Utils --> Nginx
Nginx --> BE_App
BE_App --> BE_Modules
BE_Modules --> BE_Services
BE_Services --> BE_DB
BE_Services --> Storage
BE_Services --> FFmpeg
Docker --> Nginx
```

图表来源
- [server/src/app.ts:57-130](file://server/src/app.ts#L57-L130)
- [my-uniapp-vue3/src/main.ts:10-31](file://my-uniapp-vue3/src/main.ts#L10-L31)
- [my-uniapp-vue3/src/utils/request.ts:35-99](file://my-uniapp-vue3/src/utils/request.ts#L35-L99)
- [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15)

章节来源
- [README.md:18-52](file://README.md#L18-L52)
- [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)

## 核心组件
- 前端应用（uniapp + Vue 3 + TypeScript）
  - 使用 Pinia 管理状态，提供 H5 与微信小程序等多端运行
  - 通过统一请求封装与调试日志，支持重试、缓存与错误提示
- 后端服务（Koa.js）
  - 中间件链路：错误处理、CORS、日志、安全防护、限流、性能监控
  - 路由按模块划分：认证、TTS、会员、播放器、收藏、偏好、搜索、分类、评论、通知、模板、BGM、音频编辑、书籍生成、视频生成等
  - 配置集中管理：端口、JWT、DashScope TTS、模型列表、上传目录等
  - 数据持久化：Prisma + MySQL，模型覆盖用户、书籍、章节、音频、视频、订单、订阅等
- 音频处理（FFmpeg）
  - 支持远程 URL 下载、合并、格式转换、裁剪、音量调整、音视频合并等
  - 自动上传至对象存储或本地存储
- 部署与反向代理
  - Nginx 反向代理到后端 3000 端口，便于域名访问与 HTTPS 协议透传

章节来源
- [my-uniapp-vue3/src/main.ts:10-31](file://my-uniapp-vue3/src/main.ts#L10-L31)
- [my-uniapp-vue3/src/utils/request.ts:35-99](file://my-uniapp-vue3/src/utils/request.ts#L35-L99)
- [server/src/app.ts:64-130](file://server/src/app.ts#L64-L130)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [server/prisma/schema.prisma:10-472](file://server/prisma/schema.prisma#L10-L472)
- [server/src/services/ffmpeg.processor.ts:24-379](file://server/src/services/ffmpeg.processor.ts#L24-L379)
- [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15)

## 架构总览
系统采用“前端 uniapp + 后端 Koa + 数据库 MySQL + 第三方服务/工具”的分层架构。前端通过 HTTP/HTTPS 与后端交互；后端通过 Prisma 访问 MySQL；音频处理通过 FFmpeg 与对象存储协同；Nginx 作为反向代理统一入口。

```mermaid
graph TB
Client["客户端(H5/小程序)"]
FE["前端 uniapp 应用"]
API["Koa 后端服务"]
DB["MySQL 数据库"]
OSS["对象存储(本地/阿里云OSS)"]
FFMPEG["FFmpeg 处理器"]
Nginx["Nginx 反向代理"]
Client --> FE
FE --> Nginx
Nginx --> API
API --> DB
API --> OSS
API --> FFMPEG
FFMPEG --> OSS
```

图表来源
- [server/src/app.ts:133-194](file://server/src/app.ts#L133-L194)
- [server/src/services/ffmpeg.processor.ts:24-379](file://server/src/services/ffmpeg.processor.ts#L24-L379)
- [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15)

## 详细组件分析

### 前端组件分析（uniapp + Vue 3 + TypeScript）
- 应用入口与状态
  - 创建 SSR App、注册 Pinia，初始化用户状态
- 网络请求封装
  - 统一基地址、Token 注入、重试、缓存、超时、错误处理与登录态失效跳转
- 页面与组件
  - 页面路由、播放器、骨架屏、下载组件等

```mermaid
sequenceDiagram
participant U as "用户"
participant P as "前端页面"
participant R as "请求封装"
participant N as "Nginx 反代"
participant S as "Koa 后端"
U->>P : 触发操作
P->>R : request(url, options)
R->>R : 注入 Authorization/缓存/重试
R->>N : HTTP 请求
N->>S : 反向代理转发
S-->>R : 返回 {code,data}
R-->>P : 成功/失败处理与提示
P-->>U : 更新界面
```

图表来源
- [my-uniapp-vue3/src/utils/request.ts:35-99](file://my-uniapp-vue3/src/utils/request.ts#L35-L99)
- [docker-nginx/bookapi.conf:6-13](file://docker-nginx/bookapi.conf#L6-L13)
- [server/src/app.ts:92-130](file://server/src/app.ts#L92-L130)

章节来源
- [my-uniapp-vue3/src/main.ts:10-31](file://my-uniapp-vue3/src/main.ts#L10-L31)
- [my-uniapp-vue3/src/utils/request.ts:35-99](file://my-uniapp-vue3/src/utils/request.ts#L35-L99)

### 后端组件分析（Koa.js + 模块化路由）
- 应用入口与中间件
  - 错误处理、Sentry、性能监控、Winston 日志、CORS、安全防护、限流、BodyParser、静态文件挂载
- 路由模块
  - 认证、TTS、会员、播放器、收藏、偏好、搜索、分类、评论、通知、模板、BGM、音频编辑、书籍生成、视频生成等
- 配置与模型
  - 端口、JWT、DashScope TTS、模型列表、上传目录等
  - Prisma 模型覆盖用户、书籍、章节、音频、视频、订单、订阅等

```mermaid
classDiagram
class KoaApp {
+中间件链
+路由注册
+静态文件
}
class AuthController {
+发送验证码
+手机号登录
+获取/更新用户信息
}
class TTSController {
+获取音色/服务商
+异步生成音频
+预览音色
+下载信息/批量下载
}
class MemberController {
+权益信息
+会员状态
+创建订单
+模拟支付
+订单列表
}
class BookGenController {
+批量生成书籍
+取消任务
+查询状态
}
class VideoGenController {
+项目管理
+生成视频
+素材管理
+从书籍生成项目
}
KoaApp --> AuthController : "注册路由"
KoaApp --> TTSController : "注册路由"
KoaApp --> MemberController : "注册路由"
KoaApp --> BookGenController : "注册路由"
KoaApp --> VideoGenController : "注册路由"
```

图表来源
- [server/src/app.ts:64-130](file://server/src/app.ts#L64-L130)
- [server/src/modules/auth/auth.controller.ts:10-94](file://server/src/modules/auth/auth.controller.ts#L10-L94)
- [server/src/modules/tts/tts.controller.ts:12-274](file://server/src/modules/tts/tts.controller.ts#L12-L274)
- [server/src/modules/member/member.controller.ts:9-90](file://server/src/modules/member/member.controller.ts#L9-L90)
- [server/src/modules/book-generator/book-generator.controller.ts:24-199](file://server/src/modules/book-generator/book-generator.controller.ts#L24-L199)
- [server/src/modules/video-generator/video-generator.controller.ts:28-244](file://server/src/modules/video-generator/video-generator.controller.ts#L28-L244)

章节来源
- [server/src/app.ts:64-130](file://server/src/app.ts#L64-L130)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [server/prisma/schema.prisma:10-472](file://server/prisma/schema.prisma#L10-L472)

### 音频处理流程（FFmpeg）
- 支持的功能
  - 下载远程文件、合并音频、音视频合并、获取时长、格式转换、裁剪、音量调整
  - 自动清理临时文件，上传至对象存储
- 流程示意

```mermaid
flowchart TD
Start(["进入处理"]) --> CheckURL["校验输入URL/本地路径"]
CheckURL --> Download["下载到本地临时目录"]
Download --> DecideOp{"操作类型？"}
DecideOp --> |合并音频| Merge["构建文件列表并执行合并"]
DecideOp --> |音视频合并| MergeAV["合并音视频(可选BGM混音)"]
DecideOp --> |获取时长| Probe["ffprobe 获取时长"]
DecideOp --> |格式转换| Convert["按目标格式转换"]
DecideOp --> |裁剪| Trim["按时间段裁剪"]
DecideOp --> |音量调整| Volume["按倍数调整音量"]
Merge & MergeAV & Probe & Convert & Trim & Volume --> Upload["上传至对象存储"]
Upload --> Cleanup["清理临时文件"]
Cleanup --> End(["结束"])
```

图表来源
- [server/src/services/ffmpeg.processor.ts:24-379](file://server/src/services/ffmpeg.processor.ts#L24-L379)

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

### 微服务化模块划分策略
- 认证模块：手机号登录、验证码、用户信息维护
- TTS 模块：音色/服务商查询、异步生成、预览、下载与批量下载
- 会员模块：权益、状态、订单、模拟支付、订单列表
- 书籍生成模块：内容生成、音频生成、音频合并、视频生成、视频合并、批量任务与取消
- 视频生成模块：项目管理、素材管理、从书籍生成项目
- 其他模块：播放器、收藏、偏好、搜索、分类、评论、通知、模板、BGM、音频编辑、历史、草稿、发布、签到、订阅、支付、反馈等

章节来源
- [server/src/modules/auth/auth.controller.ts:10-94](file://server/src/modules/auth/auth.controller.ts#L10-L94)
- [server/src/modules/tts/tts.controller.ts:12-274](file://server/src/modules/tts/tts.controller.ts#L12-L274)
- [server/src/modules/member/member.controller.ts:9-90](file://server/src/modules/member/member.controller.ts#L9-L90)
- [server/src/modules/book-generator/book-generator.controller.ts:24-199](file://server/src/modules/book-generator/book-generator.controller.ts#L24-L199)
- [server/src/modules/video-generator/video-generator.controller.ts:28-244](file://server/src/modules/video-generator/video-generator.controller.ts#L28-L244)

### 部署架构（Docker + Nginx 反向代理）
- Docker Compose 启动 Nginx，监听 80 端口，将请求代理到 host.docker.internal:3000
- 后端服务监听 3000 端口，提供健康检查与静态资源服务
- 建议在生产环境增加 HTTPS、负载均衡与多实例部署

```mermaid
graph TB
subgraph "容器编排"
D["docker-compose.yml"]
N["Nginx 容器"]
S["后端服务容器"]
end
D --> N
D --> S
N --> S
```

图表来源
- [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12)
- [docker-nginx/bookapi.conf:6-13](file://docker-nginx/bookapi.conf#L6-L13)
- [deploy-package/server/app.js:82-97](file://deploy-package/server/app.js#L82-L97)

章节来源
- [docker-nginx/docker-compose.yml:1-12](file://docker-nginx/docker-compose.yml#L1-L12)
- [docker-nginx/bookapi.conf:1-15](file://docker-nginx/bookapi.conf#L1-L15)
- [deploy-package/server/app.js:82-97](file://deploy-package/server/app.js#L82-L97)

## 依赖分析
- 前端依赖
  - uni-app 生态、Vue 3、Pinia、vconsole、marked、katex 等
- 后端依赖
  - Koa 生态、@koa/router、@koa/bodyparser、@koa/cors、Prisma、LangChain、Sentry、Bull 队列、Redis、OpenAI、阿里云 OSS、FFmpeg 等
- 数据模型
  - 用户、书籍、章节、音频、视频、订单、订阅、播放记录、收藏、评论、通知、搜索历史、签到、播放列表、草稿、发布任务、素材、反馈等

```mermaid
graph LR
FE["前端 uniapp"] --> API["Koa 后端"]
API --> PRISMA["Prisma"]
PRISMA --> MYSQL["MySQL"]
API --> REDIS["Redis"]
API --> OSS["对象存储"]
API --> FFMPEG["FFmpeg"]
API --> LLM["LangChain/LangGraph"]
```

图表来源
- [server/package.json:11-44](file://server/package.json#L11-L44)
- [server/prisma/schema.prisma:10-472](file://server/prisma/schema.prisma#L10-L472)
- [server/src/services/ffmpeg.processor.ts:24-379](file://server/src/services/ffmpeg.processor.ts#L24-L379)

章节来源
- [server/package.json:11-44](file://server/package.json#L11-L44)
- [server/prisma/schema.prisma:10-472](file://server/prisma/schema.prisma#L10-L472)

## 性能考虑
- 前端
  - 使用请求缓存与重试，减少重复请求与网络波动影响
  - 在 H5 环境可按需开启 vConsole 调试
- 后端
  - 中间件包含性能监控与日志，建议启用限流与安全防护
  - 音频/视频处理为 CPU 密集型，建议配合队列与异步处理
  - 对象存储与本地存储可按需切换，注意带宽与成本
- 部署
  - Nginx 反代简化部署与域名管理，建议横向扩展与负载均衡

## 故障排查指南
- 常见问题定位
  - 健康检查：访问 /health 确认服务可用
  - 日志：查看后端启动日志与错误日志
  - 前端网络：检查请求封装中的错误提示与重试逻辑
- 常见错误与处理
  - 登录态失效：前端检测到 401 自动清空 token 并跳转登录
  - 请求过于频繁：后端返回 429，前端提示稍后再试
  - 服务器错误：后端返回 5xx，前端提示服务器错误
- FFmpeg 处理
  - 检查临时目录权限与磁盘空间
  - 确认远程 URL 可访问与超时设置合理

章节来源
- [server/src/app.ts:92-98](file://server/src/app.ts#L92-L98)
- [my-uniapp-vue3/src/utils/request.ts:135-159](file://my-uniapp-vue3/src/utils/request.ts#L135-L159)
- [server/src/services/ffmpeg.processor.ts:346-375](file://server/src/services/ffmpeg.processor.ts#L346-L375)

## 结论
该系统以 uniapp 实现跨端一致性体验，以 Koa.js 提供轻量且模块化的后端服务，以 Prisma + MySQL 保障数据结构清晰与扩展性，以 FFmpeg 与对象存储支撑音频/视频处理与分发。通过 Nginx 反向代理与容器化部署，具备良好的可运维性与扩展性。后续可在生产环境引入负载均衡、CDN、更完善的限流与监控体系，并持续优化音频/视频处理的并发与成本。

## 附录
- 快速开始与环境要求
  - Node.js >= 18、MySQL >= 6.0、FFmpeg（用于音频处理）
- API 示例（节选）
  - 认证：发送验证码、手机号登录、获取用户信息
  - TTS：音色列表、生成音频、预览音色、下载信息与批量下载
  - 会员：权益信息、会员状态、创建订单、模拟支付、订单列表
  - 书籍生成：批量生成、取消任务、查询状态
  - 视频生成：项目管理、生成视频、素材管理、从书籍生成项目

章节来源
- [README.md:56-113](file://README.md#L56-L113)
- [server/src/modules/auth/auth.controller.ts:10-94](file://server/src/modules/auth/auth.controller.ts#L10-L94)
- [server/src/modules/tts/tts.controller.ts:12-274](file://server/src/modules/tts/tts.controller.ts#L12-L274)
- [server/src/modules/member/member.controller.ts:9-90](file://server/src/modules/member/member.controller.ts#L9-L90)
- [server/src/modules/book-generator/book-generator.controller.ts:24-199](file://server/src/modules/book-generator/book-generator.controller.ts#L24-L199)
- [server/src/modules/video-generator/video-generator.controller.ts:28-244](file://server/src/modules/video-generator/video-generator.controller.ts#L28-L244)