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

**实施日期**：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  
**审核状态**：待测试验证