998211c483
- 从服务器拉取完整代码 - 按框架规范整理项目结构 - 配置 Drone CI 测试环境部署 - 包含后端(FastAPI)、前端(Vue3)、管理端 技术栈: Vue3 + TypeScript + FastAPI + MySQL
378 lines
9.3 KiB
Markdown
378 lines
9.3 KiB
Markdown
# 课程资料预览功能 - 实施完成报告
|
||
|
||
**实施日期**：2025-10-14
|
||
**实施状态**：代码实现完成，待测试验证
|
||
|
||
---
|
||
|
||
## 一、功能概述
|
||
|
||
实现了课程学习页面的资料在线预览功能，支持多种文件格式的查看：
|
||
- 左侧：课程资料文件列表（支持搜索和筛选）
|
||
- 右侧：根据文件类型实现不同的预览方式
|
||
|
||
### 支持的文件格式
|
||
|
||
| 类型 | 格式 | 预览方式 |
|
||
|------|------|----------|
|
||
| PDF | .pdf | iframe嵌入预览 |
|
||
| Office文档 | .docx, .doc, .pptx, .ppt, .xlsx, .xls | 转换为PDF后预览 |
|
||
| 视频 | .mp4, .avi, .mov, .wmv | HTML5 video播放器 |
|
||
| 音频 | .mp3, .wav, .ogg, .m4a | HTML5 audio播放器 |
|
||
| 图片 | .jpg, .jpeg, .png, .gif | 图片查看器（支持放大） |
|
||
| 文本 | .txt, .md | 直接显示内容 |
|
||
| 其他 | .zip等 | 提供下载 |
|
||
|
||
---
|
||
|
||
## 二、已完成的工作
|
||
|
||
### 2.1 后端开发
|
||
|
||
#### ✅ 文档转换服务
|
||
**文件**：`kaopeilian-backend/app/services/document_converter.py`
|
||
|
||
- 使用LibreOffice命令行将Office文档转换为PDF
|
||
- 支持docx、doc、pptx、ppt、xlsx、xls格式
|
||
- 实现转换缓存机制（检查文件修改时间）
|
||
- 转换超时设置：60秒
|
||
- 转换文件存储：`/uploads/converted/{course_id}/{material_id}.pdf`
|
||
|
||
#### ✅ 预览API接口
|
||
**文件**：`kaopeilian-backend/app/api/v1/preview.py`
|
||
|
||
实现的接口：
|
||
1. `GET /api/v1/preview/material/{material_id}` - 获取资料预览信息
|
||
- 根据文件类型返回合适的预览方式
|
||
- 自动触发Office文档转换
|
||
- 返回preview_type、preview_url等信息
|
||
|
||
2. `GET /api/v1/preview/check-converter` - 检查转换服务状态
|
||
- 用于调试LibreOffice是否正确安装
|
||
- 返回安装状态、版本信息、支持格式
|
||
|
||
#### ✅ Docker配置更新
|
||
**文件**：`kaopeilian-backend/Dockerfile`
|
||
|
||
在后端容器中添加了LibreOffice安装：
|
||
```dockerfile
|
||
RUN apt-get update && apt-get install -y \
|
||
libreoffice-writer \
|
||
libreoffice-impress \
|
||
libreoffice-calc \
|
||
libreoffice-core \
|
||
--no-install-recommends \
|
||
&& rm -rf /var/lib/apt/lists/*
|
||
```
|
||
|
||
#### ✅ API路由注册
|
||
**文件**：`kaopeilian-backend/app/api/v1/__init__.py`
|
||
|
||
注册了preview路由到主API路由器
|
||
|
||
### 2.2 前端开发
|
||
|
||
#### ✅ 类型定义
|
||
**文件**：`kaopeilian-frontend/src/types/material.ts`
|
||
|
||
定义的类型：
|
||
- `Material` - 课程资料信息
|
||
- `PreviewInfo` - 预览信息
|
||
- `PreviewType` - 预览类型枚举
|
||
|
||
工具函数：
|
||
- `formatFileSize` - 文件大小格式化
|
||
- `getFileCategory` - 文件分类判断
|
||
- `getFileExtension` - 获取文件扩展名
|
||
- `getFileTypeIcon` - 获取文件类型图标
|
||
|
||
#### ✅ API封装
|
||
**文件**：`kaopeilian-frontend/src/api/material.ts`
|
||
|
||
封装的API方法：
|
||
- `getMaterials` - 获取课程资料列表
|
||
- `getPreview` - 获取资料预览信息
|
||
- `downloadFile` - 下载文件
|
||
- `checkConverterStatus` - 检查转换服务状态（调试用）
|
||
|
||
#### ✅ 课程详情页重构
|
||
**文件**：`kaopeilian-frontend/src/views/trainee/course-detail.vue`
|
||
|
||
实现的功能：
|
||
- **左侧资料列表**：
|
||
- 显示文件名、大小、类型
|
||
- 支持关键词搜索
|
||
- 支持按类型筛选（全部/文档/视频/音频/图片）
|
||
- 点击选中高亮
|
||
|
||
- **右侧预览区域**：
|
||
- PDF：iframe嵌入预览
|
||
- 视频：HTML5 video标签，支持播放控制
|
||
- 音频：HTML5 audio标签，支持播放控制
|
||
- 图片：el-image组件，支持放大查看
|
||
- 文本：pre标签显示内容
|
||
- Office文档：显示转换中提示，完成后显示PDF
|
||
- 其他格式：显示下载界面
|
||
|
||
- **工具栏**：
|
||
- 下载按钮：下载当前文件
|
||
- 全屏按钮：PDF/视频/图片支持全屏查看
|
||
|
||
### 2.3 文档更新
|
||
|
||
#### ✅ 测试指南
|
||
**文件**：`kaopeilian-frontend/课程资料预览功能测试指南.md`
|
||
|
||
包含内容：
|
||
- 测试前准备（Docker镜像重建）
|
||
- 详细的功能测试步骤
|
||
- API接口测试方法
|
||
- 性能测试建议
|
||
- 常见问题排查
|
||
- 预期效果说明
|
||
|
||
#### ✅ 联调经验汇总
|
||
**文件**：`考培练系统规划/全链路联调/联调经验汇总.md`
|
||
|
||
新增章节：
|
||
- 需求背景和核心策略
|
||
- 详细的变更内容
|
||
- 核心设计决策
|
||
- 技术亮点
|
||
- 验证结果
|
||
- 核心问题与解决方案
|
||
- 经验沉淀
|
||
- 后续优化方向
|
||
|
||
#### ✅ 规范与约定
|
||
**文件**：`考培练系统规划/全链路联调/规范与约定-团队基线.md`
|
||
|
||
新增规范：
|
||
- 文件类型与预览方式映射
|
||
- 文档转换服务规范
|
||
- API接口规范
|
||
- 前端实现规范
|
||
- Docker环境配置
|
||
- 性能优化建议
|
||
- 安全注意事项
|
||
|
||
#### ✅ 启动脚本
|
||
**文件**：`启动资料预览功能.sh`
|
||
|
||
自动化脚本功能：
|
||
- 停止现有服务
|
||
- 重建后端Docker镜像
|
||
- 启动所有服务
|
||
- 显示服务信息和测试建议
|
||
|
||
#### ✅ 测试脚本
|
||
**文件**：`测试资料预览功能.sh`
|
||
|
||
快速测试功能：
|
||
- 检查后端服务状态
|
||
- 检查LibreOffice安装
|
||
- 获取课程资料列表
|
||
- 测试预览接口
|
||
|
||
---
|
||
|
||
## 三、技术架构
|
||
|
||
### 3.1 核心技术栈
|
||
|
||
**后端**：
|
||
- FastAPI - Web框架
|
||
- LibreOffice - 文档转换工具
|
||
- Python Subprocess - 执行系统命令
|
||
|
||
**前端**：
|
||
- Vue 3 - 框架
|
||
- TypeScript - 类型系统
|
||
- Element Plus - UI组件库
|
||
- HTML5 - video/audio标签
|
||
|
||
### 3.2 文件流转流程
|
||
|
||
```
|
||
1. 用户上传 Office 文档
|
||
↓
|
||
2. 保存到 /uploads/courses/{course_id}/
|
||
↓
|
||
3. 用户点击预览
|
||
↓
|
||
4. 前端调用 /api/v1/preview/material/{id}
|
||
↓
|
||
5. 后端判断文件类型
|
||
↓
|
||
6. 如果是Office文档：
|
||
- 检查缓存 /uploads/converted/{course_id}/{material_id}.pdf
|
||
- 如果缓存不存在或过期，执行转换
|
||
- 返回转换后的PDF URL
|
||
↓
|
||
7. 如果是其他类型：
|
||
- 直接返回原始文件URL
|
||
↓
|
||
8. 前端根据preview_type渲染对应组件
|
||
```
|
||
|
||
### 3.3 转换缓存策略
|
||
|
||
```python
|
||
def need_convert(source_file, converted_file):
|
||
# 缓存不存在 → 需要转换
|
||
if not converted_file.exists():
|
||
return True
|
||
|
||
# 源文件修改时间 > 缓存修改时间 → 需要重新转换
|
||
if source_file.stat().st_mtime > converted_file.stat().st_mtime:
|
||
return True
|
||
|
||
# 缓存有效
|
||
return False
|
||
```
|
||
|
||
---
|
||
|
||
## 四、待完成的工作
|
||
|
||
### 4.1 立即执行（必需）
|
||
|
||
- [ ] **重建Docker镜像**
|
||
```bash
|
||
cd kaopeilian-backend
|
||
docker-compose -f docker-compose.dev.yml build backend
|
||
docker-compose -f docker-compose.dev.yml up -d
|
||
```
|
||
|
||
- [ ] **验证LibreOffice安装**
|
||
```bash
|
||
curl http://localhost:8000/api/v1/preview/check-converter
|
||
```
|
||
预期返回：`"libreoffice_installed": true`
|
||
|
||
### 4.2 功能测试（必需）
|
||
|
||
- [ ] 上传各种格式的测试文件到课程中
|
||
- [ ] 访问课程详情页：`http://localhost:3001/trainee/course-detail?id=1`
|
||
- [ ] 测试PDF文件预览
|
||
- [ ] 测试Office文档转换预览（docx、pptx、xlsx）
|
||
- [ ] 测试视频文件播放
|
||
- [ ] 测试音频文件播放
|
||
- [ ] 测试图片文件查看
|
||
- [ ] 测试文本文件显示
|
||
- [ ] 测试搜索功能
|
||
- [ ] 测试类型筛选功能
|
||
- [ ] 测试下载功能
|
||
- [ ] 测试全屏功能
|
||
|
||
### 4.3 性能测试（建议）
|
||
|
||
- [ ] 测试5MB Office文档转换时间
|
||
- [ ] 测试转换缓存是否生效
|
||
- [ ] 测试并发转换请求
|
||
|
||
### 4.4 错误场景测试（建议）
|
||
|
||
- [ ] 测试不存在的文件ID
|
||
- [ ] 测试损坏的Office文档
|
||
- [ ] 测试不支持的文件格式
|
||
- [ ] 测试超大文件（>15MB）
|
||
|
||
---
|
||
|
||
## 五、快速启动指南
|
||
|
||
### 5.1 使用启动脚本（推荐）
|
||
|
||
```bash
|
||
# 进入项目根目录
|
||
cd /Users/nongjun/Desktop/Ai公司/本地开发与测试
|
||
|
||
# 运行启动脚本
|
||
./启动资料预览功能.sh
|
||
```
|
||
|
||
等待5-10分钟（首次构建LibreOffice镜像较慢）
|
||
|
||
### 5.2 手动启动
|
||
|
||
```bash
|
||
# 1. 进入后端目录
|
||
cd kaopeilian-backend
|
||
|
||
# 2. 停止现有服务
|
||
docker-compose -f docker-compose.dev.yml down
|
||
|
||
# 3. 重建镜像
|
||
docker-compose -f docker-compose.dev.yml build backend
|
||
|
||
# 4. 启动服务
|
||
docker-compose -f docker-compose.dev.yml up -d
|
||
|
||
# 5. 查看日志
|
||
docker-compose -f docker-compose.dev.yml logs -f backend
|
||
```
|
||
|
||
### 5.3 验证安装
|
||
|
||
```bash
|
||
# 运行测试脚本
|
||
./测试资料预览功能.sh
|
||
```
|
||
|
||
或手动测试：
|
||
|
||
```bash
|
||
# 检查后端服务
|
||
curl http://localhost:8000/health
|
||
|
||
# 检查LibreOffice
|
||
curl http://localhost:8000/api/v1/preview/check-converter
|
||
|
||
# 获取课程资料
|
||
curl http://localhost:8000/api/v1/courses/1/materials
|
||
```
|
||
|
||
---
|
||
|
||
## 六、已知限制
|
||
|
||
1. **文件大小限制**：当前设置为15MB
|
||
2. **转换超时**：单个文件转换超时60秒
|
||
3. **支持格式**：仅支持常见的Office文档格式
|
||
4. **并发转换**：未做并发限制，可能影响服务器性能
|
||
5. **权限检查**：TODO标记，需要实现用户权限验证
|
||
|
||
---
|
||
|
||
## 七、后续优化建议
|
||
|
||
### 短期优化
|
||
1. 添加转换进度实时提示
|
||
2. 实现用户权限检查
|
||
3. 优化大文件加载体验
|
||
4. 添加转换任务队列
|
||
|
||
### 长期优化
|
||
1. 支持Markdown渲染预览
|
||
2. 支持代码文件语法高亮
|
||
3. 添加文件预览历史记录
|
||
4. 支持批量下载
|
||
5. 添加文件注释和标记功能
|
||
|
||
---
|
||
|
||
## 八、联系与支持
|
||
|
||
如遇到问题，请查看：
|
||
1. **测试指南**：`kaopeilian-frontend/课程资料预览功能测试指南.md`
|
||
2. **联调经验**：`考培练系统规划/全链路联调/联调经验汇总.md`
|
||
3. **规范约定**：`考培练系统规划/全链路联调/规范与约定-团队基线.md`
|
||
|
||
---
|
||
|
||
**报告生成时间**：2025-10-14
|
||
**实施人员**：AI Assistant
|
||
**审核状态**：待测试验证
|
||
|