# 文档预览功能使用指南

## 功能概述

知识库系统现在支持在线预览 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 转换功能