# 模块架构

<cite>
**本文引用的文件**
- [server/src/app.ts](file://server/src/app.ts)
- [server/src/config/index.ts](file://server/src/config/index.ts)
- [server/src/services/queue.service.ts](file://server/src/services/queue.service.ts)
- [server/src/services/redis.service.ts](file://server/src/services/redis.service.ts)
- [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/player/player.controller.ts](file://server/src/modules/player/player.controller.ts)
- [server/src/modules/subscription/subscription.controller.ts](file://server/src/modules/subscription/subscription.controller.ts)
- [server/src/modules/payment/payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [server/src/modules/video-generator/video-generator.controller.ts](file://server/src/modules/video-generator/video-generator.controller.ts)
- [server/src/modules/book-generator/index.ts](file://server/src/modules/book-generator/index.ts)
- [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. [附录](#附录)

## 简介
本文件面向AI有声书生成平台，系统性梳理其模块化架构与运行机制。平台采用按功能域划分的模块组织方式，围绕“用户认证”“AI内容生成”“TTS语音合成”“音频处理”“视频生成”“播放器”“订阅付费”等核心业务模块构建，并通过统一的路由注册、中间件体系与队列服务实现模块间的解耦与协作。文档同时阐述模块间通信机制（RESTful API、消息队列、事件驱动）、模块生命周期管理（初始化顺序、依赖注入、错误处理策略），并提供架构图与流程图帮助读者快速理解系统。

## 项目结构
后端采用Koa应用作为统一入口，集中注册路由与中间件；各业务模块以“控制器-服务”分层组织，服务层进一步拆分通用能力（如队列、缓存、存储、日志、安全等）。整体结构如下：

```mermaid
graph TB
subgraph "应用入口"
APP["server/src/app.ts"]
end
subgraph "通用服务层"
CFG["server/src/config/index.ts"]
REDIS["server/src/services/redis.service.ts"]
QUEUE["server/src/services/queue.service.ts"]
end
subgraph "业务模块"
AUTH["server/src/modules/auth/auth.controller.ts"]
TTS["server/src/modules/tts/tts.controller.ts"]
PLAYER["server/src/modules/player/player.controller.ts"]
SUB["server/src/modules/subscription/subscription.controller.ts"]
PAY["server/src/modules/payment/payment.controller.ts"]
VIDEOT["server/src/modules/video-generator/video-generator.controller.ts"]
BG["server/src/modules/book-generator/index.ts"]
BGC["server/src/modules/book-generator/book-generator.controller.ts"]
end
APP --> AUTH
APP --> TTS
APP --> PLAYER
APP --> SUB
APP --> PAY
APP --> VIDEOT
APP --> BG
APP --> BGC
APP --> CFG
APP --> REDIS
APP --> QUEUE
```

图表来源
- [server/src/app.ts:100-128](file://server/src/app.ts#L100-L128)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)
- [server/src/services/redis.service.ts:1-274](file://server/src/services/redis.service.ts#L1-L274)
- [server/src/services/queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)
- [server/src/modules/auth/auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [server/src/modules/tts/tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)
- [server/src/modules/player/player.controller.ts:1-344](file://server/src/modules/player/player.controller.ts#L1-L344)
- [server/src/modules/subscription/subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [server/src/modules/payment/payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [server/src/modules/video-generator/video-generator.controller.ts:1-244](file://server/src/modules/video-generator/video-generator.controller.ts#L1-L244)
- [server/src/modules/book-generator/index.ts:1-104](file://server/src/modules/book-generator/index.ts#L1-L104)
- [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/app.ts:100-128](file://server/src/app.ts#L100-L128)

## 核心组件
- 应用入口与中间件
  - 统一路由注册、CORS、日志、安全中间件、限流、静态资源挂载、健康检查与指标暴露。
- 通用服务
  - 配置中心：统一加载环境变量与模型配置。
  - 缓存服务：基于Redis的键值与Hash操作、连接测试与优雅断开。
  - 队列服务：基于Bull的任务队列封装，支持Redis与内存回退、进度回调、统计与生命周期管理。
- 业务模块控制器
  - 用户认证、TTS、播放器、订阅与付费、视频生成、书籍生成等模块均提供独立路由控制器。

章节来源
- [server/src/app.ts:63-130](file://server/src/app.ts#L63-L130)
- [server/src/config/index.ts:13-117](file://server/src/config/index.ts#L13-L117)
- [server/src/services/redis.service.ts:1-274](file://server/src/services/redis.service.ts#L1-L274)
- [server/src/services/queue.service.ts:1-347](file://server/src/services/queue.service.ts#L1-L347)

## 架构总览
平台采用“控制器-服务-通用能力”的分层架构，模块间通过REST API交互，复杂任务通过队列异步处理，缓存与存储抽象对外透明。下图展示模块间主要交互与数据流向：

```mermaid
graph TB
CLIENT["客户端/前端"] --> ROUTER["Koa 路由"]
ROUTER --> AUTH_C["认证控制器"]
ROUTER --> TTS_C["TTS 控制器"]
ROUTER --> PLAYER_C["播放器控制器"]
ROUTER --> SUB_C["订阅控制器"]
ROUTER --> PAY_C["支付控制器"]
ROUTER --> VIDEO_C["视频生成控制器"]
ROUTER --> BOOK_C["书籍生成控制器"]
TTS_C --> QUEUE_S["队列服务"]
BOOK_C --> QUEUE_S
VIDEO_C --> QUEUE_S
QUEUE_S --> REDIS_S["Redis 缓存"]
AUTH_C --> CFG_S["配置中心"]
TTS_C --> CFG_S
PLAYER_C --> CFG_S
SUB_C --> CFG_S
PAY_C --> CFG_S
VIDEO_C --> CFG_S
BOOK_C --> CFG_S
```

图表来源
- [server/src/app.ts:100-128](file://server/src/app.ts#L100-L128)
- [server/src/services/queue.service.ts:18-347](file://server/src/services/queue.service.ts#L18-L347)
- [server/src/services/redis.service.ts:1-274](file://server/src/services/redis.service.ts#L1-L274)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)

## 详细组件分析

### 用户认证模块
- 职责
  - 发送短信验证码、手机号登录、获取与更新用户信息。
- 接口要点
  - 登录接口支持跳过验证码校验（便于联调）。
  - 用户信息读取与更新均受鉴权中间件保护。
- 数据流
  - 控制器接收请求→参数校验→调用服务→返回标准化响应。

```mermaid
sequenceDiagram
participant C as "客户端"
participant R as "路由(auth)"
participant S as "AuthService"
participant DB as "数据库"
C->>R : POST "/api/auth/login"
R->>R : 参数校验
R->>S : loginWithPhone(phone, code?)
S->>DB : 查询/创建用户
DB-->>S : 用户信息
S-->>R : JWT令牌与用户信息
R-->>C : 标准化响应
```

图表来源
- [server/src/modules/auth/auth.controller.ts:32-52](file://server/src/modules/auth/auth.controller.ts#L32-L52)

章节来源
- [server/src/modules/auth/auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)

### AI内容生成模块（LangGraph书籍生成）
- 职责
  - 通过策略选择器切换生成策略（串行/一步大纲+并行/逐章内聚），支持按书籍规模与层级自动推荐生成策略。
- 接口要点
  - 对外提供独立的大纲生成函数，便于API直连。
  - 主类提供统一生成入口，内部委派给当前策略执行。
- 生命周期
  - 通过应用启动时初始化队列与恢复中断任务，保障生成任务的连续性。

```mermaid
classDiagram
class LangGraphBookGenerator {
+generate(bookId, topic, bookScale, genLevel) void
}
class StrategiesSelector {
+setCurrentStrategy(name) void
+getCurrentStrategy() Strategy
}
class BookStore {
+getById(id) any
}
LangGraphBookGenerator --> StrategiesSelector : "使用"
LangGraphBookGenerator --> BookStore : "读取书籍"
```

图表来源
- [server/src/modules/book-generator/index.ts:60-104](file://server/src/modules/book-generator/index.ts#L60-L104)

章节来源
- [server/src/modules/book-generator/index.ts:1-104](file://server/src/modules/book-generator/index.ts#L1-L104)

### TTS语音合成模块
- 职责
  - 提供音色列表、服务商列表查询；异步音频生成；状态查询；预览音色；批量下载音频。
- 接口要点
  - 生成接口支持可选鉴权、参数校验、配额检查与消费、异步返回任务ID。
  - 下载接口直接返回存储URL，避免服务端中转。
- 通信机制
  - 生成任务通过队列服务异步执行，进度可通过回调或轮询状态接口获取。

```mermaid
sequenceDiagram
participant C as "客户端"
participant R as "路由(tts)"
participant S as "TtsService"
participant Q as "队列服务"
participant SUB as "订阅服务"
participant DB as "数据库"
C->>R : POST "/api/tts/generate"
R->>R : 参数校验/鉴权/配额检查
R->>S : generateAudio(userId, text, voiceId, params, ...)
S->>Q : addTask(AUDIO_GENERATION, data)
Q-->>S : 返回任务ID
S-->>R : {audioId, audioUrl?}
R-->>C : 任务已创建
C->>R : GET "/api/tts/status/ : audioId"
R->>S : getAudioStatus(audioId)
S->>Q : getTaskStatus(...)
Q-->>S : 状态/进度
S-->>R : 状态数据
R-->>C : 状态响应
```

图表来源
- [server/src/modules/tts/tts.controller.ts:52-127](file://server/src/modules/tts/tts.controller.ts#L52-L127)
- [server/src/services/queue.service.ts:131-190](file://server/src/services/queue.service.ts#L131-L190)

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

### 音频处理模块（播放器与历史）
- 职责
  - 播放进度记录与查询、最近播放列表、公开状态管理、章节音频适配（合并章级小节音频）。
- 接口要点
  - 支持未登录场景下的测试用户ID回退；公开与私有音频访问控制。
- 数据流
  - 控制器读取鉴权上下文→查询数据库→按规则合并音频URL→返回适配格式。

```mermaid
flowchart TD
Start(["请求进入"]) --> GetCtx["获取用户上下文"]
GetCtx --> Validate["参数校验"]
Validate --> QueryDB["查询章节与书籍信息"]
QueryDB --> CheckPerm{"是否公开或所有者?"}
CheckPerm --> |否| Deny["返回403"]
CheckPerm --> |是| Merge["按层级合并音频URL"]
Merge --> BuildResp["组装适配格式"]
BuildResp --> End(["返回响应"])
Deny --> End
```

图表来源
- [server/src/modules/player/player.controller.ts:136-294](file://server/src/modules/player/player.controller.ts#L136-L294)

章节来源
- [server/src/modules/player/player.controller.ts:1-344](file://server/src/modules/player/player.controller.ts#L1-L344)

### 视频生成模块
- 职责
  - 视频项目管理（创建/更新/删除/查询）、素材管理（上传/删除/查询）、从书籍一键生成视频项目。
- 接口要点
  - 上传素材支持multipart/form-data与URL两种方式；生成视频项目支持从书籍一键创建。
- 通信机制
  - 生成任务通过队列服务异步执行，进度可通过状态接口轮询。

章节来源
- [server/src/modules/video-generator/video-generator.controller.ts:1-244](file://server/src/modules/video-generator/video-generator.controller.ts#L1-L244)
- [server/src/services/queue.service.ts:176-190](file://server/src/services/queue.service.ts#L176-L190)

### 订阅付费模块
- 职责
  - 套餐查询、用户订阅信息、Token余额与使用记录、书籍生成与音频生成配额检查与估算、支付订单创建与回调处理。
- 接口要点
  - 支付宝/微信回调分别处理异步通知与同步返回；提供模拟支付接口（开发环境）。
- 生命周期
  - 应用启动时初始化订阅套餐数据，保证后续配额检查可用。

```mermaid
sequenceDiagram
participant C as "客户端"
participant R as "路由(subscription)"
participant P as "路由(payment)"
participant PS as "PaymentService"
participant SS as "SubscriptionService"
participant DB as "数据库"
C->>R : GET "/api/subscription/audio-balance"
R->>SS : getUserAudioBalance(userId)
SS-->>R : 余额信息
R-->>C : 响应
C->>P : POST "/api/payment/create"
P->>PS : createPaymentOrder(userId, planId, method)
PS->>DB : 创建订单
PS-->>P : 订单信息
P-->>C : 返回订单
```

图表来源
- [server/src/modules/subscription/subscription.controller.ts:160-170](file://server/src/modules/subscription/subscription.controller.ts#L160-L170)
- [server/src/modules/payment/payment.controller.ts:9-33](file://server/src/modules/payment/payment.controller.ts#L9-L33)

章节来源
- [server/src/modules/subscription/subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [server/src/modules/payment/payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)

### 书籍生成编排模块
- 职责
  - 提供一键完整生成API，支持内容、音频、合并、视频、合并等步骤编排与取消。
- 接口要点
  - 启动批量任务时进行步骤校验与并发冲突检测；完成后通过WebSocket推送进度。
- 生命周期
  - 应用启动时初始化队列处理器并恢复中断任务，保障生成任务连续性。

章节来源
- [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/app.ts:168-172](file://server/src/app.ts#L168-L172)

## 依赖分析
- 模块耦合与内聚
  - 控制器层仅负责请求解析与响应封装，业务逻辑集中在服务层，提升内聚性与可测试性。
  - 通用服务（配置、缓存、队列）对各模块透明暴露，降低重复实现。
- 直接与间接依赖
  - 控制器依赖服务；服务依赖通用能力（配置、缓存、队列）；控制器之间无直接依赖。
- 外部依赖与集成点
  - Redis用于队列与缓存；数据库通过ORM访问；支付对接支付宝/微信；TTS对接多家模型供应商。
- 接口契约
  - 控制器统一返回结构体（code/message/data），便于前端与监控系统消费。

```mermaid
graph LR
CTRL["控制器层"] --> SVC["服务层"]
SVC --> CFG["配置中心"]
SVC --> REDIS["缓存服务"]
SVC --> QUEUE["队列服务"]
CTRL --> DB["数据库"]
CTRL --> PAY["支付网关"]
CTRL --> TTS["TTS供应商"]
```

图表来源
- [server/src/app.ts:100-128](file://server/src/app.ts#L100-L128)
- [server/src/services/queue.service.ts:18-347](file://server/src/services/queue.service.ts#L18-L347)
- [server/src/services/redis.service.ts:1-274](file://server/src/services/redis.service.ts#L1-L274)
- [server/src/config/index.ts:69-117](file://server/src/config/index.ts#L69-L117)

## 性能考虑
- 异步化与并发控制
  - 音频/视频/书籍生成通过队列异步执行，避免阻塞主线程；队列提供超时与统计能力。
- 缓存与降级
  - Redis连接失败时自动回退至内存队列，保证系统可用性；缓存提供JSON序列化与批量删除能力。
- 中间件优化
  - CORS、日志、安全中间件按需启用；性能监控与错误上报贯穿全链路。
- I/O与存储
  - 静态资源挂载上传目录与视频目录，减少服务端文件处理压力；下载接口直接返回URL。

章节来源
- [server/src/services/queue.service.ts:131-190](file://server/src/services/queue.service.ts#L131-L190)
- [server/src/services/redis.service.ts:246-267](file://server/src/services/redis.service.ts#L246-L267)
- [server/src/app.ts:63-94](file://server/src/app.ts#L63-L94)

## 故障排查指南
- 启动阶段
  - 数据库连接失败：检查连接字符串与网络；查看启动日志中的连接结果。
  - Redis连接失败：确认Redis服务可用与凭据正确；若不可用，队列将回退至内存模式。
  - 订阅套餐初始化失败：检查数据库中套餐数据完整性。
- 运行阶段
  - 队列不可用：查看队列错误监听与可用性标记；必要时清理队列或重启服务。
  - TTS生成失败：检查供应商配置、配额与模型切换策略；核对任务状态与进度回调。
  - 支付回调异常：核对签名验证与回调参数；查看支付网关日志。
- 常见问题定位
  - WebSocket推送：确认初始化与连接状态；检查任务完成后的进度推送。
  - 静态资源访问：确认挂载路径与上传目录权限。

章节来源
- [server/src/app.ts:133-192](file://server/src/app.ts#L133-L192)
- [server/src/services/queue.service.ts:72-122](file://server/src/services/queue.service.ts#L72-L122)
- [server/src/services/redis.service.ts:246-267](file://server/src/services/redis.service.ts#L246-L267)
- [server/src/modules/payment/payment.controller.ts:57-125](file://server/src/modules/payment/payment.controller.ts#L57-L125)

## 结论
本平台通过清晰的功能域划分与分层架构，实现了高内聚低耦合的模块组织；借助统一的路由与中间件体系、队列与缓存抽象，以及严格的生命周期管理与错误处理策略，平台在复杂业务（书籍生成、TTS、视频生成）场景下仍保持良好的扩展性与稳定性。建议持续完善监控与告警、灰度发布与容灾演练，以进一步提升线上可靠性。

## 附录
- 模块初始化顺序（启动时序）
  - 初始化Sentry与日志
  - 连接数据库
  - 测试Redis与存储连接
  - 初始化订阅套餐
  - 初始化WebSocket
  - 启动HTTP服务
  - 初始化书籍生成队列处理器并恢复中断任务
  - 注册优雅关闭钩子（关闭队列与Redis）

章节来源
- [server/src/app.ts:133-192](file://server/src/app.ts#L133-L192)