audio_codebuddy/.qoder/repowiki/zh/content/核心模块/核心模块.md

核心模块

本文引用的文件

• auth.controller.ts
• auth.service.ts
• tts.controller.ts
• tts.service.ts
• player.controller.ts
• player.service.ts
• member.controller.ts
• member.service.ts

目录

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。

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
• auth.service.ts:1-115
• tts.controller.ts:1-274
• tts.service.ts:1-715
• player.controller.ts:1-344
• player.service.ts:1-280
• member.controller.ts:1-90
• member.service.ts:1-183

章节来源

• auth.controller.ts:1-94
• auth.service.ts:1-115
• tts.controller.ts:1-274
• tts.service.ts:1-715
• player.controller.ts:1-344
• player.service.ts:1-280
• member.controller.ts:1-90
• member.service.ts:1-183

核心组件

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

章节来源

• auth.controller.ts:10-94
• auth.service.ts:11-115
• tts.controller.ts:13-274
• tts.service.ts:24-715
• player.controller.ts:14-344
• player.service.ts:10-280
• member.controller.ts:10-90
• member.service.ts:11-183

架构总览

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

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
• auth.service.ts:1-115
• tts.controller.ts:1-274
• tts.service.ts:1-715
• player.controller.ts:1-344
• player.service.ts:1-280
• member.controller.ts:1-90
• member.service.ts:1-183

详细组件分析

认证模块

• 职责
  • 发送验证码（开发环境直接返回验证码）
  • 手机号登录（支持免验证码直登）
  • 用户信息查询与更新
  • JWT令牌签发与中间件校验
• 实现要点
  • 验证码存储使用内存Map（生产建议Redis）
  • 登录流程：查重/创建用户 → 生成JWT → 返回用户信息与令牌
  • 控制器对手机号格式与验证码进行前置校验

• 使用方式

  • 前端先调用发送验证码接口，再提交手机号+验证码登录

  • 后续接口通过认证中间件携带用户ID

    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
• auth.service.ts:44-97

章节来源

• auth.controller.ts:11-92
• auth.service.ts:11-97

TTS语音合成模块

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

• 使用方式

  • 调用生成接口传入文本、音色、参数与可选书籍/章节信息
  • 轮询状态接口直至完成

  • 完成后通过下载接口获取URL

    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
• tts.service.ts:201-542

章节来源

• tts.controller.ts:13-274
• tts.service.ts:24-715

播放器模块

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

• 使用方式

  • 播放过程中定时上报进度

  • 播放章时自动合并小节音频，提升体验

    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
• player.service.ts:147-242

章节来源

• player.controller.ts:14-344
• player.service.ts:10-280

会员系统模块

• 职责
  • 会员权益与配额展示
  • 订单创建与模拟支付
  • 会员状态查询与订单列表
• 实现要点
  • 权益与配额：免费版/月度会员/年度会员三档
  • 配额：每日生成次数与字数限制，支持无限额度
  • 订单：生成唯一订单号，模拟支付后更新用户会员等级与到期时间

• 使用方式

  • 用户下单后进入支付流程，开发环境可模拟支付成功

    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
• member.service.ts:11-183

章节来源

• member.controller.ts:9-90
• member.service.ts:11-183

依赖分析

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

• 会员模块

  • 依赖：数据库用户与订单表

  • 与TTS：提供配额与优先级能力

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

图表来源

• auth.controller.ts:1-94
• tts.service.ts:1-715
• player.service.ts:1-280
• member.service.ts:1-183

章节来源

• auth.controller.ts:1-94
• tts.service.ts:1-715
• player.service.ts:1-280
• member.service.ts:1-183

性能考量

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

故障排查指南

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

章节来源

• tts.service.ts:518-542
• tts.service.ts:547-597
• player.service.ts:46-81
• member.service.ts:40-73

结论

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

附录

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