# 核心模块

<cite>
**本文引用的文件**   
- [auth.controller.ts](file://server/src/modules/auth/auth.controller.ts)
- [auth.service.ts](file://server/src/modules/auth/auth.service.ts)
- [tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [player.controller.ts](file://server/src/modules/player/player.controller.ts)
- [player.service.ts](file://server/src/modules/player/player.service.ts)
- [member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)
</cite>

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

## 简介
本文件面向AI有声书生成平台的核心模块，系统性梳理并解释以下关键模块的功能职责、实现原理与使用方式：
- 用户认证模块：手机号登录、验证码机制、JWT令牌签发与校验
- TTS语音合成模块：多音色提供商集成（阿里云、MiniMax、Mock）、参数调节、异步生成与状态查询
- 音频处理模块：本地与云端音频文件的合并、时长与大小统计、统一上传至存储服务
- 播放器模块：播放进度持久化、章节合并播放、公开状态管理
- 会员系统模块：会员权益与配额、订单创建与模拟支付、会员状态查询

文档同时阐述模块间的依赖关系与数据交互模式，并提供扩展与自定义的指导原则、配置要点、性能优化建议与常见问题排查方法。

## 项目结构
后端采用模块化组织，核心模块位于 server/src/modules 下，控制器负责HTTP路由与请求参数解析，服务层封装业务逻辑与第三方集成，类型与配置位于 server/src/types 与 server/src/config。

```mermaid
graph TB
subgraph "认证模块"
AC["auth.controller.ts"]
AS["auth.service.ts"]
end
subgraph "TTS模块"
TC["tts.controller.ts"]
TS["tts.service.ts"]
end
subgraph "播放器模块"
PC["player.controller.ts"]
PS["player.service.ts"]
end
subgraph "会员模块"
MC["member.controller.ts"]
MS["member.service.ts"]
end
AC --> AS
TC --> TS
PC --> PS
MC --> MS
TS --> PS
PC --> TS
AC --> TC
AC --> PC
AC --> MC
```

图表来源
- [auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [auth.service.ts:1-115](file://server/src/modules/auth/auth.service.ts#L1-L115)
- [tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [player.controller.ts:1-344](file://server/src/modules/player/player.controller.ts#L1-L344)
- [player.service.ts:1-280](file://server/src/modules/player/player.service.ts#L1-L280)
- [member.controller.ts:1-90](file://server/src/modules/member/member.controller.ts#L1-L90)
- [member.service.ts:1-183](file://server/src/modules/member/member.service.ts#L1-L183)

章节来源
- [auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [auth.service.ts:1-115](file://server/src/modules/auth/auth.service.ts#L1-L115)
- [tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [player.controller.ts:1-344](file://server/src/modules/player/player.controller.ts#L1-L344)
- [player.service.ts:1-280](file://server/src/modules/player/player.service.ts#L1-L280)
- [member.controller.ts:1-90](file://server/src/modules/member/member.controller.ts#L1-L90)
- [member.service.ts:1-183](file://server/src/modules/member/member.service.ts#L1-L183)

## 核心组件
- 认证模块：提供手机号登录、验证码生成与校验、用户信息查询与更新、JWT签发与中间件校验
- TTS模块：提供音色与提供商查询、文本转音频的异步生成、状态查询、预览音频、批量下载
- 播放器模块：提供播放进度的增删改查、最近播放记录、章节音频合并、公开状态管理
- 会员模块：提供会员权益与配额、订单创建、模拟支付、订单列表与会员状态查询

章节来源
- [auth.controller.ts:10-94](file://server/src/modules/auth/auth.controller.ts#L10-L94)
- [auth.service.ts:11-115](file://server/src/modules/auth/auth.service.ts#L11-L115)
- [tts.controller.ts:13-274](file://server/src/modules/tts/tts.controller.ts#L13-L274)
- [tts.service.ts:24-715](file://server/src/modules/tts/tts.service.ts#L24-L715)
- [player.controller.ts:14-344](file://server/src/modules/player/player.controller.ts#L14-L344)
- [player.service.ts:10-280](file://server/src/modules/player/player.service.ts#L10-L280)
- [member.controller.ts:10-90](file://server/src/modules/member/member.controller.ts#L10-L90)
- [member.service.ts:11-183](file://server/src/modules/member/member.service.ts#L11-L183)

## 架构总览
整体采用“控制器-服务”分层，控制器负责参数校验与响应封装，服务层负责业务流程与外部集成。TTS服务与播放器服务之间通过章节与音频记录进行数据关联；认证服务贯穿各模块用于身份校验与用户信息获取；会员服务为TTS生成提供配额与权限控制。

```mermaid
graph TB
Client["客户端"] --> AuthC["认证控制器<br/>auth.controller.ts"]
Client --> TTSC["TTS控制器<br/>tts.controller.ts"]
Client --> PlayerC["播放器控制器<br/>player.controller.ts"]
Client --> MemberC["会员控制器<br/>member.controller.ts"]
AuthC --> AuthService["认证服务<br/>auth.service.ts"]
TTSC --> TTSService["TTS服务<br/>tts.service.ts"]
PlayerC --> PlayerService["播放器服务<br/>player.service.ts"]
MemberC --> MemberService["会员服务<br/>member.service.ts"]
TTSService --> Storage["存储服务<br/>storage.service.ts"]
TTSService --> Merger["音频合并器<br/>audio-merger.ts"]
TTSService --> WS["WebSocket服务<br/>websocket.service.js"]
PlayerService --> Merger
PlayerService --> DB["Prisma 数据库"]
TTSService --> DB
AuthC --> DB
MemberC --> DB
MemberService --> DB
```

图表来源
- [auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [auth.service.ts:1-115](file://server/src/modules/auth/auth.service.ts#L1-L115)
- [tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [player.controller.ts:1-344](file://server/src/modules/player/player.controller.ts#L1-L344)
- [player.service.ts:1-280](file://server/src/modules/player/player.service.ts#L1-L280)
- [member.controller.ts:1-90](file://server/src/modules/member/member.controller.ts#L1-L90)
- [member.service.ts:1-183](file://server/src/modules/member/member.service.ts#L1-L183)

## 详细组件分析

### 认证模块
- 职责
  - 发送验证码（开发环境直接返回验证码）
  - 手机号登录（支持免验证码直登）
  - 用户信息查询与更新
  - JWT令牌签发与中间件校验
- 实现要点
  - 验证码存储使用内存Map（生产建议Redis）
  - 登录流程：查重/创建用户 → 生成JWT → 返回用户信息与令牌
  - 控制器对手机号格式与验证码进行前置校验
- 使用方式
  - 前端先调用发送验证码接口，再提交手机号+验证码登录
  - 后续接口通过认证中间件携带用户ID

```mermaid
sequenceDiagram
participant C as "客户端"
participant Ctrl as "认证控制器"
participant Svc as "认证服务"
participant DB as "数据库"
C->>Ctrl : POST /auth/send-code
Ctrl->>Svc : generateSmsCode(phone)
Svc-->>Ctrl : 返回验证码
Ctrl-->>C : {code,message,data : {phone,code}}
C->>Ctrl : POST /auth/login
Ctrl->>Svc : loginWithPhone(phone, code)
Svc->>DB : 查询/创建用户
Svc-->>Ctrl : {token,user}
Ctrl-->>C : {code,message,data}
```

图表来源
- [auth.controller.ts:11-52](file://server/src/modules/auth/auth.controller.ts#L11-L52)
- [auth.service.ts:44-97](file://server/src/modules/auth/auth.service.ts#L44-L97)

章节来源
- [auth.controller.ts:11-92](file://server/src/modules/auth/auth.controller.ts#L11-L92)
- [auth.service.ts:11-97](file://server/src/modules/auth/auth.service.ts#L11-L97)

### TTS语音合成模块
- 职责
  - 提供可用音色与提供商列表
  - 异步生成音频（立即返回任务ID）
  - 查询生成状态（processing/completed/failed）
  - 预览音色（短文本）
  - 批量下载音频
- 实现要点
  - Provider工厂：优先级选择（MiniMax > 阿里云 > Mock），支持强制指定
  - 文本分段策略：阿里云HTTP模式按段落与句子切分，MiniMax支持长文本
  - 并发控制：MiniMax串行，其他并发2段
  - 合并与上传：本地分段音频合并，统一通过存储服务上传
  - 配额与用量：结合会员配额与字数估算进行消费
- 使用方式
  - 调用生成接口传入文本、音色、参数与可选书籍/章节信息
  - 轮询状态接口直至完成
  - 完成后通过下载接口获取URL

```mermaid
sequenceDiagram
participant C as "客户端"
participant Ctrl as "TTS控制器"
participant Svc as "TTS服务"
participant Prov as "TTS提供商"
participant Merge as "音频合并器"
participant Store as "存储服务"
participant DB as "数据库"
C->>Ctrl : POST /tts/generate
Ctrl->>Ctrl : 参数校验/配额检查
Ctrl->>Svc : generateAudio(userId,text,voiceId,params,options)
Svc->>DB : 创建AudioRecord(processing)
Svc->>Prov : synthesize(分段)
Prov-->>Svc : 本地分段音频/云端URL
alt 云端URL
Svc->>Store : uploadAudio(临时文件)
Store-->>Svc : 返回统一URL
else 本地分段
Svc->>Merge : merge(分段->output.mp3)
Merge-->>Svc : 合并文件
Svc->>Store : uploadAudio(合并文件)
Store-->>Svc : 返回统一URL
end
Svc->>DB : 更新AudioRecord(completed,audioUrl,duration,size,title)
Svc-->>Ctrl : {audioId,audioUrl,bookId}
Ctrl-->>C : {code,message,data}
```

图表来源
- [tts.controller.ts:53-127](file://server/src/modules/tts/tts.controller.ts#L53-L127)
- [tts.service.ts:201-542](file://server/src/modules/tts/tts.service.ts#L201-L542)

章节来源
- [tts.controller.ts:13-274](file://server/src/modules/tts/tts.controller.ts#L13-L274)
- [tts.service.ts:24-715](file://server/src/modules/tts/tts.service.ts#L24-L715)

### 播放器模块
- 职责
  - 播放进度的增删改查与最近播放记录
  - 章节音频合并（章级别自动聚合小节音频）
  - 章节公开状态管理
- 实现要点
  - 进度持久化使用upsert语义，避免重复记录
  - 合并逻辑：仅对章（level=1）聚合其下所有小节（level=3）音频
  - 公开状态校验：仅章节所属用户可修改
- 使用方式
  - 播放过程中定时上报进度
  - 播放章时自动合并小节音频，提升体验

```mermaid
flowchart TD
Start(["进入播放器"]) --> CheckType["判断是否为章(level=1)"]
CheckType --> |否| PlayDirect["直接播放当前音频"]
CheckType --> |是| HasMerged{"已有合并音频?"}
HasMerged --> |是| PlayMerged["播放合并音频"]
HasMerged --> |否| FetchSub["获取所有小节音频URL"]
FetchSub --> Merge["合并音频并写入数据库"]
Merge --> PlayMerged
PlayMerged --> SaveProgress["保存播放进度"]
SaveProgress --> End(["结束"])
```

图表来源
- [player.controller.ts:136-227](file://server/src/modules/player/player.controller.ts#L136-L227)
- [player.service.ts:147-242](file://server/src/modules/player/player.service.ts#L147-L242)

章节来源
- [player.controller.ts:14-344](file://server/src/modules/player/player.controller.ts#L14-L344)
- [player.service.ts:10-280](file://server/src/modules/player/player.service.ts#L10-L280)

### 会员系统模块
- 职责
  - 会员权益与配额展示
  - 订单创建与模拟支付
  - 会员状态查询与订单列表
- 实现要点
  - 权益与配额：免费版/月度会员/年度会员三档
  - 配额：每日生成次数与字数限制，支持无限额度
  - 订单：生成唯一订单号，模拟支付后更新用户会员等级与到期时间
- 使用方式
  - 用户下单后进入支付流程，开发环境可模拟支付成功

```mermaid
sequenceDiagram
participant C as "客户端"
participant Ctrl as "会员控制器"
participant Svc as "会员服务"
participant DB as "数据库"
C->>Ctrl : GET /member/benefits
Ctrl-->>C : 权益与配额信息
C->>Ctrl : POST /member/order
Ctrl->>Svc : createOrder(userId, productType)
Svc->>DB : 创建订单(pending)
Svc-->>Ctrl : {orderNo,amount}
Ctrl-->>C : {code,message,data}
C->>Ctrl : POST /member/pay/mock
Ctrl->>Svc : mockPaymentSuccess(orderNo,userId)
Svc->>DB : 更新订单为paid
Svc->>DB : 更新用户会员等级与到期时间
Svc-->>Ctrl : {success,memberLevel,expireAt}
Ctrl-->>C : {code,message,data}
```

图表来源
- [member.controller.ts:9-90](file://server/src/modules/member/member.controller.ts#L9-L90)
- [member.service.ts:11-183](file://server/src/modules/member/member.service.ts#L11-L183)

章节来源
- [member.controller.ts:9-90](file://server/src/modules/member/member.controller.ts#L9-L90)
- [member.service.ts:11-183](file://server/src/modules/member/member.service.ts#L11-L183)

## 依赖分析
- 认证模块
  - 依赖：JWT签名、手机号格式校验、数据库用户表
  - 与其他模块：为TTS、播放器、会员模块提供用户身份
- TTS模块
  - 依赖：Provider（阿里云、MiniMax、Mock）、音频合并器、存储服务、WebSocket推送
  - 与播放器：章节音频完成后回写章节记录
  - 与会员：生成前检查配额，生成后消耗分钟数
- 播放器模块
  - 依赖：音频合并器、数据库章节与播放记录
  - 与TTS：读取章节音频URL，必要时合并
- 会员模块
  - 依赖：数据库用户与订单表
  - 与TTS：提供配额与优先级能力

```mermaid
graph LR
Auth["认证模块"] --> TTS["TTS模块"]
Auth --> Player["播放器模块"]
Auth --> Member["会员模块"]
TTS --> Player
TTS --> Storage["存储服务"]
TTS --> Merger["音频合并器"]
Player --> Merger
Member --> TTS
```

图表来源
- [auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [player.service.ts:1-280](file://server/src/modules/player/player.service.ts#L1-L280)
- [member.service.ts:1-183](file://server/src/modules/member/member.service.ts#L1-L183)

章节来源
- [auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [player.service.ts:1-280](file://server/src/modules/player/player.service.ts#L1-L280)
- [member.service.ts:1-183](file://server/src/modules/member/member.service.ts#L1-L183)

## 性能考量
- Provider选择与并发
  - MiniMax串行以降低轮询开销；阿里云/模拟并发2段，提升吞吐
- 文本分段
  - 阿里云HTTP模式按段落与句子切分，避免超限；长文本模式暂时禁用实时流
- 存储与合并
  - 合并后统一上传，减少跨域与CDN分发复杂度
- 配额与限流
  - 生成前检查配额，失败快速返回，避免无效资源消耗
- 缓存与索引
  - 播放进度按用户+章节组合键查询，建议确保索引完善

## 故障排查指南
- TTS生成失败
  - 检查Provider额度限制（如触发usage limit/rate limit/quota exceeded），服务会自动切换下一Provider
  - 查看任务目录下的失败标记文件，定位具体错误
  - 确认存储服务可用与网络可达
- 状态查询异常
  - 若目录存在但长时间无文件，视为僵尸任务，数据库会被标记为失败
- 播放进度丢失
  - 确认upsert逻辑是否正常，检查用户ID与章节ID是否匹配
- 会员配额不足
  - 检查用户当日使用次数与字数是否超出限额，或会员等级是否生效

章节来源
- [tts.service.ts:518-542](file://server/src/modules/tts/tts.service.ts#L518-L542)
- [tts.service.ts:547-597](file://server/src/modules/tts/tts.service.ts#L547-L597)
- [player.service.ts:46-81](file://server/src/modules/player/player.service.ts#L46-L81)
- [member.service.ts:40-73](file://server/src/modules/member/member.service.ts#L40-L73)

## 结论
本平台围绕“认证—TTS—播放—会员”形成闭环：认证提供身份，TTS产出内容，播放器承载体验，会员体系保障可持续使用。模块间通过清晰的控制器与服务边界协作，配合Provider工厂与存储抽象，具备良好的扩展性与可维护性。建议在生产环境中替换内存验证码为Redis、完善监控与告警，并持续评估Provider性能与成本。

## 附录
- 扩展与自定义指导
  - 新增Provider：实现synthesize接口，加入Provider工厂优先级
  - 自定义音色映射：在音色列表与映射表中新增条目
  - 自定义存储：实现storage service接口，替换上传行为
  - 自定义播放器合并策略：调整章节层级与合并条件
- 配置项参考
  - JWT密钥与过期时间
  - Provider API Key与模型列表
  - 上传目录与存储类型
  - 会员配额与价格
- 最佳实践
  - 严格参数校验与错误分类
  - 异步生成与状态轮询分离
  - 合并前检查与幂等更新
  - 生产环境禁用免验证码登录