audio_codebuddy/.qoder/repowiki/zh/content/项目概述/项目结构说明.md

项目结构说明

本文档引用的文件

• README.md
• package.json
• server/package.json
• my-uniapp-vue3/package.json
• server/src/app.ts
• server/src/config/index.ts
• server/prisma/schema.prisma
• server/src/middleware/auth.ts
• server/src/services/storage.service.ts
• my-uniapp-vue3/src/main.ts
• my-uniapp-vue3/src/store/user.ts
• my-uniapp-vue3/src/store/audio.ts
• my-uniapp-vue3/src/utils/request.ts
• my-uniapp-vue3/src/pages/index/index.vue
• server/src/modules/book-generator/book-generator.controller.ts

目录

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

  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
• server/src/config/index.ts:1-117
• server/prisma/schema.prisma:1-472
• my-uniapp-vue3/src/main.ts:1-32

章节来源

• README.md:31-52

后端服务架构

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

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
• server/src/middleware/auth.ts:1-81
• server/src/services/storage.service.ts:1-278

章节来源

• server/src/app.ts:133-194
• server/src/config/index.ts:69-117

前端应用架构

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

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
• my-uniapp-vue3/src/store/user.ts:1-107
• my-uniapp-vue3/src/store/audio.ts:1-297
• my-uniapp-vue3/src/utils/request.ts:1-207

章节来源

• my-uniapp-vue3/src/pages/index/index.vue:1-758

分层架构设计

项目采用典型的三层架构：

• 表现层（Presentation Layer）
  • 前端页面与组件负责用户交互与展示，状态管理与工具函数解耦业务逻辑
• 业务逻辑层（Business Logic Layer）
  • 后端模块控制器负责接收请求、调用服务层处理业务、返回标准化响应

• 数据访问层（Data Access Layer）

  • Prisma ORM 提供数据库抽象，支持 MySQL；存储服务统一对接 OSS 与本地存储

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

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

配置与环境管理

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

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
• server/src/services/storage.service.ts:139-193

章节来源

• server/src/config/index.ts:70-117
• server/src/services/storage.service.ts:139-193

构建与部署流程

• 后端构建与启动
  • 开发：使用 tsx 监听模式启动，支持热更新
  • 生产：TypeScript 编译为 JavaScript，运行 dist/app.js
• 前端构建与多端编译
  • H5 开发与生产构建
  • 微信小程序等多端构建命令

• 部署架构

  • Nginx 反向代理与静态资源服务
  • 前端构建产物放置于 Nginx 目录

  • 后端服务独立部署，通过环境变量配置数据库与存储

    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
• my-uniapp-vue3/package.json:4-36

章节来源

• README.md:62-90
• server/package.json:6-9
• my-uniapp-vue3/package.json:4-36

扩展性与模块化设计

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

• WebSocket 与实时通信

  • 提供 WebSocket 服务，支持任务进度推送与实时交互

    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
• server/src/modules/book-generator/book-generator.controller.ts:1-199

章节来源

• server/src/modules/book-generator/book-generator.controller.ts:24-119

性能与可靠性

• 中间件与安全
  • CORS、性能监控、日志记录、安全防护与速率限制中间件
  • 认证中间件支持可选认证与测试用户降级
• 存储与缓存
  • Redis 缓存连接测试与降级策略
  • 存储服务支持签名 URL 与目录清理

• 错误处理与监控

  • 统一错误处理与 Sentry 错误上报

  • 健康检查与性能指标接口

    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
• server/src/middleware/auth.ts:7-49

章节来源

• server/src/app.ts:64-98
• server/src/middleware/auth.ts:52-81

故障排查指南

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

章节来源

• server/src/app.ts:133-194
• server/src/middleware/auth.ts:8-18
• server/src/services/storage.service.ts:252-272
• my-uniapp-vue3/src/utils/request.ts:135-159

结论

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