# 听书模块功能说明

## 一、功能概述

已实现完整的听书模块前后端功能，包括：
1. 听书列表展示（最近上新、热门听书、推荐听书、畅听榜）
2. 听书详情展示（包含章节列表）
3. 音频播放功能（播放、暂停、快进、快退、进度保存）
4. 听书历史记录
5. 听书进度保存和恢复

## 二、数据库设计

### 1. 听书专辑表 (audiobooks)
- 存储听书的基本信息：标题、作者、主播、封面、简介等
- 包含统计信息：章节数、总时长、播放次数、浏览次数、点赞数
- 支持VIP和免费区分

### 2. 听书章节表 (audiobook_chapters)
- 存储每个章节的信息：标题、音频URL、时长、文件大小
- 支持免费和VIP章节区分
- 记录每个章节的播放次数

### 3. 用户听书历史记录表 (user_listening_history)
- 记录用户最后收听的章节
- 用于"最近播放"功能

### 4. 用户听书进度表 (user_listening_progress)
- 记录用户每个章节的播放进度
- 支持断点续播功能

## 三、后端接口

### 1. 听书列表接口
- `GET /api/audiobook/recent?limit=8` - 获取最近上新
- `GET /api/audiobook/popular?limit=10` - 获取热门听书
- `GET /api/audiobook/recommend?limit=10` - 获取推荐听书
- `GET /api/audiobook/ranking?limit=10` - 获取畅听榜

### 2. 听书详情接口
- `GET /api/audiobook/{id}?userId=xxx` - 获取听书详情（包含章节列表）
- `GET /api/audiobook/chapter/{chapterId}` - 获取章节详情

### 3. 播放相关接口
- `POST /api/audiobook/play` - 播放章节（增加播放次数）
- `POST /api/audiobook/history` - 记录听书历史
- `POST /api/audiobook/progress` - 保存听书进度
- `GET /api/audiobook/progress?userId=xxx&chapterId=xxx` - 获取听书进度

## 四、前端页面

### 1. 听书首页 (listen.vue)
- 显示横幅推荐（热门听书）
- 显示分类导航
- 显示最近上新列表
- 显示推荐听书列表
- 所有数据从后端API获取

### 2. 听书详情页 (listen-detail.vue)
- 显示听书基本信息
- 显示章节列表
- 支持播放全部功能
- 支持章节播放
- VIP章节权限检查

### 3. 播放器页面 (player.vue)
- 音频播放控制（播放、暂停）
- 进度条显示和控制
- 快进15秒、快退15秒
- 上一章、下一章（待实现）
- 自动保存播放进度（每30秒）
- 支持断点续播

## 五、使用步骤

### 1. 数据库初始化
执行 `book/src/main/resources/db/audiobook_schema.sql` 创建听书相关表并插入示例数据。

### 2. 后端启动
启动Spring Boot应用，确保数据库连接正常。

### 3. 前端测试
1. 打开听书页面，查看听书列表
2. 点击听书进入详情页，查看章节列表
3. 点击章节播放，进入播放器页面
4. 测试播放、暂停、快进、快退功能
5. 退出播放器后重新进入，测试断点续播功能

## 六、注意事项

1. **音频文件URL**: 示例数据中的音频URL为占位符，实际使用时需要替换为真实的音频文件URL。
2. **VIP权限**: VIP章节需要用户登录且为VIP会员才能播放。
3. **进度保存**: 播放进度每30秒自动保存一次，页面卸载时也会保存。
4. **音频格式**: 确保音频文件格式支持小程序播放（建议使用MP3格式）。
5. **网络请求**: 确保前端API配置正确，后端接口可正常访问。

## 七、后续优化建议

1. 实现上一章、下一章自动切换功能
2. 添加播放倍速调节功能
3. 添加播放列表功能
4. 添加下载功能（离线播放）
5. 添加评论功能
6. 优化音频加载和缓冲
7. 添加播放历史记录页面
8. 添加收藏功能

## 八、文件清单

### 后端文件
- `book/src/main/resources/db/audiobook_schema.sql` - 数据库表结构
- `book/src/main/java/com/yu/book/domain/Audiobook.java` - 听书实体类
- `book/src/main/java/com/yu/book/domain/AudiobookChapter.java` - 章节实体类
- `book/src/main/java/com/yu/book/domain/UserListeningHistory.java` - 历史记录实体类
- `book/src/main/java/com/yu/book/domain/UserListeningProgress.java` - 进度实体类
- `book/src/main/java/com/yu/book/vo/AudiobookVO.java` - 听书VO
- `book/src/main/java/com/yu/book/vo/ChapterVO.java` - 章节VO
- `book/src/main/java/com/yu/book/vo/AudiobookDetailVO.java` - 详情VO
- `book/src/main/java/com/yu/book/mapper/AudiobookMapper.java` - 听书Mapper
- `book/src/main/java/com/yu/book/mapper/ChapterMapper.java` - 章节Mapper
- `book/src/main/java/com/yu/book/mapper/ListeningHistoryMapper.java` - 历史Mapper
- `book/src/main/java/com/yu/book/mapper/ListeningProgressMapper.java` - 进度Mapper
- `book/src/main/resources/mapper/AudiobookMapper.xml` - 听书Mapper XML
- `book/src/main/resources/mapper/ChapterMapper.xml` - 章节Mapper XML
- `book/src/main/resources/mapper/ListeningHistoryMapper.xml` - 历史Mapper XML
- `book/src/main/resources/mapper/ListeningProgressMapper.xml` - 进度Mapper XML
- `book/src/main/java/com/yu/book/service/AudiobookService.java` - 听书服务类
- `book/src/main/java/com/yu/book/controller/AudiobookController.java` - 听书控制器

### 前端文件
- `books/utils/api.js` - 添加了听书相关API方法
- `books/pages/listen/listen.vue` - 听书首页（已连接后端）
- `books/pages/listen-detail/listen-detail.vue` - 听书详情页（已连接后端）
- `books/pages/player/player.vue` - 播放器页面（已实现播放功能）

## 九、API调用示例

### 获取最近上新
```javascript
import { getRecentAudiobooks } from '../../utils/api.js'

const res = await getRecentAudiobooks(8)
if (res && res.code === 200) {
    const audiobooks = res.data
    // 处理听书列表
}
```

### 获取听书详情
```javascript
import { getAudiobookDetail } from '../../utils/api.js'

const res = await getAudiobookDetail(audiobookId, userId)
if (res && res.code === 200) {
    const detail = res.data
    // 处理听书详情和章节列表
}
```

### 保存播放进度
```javascript
import { saveListeningProgress } from '../../utils/api.js'

await saveListeningProgress(userId, audiobookId, chapterId, currentPosition, duration)
```

## 十、测试建议

1. **数据库测试**: 确认表结构正确，数据可以正常插入和查询
2. **接口测试**: 使用Postman或类似工具测试所有接口
3. **前端测试**: 在小程序中测试各个页面的功能
4. **播放测试**: 测试音频播放、进度保存、断点续播等功能
5. **权限测试**: 测试VIP章节的权限控制
6. **性能测试**: 测试大量数据下的列表加载性能