audio_codebuddy/.qoder/repowiki/zh/content/API接口文档/API接口文档.md

API接口文档

本文档引用的文件

• server/src/app.ts
• server/src/modules/auth/auth.controller.ts
• server/src/modules/tts/tts.controller.ts
• server/src/modules/member/member.controller.ts
• server/src/modules/favorites/favorites.controller.ts
• server/src/modules/player/player.controller.ts
• server/src/modules/search/search.controller.ts
• server/src/modules/categories/categories.controller.ts
• server/src/modules/notifications/notifications.controller.ts
• server/src/modules/book-generator/book-generator.controller.ts
• server/src/modules/payment/payment.controller.ts
• server/src/modules/subscription/subscription.controller.ts
• server/src/modules/history/history.controller.ts
• server/src/modules/drafts/drafts.controller.ts
• server/src/modules/comments/comments.controller.ts
• server/src/modules/preferences/preferences.controller.ts

目录

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

简介

本API接口文档面向AI有声书生成平台，覆盖认证、TTS语音合成、音频管理、会员与支付、播放器、搜索与分类、收藏、历史、草稿、评论与偏好等模块。文档提供各接口的HTTP方法、URL模式、请求参数、响应格式、错误码说明及最佳实践建议，并给出架构图与流程图帮助理解。

项目结构

后端基于Koa框架，通过路由注册统一挂载在/api前缀下，核心入口负责中间件装配、静态资源映射、健康检查与指标暴露。

graph TB
A["应用入口<br/>server/src/app.ts"] --> B["路由注册<br/>/api/*"]
B --> C["认证模块<br/>/api/auth"]
B --> D["TTS模块<br/>/api/tts"]
B --> E["会员与支付模块<br/>/api/member, /api/payment, /api/subscription"]
B --> F["收藏模块<br/>/api/favorites"]
B --> G["播放器模块<br/>/api/player"]
B --> H["搜索与分类模块<br/>/api/search, /api/categories"]
B --> I["通知模块<br/>/api/notifications"]
B --> J["书籍生成模块<br/>/api/book-generator"]
B --> K["其他模块<br/>/api/history, /api/drafts, /api/comments, /api/user/preferences"]

图表来源

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

章节来源

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

核心组件

• 应用入口与中间件：健康检查、性能监控、日志、CORS、限流、安全防护、静态资源挂载、路由注册。
• 模块化路由：按业务域划分控制器，统一以/api前缀对外提供RESTful接口。
• 数据访问：Prisma ORM封装数据库交互；部分模块结合Redis、OSS等外部服务。

章节来源

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

架构总览

整体采用分层架构：入口层（Koa）、路由层（Router）、业务层（Service）、数据层（Prisma/存储）。安全方面包含XSS与SQL注入防护、可选鉴权中间件、限流策略等。

graph TB
subgraph "入口层"
APP["Koa应用<br/>server/src/app.ts"]
end
subgraph "中间件层"
SEC["安全防护<br/>XSS/SQL注入"]
CORS["跨域支持"]
LOG["日志与性能监控"]
RATE["限流策略"]
end
subgraph "路由层"
ROUTER["Koa Router<br/>/api/*"]
end
subgraph "业务层"
AUTH["认证模块"]
TTS["TTS模块"]
MEMBER["会员与支付模块"]
FAV["收藏模块"]
PLAYER["播放器模块"]
SEARCH["搜索与分类模块"]
BOOK["书籍生成模块"]
OTHER["历史/草稿/评论/偏好等"]
end
subgraph "数据层"
PRISMA["Prisma ORM"]
REDIS["Redis"]
OSS["对象存储(OSS/本地)"]
end
APP --> SEC --> CORS --> LOG --> RATE --> ROUTER
ROUTER --> AUTH & TTS & MEMBER & FAV & PLAYER & SEARCH & BOOK & OTHER
OTHER --> PRISMA
TTS --> PRISMA
MEMBER --> PRISMA
PLAYER --> PRISMA
SEARCH --> PRISMA
BOOK --> PRISMA
OTHER --> REDIS
TTS --> OSS

图表来源

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

详细组件分析

认证接口

• 发送验证码

  • 方法与路径：POST /api/auth/send-code
  • 请求体字段：phone（字符串，手机号格式校验）
  • 响应体字段：code、message、data.phone、data.code
  • 错误码：400（参数非法）
  • 示例请求：{"phone":"13800001111"}
  • 示例响应：{"code":0,"message":"验证码发送成功","data":{"phone":"13800001111","code":"123456"}}

• 手机号登录

  • 方法与路径：POST /api/auth/login
  • 请求体字段：phone（字符串）、code（字符串，可选）
  • 响应体字段：code、message、data（令牌/用户标识等）
  • 错误码：400（参数非法）
  • 示例请求：{"phone":"13800001111","code":"123456"}

• 获取用户信息

  • 方法与路径：GET /api/auth/user-info
  • 鉴权：需要携带有效令牌
  • 响应体字段：code、message、data（用户信息）
  • 错误码：401（未授权）、404（用户不存在）

• 更新用户信息

  • 方法与路径：PUT /api/auth/user-info
  • 鉴权：需要携带有效令牌
  • 请求体字段：nickname（字符串，可选）、avatar（字符串，可选）
  • 响应体字段：code、message、data（更新后的昵称与头像）
  • 错误码：400（用户不存在）

章节来源

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

TTS相关接口

• 获取可用音色列表

  • 方法与路径：GET /api/tts/voices
  • 响应体字段：code、message、data.voices
  • 错误码：无（内部错误通过全局错误处理）

• 获取可用TTS服务商列表

  • 方法与路径：GET /api/tts/providers
  • 响应体字段：code、message、data.providers

• 生成音频（异步）

  • 方法与路径：POST /api/tts/generate
  • 鉴权：可选（optionalAuth）
  • 请求体字段：text（字符串，必填）、voiceId（字符串，必填）、voiceParams（对象，可选，包含speed、pitch、volume）、bookId（字符串，可选）、chapterTitle（字符串，可选）、ttsProvider（枚举，可选）
  • 响应体字段：code、message、data（包含audioId、audioUrl占位）
  • 错误码：400（参数缺失/不合法）、404（书籍不存在）、401（未授权，当需要鉴权时）
  • 说明：生成完成后会扣除音频分钟配额（若用户存在）

• 获取音频生成状态

  • 方法与路径：GET /api/tts/status/{audioId}
  • 响应体字段：code、message、data（状态、进度、URL等）
  • 错误码：404（音频不存在）

• 预览音色

  • 方法与路径：POST /api/tts/preview
  • 请求体字段：voiceId（字符串，必填）、voiceParams（对象，可选）、ttsProvider（枚举，可选）
  • 响应体字段：code、message、data.previewText、data.voiceId、data.audioUrl
  • 错误码：400（参数缺失）、500（生成失败）

• 获取音频下载信息

  • 方法与路径：GET /api/tts/download/{audioId}
  • 响应体字段：code、message、data（id、title、audioUrl、duration、size、downloadUrl）
  • 错误码：404（音频不存在或文件不存在）

• 批量下载音频

  • 方法与路径：POST /api/tts/download/batch
  • 请求体字段：audioIds（数组，最多50项）
  • 响应体字段：code、message、data.total、data.audios（每项包含id、title、downloadUrl、duration、size）
  • 错误码：400（参数非法）、500（查询失败）

章节来源

• server/src/modules/tts/tts.controller.ts:12-274

音频管理接口（收藏、播放进度、历史、草稿、评论、偏好）

• 收藏管理

  • 获取收藏列表：GET /api/favorites（可选鉴权）
  • 添加收藏：POST /api/favorites（可选鉴权）
  • 取消收藏：DELETE /api/favorites/{audioId}（可选鉴权）
  • 检查是否已收藏：GET /api/favorites/check/{audioId}（可选鉴权）
  • 错误码：400（参数缺失）

• 播放器接口

  • 获取播放进度列表：GET /api/player/progress（可选鉴权）
  • 保存播放进度：POST /api/player/progress（可选鉴权）
  • 更新播放进度：PUT /api/player/progress/{audioId}（可选鉴权）
  • 删除播放记录：DELETE /api/player/progress/{audioId}（可选鉴权）
  • 批量删除播放记录：DELETE /api/player/progress/batch（可选鉴权）
  • 最近播放：GET /api/player/recent（可选鉴权）
  • 旧播放器适配：GET /api/player/audio/list、GET /api/player/audio/{id}、PUT /api/player/audio/{id}/public

• 音频生成历史

  • 列表查询：GET /api/history（可选鉴权）
  • 分页参数：page、pageSize、startDate

• 草稿管理

  • 获取草稿列表：GET /api/drafts（可选鉴权）
  • 获取单个草稿：GET /api/drafts/{id}（可选鉴权）
  • 保存草稿：POST /api/drafts（可选鉴权）
  • 更新草稿：PUT /api/drafts/{id}（可选鉴权）
  • 删除草稿：DELETE /api/drafts/{id}（可选鉴权）

• 评论接口

  • 获取章节评论：GET /api/comments/{chapterId}
  • 添加评论：POST /api/comments（开发环境使用测试用户ID）

• 用户偏好

  • 获取偏好：GET /api/user/preferences（可选鉴权）
  • 更新偏好：PUT /api/user/preferences（可选鉴权）

章节来源

• server/src/modules/favorites/favorites.controller.ts:12-76
• server/src/modules/player/player.controller.ts:13-344
• server/src/modules/history/history.controller.ts:10-67
• server/src/modules/drafts/drafts.controller.ts:9-78
• server/src/modules/comments/comments.controller.ts:9-59
• server/src/modules/preferences/preferences.controller.ts:12-50

会员与支付接口

• 权益查询

  • 方法与路径：GET /api/member/benefits
  • 响应体字段：code、message、data（权益信息）

• 会员状态

  • 方法与路径：GET /api/member/status
  • 鉴权：需要携带有效令牌
  • 响应体字段：code、message、data（会员状态）

• 创建订单

  • 方法与路径：POST /api/member/order
  • 鉴权：需要携带有效令牌
  • 请求体字段：productType（枚举："monthly"|"yearly"）
  • 响应体字段：code、message、data（订单信息）

• 模拟支付（开发环境）

  • 方法与路径：POST /api/member/pay/mock
  • 鉴权：需要携带有效令牌
  • 请求体字段：orderNo（字符串）
  • 响应体字段：code、message、data（支付结果）

• 订单列表

  • 方法与路径：GET /api/member/orders
  • 鉴权：需要携带有效令牌
  • 查询参数：page、pageSize

• 套餐与订阅

  • 获取套餐列表：GET /api/subscription/plans
  • 获取套餐详情：GET /api/subscription/plans/{id}
  • 获取用户订阅信息：GET /api/subscription/subscription
  • 获取用户Token余额：GET /api/subscription/balance
  • Token使用记录：GET /api/subscription/usage
  • 获取用户配额（兼容）：GET /api/subscription/quota
  • 检查配额：POST /api/subscription/check-quota
  • 书籍规模预估字数：GET /api/subscription/book-scale-estimate
  • 书籍生成配额检查：GET /api/subscription/book-generation-quota
  • 检查当前额度（按字数）：POST /api/subscription/check-quota-words
  • 获取用户音频时长余额：GET /api/subscription/audio-balance
  • 音频生成预估：GET /api/subscription/audio-estimate

• 支付相关

  • 创建支付订单：POST /api/payment/create
  • 模拟支付（开发环境）：POST /api/payment/mock
  • 支付宝异步通知：POST /api/payment/alipay/notify
  • 支付宝同步返回：GET /api/payment/alipay/return
  • 微信支付回调：POST /api/payment/wechat/notify
  • 查询微信支付订单：GET /api/payment/wechat/query/{orderNo}
  • 订单列表：GET /api/payment/orders
  • 订单详情：GET /api/payment/orders/{orderNo}
  • 支付宝扫码支付二维码：POST /api/payment/alipay/qrcode

章节来源

• server/src/modules/member/member.controller.ts:9-90
• server/src/modules/subscription/subscription.controller.ts:9-191
• server/src/modules/payment/payment.controller.ts:9-258

搜索与分类接口

• 搜索音频

  • 方法与路径：GET /api/search
  • 查询参数：q（关键词）、limit（限制数量）
  • 响应体字段：code、message、data（结果列表）

• 热门搜索词

  • 方法与路径：GET /api/search/hot
  • 查询参数：limit
  • 响应体字段：code、message、data（热门词列表）

• 搜索历史

  • 获取历史：GET /api/search/history?userId=&limit=
  • 保存历史：POST /api/search/history（请求体：userId、keyword）
  • 删除单条历史：DELETE /api/search/history?userId=&keyword=
  • 清空历史：DELETE /api/search/history/all?userId=

• 分类列表

  • 方法与路径：GET /api/categories
  • 响应体字段：code、message、data（分类列表）

• 按分类获取音频

  • 方法与路径：GET /api/categories/{id}?page=&pageSize=
  • 响应体字段：code、message、data（分页结果）

章节来源

• server/src/modules/search/search.controller.ts:6-170
• server/src/modules/categories/categories.controller.ts:6-55

通知接口

• 获取通知列表：GET /api/notifications（可选鉴权）
• 标记为已读：POST /api/notifications/read（请求体：id）
• 全部标记为已读：PUT /api/notifications/read-all（可选鉴权）

章节来源

• server/src/modules/notifications/notifications.controller.ts:11-68

书籍生成接口

• 一键完整生成书籍（内容、音频、合并、视频、合并）

  • 方法与路径：POST /api/book-generator/books/{id}/batch-generate
  • 请求体字段：steps（数组，可选，默认全部步骤）
  • 响应体字段：code、message、data（包含taskId、bookId、status、steps）
  • 错误码：400（步骤无效/已有任务运行）、404（书籍不存在）、500（启动失败）

• 取消批量生成任务

  • 方法与路径：POST /api/book-generator/books/{id}/batch-generate/cancel
  • 响应体字段：code、message、data（taskId、bookId）

• 查询批量生成任务状态

  • 方法与路径：GET /api/book-generator/books/{id}/batch-generate/status
  • 响应体字段：code、message、data（isRunning、taskId、bookId）

章节来源

• server/src/modules/book-generator/book-generator.controller.ts:20-199

依赖关系分析

• 路由到控制器：入口文件统一注册各模块路由，形成清晰的命名空间隔离。
• 控制器到服务：控制器负责参数校验与响应封装，具体业务逻辑在对应service中实现。
• 数据访问：Prisma作为ORM，统一处理数据库读写；TTS模块涉及外部存储（OSS/本地）与第三方TTS提供商。

• 安全与限流：中间件层集中处理CORS、日志、性能监控、安全防护与限流策略。

  graph LR
  R["/api/* 路由"] --> AC["认证控制器"]
  R --> TC["TTS控制器"]
  R --> MC["会员/支付控制器"]
  R --> FC["收藏控制器"]
  R --> PC["播放器控制器"]
  R --> SC["搜索/分类控制器"]
  R --> NC["通知控制器"]
  R --> BC["书籍生成控制器"]
  AC --> S1["AuthService"]
  TC --> S2["TtsService"]
  MC --> S3["Member/Payment/Subscription Service"]
  FC --> S4["FavoritesService"]
  PC --> S5["PlayerService"]
  SC --> S6["Search/Categories Service"]
  NC --> S7["NotificationsService"]
  BC --> S8["BookGenerator Service"]
  

图表来源

• server/src/app.ts:100-128
• server/src/modules/auth/auth.controller.ts:1-94
• server/src/modules/tts/tts.controller.ts:1-274
• server/src/modules/member/member.controller.ts:1-90
• server/src/modules/favorites/favorites.controller.ts:1-76
• server/src/modules/player/player.controller.ts:1-344
• server/src/modules/search/search.controller.ts:1-170
• server/src/modules/notifications/notifications.controller.ts:1-68
• server/src/modules/book-generator/book-generator.controller.ts:1-199

性能考量

• 异步生成与队列：TTS生成采用异步模式，立即返回任务标识，避免阻塞请求。
• 配额与限流：TTS接口内置配额检查与扣减逻辑；可选开启全局限流中间件以保护后端。
• 缓存与CDN：静态资源通过koa-static与挂载目录提供；推荐结合CDN加速音频/视频资源访问。
• 数据库查询：分页查询与条件过滤，避免一次性加载大量数据；对热点查询可引入Redis缓存。
• 并发与优雅停机：服务启动时初始化队列与WebSocket，进程退出时优雅关闭连接与队列。

故障排查指南

• 常见错误码
  • 400：参数错误/请求体缺失
  • 401：未授权（缺少或无效令牌）
  • 403：无权限（非资源所有者）
  • 404：资源不存在
  • 500：服务器内部错误
• 排查步骤
  • 检查请求参数与鉴权头（Authorization）
  • 查看服务端日志与性能监控指标
  • 对TTS生成问题，确认配额状态与提供商可用性
  • 对支付回调问题，核对签名验证与订单状态一致性

章节来源

• server/src/modules/tts/tts.controller.ts:70-96
• server/src/modules/member/member.controller.ts:37-38
• server/src/modules/payment/payment.controller.ts:58-125

结论

本API文档梳理了AI有声书平台的核心RESTful接口，涵盖认证、TTS、音频管理、会员与支付、播放器、搜索与分类、收藏、历史、草稿、评论与偏好等模块。通过统一的路由组织与中间件体系，平台实现了高内聚、低耦合的接口设计。建议在生产环境中启用鉴权、限流与安全防护，并结合CDN与缓存提升性能与稳定性。

附录

API调用最佳实践

• 鉴权：所有需要用户身份的接口均需携带令牌；避免在客户端硬编码敏感信息。
• 参数校验：严格遵循接口文档的参数类型与约束，减少无效请求。
• 异步任务：TTS生成等耗时操作采用异步模式，定期轮询状态接口获取结果。
• 错误处理：统一处理4xx/5xx错误，记录上下文信息便于定位问题。
• 版本管理：建议在URL中加入版本号（如/api/v1/...），并保持向后兼容策略。

安全考虑

• 输入验证：对所有输入进行白名单校验与长度限制。
• CORS与安全头：确保跨域与安全策略符合业务需求。
• 速率限制：根据业务场景开启限流，防止滥用。
• 日志与审计：记录关键操作日志，便于审计与追踪。

性能优化建议

• 使用分页与条件过滤，避免全量拉取。
• 对热点数据引入缓存，降低数据库压力。
• 将静态资源与媒体文件托管至CDN，缩短访问延迟。
• 对TTS与视频生成任务使用队列异步处理，提高吞吐量。