# 项目结构说明

<cite>
**本文档引用的文件**
- [README.md](file://README.md)
- [package.json](file://package.json)
- [server/package.json](file://server/package.json)
- [my-uniapp-vue3/package.json](file://my-uniapp-vue3/package.json)
- [server/src/app.ts](file://server/src/app.ts)
- [server/src/config/index.ts](file://server/src/config/index.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [server/src/middleware/auth.ts](file://server/src/middleware/auth.ts)
- [server/src/services/storage.service.ts](file://server/src/services/storage.service.ts)
- [my-uniapp-vue3/src/main.ts](file://my-uniapp-vue3/src/main.ts)
- [my-uniapp-vue3/src/store/user.ts](file://my-uniapp-vue3/src/store/user.ts)
- [my-uniapp-vue3/src/store/audio.ts](file://my-uniapp-vue3/src/store/audio.ts)
- [my-uniapp-vue3/src/utils/request.ts](file://my-uniapp-vue3/src/utils/request.ts)
- [my-uniapp-vue3/src/pages/index/index.vue](file://my-uniapp-vue3/src/pages/index/index.vue)
- [server/src/modules/book-generator/book-generator.controller.ts](file://server/src/modules/book-generator/book-generator.controller.ts)
</cite>

## 目录
1. [项目简介](#项目简介)
2. [项目结构总览](#项目结构总览)
3. [后端服务架构](#后端服务架构)
4. [前端应用架构](#前端应用架构)
5. [分层架构设计](#分层架构设计)
6. [配置与环境管理](#配置与环境管理)
7. [构建与部署流程](#构建与部署流程)
8. [扩展性与模块化设计](#扩展性与模块化设计)
9. [性能与可靠性](#性能与可靠性)
10. [故障排查指南](#故障排查指南)
11. [结论](#结论)

## 项目简介
本项目是一个基于 AI 的有声书生成平台，提供从文本到音频的全流程自动化能力，并支持音视频内容的创作与发布。后端采用 Node.js + Koa 架构，结合 Prisma ORM 和 MySQL；前端基于 uniapp + Vue 3 + TypeScript，使用 Pinia 进行状态管理，覆盖 H5 与微信小程序等多端。

## 项目结构总览
项目采用前后端分离的模块化组织方式，核心目录如下：
- server：后端 Node.js 服务，包含模块化业务组件、中间件、配置与数据模型
- my-uniapp-vue3：前端 uniapp 应用，包含页面、状态管理、工具函数与类型定义
- deploy-package：部署打包产物，包含前端构建结果与后端配置
- docs：项目文档与部署说明
- docker-nginx：Nginx 部署配置

```mermaid
graph TB
subgraph "后端服务(server)"
A_app["应用入口<br/>src/app.ts"]
A_cfg["配置中心<br/>src/config/index.ts"]
A_mod["业务模块<br/>src/modules/*"]
A_mdw["中间件<br/>src/middleware/*"]
A_svc["服务层<br/>src/services/*"]
A_db["数据模型<br/>prisma/schema.prisma"]
end
subgraph "前端应用(my-uniapp-vue3)"
F_main["应用入口<br/>src/main.ts"]
F_pages["页面组件<br/>src/pages/*"]
F_store["状态管理<br/>src/store/*"]
F_utils["工具函数<br/>src/utils/*"]
F_types["类型定义<br/>src/types/*"]
end
subgraph "部署与文档"
D_pkg["部署包<br/>deploy-package/*"]
D_docs["文档<br/>docs/*"]
D_nginx["Nginx配置<br/>docker-nginx/*"]
end
F_main --> F_store
F_main --> F_pages
F_pages --> F_utils
F_store --> F_utils
F_utils --> F_types
A_app --> A_mod
A_app --> A_mdw
A_app --> A_svc
A_mod --> A_cfg
A_svc --> A_db
```

**图表来源**
- [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/src/main.ts:1-32](file://my-uniapp-vue3/src/main.ts#L1-L32)

**章节来源**
- [README.md:31-52](file://README.md#L31-L52)

## 后端服务架构
后端采用 Koa 作为 Web 框架，通过模块化的方式组织业务功能，涵盖认证、TTS、播放器、收藏、偏好、搜索、分类、评论、通知、背景音乐、音频编辑、书籍生成、播放列表、草稿、视频生成、发布、签到、订阅、支付、历史记录与反馈等模块。应用启动时完成数据库连接、缓存与存储服务测试、订阅套餐初始化、WebSocket 服务启动以及书籍生成队列处理器初始化。

```mermaid
graph TB
S_app["应用入口<br/>src/app.ts"]
S_cfg["配置中心<br/>src/config/index.ts"]
S_auth["认证中间件<br/>src/middleware/auth.ts"]
S_storage["存储服务<br/>src/services/storage.service.ts"]
S_app --> S_auth
S_app --> S_cfg
S_app --> S_storage
S_app --> S_modules["业务模块路由注册<br/>src/app.ts 行100-128"]
```

**图表来源**
- [server/src/app.ts:64-130](file://server/src/app.ts#L64-L130)
- [server/src/middleware/auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [server/src/services/storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)

**章节来源**
- [server/src/app.ts:133-194](file://server/src/app.ts#L133-L194)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)

## 前端应用架构
前端基于 uniapp + Vue 3 + TypeScript，采用 Pinia 进行状态管理，页面结构清晰，包含首页、搜索、播放器、书籍生成、专辑管理、个人中心、设置等多个页面。状态管理分为用户状态与音频播放状态两大 Store，工具函数负责网络请求、配置读取、调试输出与本地存储。

```mermaid
graph TB
F_main["应用入口<br/>src/main.ts"]
F_user["用户状态<br/>src/store/user.ts"]
F_audio["音频状态<br/>src/store/audio.ts"]
F_req["请求封装<br/>src/utils/request.ts"]
F_pages["页面组件<br/>src/pages/*"]
F_main --> F_user
F_main --> F_audio
F_user --> F_req
F_audio --> F_req
F_pages --> F_req
F_pages --> F_user
F_pages --> F_audio
```

**图表来源**
- [my-uniapp-vue3/src/main.ts:10-31](file://my-uniapp-vue3/src/main.ts#L10-L31)
- [my-uniapp-vue3/src/store/user.ts:1-107](file://my-uniapp-vue3/src/store/user.ts#L1-L107)
- [my-uniapp-vue3/src/store/audio.ts:1-297](file://my-uniapp-vue3/src/store/audio.ts#L1-L297)
- [my-uniapp-vue3/src/utils/request.ts:1-207](file://my-uniapp-vue3/src/utils/request.ts#L1-L207)

**章节来源**
- [my-uniapp-vue3/src/pages/index/index.vue:1-758](file://my-uniapp-vue3/src/pages/index/index.vue#L1-L758)

## 分层架构设计
项目采用典型的三层架构：
- 表现层（Presentation Layer）
  - 前端页面与组件负责用户交互与展示，状态管理与工具函数解耦业务逻辑
- 业务逻辑层（Business Logic Layer）
  - 后端模块控制器负责接收请求、调用服务层处理业务、返回标准化响应
- 数据访问层（Data Access Layer）
  - Prisma ORM 提供数据库抽象，支持 MySQL；存储服务统一对接 OSS 与本地存储

```mermaid
graph TB
P["表现层<br/>前端页面/组件"]
B["业务逻辑层<br/>后端模块控制器"]
D["数据访问层<br/>Prisma ORM/存储服务"]
P --> B
B --> D
```

[此图为概念性架构图，无需图表来源]

## 配置与环境管理
后端通过 dotenv 读取环境变量，集中管理端口、数据库、JWT、模型配置与上传目录等参数；前端通过环境变量区分开发与生产环境，统一请求基地址与调试开关。存储服务支持 OSS 与本地存储无缝切换，便于开发与生产环境迁移。

```mermaid
flowchart TD
C_start["启动应用"] --> C_load_env["加载环境变量<br/>.env/.env.local"]
C_load_env --> C_config["初始化配置<br/>config/index.ts"]
C_config --> C_storage["检测存储类型<br/>OSS/Local"]
C_storage --> C_db["连接数据库<br/>Prisma"]
C_db --> C_ready["服务就绪"]
```

**图表来源**
- [server/src/config/index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [server/src/services/storage.service.ts:139-193](file://server/src/services/storage.service.ts#L139-L193)

**章节来源**
- [server/src/config/index.ts:70-117](file://server/src/config/index.ts#L70-L117)
- [server/src/services/storage.service.ts:139-193](file://server/src/services/storage.service.ts#L139-L193)

## 构建与部署流程
- 后端构建与启动
  - 开发：使用 tsx 监听模式启动，支持热更新
  - 生产：TypeScript 编译为 JavaScript，运行 dist/app.js
- 前端构建与多端编译
  - H5 开发与生产构建
  - 微信小程序等多端构建命令
- 部署架构
  - Nginx 反向代理与静态资源服务
  - 前端构建产物放置于 Nginx 目录
  - 后端服务独立部署，通过环境变量配置数据库与存储

```mermaid
sequenceDiagram
participant Dev as "开发者"
participant FE as "前端构建"
participant BE as "后端构建"
participant NGINX as "Nginx"
participant DB as "数据库"
Dev->>FE : npm run dev : h5 / build : mp-weixin
FE-->>NGINX : 上传构建产物
Dev->>BE : npm run build / start
BE->>DB : 连接数据库
BE-->>NGINX : 暴露 API 端点
```

**图表来源**
- [server/package.json:6-9](file://server/package.json#L6-L9)
- [my-uniapp-vue3/package.json:4-36](file://my-uniapp-vue3/package.json#L4-L36)

**章节来源**
- [README.md:62-90](file://README.md#L62-L90)
- [server/package.json:6-9](file://server/package.json#L6-L9)
- [my-uniapp-vue3/package.json:4-36](file://my-uniapp-vue3/package.json#L4-L36)

## 扩展性与模块化设计
- 模块化组织
  - 后端按功能域拆分模块，每个模块包含控制器、服务与类型定义，便于独立开发与测试
  - 前端按页面与功能拆分 Store、组件与工具函数，降低耦合度
- 插件化与可替换性
  - 存储服务支持 OSS 与本地存储切换，便于横向扩展
  - 模型配置统一管理，支持多供应商与自动切换
- 队列与异步处理
  - 书籍生成采用队列与处理器，支持批量任务与断点续跑
- WebSocket 与实时通信
  - 提供 WebSocket 服务，支持任务进度推送与实时交互

```mermaid
graph TB
M_auth["认证模块"]
M_tts["TTS模块"]
M_player["播放器模块"]
M_bookgen["书籍生成模块"]
M_video["视频生成模块"]
M_storage["存储服务"]
M_queue["队列服务"]
M_bookgen --> M_queue
M_bookgen --> M_storage
M_tts --> M_storage
M_player --> M_storage
```

**图表来源**
- [server/src/app.ts:26-54](file://server/src/app.ts#L26-L54)
- [server/src/modules/book-generator/book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199)

**章节来源**
- [server/src/modules/book-generator/book-generator.controller.ts:24-119](file://server/src/modules/book-generator/book-generator.controller.ts#L24-L119)

## 性能与可靠性
- 中间件与安全
  - CORS、性能监控、日志记录、安全防护与速率限制中间件
  - 认证中间件支持可选认证与测试用户降级
- 存储与缓存
  - Redis 缓存连接测试与降级策略
  - 存储服务支持签名 URL 与目录清理
- 错误处理与监控
  - 统一错误处理与 Sentry 错误上报
  - 健康检查与性能指标接口

```mermaid
flowchart TD
R_req["请求进入"] --> R_cors["CORS处理"]
R_cors --> R_perf["性能监控"]
R_perf --> R_log["请求日志"]
R_log --> R_sec["安全防护"]
R_sec --> R_auth["认证中间件"]
R_auth --> R_route["路由分发"]
R_route --> R_err["统一错误处理"]
```

**图表来源**
- [server/src/app.ts:64-83](file://server/src/app.ts#L64-L83)
- [server/src/middleware/auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)

**章节来源**
- [server/src/app.ts:64-98](file://server/src/app.ts#L64-L98)
- [server/src/middleware/auth.ts:52-81](file://server/src/middleware/auth.ts#L52-L81)

## 故障排查指南
- 启动失败
  - 检查数据库连接字符串与端口占用
  - 查看 Redis 与存储服务连接日志
- 认证问题
  - 确认 Authorization 头格式与 JWT Secret 一致性
  - 开发环境可通过环境变量开启/关闭强制认证
- 存储问题
  - 切换 STORAGE_TYPE 验证 OSS/本地存储连通性
  - 检查上传目录权限与磁盘空间
- 前端请求失败
  - 检查 API 基础地址与跨域配置
  - 查看请求缓存与重试机制

**章节来源**
- [server/src/app.ts:133-194](file://server/src/app.ts#L133-L194)
- [server/src/middleware/auth.ts:8-18](file://server/src/middleware/auth.ts#L8-L18)
- [server/src/services/storage.service.ts:252-272](file://server/src/services/storage.service.ts#L252-L272)
- [my-uniapp-vue3/src/utils/request.ts:135-159](file://my-uniapp-vue3/src/utils/request.ts#L135-L159)

## 结论
本项目通过清晰的前后端分层、模块化设计与完善的配置管理，实现了从文本到音频/视频的自动化生成与播放体验。后端以 Koa + Prisma 为基础，具备良好的扩展性与可靠性；前端以 uniapp 为核心，覆盖多端场景。通过队列与存储服务的插件化设计，平台能够灵活适配不同部署环境与业务需求。