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