# 开发指南

<cite>
**本文引用的文件**
- [README.md](file://README.md)
- [API.md](file://docs/API.md)
- [app.ts](file://server/src/app.ts)
- [index.ts](file://server/src/config/index.ts)
- [errorHandler.ts](file://server/src/middleware/errorHandler.ts)
- [logger.service.ts](file://server/src/services/logger.service.ts)
- [sentry.service.ts](file://server/src/services/sentry.service.ts)
- [queue.service.ts](file://server/src/services/queue.service.ts)
- [storage.service.ts](file://server/src/services/storage.service.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [book-generator.service.ts](file://server/src/modules/book-generator/book-generator.service.ts)
- [main.ts](file://my-uniapp-vue3/src/main.ts)
- [package.json](file://my-uniapp-vue3/package.json)
- [package.json](file://package.json)
</cite>

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

## 引言
本开发指南面向AI有声书生成平台的开发者与团队，提供统一的代码规范、开发流程、质量保障体系与协作实践。文档覆盖以下主题：
- 代码规范与最佳实践
- 开发流程与版本/分支管理
- 功能迭代策略与质量保证
- 代码评审、单元测试、集成测试与性能测试
- 新功能开发模板、Bug修复流程与文档更新规范
- 开发工具配置、调试技巧与性能分析方法

## 项目结构
项目采用前后端分离架构，后端基于Koa，前端基于uniapp+Vue3+TypeScript，数据库与存储通过配置化抽象支持本地与OSS两种模式。

```mermaid
graph TB
subgraph "前端(uniapp)"
FE_App["应用入口<br/>main.ts"]
FE_Packages["脚本与依赖<br/>package.json"]
end
subgraph "后端(Koa)"
BE_App["应用入口<br/>server/src/app.ts"]
BE_Config["配置中心<br/>server/src/config/index.ts"]
BE_MW_Error["错误处理中间件<br/>server/src/middleware/errorHandler.ts"]
BE_Services["服务层<br/>server/src/services/*"]
BE_Modules["业务模块<br/>server/src/modules/*"]
end
subgraph "文档与测试"
Docs_API["API文档<br/>docs/API.md"]
Repo_Readme["仓库说明<br/>README.md"]
end
FE_App --> BE_App
FE_Packages --> FE_App
BE_App --> BE_Config
BE_App --> BE_MW_Error
BE_App --> BE_Services
BE_App --> BE_Modules
Docs_API --> BE_Modules
Repo_Readme --> BE_App
```

图表来源
- [app.ts:1-194](file://server/src/app.ts#L1-L194)
- [index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [API.md:1-499](file://docs/API.md#L1-L499)
- [README.md:1-168](file://README.md#L1-L168)
- [main.ts:1-32](file://my-uniapp-vue3/src/main.ts#L1-L32)
- [package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)

章节来源
- [README.md:1-168](file://README.md#L1-L168)
- [API.md:1-499](file://docs/API.md#L1-L499)
- [app.ts:1-194](file://server/src/app.ts#L1-L194)
- [index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [main.ts:1-32](file://my-uniapp-vue3/src/main.ts#L1-L32)
- [package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)

## 核心组件
- 应用入口与路由注册：后端通过Koa创建HTTP服务，集中注册认证、TTS、播放器、收藏、偏好、搜索、分类、评论、通知、BGM、音频编辑、书籍生成、播放列表、草稿、视频生成、签到、订阅、支付、发布、反馈等模块路由，并挂载静态资源与健康检查。
- 配置中心：集中管理端口、JWT、DashScope/TTS模型、上传目录与大小等配置，支持模型自动切换与默认模型选择。
- 中间件体系：统一错误处理、Sentry错误监控、性能监控、日志记录、CORS、安全防护（XSS/SQL注入）、速率限制等。
- 服务层：日志服务、Sentry服务、队列服务（Bull+Redis，降级至内存队列）、存储服务（OSS/本地无缝切换）、WebSocket服务等。
- 业务模块：TTS服务（多提供商、分段与合并、LRC歌词生成、AI摘要/标签）、书籍生成编排（LangGraph内容生成、音频/视频生成与合并、进度推送）、视频生成（FFmpeg封装）等。

章节来源
- [app.ts:1-194](file://server/src/app.ts#L1-L194)
- [index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)
- [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)

## 架构总览
下图展示后端核心组件交互与数据流：

```mermaid
graph TB
Client["客户端/前端"]
Koa["Koa 应用<br/>server/src/app.ts"]
Cfg["配置中心<br/>server/src/config/index.ts"]
MW_Err["错误处理中间件<br/>server/src/middleware/errorHandler.ts"]
Log["日志服务<br/>server/src/services/logger.service.ts"]
Sen["Sentry 服务<br/>server/src/services/sentry.service.ts"]
Q["队列服务<br/>server/src/services/queue.service.ts"]
Store["存储服务<br/>server/src/services/storage.service.ts"]
TTS["TTS 服务<br/>server/src/modules/tts/tts.service.ts"]
BG["书籍生成编排<br/>server/src/modules/book-generator/book-generator.service.ts"]
Client --> Koa
Koa --> MW_Err
Koa --> Log
Koa --> Sen
Koa --> Cfg
Koa --> TTS
Koa --> BG
TTS --> Q
TTS --> Store
BG --> Q
BG --> Store
```

图表来源
- [app.ts:1-194](file://server/src/app.ts#L1-L194)
- [index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)
- [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)

## 详细组件分析

### TTS 服务（文本转音频）
- 多提供商支持：阿里云百炼、MiniMax、Mock，具备自动切换与降级能力。
- 文本分段与合并：针对不同提供商特性进行分段与并发生成，最后统一合并输出。
- LRC歌词生成：基于文本与时长生成时间轴歌词。
- AI摘要/标签：异步生成标题、摘要与标签，提升内容可发现性。
- 存储与回退：优先上传OSS，失败时回退到本地存储；支持云端URL下载后上传OSS。

```mermaid
sequenceDiagram
participant C as "客户端"
participant T as "TTS服务<br/>tts.service.ts"
participant P as "TTS提供商"
participant M as "音频合并器"
participant S as "存储服务<br/>storage.service.ts"
C->>T : "提交文本与参数"
T->>P : "分段并行合成"
P-->>T : "返回音频片段"
T->>M : "合并片段"
M-->>T : "输出MP3"
T->>S : "上传到OSS或本地"
S-->>T : "返回访问URL"
T-->>C : "返回音频ID/URL/时长"
```

图表来源
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)

章节来源
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)

### 书籍生成编排（批量内容/音频/视频生成）
- 步骤编排：内容生成（LangGraph）、音频生成、音频合并、视频生成、视频合并。
- 进度推送：通过WebSocket向客户端推送实时进度。
- 取消机制：支持任务取消标志，避免浪费资源。
- 超时与轮询：对长耗时步骤采用轮询检查与最大等待时间控制。

```mermaid
flowchart TD
Start(["开始"]) --> Init["加载书籍信息"]
Init --> Step1["内容生成<br/>LangGraph"]
Step1 --> Step2["音频生成<br/>并发分段合成"]
Step2 --> MergeA["音频合并<br/>按父章节聚合"]
MergeA --> Step3["视频生成<br/>创建项目并生成"]
Step3 --> MergeV["视频合并<br/>简化处理"]
MergeV --> Done(["完成"])
Step1 --> |失败| Fail["返回失败并记录错误"]
Step2 --> |失败| Fail
Step3 --> |失败| Fail
MergeA --> |失败| Fail
MergeV --> |失败| Fail
```

图表来源
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)

章节来源
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)

### 队列服务（任务调度与并发控制）
- 职责边界：仅负责排队与并发控制，失败重试与超时由容错层与AI服务层处理。
- 降级策略：Redis不可用时自动降级到内存队列，保证基本可用。
- 超时与统计：为不同类型任务设置合理超时，提供队列统计与暂停/恢复能力。

```mermaid
classDiagram
class QueueService {
+addTask(queueType, data, options) Promise<string|null>
+addAudioGenerationTask(data) Promise<string|null>
+addVideoGenerationTask(data) Promise<string|null>
+addBookGenerationTask(data) Promise<string|null>
+getTaskStatus(queueType, jobId) Promise<status>
+updateProgress(queueType, jobId, progress, data) Promise<void>
+getQueueStats(queueType) Promise<counts>
+pauseQueue(queueType) Promise<void>
+resumeQueue(queueType) Promise<void>
+clearQueue(queueType) Promise<void>
+closeAll() Promise<void>
}
```

图表来源
- [queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)

章节来源
- [queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)

### 存储服务（OSS/本地无缝切换）
- 统一接口：提供音频、视频、封面与通用文件的上传/下载/删除/签名URL能力。
- 环境切换：通过环境变量在OSS与本地存储之间切换。
- 本地测试：提供连接测试与目录写入测试，便于开发环境自检。

```mermaid
classDiagram
class StorageService {
+setStorageType(type) void
+getStorageType() StorageType
+uploadAudio(localPath, audioId) Promise<string>
+uploadVideo(localPath, videoId) Promise<string>
+uploadCover(localPath, bookId) Promise<string>
+uploadFile(localPath, category, id) Promise<string>
+uploadBuffer(buffer, objectKey, contentType) Promise<string>
+deleteFile(url) Promise<void>
+deleteDirectory(prefix, id) Promise<void>
+downloadFile(url) Promise<Buffer>
+getSignedUrl(url, expires) Promise<string>
+testConnection() Promise<boolean>
}
```

图表来源
- [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)

章节来源
- [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)

### 日志与错误监控
- 统一日志：Winston输出到控制台与文件，区分错误与HTTP请求日志。
- 错误处理：统一错误响应格式，开发环境返回堆栈，生产环境隐藏细节。
- 错误监控：Sentry初始化与错误捕获，支持用户上下文与标签设置。

```mermaid
sequenceDiagram
participant MW as "错误处理中间件"
participant LOG as "日志服务"
participant SEN as "Sentry服务"
MW->>LOG : "记录错误与请求信息"
MW->>SEN : "捕获异常并上报"
MW-->>MW : "返回统一错误响应"
```

图表来源
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)

章节来源
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)

## 依赖关系分析
- 组件耦合：服务层（日志、Sentry、队列、存储）被业务模块广泛依赖，形成清晰的基础设施层。
- 外部依赖：Redis（队列）、OSS（对象存储）、FFmpeg（视频处理）、阿里云/MiniMax（TTS）。
- 循环依赖：未见明显循环依赖，模块间通过服务接口解耦。

```mermaid
graph LR
TTS["TTS服务"] --> Q["队列服务"]
TTS --> Store["存储服务"]
BG["书籍生成编排"] --> Q
BG --> Store
App["应用入口"] --> MW["中间件"]
App --> Log["日志服务"]
App --> Sen["Sentry服务"]
App --> Cfg["配置中心"]
```

图表来源
- [app.ts:1-194](file://server/src/app.ts#L1-L194)
- [queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)
- [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [index.ts:1-117](file://server/src/config/index.ts#L1-L117)

章节来源
- [app.ts:1-194](file://server/src/app.ts#L1-L194)
- [queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)
- [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [index.ts:1-117](file://server/src/config/index.ts#L1-L117)

## 性能考虑
- 并发与限流：TTS分段并发控制，队列为不同类型任务设置超时；全局限流中间件可按需启用。
- 存储与网络：优先OSS上传，失败回退本地；云端URL下载后统一上传OSS，减少跨域与带宽波动影响。
- 日志与监控：Winston结构化日志，Sentry性能采样与错误过滤，结合HTTP请求日志定位瓶颈。
- 前端调试：H5环境可选vConsole，生产环境保持精简。

章节来源
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [main.ts:1-32](file://my-uniapp-vue3/src/main.ts#L1-L32)

## 故障排查指南
- 常见错误与处理
  - 401/403/404：检查认证与资源存在性，查看统一错误响应。
  - 429：额度/限流，等待或切换提供商；查看模型自动切换逻辑。
  - 500：查看Sentry错误与Winston错误日志，定位具体模块。
- 存储问题
  - OSS连接失败：检查AK/SK与Bucket配置；切换STORAGE_TYPE为local进行本地验证。
- 队列问题
  - Redis不可用：确认Redis服务；队列会自动降级到内存队列；关注队列统计与暂停/恢复。
- TTS生成异常
  - 分段失败：检查文本清理与分段策略；确认提供商可用性与API Key。
  - 合并失败：检查音频文件完整性与时长计算；确认存储上传成功。
- 健康检查
  - 访问 /health 与 /api/metrics，确认服务与指标正常。

章节来源
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)
- [queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [app.ts:1-194](file://server/src/app.ts#L1-L194)

## 结论
本指南提供了从架构、组件到流程与质量保障的完整开发参考。建议团队在日常开发中严格遵循统一的代码规范与评审流程，结合完善的日志与监控体系，持续优化TTS与生成链路的性能与稳定性。

## 附录

### 代码规范与最佳实践
- 命名规范：模块/服务/控制器/类型使用清晰语义，避免缩写。
- 错误处理：统一使用AppError及其子类，明确状态码与业务含义。
- 日志规范：区分info/warn/error/debug/http，避免敏感信息泄露。
- 配置管理：通过config集中管理，支持环境变量与模型配置文件。
- 存储策略：优先OSS，提供本地回退；上传前校验与失败回退。

章节来源
- [errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)

### 开发流程与版本/分支管理
- 版本策略：采用语义化版本，主干稳定发布，hotfix紧急修复。
- 分支模型：主分支(main)用于稳定发布，开发分支(dev)，功能分支(feature-*)，修复分支(hotfix-*)。
- 提交规范：使用约定式提交，如 feat/fix/docs/chore等前缀。
- 合并与审核：Pull Request必须通过代码评审与自动化测试。

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

### 功能迭代策略与质量保证
- 迭代节奏：两周冲刺，优先交付MVP核心能力，逐步完善TTS、播放器、历史与会员体系。
- 质量门禁：单元测试覆盖率不低于80%，集成测试覆盖关键流程，性能测试评估TTS与生成链路。
- 回归测试：每次发布前执行全链路回归，重点关注存储切换与队列降级场景。

章节来源
- [README.md:145-168](file://README.md#L145-L168)

### 代码评审流程
- 评审清单：需求一致性、边界条件、错误处理、日志与监控、性能与资源占用、安全与权限。
- 工具与标准：使用PR模板与检查清单，强制通过自动化检查后再合并。

章节来源
- [API.md:1-499](file://docs/API.md#L1-L499)

### 单元测试、集成测试与性能测试
- 单元测试：覆盖核心算法（文本分段、LRC生成、队列状态查询）。
- 集成测试：覆盖TTS生成端到端流程、书籍生成编排、存储上传与下载。
- 性能测试：评估不同并发下的TTS吞吐、队列延迟与视频生成时延。

章节来源
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [book-generator.service.ts:1-549](file://server/src/modules/book-generator/book-generator.service.ts#L1-L549)
- [queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)
- [storage.service.ts:1-278](file://server/src/services/storage.service.ts#L1-L278)

### 新功能开发模板
- 需求评审：明确API契约、数据模型与边界条件。
- 设计文档：接口定义、流程图、错误码与返回格式。
- 开发实现：遵循模块化与服务化，新增控制器/服务/中间件（如需）。
- 测试用例：单元测试与集成测试，覆盖正常/异常/边界场景。
- 文档更新：API文档同步更新，README补充使用说明。

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

### Bug修复流程
- 重现与定位：使用Sentry与日志快速定位问题；必要时开启vConsole。
- 修复与验证：最小改动修复，补充测试用例；回归验证。
- 发布与观察：热修复分支合并主干，观察监控与告警。

章节来源
- [sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [main.ts:1-32](file://my-uniapp-vue3/src/main.ts#L1-L32)

### 文档更新规范
- API文档：接口变更需同步更新API.md，保持请求/响应与错误码一致。
- README：新增功能或重大变更需更新README与开发计划。

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

### 开发工具配置与调试技巧
- 前端
  - H5开发：使用uni的H5脚本，按需启用vConsole。
  - 多端构建：通过脚本统一管理H5与小程序构建。
- 后端
  - 环境变量：复制.env.example并按需配置数据库、JWT、TTS与Sentry。
  - 调试：结合Winston日志与Sentry错误追踪，必要时开启性能采样。
- 性能分析
  - 使用Sentry Profiling与HTTP请求日志定位热点。
  - 队列与存储：关注Redis可用性与OSS连接状态。

章节来源
- [main.ts:1-32](file://my-uniapp-vue3/src/main.ts#L1-L32)
- [package.json:1-65](file://my-uniapp-vue3/package.json#L1-L65)
- [index.ts:1-117](file://server/src/config/index.ts#L1-L117)
- [logger.service.ts:1-114](file://server/src/services/logger.service.ts#L1-L114)
- [sentry.service.ts:1-113](file://server/src/services/sentry.service.ts#L1-L113)