# API接口文档

<cite>
**本文档引用的文件**
- [server/src/app.ts](file://server/src/app.ts)
- [server/src/modules/auth/auth.controller.ts](file://server/src/modules/auth/auth.controller.ts)
- [server/src/modules/tts/tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [server/src/modules/member/member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [server/src/modules/favorites/favorites.controller.ts](file://server/src/modules/favorites/favorites.controller.ts)
- [server/src/modules/player/player.controller.ts](file://server/src/modules/player/player.controller.ts)
- [server/src/modules/search/search.controller.ts](file://server/src/modules/search/search.controller.ts)
- [server/src/modules/categories/categories.controller.ts](file://server/src/modules/categories/categories.controller.ts)
- [server/src/modules/notifications/notifications.controller.ts](file://server/src/modules/notifications/notifications.controller.ts)
- [server/src/modules/book-generator/book-generator.controller.ts](file://server/src/modules/book-generator/book-generator.controller.ts)
- [server/src/modules/payment/payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [server/src/modules/subscription/subscription.controller.ts](file://server/src/modules/subscription/subscription.controller.ts)
- [server/src/modules/history/history.controller.ts](file://server/src/modules/history/history.controller.ts)
- [server/src/modules/drafts/drafts.controller.ts](file://server/src/modules/drafts/drafts.controller.ts)
- [server/src/modules/comments/comments.controller.ts](file://server/src/modules/comments/comments.controller.ts)
- [server/src/modules/preferences/preferences.controller.ts](file://server/src/modules/preferences/preferences.controller.ts)
</cite>

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

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

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

```mermaid
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](file://server/src/app.ts#L92-L128)

章节来源
- [server/src/app.ts:57-130](file://server/src/app.ts#L57-L130)

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

章节来源
- [server/src/app.ts:63-98](file://server/src/app.ts#L63-L98)
- [server/src/app.ts:100-128](file://server/src/app.ts#L100-L128)

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

```mermaid
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](file://server/src/app.ts#L63-L98)
- [server/src/app.ts:100-128](file://server/src/app.ts#L100-L128)

## 详细组件分析

### 认证接口
- 发送验证码
  - 方法与路径：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](file://server/src/modules/auth/auth.controller.ts#L10-L94)

### 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](file://server/src/modules/tts/tts.controller.ts#L12-L274)

### 音频管理接口（收藏、播放进度、历史、草稿、评论、偏好）
- 收藏管理
  - 获取收藏列表：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](file://server/src/modules/favorites/favorites.controller.ts#L12-L76)
- [server/src/modules/player/player.controller.ts:13-344](file://server/src/modules/player/player.controller.ts#L13-L344)
- [server/src/modules/history/history.controller.ts:10-67](file://server/src/modules/history/history.controller.ts#L10-L67)
- [server/src/modules/drafts/drafts.controller.ts:9-78](file://server/src/modules/drafts/drafts.controller.ts#L9-L78)
- [server/src/modules/comments/comments.controller.ts:9-59](file://server/src/modules/comments/comments.controller.ts#L9-L59)
- [server/src/modules/preferences/preferences.controller.ts:12-50](file://server/src/modules/preferences/preferences.controller.ts#L12-L50)

### 会员与支付接口
- 权益查询
  - 方法与路径：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](file://server/src/modules/member/member.controller.ts#L9-L90)
- [server/src/modules/subscription/subscription.controller.ts:9-191](file://server/src/modules/subscription/subscription.controller.ts#L9-L191)
- [server/src/modules/payment/payment.controller.ts:9-258](file://server/src/modules/payment/payment.controller.ts#L9-L258)

### 搜索与分类接口
- 搜索音频
  - 方法与路径：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](file://server/src/modules/search/search.controller.ts#L6-L170)
- [server/src/modules/categories/categories.controller.ts:6-55](file://server/src/modules/categories/categories.controller.ts#L6-L55)

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

章节来源
- [server/src/modules/notifications/notifications.controller.ts:11-68](file://server/src/modules/notifications/notifications.controller.ts#L11-L68)

### 书籍生成接口
- 一键完整生成书籍（内容、音频、合并、视频、合并）
  - 方法与路径：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](file://server/src/modules/book-generator/book-generator.controller.ts#L20-L199)

## 依赖关系分析
- 路由到控制器：入口文件统一注册各模块路由，形成清晰的命名空间隔离。
- 控制器到服务：控制器负责参数校验与响应封装，具体业务逻辑在对应service中实现。
- 数据访问：Prisma作为ORM，统一处理数据库读写；TTS模块涉及外部存储（OSS/本地）与第三方TTS提供商。
- 安全与限流：中间件层集中处理CORS、日志、性能监控、安全防护与限流策略。

```mermaid
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](file://server/src/app.ts#L100-L128)
- [server/src/modules/auth/auth.controller.ts:1-94](file://server/src/modules/auth/auth.controller.ts#L1-L94)
- [server/src/modules/tts/tts.controller.ts:1-274](file://server/src/modules/tts/tts.controller.ts#L1-L274)
- [server/src/modules/member/member.controller.ts:1-90](file://server/src/modules/member/member.controller.ts#L1-L90)
- [server/src/modules/favorites/favorites.controller.ts:1-76](file://server/src/modules/favorites/favorites.controller.ts#L1-L76)
- [server/src/modules/player/player.controller.ts:1-344](file://server/src/modules/player/player.controller.ts#L1-L344)
- [server/src/modules/search/search.controller.ts:1-170](file://server/src/modules/search/search.controller.ts#L1-L170)
- [server/src/modules/notifications/notifications.controller.ts:1-68](file://server/src/modules/notifications/notifications.controller.ts#L1-L68)
- [server/src/modules/book-generator/book-generator.controller.ts:1-199](file://server/src/modules/book-generator/book-generator.controller.ts#L1-L199)

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

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

章节来源
- [server/src/modules/tts/tts.controller.ts:70-96](file://server/src/modules/tts/tts.controller.ts#L70-L96)
- [server/src/modules/member/member.controller.ts:37-38](file://server/src/modules/member/member.controller.ts#L37-L38)
- [server/src/modules/payment/payment.controller.ts:58-125](file://server/src/modules/payment/payment.controller.ts#L58-L125)

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

## 附录

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

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

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