012-kaopeilian/frontend/课程资料预览功能测试指南.md

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

功能概述

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

测试前准备

1. 重新构建后端Docker镜像

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

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

预期返回：

{
  "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. 获取课程资料列表

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

2. 获取资料预览信息

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

预期返回示例（PDF）：

{
  "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转换）：

{
  "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. 手动测试转换命令：

   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. 支持文件批量下载