feat: 初始化考培练系统项目
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
This commit is contained in:
111
265
frontend/课程资料预览功能测试指南.md
Normal file
265
frontend/课程资料预览功能测试指南.md
Normal file
@@ -0,0 +1,265 @@
|
||||
# 课程资料预览功能测试指南
|
||||
|
||||
## 功能概述
|
||||
|
||||
本次实现了课程学习页面的资料在线预览功能，支持多种文件格式的在线查看。
|
||||
|
||||
## 测试前准备
|
||||
|
||||
### 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. 支持文件批量下载
|
||||
|
||||
Reference in New Issue
Block a user