audio_codebuddy/.qoder/repowiki/zh/content/系统架构/模块架构/核心业务模块/核心业务模块.md

核心业务模块

本文档引用的文件

• server/src/app.ts
• server/src/modules/auth/auth.controller.ts
• server/src/modules/auth/auth.service.ts
• server/src/modules/book-generator/book-generator.controller.ts
• server/src/modules/book-generator/book-generator.service.ts
• server/src/modules/tts/tts.controller.ts
• server/src/modules/tts/tts.service.ts
• server/src/modules/video-generator/video-generator.controller.ts
• server/src/modules/video-generator/video-generator.service.ts
• server/src/modules/player/player.controller.ts
• server/src/modules/player/player.service.ts
• server/src/modules/subscription/subscription.controller.ts
• server/src/modules/subscription/subscription.service.ts
• server/src/modules/payment/payment.controller.ts
• server/src/modules/payment/payment.service.ts

目录

1. 简介
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖分析
7. 性能考虑
8. 故障排查指南
9. 结论

简介

本文件面向AI有声书生成平台的核心业务模块，系统性梳理用户认证、AI书籍生成、TTS语音合成、视频生成、播放器、订阅付费等模块的职责边界、实现原理与交互关系。文档以代码为依据，结合架构图与流程图，帮助开发者快速理解模块设计与数据流转，并提供性能与运维建议。

项目结构

后端采用Koa框架，路由集中注册于应用入口，各模块按功能域划分控制器、服务层与业务逻辑，配合中间件实现安全、限流、日志与性能监控。静态资源通过挂载目录提供上传音频与生成视频文件访问。

graph TB
subgraph "应用入口"
APP["server/src/app.ts"]
end
subgraph "认证模块"
AUTH_C["auth.controller.ts"]
AUTH_S["auth.service.ts"]
end
subgraph "书籍生成模块"
BG_C["book-generator.controller.ts"]
BG_S["book-generator.service.ts"]
end
subgraph "TTS模块"
TTS_C["tts.controller.ts"]
TTS_S["tts.service.ts"]
end
subgraph "视频生成模块"
VG_C["video-generator.controller.ts"]
VG_S["video-generator.service.ts"]
end
subgraph "播放器模块"
PL_C["player.controller.ts"]
PL_S["player.service.ts"]
end
subgraph "订阅付费模块"
SUB_C["subscription.controller.ts"]
SUB_S["subscription.service.ts"]
PAY_C["payment.controller.ts"]
PAY_S["payment.service.ts"]
end
APP --> AUTH_C
APP --> BG_C
APP --> TTS_C
APP --> VG_C
APP --> PL_C
APP --> SUB_C
APP --> PAY_C
AUTH_C --> AUTH_S
BG_C --> BG_S
TTS_C --> TTS_S
VG_C --> VG_S
PL_C --> PL_S
SUB_C --> SUB_S
PAY_C --> PAY_S

图表来源

• server/src/app.ts:100-128
• server/src/modules/auth/auth.controller.ts:1-94
• server/src/modules/book-generator/book-generator.controller.ts:1-199
• server/src/modules/tts/tts.controller.ts:1-274
• server/src/modules/video-generator/video-generator.controller.ts:1-244
• server/src/modules/player/player.controller.ts:1-344
• server/src/modules/subscription/subscription.controller.ts:1-191
• server/src/modules/payment/payment.controller.ts:1-258

章节来源

• server/src/app.ts:57-130

核心组件

• 用户认证模块：提供短信验证码登录、用户信息查询与更新、JWT令牌签发与校验。
• AI书籍生成模块：基于LangGraph的工作流编排，支持内容生成、音频生成、章节合并、视频生成与合并。
• TTS语音合成模块：多供应商集成（阿里云、MiniMax、Mock），音色管理，文本分段与合并，LRC歌词生成。
• 视频生成模块：FFmpeg集成，项目管理、素材管理、字幕生成、进度跟踪。
• 播放器模块：播放进度记录、章节合并音频、最近播放列表。
• 订阅付费模块：套餐设计、Token与音频时长配额、计费策略、支付流程。

章节来源

• server/src/modules/auth/auth.controller.ts:1-94
• server/src/modules/book-generator/book-generator.service.ts:45-143
• server/src/modules/tts/tts.service.ts:160-190
• server/src/modules/video-generator/video-generator.service.ts:154-312
• server/src/modules/player/player.service.ts:10-122
• server/src/modules/subscription/subscription.service.ts:158-296
• server/src/modules/payment/payment.service.ts:121-191

架构总览

整体采用“控制器-服务层”分层，中间件负责安全、限流与日志。模块间通过服务层协作，使用WebSocket推送生成进度，使用存储服务统一对接OSS或本地存储。

sequenceDiagram
participant Client as "客户端"
participant AuthC as "认证控制器"
participant AuthS as "认证服务"
participant SubC as "订阅控制器"
participant SubS as "订阅服务"
participant PayC as "支付控制器"
participant PayS as "支付服务"
Client->>AuthC : POST /api/auth/login
AuthC->>AuthS : loginWithPhone(phone, code)
AuthS-->>AuthC : {token, user}
AuthC-->>Client : 登录成功
Client->>SubC : GET /api/subscription/plans
SubC->>SubS : getPlans()
SubS-->>SubC : 套餐列表
SubC-->>Client : 套餐数据
Client->>PayC : POST /api/payment/create
PayC->>PayS : createPaymentOrder(userId, planId, method)
PayS-->>PayC : 支付链接/二维码
PayC-->>Client : 支付信息

图表来源

• server/src/modules/auth/auth.controller.ts:32-52
• server/src/modules/auth/auth.service.ts:44-97
• server/src/modules/subscription/subscription.controller.ts:9-18
• server/src/modules/subscription/subscription.service.ts:312-324
• server/src/modules/payment/payment.controller.ts:9-33
• server/src/modules/payment/payment.service.ts:121-191

详细组件分析

用户认证模块

• 控制器职责
  • 发送验证码：校验手机号格式，生成并返回验证码（开发环境直返）。
  • 手机号登录：校验参数，支持免验证码登录，返回JWT与用户信息。
  • 用户信息查询与更新：基于鉴权中间件，查询与更新用户昵称/头像。
• 服务层职责
  • 短信验证码：Map存储（生产建议Redis），5分钟有效期。
  • JWT签发：使用固定密钥签发7天有效期token，payload包含用户ID与手机号。
  • 登录注册：查找或创建用户，返回新用户标识。
• 权限控制
  • 用户信息与更新接口使用鉴权中间件，从token中解析用户ID。

• 数据模型

  • 用户表字段包含手机号、昵称、头像、会员等级、每日用量等。

    sequenceDiagram
    participant C as "客户端"
    participant Ctrl as "auth.controller"
    participant Svc as "auth.service"
    participant DB as "Prisma"
    C->>Ctrl : POST /api/auth/send-code
    Ctrl->>Svc : generateSmsCode(phone)
    Svc-->>Ctrl : code
    Ctrl-->>C : 返回验证码
    C->>Ctrl : POST /api/auth/login
    Ctrl->>Svc : loginWithPhone(phone, code)
    Svc->>DB : 查找/创建用户
    Svc-->>Ctrl : {token, user}
    Ctrl-->>C : 登录成功
    

图表来源

• server/src/modules/auth/auth.controller.ts:10-30
• server/src/modules/auth/auth.controller.ts:32-52
• server/src/modules/auth/auth.service.ts:11-32
• server/src/modules/auth/auth.service.ts:44-97

章节来源

• server/src/modules/auth/auth.controller.ts:1-94
• server/src/modules/auth/auth.service.ts:1-115

AI书籍生成模块（LangGraph工作流）

• 控制器职责
  • 批量生成：接收书籍ID与步骤列表，创建编排器并后台执行，支持取消与状态查询。
  • 取消与状态：维护运行中的任务映射，设置/清除取消标志，推送进度。
• 服务层职责
  • 编排器：按序执行内容生成、音频生成、音频合并、视频生成、视频合并，推进进度并处理异常。
  • 内容生成：调用LangGraph生成书籍内容，轮询检查完成状态。
  • 音频生成：针对叶节点并发生成，轮询检查完成状态。
  • 音频合并：按父章节合并子章节音频，更新章节URL。
  • 视频生成：基于章节音频创建视频项目并生成，更新章节视频URL。

• LangGraph与工具链

  • 通过book-generator入口导入LangGraph生成器，按书籍规模解析生成层级。

  • 与视频生成服务协作，将章节音频转为视频素材。

    sequenceDiagram
    participant Client as "客户端"
    participant Ctrl as "book-generator.controller"
    participant Orchestrator as "BatchGenerationOrchestrator"
    participant BG as "book-generator.service"
    participant WS as "WebSocket服务"
    Client->>Ctrl : POST /api/book-generator/books/ : id/batch-generate
    Ctrl->>BG : createBatchGenerationTask(bookId, steps)
    BG-->>Ctrl : {taskId, orchestrator}
    Ctrl->>Orchestrator : execute()
    Orchestrator->>WS : 推送进度(generate_content)
    Orchestrator->>WS : 推送进度(generate_audio)
    Orchestrator->>WS : 推送进度(merge_audio)
    Orchestrator->>WS : 推送进度(generate_video)
    Orchestrator->>WS : 推送进度(merge_video)
    Orchestrator-->>Ctrl : 完成/失败
    Ctrl-->>Client : 任务状态
    

图表来源

• server/src/modules/book-generator/book-generator.controller.ts:24-119
• server/src/modules/book-generator/book-generator.service.ts:45-143
• server/src/modules/book-generator/book-generator.service.ts:149-217
• server/src/modules/book-generator/book-generator.service.ts:222-285
• server/src/modules/book-generator/book-generator.service.ts:289-359
• server/src/modules/book-generator/book-generator.service.ts:364-453
• server/src/modules/book-generator/book-generator.service.ts:458-528

章节来源

• server/src/modules/book-generator/book-generator.controller.ts:1-199
• server/src/modules/book-generator/book-generator.service.ts:1-549

TTS语音合成模块（多供应商集成）

• 控制器职责
  • 音色与供应商查询：返回可用音色列表与供应商列表。
  • 异步音频生成：接收文本、音色、参数与可选书籍/章节信息，创建任务并立即返回。
  • 状态查询与下载：查询生成状态，提供单个与批量下载接口。
  • 预览音色：生成简短预览音频。
• 服务层职责
  • Provider工厂：优先级选择MiniMax或阿里云，兜底Mock；支持显式指定供应商。
  • 文本分段：阿里云限制单段长度，按段落与句子切分并保留安全余量。
  • 并发生成：根据供应商类型调整并发度，支持云端URL回源与本地降级。
  • 合并与上传：统一通过存储服务上传至OSS或本地，记录时长与大小。
  • 配额检查：在生成前校验用户音频时长配额，生成后扣减分钟数。
  • LRC歌词：基于文本与时长生成歌词时间轴。

• 音色管理

  • 前端音色ID映射到阿里云音色名称，内置音色列表与描述。

    flowchart TD
    Start(["生成请求"]) --> Validate["参数校验<br/>文本/音色/可选书籍"]
    Validate --> Quota["检查音频配额"]
    Quota --> ProviderSel["选择供应商(优先级)"]
    ProviderSel --> Split["文本分段(按供应商)"]
    Split --> Concurrency["并发生成音频片段"]
    Concurrency --> Merge["合并音频文件"]
    Merge --> Upload["上传至存储服务(OSS/本地)"]
    Upload --> SaveMeta["保存章节/记录元数据"]
    SaveMeta --> LRC["生成LRC歌词"]
    LRC --> Done(["完成"])
    

图表来源

• server/src/modules/tts/tts.controller.ts:52-127
• server/src/modules/tts/tts.service.ts:200-280
• server/src/modules/tts/tts.service.ts:285-542
• server/src/modules/tts/tts.service.ts:599-644

章节来源

• server/src/modules/tts/tts.controller.ts:1-274
• server/src/modules/tts/tts.service.ts:1-715

视频生成模块（FFmpeg集成、字幕生成）

• 控制器职责
  • 项目管理：创建、查询、更新、删除视频项目。
  • 生成流程：启动生成、查询进度、从书籍创建项目。
  • 素材管理：上传、查询、删除素材，支持分类与标签。
• 服务层职责
  • 生成逻辑：根据配置与章节音频生成视频，支持带/不带背景音乐两种路径。
  • FFmpeg封装：提供生成视频与带BGM视频的方法，返回时长与文件大小。
  • 进度与状态：更新项目状态与进度，失败时记录错误信息。
  • 章节联动：生成完成后更新章节视频URL并推送WebSocket事件。

• 字幕与素材

  • 字幕：从章节标题生成字幕配置；素材支持图片与音频，自动下载到临时目录。

  • 权限：素材支持全局与用户私有，查询时按可见性过滤。

    sequenceDiagram
    participant Client as "客户端"
    participant Ctrl as "video-generator.controller"
    participant Svc as "video-generator.service"
    participant FFMPEG as "FFmpeg处理器"
    participant DB as "Prisma"
    Client->>Ctrl : POST /api/video/projects/ : id/generate
    Ctrl->>Svc : generateVideoForProject(id)
    Svc->>DB : 读取项目/章节音频
    Svc->>FFMPEG : 生成视频(含/不含BGM)
    FFMPEG-->>Svc : 输出文件路径/时长/大小
    Svc->>DB : 更新项目状态/进度/输出URL
    Svc-->>Ctrl : 生成结果
    Ctrl-->>Client : 返回结果
    

图表来源

• server/src/modules/video-generator/video-generator.controller.ts:107-129
• server/src/modules/video-generator/video-generator.service.ts:154-312
• server/src/modules/video-generator/video-generator.service.ts:498-555

章节来源

• server/src/modules/video-generator/video-generator.controller.ts:1-244
• server/src/modules/video-generator/video-generator.service.ts:1-556

播放器模块（音频播放控制、进度管理）

• 控制器职责
  • 播放进度：查询、保存、更新、删除；支持批量删除。
  • 最近播放：获取用户最近播放记录。
  • 章节音频：适配旧播放器接口，公开/私有访问控制，章级自动合并小节音频。

• 服务层职责

  • 进度持久化：使用upsert语义保存/更新播放进度。
  • 章节合并：当播放章（level=1）时，自动合并其下小节音频并返回合并URL。

  • 最近播放：聚合章节与书籍信息，计算播放进度百分比。

    flowchart TD
    PStart(["播放请求"]) --> CheckAuth["鉴权(可选)"]
    CheckAuth --> LoadProgress["查询播放进度"]
    LoadProgress --> MergeCheck{"是否章(level=1)?"}
    MergeCheck -- 否 --> ReturnSingle["返回单节音频URL"]
    MergeCheck -- 是 --> Merge["合并子节音频"]
    Merge --> SaveMerged["更新章节音频URL"]
    SaveMerged --> ReturnMerged["返回合并音频URL"]
    

图表来源

• server/src/modules/player/player.controller.ts:136-294
• server/src/modules/player/player.service.ts:147-234

章节来源

• server/src/modules/player/player.controller.ts:1-344
• server/src/modules/player/player.service.ts:1-280

订阅付费模块（套餐设计、支付流程）

• 订阅服务
  • 套餐初始化：默认套餐写入数据库，支持按等级配置音频时长、Token额度、特性等。
  • 配额与计费：音频时长按“包月批发价+按量零售价”策略计费，支持月度配额重置。
  • 预估与检查：提供音频生成预估与配额检查接口。

• 支付服务

  • 支付订单：创建订单记录，返回支付宝/微信支付链接或二维码。
  • 回调处理：验证签名，处理支付成功/失败，激活订阅并更新用户等级与Token余额。

  • 微信/支付宝SDK：懒加载，支持沙箱与生产环境，证书与参数从环境变量读取。

    sequenceDiagram
    participant Client as "客户端"
    participant PayC as "payment.controller"
    participant PayS as "payment.service"
    participant Alipay as "Alipay SDK"
    participant WeChat as "WeChatPay SDK"
    participant DB as "Prisma"
    Client->>PayC : POST /api/payment/create
    PayC->>PayS : createPaymentOrder(userId, planId, method)
    alt 支付宝
    PayS->>Alipay : 生成支付链接/二维码
    Alipay-->>PayS : 支付URL/二维码
    else 微信
    PayS->>WeChat : 生成Native二维码/H5
    WeChat-->>PayS : 二维码/H5链接
    end
    PayS->>DB : 创建订单记录
    PayS-->>PayC : 返回支付信息
    PayC-->>Client : 支付链接/二维码
    Note over Client,DB : 异步回调
    Alipay-->>PayS : 通知(trade_status)
    PayS->>DB : 更新订单状态/支付ID
    PayS->>DB : 激活订阅/更新用户等级
    

图表来源

• server/src/modules/payment/payment.controller.ts:9-33
• server/src/modules/payment/payment.service.ts:121-191
• server/src/modules/payment/payment.service.ts:340-406
• server/src/modules/subscription/subscription.service.ts:298-309

章节来源

• server/src/modules/subscription/subscription.controller.ts:1-191
• server/src/modules/subscription/subscription.service.ts:1-938
• server/src/modules/payment/payment.controller.ts:1-258
• server/src/modules/payment/payment.service.ts:1-578

依赖分析

• 模块耦合
  • 认证模块被多个控制器依赖，提供鉴权中间件。
  • 订阅与支付模块相互协作：支付成功后激活订阅并更新用户配额。
  • 书籍生成模块依赖视频生成与播放器服务，形成“内容→音频→视频”的闭环。
  • TTS服务依赖存储服务与WebSocket服务，统一上传与进度推送。
• 外部依赖
  • 支付：支付宝SDK、微信支付SDK（懒加载）。
  • 存储：OSS或本地存储抽象，统一上传与URL生成。
  • FFmpeg：视频生成核心处理能力。

• 循环依赖

  • 控制器与服务层单向依赖，未发现循环依赖迹象。

    graph LR
    AUTH["认证模块"] --> ALL["所有模块(鉴权)"]
    SUB["订阅模块"] --> PAY["支付模块"]
    BG["书籍生成模块"] --> VG["视频生成模块"]
    BG --> PL["播放器模块"]
    TTS["TTS模块"] --> STORE["存储服务"]
    TTS --> WS["WebSocket服务"]
    VG --> FFMPEG["FFmpeg处理器"]
    

图表来源

• server/src/app.ts:100-128
• server/src/modules/book-generator/book-generator.service.ts:8-9
• server/src/modules/tts/tts.service.ts:13-14

章节来源

• server/src/app.ts:100-128

性能考虑

• 并发与限流
  • TTS分段并发按供应商类型动态调整，减少长文本等待时间。
  • 视频生成采用异步流程，避免阻塞主线程。
• 存储与网络
  • 统一通过存储服务上传，支持OSS直传与本地回退，降低单点风险。
  • 视频素材支持远程URL直传与本地下载，减少重复传输。
• 进度与可观测性
  • WebSocket推送生成进度，前端可实时反馈。
  • 中间件提供性能监控与日志记录，便于定位瓶颈。

故障排查指南

• 认证
  • 验证码：确认开发环境直返与有效期；生产环境建议使用Redis。
  • JWT：检查密钥与过期时间，确保客户端正确携带Authorization。
• TTS
  • 供应商额度：若出现“配额受限”，检查供应商限额与降级策略。
  • 文本分段：超长文本自动分段，注意句段边界与安全余量。
  • 上传失败：本地降级合并音频并上传，检查存储服务配置。
• 视频
  • FFmpeg：确认安装与路径；素材缺失时检查URL与下载逻辑。
  • 进度异常：检查项目状态更新与WebSocket事件推送。
• 订阅与支付
  • 支付回调：核对签名验证与订单状态更新；微信支付需正确配置证书。
  • 配额重置：确认月度配额重置逻辑与用户usedAudioMinutes更新。

章节来源

• server/src/modules/auth/auth.service.ts:11-32
• server/src/modules/tts/tts.service.ts:518-542
• server/src/modules/video-generator/video-generator.service.ts:291-311
• server/src/modules/payment/payment.service.ts:340-406

结论

本平台围绕“内容→音频→视频”的创作链路构建，通过多供应商TTS与FFmpeg视频处理实现高质量交付；订阅与支付体系保障可持续运营；模块间通过清晰的控制器-服务层边界与中间件机制实现高内聚低耦合。建议在生产环境中完善Redis缓存、证书与SDK配置校验、以及更细粒度的速率限制与熔断策略，持续提升稳定性与用户体验。