# 课程资料预览功能测试指南

## 功能概述

本次实现了课程学习页面的资料在线预览功能，支持多种文件格式的在线查看。

## 测试前准备

### 1. 重新构建后端Docker镜像

由于在Dockerfile中添加了LibreOffice，需要重新构建镜像：

```bash
cd kaopeilian-backend
docker-compose -f docker-compose.dev.yml build backend
docker-compose -f docker-compose.dev.yml up -d
```

### 2. 检查LibreOffice是否安装成功

访问调试接口：
```
GET http://localhost:8000/api/v1/preview/check-converter
```

预期返回：
```json
{
  "code": 200,
  "message": "转换服务状态检查完成",
  "data": {
    "libreoffice_installed": true,
    "libreoffice_version": "LibreOffice 版本信息",
    "supported_formats": [".docx", ".doc", ".pptx", ".ppt", ".xlsx", ".xls"],
    "converted_path": "/app/uploads/converted"
  }
}
```

## 测试步骤

### 1. 准备测试数据

为课程上传不同类型的测试文件：
- PDF文件（如：课程讲义.pdf）
- Word文档（如：学习资料.docx）
- PPT演示文稿（如：培训课件.pptx）
- Excel表格（如：数据表.xlsx）
- 视频文件（如：教学视频.mp4）
- 音频文件（如：课程音频.mp3）
- 图片文件（如：示意图.jpg）
- 文本文件（如：说明.txt）

### 2. 访问课程详情页

访问：`http://localhost:3001/trainee/course-detail?id=1`

### 3. 测试资料列表

**测试点：**
- [ ] 左侧资料列表正确显示所有已上传的文件
- [ ] 文件图标根据类型正确显示
- [ ] 文件大小正确显示
- [ ] 文件类型标签正确显示

**测试搜索功能：**
- [ ] 在搜索框输入关键词，列表正确筛选
- [ ] 清空搜索框，列表恢复显示全部

**测试类型筛选：**
- [ ] 点击"文档"按钮，只显示文档类文件
- [ ] 点击"视频"按钮，只显示视频文件
- [ ] 点击"音频"按钮，只显示音频文件
- [ ] 点击"图片"按钮，只显示图片文件
- [ ] 点击"全部"按钮，显示所有文件

### 4. 测试文件预览

#### PDF文件预览
- [ ] 点击PDF文件，右侧显示PDF预览
- [ ] PDF内容正确显示
- [ ] 可以使用浏览器内置的PDF阅读器功能（翻页、缩放等）

#### Office文档预览（重点测试）
- [ ] 点击docx文件，显示"正在转换文档"提示
- [ ] 转换完成后显示PDF预览
- [ ] 再次点击同一文件，直接显示PDF（缓存生效）
- [ ] 测试pptx文件转换预览
- [ ] 测试xlsx文件转换预览

#### 视频文件预览
- [ ] 点击mp4文件，显示视频播放器
- [ ] 视频可以正常播放
- [ ] 播放控件正常工作（播放/暂停、进度条、音量等）

#### 音频文件预览
- [ ] 点击mp3文件，显示音频播放器
- [ ] 音频可以正常播放
- [ ] 播放控件正常工作

#### 图片文件预览
- [ ] 点击jpg/png文件，显示图片
- [ ] 图片清晰显示
- [ ] 可以点击图片放大查看

#### 文本文件预览
- [ ] 点击txt文件，显示文本内容
- [ ] 文本内容正确显示，格式保持

### 5. 测试工具栏功能

- [ ] 点击"下载"按钮，文件正常下载
- [ ] 点击"全屏"按钮（PDF/视频/图片），进入全屏模式
- [ ] 按ESC键退出全屏

### 6. 测试异常情况

**文件不存在：**
- [ ] 删除某个文件的物理文件，点击后显示错误提示

**不支持的格式：**
- [ ] 上传zip等不支持预览的格式
- [ ] 点击后显示"此文件暂不支持在线预览"，提供下载按钮

**转换失败：**
- [ ] 上传损坏的docx文件
- [ ] 点击后转换失败，自动切换到下载模式

## API测试

### 1. 获取课程资料列表

```bash
curl -X GET "http://localhost:8000/api/v1/courses/1/materials" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 2. 获取资料预览信息

```bash
curl -X GET "http://localhost:8000/api/v1/preview/material/1" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

预期返回示例（PDF）：
```json
{
  "code": 200,
  "message": "获取预览信息成功",
  "data": {
    "preview_type": "pdf",
    "preview_url": "/static/uploads/courses/1/xxx.pdf",
    "file_name": "课程讲义.pdf",
    "original_url": "/static/uploads/courses/1/xxx.pdf",
    "file_size": 1024000
  }
}
```

预期返回示例（Word转换）：
```json
{
  "code": 200,
  "message": "获取预览信息成功",
  "data": {
    "preview_type": "pdf",
    "preview_url": "/static/uploads/converted/1/1.pdf",
    "file_name": "学习资料.docx",
    "original_url": "/static/uploads/courses/1/xxx.docx",
    "file_size": 2048000,
    "is_converted": true
  }
}
```

## 性能测试

### 转换性能
- [ ] 测试1MB的docx文件转换时间（应在5秒内）
- [ ] 测试5MB的pptx文件转换时间（应在10秒内）
- [ ] 测试缓存命中率（第二次访问应直接返回）

### 并发测试
- [ ] 同时请求3个不同Office文档的转换
- [ ] 观察服务器CPU和内存使用情况

## 常见问题排查

### LibreOffice未安装
**症状：** 调试接口返回 `libreoffice_installed: false`

**解决：**
1. 检查Dockerfile是否正确添加了LibreOffice安装命令
2. 重新构建Docker镜像
3. 检查容器日志：`docker logs <container_id>`

### 文档转换失败
**症状：** 转换后找不到PDF文件

**排查：**
1. 检查后端日志：`docker logs kaopeilian-backend`
2. 检查转换目录权限：`ls -la /app/uploads/converted`
3. 手动测试转换命令：
   ```bash
   docker exec -it kaopeilian-backend bash
   libreoffice --headless --convert-to pdf --outdir /tmp /path/to/test.docx
   ```

### 前端无法显示预览
**症状：** 点击文件后一直loading

**排查：**
1. 打开浏览器开发者工具，查看Network标签
2. 检查API请求是否成功
3. 检查返回的URL是否正确
4. 检查CORS配置

### 文件下载失败
**症状：** 点击下载按钮没有反应

**排查：**
1. 检查文件URL是否正确
2. 检查静态文件服务配置
3. 检查文件是否存在

## 预期效果截图位置

测试完成后，请将以下场景的截图保存到：
`/考培练系统规划/全链路联调/Ai工作流/截图/课程资料预览/`

- 资料列表展示
- PDF文件预览
- Word文档转换后预览
- 视频播放
- 音频播放
- 图片预览
- 文本预览
- 下载模式

## 测试完成标准

- [ ] 所有文件类型都能正确预览或下载
- [ ] Office文档转换功能正常
- [ ] 转换缓存机制生效
- [ ] 界面交互流畅，无明显卡顿
- [ ] 没有JavaScript错误
- [ ] 没有404或500错误
- [ ] 移动端响应式布局正常

## 注意事项

1. **首次转换会比较慢**：LibreOffice启动需要时间，首次转换可能需要10-30秒
2. **缓存目录**：转换后的PDF文件会保存在 `/uploads/converted/{course_id}/` 目录
3. **文件大小限制**：当前设置为15MB，超过此大小的文件无法上传
4. **支持的格式**：详见后端 `ALLOWED_EXTENSIONS` 配置

## 后续优化建议

1. 添加转换进度提示
2. 支持更多文件格式（如Markdown渲染）
3. 添加文件预览的快捷键操作
4. 优化大文件的加载体验
5. 添加文件预览的历史记录
6. 支持文件批量下载