acf549c43c
- 实现基于 Laravel 11 和 Filament 3.X 的文档管理系统 - 添加用户认证和分组管理功能 - 实现文档上传、分类和权限控制 - 集成 Word 文档自动转换为 Markdown - 集成 Meilisearch 全文搜索引擎 - 实现文档在线预览功能 - 添加安全日志和审计功能 - 完整的简体中文界面 - 包含完整的项目文档和部署指南 技术栈: - Laravel 11.x - Filament 3.X - Meilisearch 1.5+ - Pandoc 文档转换 - Redis 队列系统 - Pest PHP 测试框架
147 lines
3.5 KiB
Markdown
147 lines
3.5 KiB
Markdown
# 文档预览功能使用指南
|
||
|
||
## 功能概述
|
||
|
||
知识库系统现在支持在线预览 Word 文档（.doc 和 .docx 格式）。用户可以在文档查看页面直接查看文档内容，无需下载。
|
||
|
||
## 技术实现
|
||
|
||
### 核心组件
|
||
|
||
1. **DocumentPreviewService** (`app/Services/DocumentPreviewService.php`)
|
||
- 负责将 Word 文档转换为 HTML 格式
|
||
- 使用 PHPWord 库进行文档解析
|
||
- 提供文档预览能力检查
|
||
|
||
2. **ViewDocument 页面** (`app/Filament/Resources/DocumentResource/Pages/ViewDocument.php`)
|
||
- 使用 Filament Infolist 显示文档信息
|
||
- 集成文档预览组件
|
||
- 提供下载按钮
|
||
|
||
3. **预览视图** (`resources/views/filament/resources/document/preview.blade.php`)
|
||
- 渲染文档预览 HTML
|
||
- 处理错误和不支持的格式
|
||
- 提供友好的用户界面
|
||
|
||
### 依赖库
|
||
|
||
- **phpoffice/phpword**: 用于读取和转换 Word 文档
|
||
|
||
## 功能特性
|
||
|
||
### 1. 文档信息展示
|
||
|
||
在查看页面顶部显示：
|
||
- 文档标题
|
||
- 文档描述
|
||
- 文档类型（全局/专用知识库）
|
||
- 所属分组（专用文档）
|
||
- 上传者
|
||
- 文件名
|
||
- 文件大小
|
||
- 上传时间
|
||
- 更新时间
|
||
|
||
### 2. 文档预览
|
||
|
||
- **支持格式**: .doc, .docx
|
||
- **预览内容**:
|
||
- 文本内容
|
||
- 基本格式（标题、段落、列表等）
|
||
- 表格
|
||
- 图片（如果有）
|
||
- **最大高度**: 600px，超出部分可滚动查看
|
||
|
||
### 3. 错误处理
|
||
|
||
系统会优雅地处理以下情况：
|
||
- 文档文件不存在
|
||
- 文档格式不支持预览
|
||
- 文档转换失败
|
||
|
||
### 4. 下载功能
|
||
|
||
- 在页面顶部提供"下载文档"按钮
|
||
- 自动记录下载日志
|
||
- 验证用户权限
|
||
|
||
## 使用方法
|
||
|
||
### 查看文档
|
||
|
||
1. 登录系统
|
||
2. 进入"文档管理"
|
||
3. 点击任意文档的"查看"按钮
|
||
4. 系统会自动显示文档信息和预览
|
||
|
||
### 下载文档
|
||
|
||
1. 在文档查看页面
|
||
2. 点击顶部的"下载文档"按钮
|
||
3. 文档会自动下载到本地
|
||
|
||
## API 方法
|
||
|
||
### DocumentPreviewService
|
||
|
||
```php
|
||
// 检查文档是否可以预览
|
||
$canPreview = $previewService->canPreview($document);
|
||
|
||
// 将文档转换为 HTML
|
||
$htmlContent = $previewService->convertToHtml($document);
|
||
|
||
// 提取文档纯文本（用于搜索等）
|
||
$text = $previewService->extractText($document);
|
||
```
|
||
|
||
## 性能考虑
|
||
|
||
1. **首次加载**: 文档转换可能需要几秒钟，取决于文档大小和复杂度
|
||
2. **缓存**: 目前未实现缓存，每次查看都会重新转换
|
||
3. **大文件**: 建议对大文件（>10MB）提示用户下载查看
|
||
|
||
## 未来改进
|
||
|
||
1. **缓存机制**: 缓存转换后的 HTML，提高加载速度
|
||
2. **更多格式**: 支持 PDF、Excel 等格式
|
||
3. **全文搜索**: 利用提取的文本内容实现全文搜索
|
||
4. **在线编辑**: 支持在线编辑文档内容
|
||
5. **版本控制**: 支持文档版本管理
|
||
|
||
## 故障排除
|
||
|
||
### 预览失败
|
||
|
||
如果预览失败，可能的原因：
|
||
1. 文档文件损坏
|
||
2. 文档格式不标准
|
||
3. PHPWord 库不支持某些特殊格式
|
||
|
||
解决方法：
|
||
- 检查文档是否可以在本地打开
|
||
- 尝试重新上传文档
|
||
- 使用下载功能获取原始文档
|
||
|
||
### 格式显示异常
|
||
|
||
预览版本可能与原始格式略有差异，这是正常现象。如需查看完整格式，请下载文档。
|
||
|
||
## 安全考虑
|
||
|
||
1. **权限验证**: 只有有权限的用户才能查看文档
|
||
2. **文件隔离**: 文档存储在私有目录，不能直接访问
|
||
3. **XSS 防护**: HTML 内容经过清理，防止 XSS 攻击
|
||
|
||
## 测试
|
||
|
||
运行测试：
|
||
```bash
|
||
php artisan test --filter=DocumentPreviewServiceTest
|
||
```
|
||
|
||
测试覆盖：
|
||
- 文档格式检查
|
||
- 文档不存在时的错误处理
|
||
- HTML 转换功能
|