audio_codebuddy/.qoder/repowiki/zh/content/系统架构/模块架构/模块架构.md

模块架构

本文引用的文件

• server/src/app.ts
• server/src/config/index.ts
• server/src/services/queue.service.ts
• server/src/services/redis.service.ts
• server/src/modules/auth/auth.controller.ts
• server/src/modules/tts/tts.controller.ts
• server/src/modules/player/player.controller.ts
• server/src/modules/subscription/subscription.controller.ts
• server/src/modules/payment/payment.controller.ts
• server/src/modules/video-generator/video-generator.controller.ts
• server/src/modules/book-generator/index.ts
• server/src/modules/book-generator/book-generator.controller.ts

目录

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

简介

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

项目结构

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

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
• server/src/config/index.ts:69-117
• server/src/services/redis.service.ts:1-274
• server/src/services/queue.service.ts:1-347
• server/src/modules/auth/auth.controller.ts:1-94
• server/src/modules/tts/tts.controller.ts:1-274
• 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/modules/video-generator/video-generator.controller.ts:1-244
• server/src/modules/book-generator/index.ts:1-104
• server/src/modules/book-generator/book-generator.controller.ts:1-199

章节来源

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

核心组件

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

章节来源

• server/src/app.ts:63-130
• server/src/config/index.ts:13-117
• server/src/services/redis.service.ts:1-274
• server/src/services/queue.service.ts:1-347

架构总览

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

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
• server/src/services/queue.service.ts:18-347
• server/src/services/redis.service.ts:1-274
• server/src/config/index.ts:69-117

详细组件分析

用户认证模块

• 职责
  • 发送短信验证码、手机号登录、获取与更新用户信息。
• 接口要点
  • 登录接口支持跳过验证码校验（便于联调）。
  • 用户信息读取与更新均受鉴权中间件保护。

• 数据流

  • 控制器接收请求→参数校验→调用服务→返回标准化响应。

    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

章节来源

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

AI内容生成模块（LangGraph书籍生成）

• 职责
  • 通过策略选择器切换生成策略（串行/一步大纲+并行/逐章内聚），支持按书籍规模与层级自动推荐生成策略。
• 接口要点
  • 对外提供独立的大纲生成函数，便于API直连。
  • 主类提供统一生成入口，内部委派给当前策略执行。

• 生命周期

  • 通过应用启动时初始化队列与恢复中断任务，保障生成任务的连续性。

    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

章节来源

• server/src/modules/book-generator/index.ts:1-104

TTS语音合成模块

• 职责
  • 提供音色列表、服务商列表查询；异步音频生成；状态查询；预览音色；批量下载音频。
• 接口要点
  • 生成接口支持可选鉴权、参数校验、配额检查与消费、异步返回任务ID。
  • 下载接口直接返回存储URL，避免服务端中转。

• 通信机制

  • 生成任务通过队列服务异步执行，进度可通过回调或轮询状态接口获取。

    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
• server/src/services/queue.service.ts:131-190

章节来源

• server/src/modules/tts/tts.controller.ts:1-274
• server/src/services/queue.service.ts:1-347

音频处理模块（播放器与历史）

• 职责
  • 播放进度记录与查询、最近播放列表、公开状态管理、章节音频适配（合并章级小节音频）。
• 接口要点
  • 支持未登录场景下的测试用户ID回退；公开与私有音频访问控制。

• 数据流

  • 控制器读取鉴权上下文→查询数据库→按规则合并音频URL→返回适配格式。

    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

章节来源

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

视频生成模块

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

章节来源

• server/src/modules/video-generator/video-generator.controller.ts:1-244
• server/src/services/queue.service.ts:176-190

订阅付费模块

• 职责
  • 套餐查询、用户订阅信息、Token余额与使用记录、书籍生成与音频生成配额检查与估算、支付订单创建与回调处理。
• 接口要点
  • 支付宝/微信回调分别处理异步通知与同步返回；提供模拟支付接口（开发环境）。

• 生命周期

  • 应用启动时初始化订阅套餐数据，保证后续配额检查可用。

    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
• server/src/modules/payment/payment.controller.ts:9-33

章节来源

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

书籍生成编排模块

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

章节来源

• server/src/modules/book-generator/book-generator.controller.ts:1-199
• server/src/app.ts:168-172

依赖分析

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

• 接口契约

  • 控制器统一返回结构体（code/message/data），便于前端与监控系统消费。

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

图表来源

• server/src/app.ts:100-128
• server/src/services/queue.service.ts:18-347
• server/src/services/redis.service.ts:1-274
• server/src/config/index.ts:69-117

性能考虑

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

章节来源

• server/src/services/queue.service.ts:131-190
• server/src/services/redis.service.ts:246-267
• server/src/app.ts:63-94

故障排查指南

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

章节来源

• server/src/app.ts:133-192
• server/src/services/queue.service.ts:72-122
• server/src/services/redis.service.ts:246-267
• server/src/modules/payment/payment.controller.ts:57-125

结论

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

附录

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

章节来源

• server/src/app.ts:133-192