Files

- 从服务器拉取完整代码
- 按框架规范整理项目结构
- 配置 Drone CI 测试环境部署
- 包含后端(FastAPI)、前端(Vue3)、管理端

技术栈: Vue3 + TypeScript + FastAPI + MySQL

2026-01-24 19:33:28 +08:00

9.3 KiB

Raw Blame History

课程资料预览功能 - 实施完成报告

实施日期：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

实现的接口：

GET /api/v1/preview/material/{material_id} - 获取资料预览信息
- 根据文件类型返回合适的预览方式
- 自动触发Office文档转换
- 返回preview_type、preview_url等信息
GET /api/v1/preview/check-converter - 检查转换服务状态
- 用于调试LibreOffice是否正确安装
- 返回安装状态、版本信息、支持格式

✅ Docker配置更新

文件：kaopeilian-backend/Dockerfile

在后端容器中添加了LibreOffice安装：

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 转换缓存策略

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镜像

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

验证LibreOffice安装
```
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 使用启动脚本（推荐）

# 进入项目根目录
cd /Users/nongjun/Desktop/Ai公司/本地开发与测试

# 运行启动脚本
./启动资料预览功能.sh

等待5-10分钟（首次构建LibreOffice镜像较慢）

5.2 手动启动

# 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 验证安装

# 运行测试脚本
./测试资料预览功能.sh

或手动测试：

# 检查后端服务
curl http://localhost:8000/health

# 检查LibreOffice
curl http://localhost:8000/api/v1/preview/check-converter

# 获取课程资料
curl http://localhost:8000/api/v1/courses/1/materials

六、已知限制

文件大小限制：当前设置为15MB
转换超时：单个文件转换超时60秒
支持格式：仅支持常见的Office文档格式
并发转换：未做并发限制，可能影响服务器性能
权限检查：TODO标记，需要实现用户权限验证

七、后续优化建议

短期优化

添加转换进度实时提示
实现用户权限检查
优化大文件加载体验
添加转换任务队列

长期优化

支持Markdown渲染预览
支持代码文件语法高亮
添加文件预览历史记录
支持批量下载
添加文件注释和标记功能

八、联系与支持

如遇到问题，请查看：

测试指南：kaopeilian-frontend/课程资料预览功能测试指南.md
联调经验：考培练系统规划/全链路联调/联调经验汇总.md
规范约定：考培练系统规划/全链路联调/规范与约定-团队基线.md

报告生成时间：2025-10-14
实施人员：AI Assistant
审核状态：待测试验证

9.3 KiB Raw Blame History Unescape Escape