feat: 初始化知识库系统项目
- 实现基于 Laravel 11 和 Filament 3.X 的文档管理系统 - 添加用户认证和分组管理功能 - 实现文档上传、分类和权限控制 - 集成 Word 文档自动转换为 Markdown - 集成 Meilisearch 全文搜索引擎 - 实现文档在线预览功能 - 添加安全日志和审计功能 - 完整的简体中文界面 - 包含完整的项目文档和部署指南 技术栈: - Laravel 11.x - Filament 3.X - Meilisearch 1.5+ - Pandoc 文档转换 - Redis 队列系统 - Pest PHP 测试框架
This commit is contained in:
Knowledge Base System
146
docs/DOCUMENT_PREVIEW_GUIDE.md
Normal file
146
docs/DOCUMENT_PREVIEW_GUIDE.md
Normal file
@@ -0,0 +1,146 @@
|
||||
# 文档预览功能使用指南
|
||||
|
||||
## 功能概述
|
||||
|
||||
知识库系统现在支持在线预览 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 转换功能
|
||||
Reference in New Issue
Block a user