# AI有声书 v2 - API 契约

> 前后端接口定义。字段名和类型的真理源头。
> 维护者：devs（添加/变更端点时**必须**更新）

---

## 现有 API

### 书籍相关

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/books | 获取书籍列表 |
| GET | /api/books/:id | 获取书籍详情 |
| POST | /api/book-generator/books | 创建书籍 |
| POST | /api/book-generator/books/:id/generate | 生成内容 |
| POST | /api/book-generator/books/:id/generate-audio | 生成音频 |
| POST | /api/book-generator/books/:id/merge-audio | 合并音频 |
| POST | /api/book-generator/books/:id/generate-video | 生成视频 |
| POST | /api/book-generator/books/:id/publish | 发布/取消发布 |

### 播放器相关

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/player/progress | 获取播放进度 |
| POST | /api/player/progress | 保存播放进度 |

### 用户相关

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /api/auth/login | 登录 |
| GET | /api/user/profile | 获取用户信息 |

---

## 新增 API（优化项涉及）

### OPT-03: 首页最近收听

| 方法 | 路径 | 描述 |
|------|------|------|
| GET | /api/player/recent | 获取用户最近播放记录 |

Response:
```json
{
  "list": [
    {
      "id": "string",
      "title": "string",
      "coverUrl": "string",
      "progress": 45,
      "updatedAt": "2026-05-07T10:00:00Z"
    }
  ]
}
```

### OPT-08: 一键完整生成

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /api/book-generator/books/:id/batch-generate | 编排完整生成流程 |
| POST | /api/book-generator/books/:id/batch-generate/cancel | 取消生成任务 |
| GET | /api/book-generator/books/:id/batch-generate/status | 查询任务状态 |

Request:
```json
{
  "steps": ["generate_content", "generate_audio", "merge_audio", "generate_video", "merge_video"]
}
```

Response:
```json
{
  "taskId": "string",
  "bookId": "string",
  "status": "started",
  "steps": ["generate_content", "generate_audio", "merge_audio", "generate_video", "merge_video"]
}
```

WebSocket 事件: `batch_generation_progress` - 实时推送生成进度 `{ taskId, step, progress }`

### OPT-12: 意见反馈

| 方法 | 路径 | 描述 |
|------|------|------|
| POST | /api/feedback | 提交反馈 |

Request:
```json
{
  "type": "suggestion|bug|other",
  "title": "string",
  "content": "string",
  "contact": "string",
  "screenshotUrls": ["string"]
}
```

Response:
```json
{
  "id": "string",
  "status": "submitted"
}
```

### OPT-17: 歌词时间轴

LRC 格式时间戳由 TTS 服务生成，API 响应中新增 `lrcLyrics` 字段：

```json
{
  "audioUrl": "string",
  "duration": 180,
  "lrcLyrics": "[00:00.00] 第一句歌词\n[00:03.50] 第二句歌词"
}
```

---

## WebSocket 事件

### OPT-02: 生成完成推送

| 事件名 | 描述 | 数据 |
|--------|------|------|
| audio_generation_complete | 音频生成完成 | `{ bookId, chapterId, status }` |
| video_generation_complete | 视频生成完成 | `{ bookId, chapterId, status }` |
| batch_generation_progress | 批量生成进度 | `{ taskId, step, progress }` |