# 项目概述

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [API 文档](file://docs/API.md)
- [数据库结构文档](file://docs/database-structure.md)
- [前端 package.json](file://my-uniapp-vue3/package.json)
- [后端应用入口](file://server/src/app.ts)
- [后端配置](file://server/src/config/index.ts)
- [认证控制器](file://server/src/modules/auth/auth.controller.ts)
- [TTS 控制器](file://server/src/modules/tts/tts.controller.ts)
- [前端入口 main.ts](file://my-uniapp-vue3/src/main.ts)
</cite>

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

## 简介
本项目是一个面向内容创作者的“AI 有声书生成平台”，旨在以低成本、高效率的方式将文字内容转换为高质量音频，支持多种音色、参数调节、在线播放、历史管理与会员体系等功能。项目采用前后端分离架构：前端基于 uniapp + Vue 3 + TypeScript，后端基于 Node.js + Koa.js + MongoDB，并通过 FFmpeg 进行音频处理，集成阿里云 TTS 提供语音合成能力。

项目定位清晰：为自媒体作者、小说爱好者、学习者提供从“文本到音频”的一站式工具链，覆盖从创作、生成、播放到管理的全生命周期。

**章节来源**
- [README.md:1-168](file://README.md#L1-L168)

## 项目结构
项目采用“双工程”结构：前端在 my-uniapp-vue3 目录，后端在 server 目录；同时提供部署打包产物在 deploy-package 目录。整体目录组织如下：

```mermaid
graph TB
Root["项目根目录"]
Frontend["前端工程<br/>my-uniapp-vue3"]
Backend["后端工程<br/>server"]
Docs["文档<br/>docs"]
Deploy["部署包<br/>deploy-package"]
Root --> Frontend
Root --> Backend
Root --> Docs
Root --> Deploy
Frontend --> F_Pkg["package.json<br/>脚本与依赖"]
Frontend --> F_Main["src/main.ts<br/>应用入口"]
Frontend --> F_Router["pages/*<br/>页面与组件"]
Backend --> B_App["src/app.ts<br/>应用入口"]
Backend --> B_Config["src/config/index.ts<br/>配置中心"]
Backend --> B_Modules["src/modules/*<br/>业务模块"]
Backend --> B_Services["src/services/*<br/>基础设施服务"]
Backend --> B_DB["prisma/schema.prisma<br/>数据模型"]
Docs --> D_API["API.md"]
Docs --> D_DB["database-structure.md"]
```

**图表来源**
- [前端 package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [后端应用入口:1-194](file://server/src/app.ts#L1-L194)
- [后端配置:1-117](file://server/src/config/index.ts#L1-L117)

**章节来源**
- [README.md:31-52](file://README.md#L31-L52)
- [前端 package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [后端应用入口:1-194](file://server/src/app.ts#L1-L194)

## 核心组件
- 前端（uniapp + Vue 3 + TypeScript）
  - 使用 Pinia 进行状态管理，支持 H5 与微信小程序等多端运行。
  - 页面涵盖登录、播放器、历史、会员、草稿、发布、搜索、设置等。
- 后端（Node.js + Koa.js + MongoDB）
  - 提供认证、TTS、音频管理、会员与订阅、播放器、历史、分享、视频生成等模块。
  - 通过中间件实现安全、性能与错误处理；通过队列与持久化保障异步生成的可靠性。
- 音频处理与第三方服务
  - FFmpeg 用于音频处理与合并。
  - 阿里云 TTS（DashScope）提供高质量语音合成，支持实时与非实时模式。
- 数据层
  - 使用 Prisma 管理 MongoDB 数据模型，支持书籍体系与学习路径体系双轨并行。

**章节来源**
- [README.md:18-30](file://README.md#L18-L30)
- [后端应用入口:26-54](file://server/src/app.ts#L26-L54)
- [后端配置:83-93](file://server/src/config/index.ts#L83-L93)

## 架构总览
系统采用“前端多端 + 后端微服务模块化 + 第三方服务集成”的架构，核心交互流程如下：

```mermaid
graph TB
subgraph "前端"
FE_Login["登录/注册"]
FE_Player["播放器"]
FE_History["历史与收藏"]
FE_Member["会员中心"]
end
subgraph "后端"
BE_Auth["认证模块"]
BE_TTS["TTS 模块"]
BE_Player["播放器模块"]
BE_History["历史模块"]
BE_Sub["会员与订阅模块"]
BE_Share["分享模块"]
BE_Video["视频生成模块"]
end
subgraph "基础设施"
DB["MongoDB"]
OSS["对象存储"]
FFmpeg["FFmpeg"]
AliyunTTS["阿里云 TTS"]
end
FE_Login --> BE_Auth
FE_Player --> BE_Player
FE_History --> BE_History
FE_Member --> BE_Sub
BE_Auth --> DB
BE_TTS --> AliyunTTS
BE_TTS --> FFmpeg
BE_Player --> DB
BE_History --> DB
BE_Sub --> DB
BE_Share --> DB
BE_Video --> FFmpeg
BE_TTS --> OSS
BE_Player --> OSS
```

**图表来源**
- [后端应用入口:26-54](file://server/src/app.ts#L26-L54)
- [后端配置:83-93](file://server/src/config/index.ts#L83-L93)
- [API 文档:1-499](file://docs/API.md#L1-L499)

## 详细组件分析

### 认证模块
- 功能要点
  - 发送短信验证码（开发环境直接返回验证码便于调试）。
  - 手机号登录（跳过验证码校验，简化流程）。
  - 获取与更新用户信息。
- 安全与中间件
  - 使用鉴权中间件保护受保护接口。
  - 参数校验与错误处理统一由中间件承担。
- 数据模型
  - 用户信息存储于 MongoDB，Prisma 提供 ORM 能力。

```mermaid
sequenceDiagram
participant U as "用户"
participant FE as "前端"
participant AUTH as "认证控制器"
participant SVC as "认证服务"
participant DB as "数据库"
U->>FE : 输入手机号
FE->>AUTH : POST /api/auth/send-code
AUTH->>SVC : 生成并返回验证码
SVC-->>AUTH : 验证码
AUTH-->>FE : 返回验证码开发环境
U->>FE : 输入验证码/或直接登录
FE->>AUTH : POST /api/auth/login
AUTH->>SVC : 登录处理
SVC->>DB : 查询/创建用户
DB-->>SVC : 用户信息
SVC-->>AUTH : {token, user}
AUTH-->>FE : 返回登录结果
```

**图表来源**
- [认证控制器:10-52](file://server/src/modules/auth/auth.controller.ts#L10-L52)

**章节来源**
- [认证控制器:10-52](file://server/src/modules/auth/auth.controller.ts#L10-L52)
- [API 文档:15-91](file://docs/API.md#L15-L91)

### TTS 语音合成模块
- 功能要点
  - 获取音色列表与可用 TTS 供应商。
  - 生成音频（异步），支持参数调节（语速、音调、音量）。
  - 预览音色（生成短音频）。
  - 下载与批量下载音频。
- 限额与配额
  - 与会员体系联动，按字数估算音频分钟并消费配额。
- 第三方集成
  - 阿里云 TTS（DashScope）提供高质量语音合成，支持实时与非实时模式。

```mermaid
sequenceDiagram
participant U as "用户"
participant FE as "前端"
participant TTS as "TTS 控制器"
participant SVC as "TTS 服务"
participant SUB as "订阅服务"
participant TTSProv as "阿里云 TTS"
participant FS as "对象存储/文件系统"
U->>FE : 选择音色并输入文本
FE->>TTS : POST /api/tts/generate
TTS->>SUB : 检查配额/消费分钟
TTS->>SVC : 异步生成音频
SVC->>TTSProv : 调用 TTS 接口
TTSProv-->>SVC : 返回音频片段/流
SVC->>FS : 保存并合并音频
SVC-->>TTS : 返回任务信息
TTS-->>FE : 返回任务ID与预估结果
FE->>FE : 轮询状态/下载音频
```

**图表来源**
- [TTS 控制器:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127)
- [后端配置:83-93](file://server/src/config/index.ts#L83-L93)

**章节来源**
- [TTS 控制器:12-127](file://server/src/modules/tts/tts.controller.ts#L12-L127)
- [API 文档:95-156](file://docs/API.md#L95-L156)

### 音频播放与历史管理
- 播放器模块
  - 支持播放、暂停、进度控制、倍速播放等。
  - 与播放列表、专辑进行关联。
- 历史与收藏
  - 支持历史记录分页查询、收藏切换、删除。
- 数据模型
  - Audio 表存储音频元数据与状态，Album/AlbumAudio 关联专辑与音频。

```mermaid
flowchart TD
Start(["进入播放页"]) --> LoadList["加载音频列表"]
LoadList --> SelectAudio{"选择音频"}
SelectAudio --> |单个| Play["播放音频"]
SelectAudio --> |批量| Batch["加入播放列表"]
Play --> Progress["进度控制/倍速"]
Progress --> Favorite{"收藏/取消收藏"}
Favorite --> Update["更新收藏状态"]
Update --> History["写入历史记录"]
History --> End(["完成"])
```

**图表来源**
- [API 文档:160-275](file://docs/API.md#L160-L275)
- [数据库结构文档:104-128](file://docs/database-structure.md#L104-L128)

**章节来源**
- [API 文档:160-275](file://docs/API.md#L160-L275)
- [数据库结构文档:104-128](file://docs/database-structure.md#L104-L128)

### 会员与订阅体系
- 权益与等级
  - 免费版、月度会员、年度会员，差异化配额与音色权限。
- 订单与支付
  - 订单创建与支付流程（模拟接口）。
- 配额与计费
  - 按字数估算音频分钟并消费配额，支持跨模块复用。

```mermaid
classDiagram
class MemberPlan {
+level : number
+name : string
+price : number
+features : string[]
}
class User {
+id : number
+memberLevel : number
+quota : Quota
}
class Quota {
+dailyLimit : number
+dailyUsed : number
+dailyRemaining : number
+wordLimit : number
}
class SubscriptionService {
+checkAudioQuota(userId, words)
+consumeAudioMinutes(userId, words, desc)
}
User --> MemberPlan : "拥有"
User --> Quota : "持有"
SubscriptionService --> User : "读取/更新"
```

**图表来源**
- [API 文档:279-401](file://docs/API.md#L279-L401)
- [TTS 控制器:87-96](file://server/src/modules/tts/tts.controller.ts#L87-L96)

**章节来源**
- [API 文档:279-401](file://docs/API.md#L279-L401)
- [TTS 控制器:87-96](file://server/src/modules/tts/tts.controller.ts#L87-L96)

### 前端应用入口与状态管理
- 应用入口
  - 使用 Vue 3 + SSR 创建应用实例，挂载 Pinia。
  - 在 H5 环境可选开启 vConsole 调试。
- 状态管理
  - 使用 Pinia 管理用户状态与音频播放状态，保证跨页面一致性。

```mermaid
sequenceDiagram
participant H5 as "H5/小程序"
participant Main as "main.ts"
participant Pinia as "Pinia"
participant UserStore as "User Store"
H5->>Main : 启动应用
Main->>Pinia : 创建并挂载
Main->>UserStore : 初始化用户状态
UserStore-->>Main : 用户信息就绪
Main-->>H5 : 渲染应用
```

**图表来源**
- [前端入口 main.ts:10-18](file://my-uniapp-vue3/src/main.ts#L10-L18)

**章节来源**
- [前端入口 main.ts:10-18](file://my-uniapp-vue3/src/main.ts#L10-L18)
- [前端 package.json:39-51](file://my-uniapp-vue3/package.json#L39-L51)

## 依赖分析
- 前端依赖
  - @dcloudio/uni-app、vue、pinia、marked、katex 等，支持多端编译与富文本渲染。
- 后端依赖
  - Koa、@koa/router、koa-body、koa-static、@koa/cors 等，提供 Web 服务与静态资源托管。
  - Prisma/Mongoose 用于数据建模与访问。
  - Redis、OSS、FFmpeg、阿里云 TTS 等外部服务。
- 关键耦合点
  - TTS 控制器与订阅服务耦合，确保配额与计费一致。
  - 播放器与历史模块共享音频元数据，避免重复查询。

```mermaid
graph LR
FE["@dcloudio/uni-app<br/>vue<br/>pinia"] --> APP["应用"]
APP --> ROUTER["页面路由"]
ROUTER --> STORE["Pinia Store"]
BE["Koa + 路由"] --> CTRL["控制器"]
CTRL --> SVC["服务层"]
SVC --> DB["Prisma/MongoDB"]
SVC --> EXT["Redis/OSS/FFmpeg/Aliyun TTS"]
```

**图表来源**
- [前端 package.json:39-51](file://my-uniapp-vue3/package.json#L39-L51)
- [后端应用入口:57-130](file://server/src/app.ts#L57-L130)

**章节来源**
- [前端 package.json:39-51](file://my-uniapp-vue3/package.json#L39-L51)
- [后端应用入口:57-130](file://server/src/app.ts#L57-L130)

## 性能考虑
- 异步生成与队列
  - TTS 生成采用异步任务与队列机制，避免阻塞请求线程，提升吞吐。
- 缓存与限流
  - Redis 作为缓存层，减少数据库压力；限流中间件保护接口稳定。
- 静态资源与 CDN
  - 音频与视频文件通过静态托管与对象存储分发，降低服务器负载。
- 音频处理优化
  - FFmpeg 合并与格式转换在后台执行，前端仅接收任务状态与下载链接。

[本节为通用指导，无需具体文件分析]

## 故障排查指南
- 常见问题定位
  - 启动失败：查看后端健康检查接口与日志输出，确认数据库、Redis、存储连接状态。
  - TTS 生成失败：检查阿里云 TTS 配置与网络连通性，关注实时/非实时模式切换。
  - 音频无法播放：确认对象存储 URL 可访问，检查 CORS 配置。
- 错误码与响应格式
  - 统一响应格式，错误码 400/401/403/404/500 明确含义，便于前端提示与日志追踪。

**章节来源**
- [后端应用入口:92-94](file://server/src/app.ts#L92-L94)
- [API 文档:475-498](file://docs/API.md#L475-L498)

## 结论
本项目以“易用、高效、可扩展”为目标，构建了从文本到音频的完整工具链。前端多端适配与后端模块化设计，配合 FFmpeg 与阿里云 TTS 的强大能力，能够满足内容创作者的多样化需求。通过会员体系与配额机制，平台实现了可持续的商业化闭环。未来可在批量生成、音频编辑、多格式导出等方面持续演进，进一步提升用户体验与生产效率。

[本节为总结性内容，无需具体文件分析]

## 附录
- 快速开始
  - 后端：安装依赖、复制环境变量、启动开发服务。
  - 前端：安装依赖、启动 H5 开发或编译小程序。
- API 参考
  - 认证、TTS、音频、会员、分享等模块接口与参数说明详见 API 文档。
- 数据模型
  - 书籍体系与学习路径体系双轨结构，支持复杂内容组织与检索。

**章节来源**
- [README.md:54-90](file://README.md#L54-L90)
- [API 文档:1-499](file://docs/API.md#L1-L499)
- [数据库结构文档:1-402](file://docs/database-structure.md#L1-L402)