KnowledgeBase/docs/PROJECT_OVERVIEW.md

# 知识库系统项目概览

## 项目简介

知识库系统是一个基于 Laravel 11 和 Filament 3.X 构建的企业级文档管理平台。系统支持 Word 文档上传、自动转换为 Markdown 格式、全文搜索、在线预览以及基于用户分组的细粒度权限控制。

## 核心功能

### 1. 文档管理
- **文档上传**：支持 .doc 和 .docx 格式的 Word 文档上传
- **文档分类**：
  - 全局知识库：所有用户可访问
  - 专用知识库：仅特定分组用户可访问
- **文档下载**：支持原始 Word 文档下载，并记录下载日志
- **文档预览**：在线预览 Markdown 渲染后的文档内容

### 2. 自动文档转换
- **异步转换**：使用队列系统异步将 Word 文档转换为 Markdown 格式
- **转换工具**：支持 Pandoc 或 PHPWord 作为转换引擎
- **状态跟踪**：实时跟踪转换状态（pending、processing、completed、failed）
- **错误处理**：转换失败不影响文档的正常使用

### 3. 全文搜索
- **搜索引擎**：集成 Meilisearch 提供快速的全文搜索
- **搜索范围**：支持搜索文档标题、描述和 Markdown 内容
- **权限过滤**：搜索结果自动过滤，只显示用户有权访问的文档
- **高级筛选**：支持按文档类型、分组等条件筛选

### 4. 权限控制
- **用户分组**：用户可以属于多个分组
- **访问控制**：
  - 全局文档：所有用户可访问
  - 专用文档：只有所属分组的用户可访问
- **权限验证**：在数据查询、下载、预览等操作中强制执行权限检查
- **安全日志**：记录所有未授权访问尝试

### 5. 用户界面
- **中文界面**：完整的简体中文用户界面
- **管理面板**：基于 Filament 3.X 的现代化管理界面
- **响应式设计**：支持桌面和移动设备访问

## 技术栈

### 后端
- **框架**：Laravel 11.x
- **管理面板**：Filament 3.X
- **数据库**：MySQL 8.0+ / PostgreSQL 13+
- **搜索引擎**：Meilisearch 1.5+
- **队列系统**：Redis Queue
- **文档转换**：Pandoc 2.x+ 或 PHPWord

### 前端
- **模板引擎**：Laravel Blade
- **CSS 框架**：Tailwind CSS 3.x
- **JavaScript**：Alpine.js 3.x（Filament 内置）

### 开发工具
- **包管理**：Composer 2.x, npm
- **测试框架**：Pest PHP
- **代码质量**：PHPStan, Laravel Pint

## 项目结构

```
knowledge-base-system/
├── app/
│   ├── Filament/           # Filament 资源和页面
│   │   ├── Pages/          # 自定义页面（搜索页面）
│   │   └── Resources/      # 资源管理（文档、分组、用户）
│   ├── Http/
│   │   └── Controllers/    # 控制器（文档预览）
│   ├── Jobs/               # 队列任务（文档转换）
│   ├── Models/             # Eloquent 模型
│   ├── Observers/          # 模型观察者（文档索引）
│   ├── Policies/           # 授权策略
│   └── Services/           # 业务逻辑服务
├── config/
│   ├── documents.php       # 文档转换配置
│   ├── filesystems.php     # 文件存储配置
│   └── scout.php           # Meilisearch 配置
├── database/
│   ├── factories/          # 测试数据工厂
│   ├── migrations/         # 数据库迁移
│   └── seeders/            # 数据填充
├── docs/                   # 项目文档
├── resources/
│   └── views/              # Blade 视图模板
├── storage/
│   └── app/
│       └── private/
│           ├── documents/  # 原始 Word 文档存储
│           └── markdown/   # Markdown 文件存储
├── tests/                  # 测试文件
└── .kiro/
    └── specs/              # 功能规格文档
```

## 数据模型

### 核心实体

1. **User（用户）**
   - 系统用户
   - 可属于多个分组
   - 可上传文档

2. **Group（分组）**
   - 用户组织单位
   - 拥有专用知识库文档
   - 管理成员访问权限

3. **Document（文档）**
   - 文档记录
   - 包含原始文件和 Markdown 内容
   - 关联分组和上传者

4. **DownloadLog（下载日志）**
   - 记录文档下载历史
   - 用于审计和统计

### 关系图

```
User ──┬── uploads ──> Document
       └── belongs_to ──> Group ──> owns ──> Document
                                              │
                                              └── has ──> DownloadLog
```

## 已实现功能清单

### ✅ 核心功能
- [x] 用户认证和授权
- [x] 用户分组管理
- [x] 文档上传和存储
- [x] 文档分类（全局/专用）
- [x] 基于分组的权限控制
- [x] 文档下载和日志记录
- [x] 文档搜索和筛选

### ✅ 高级功能
- [x] Word 文档自动转换为 Markdown
- [x] 异步队列处理转换任务
- [x] Meilisearch 全文搜索集成
- [x] 文档 Markdown 在线预览
- [x] 搜索结果权限过滤
- [x] 安全日志记录

### ✅ 用户界面
- [x] Filament 管理面板
- [x] 完整中文界面
- [x] 文档管理界面
- [x] 分组管理界面
- [x] 用户管理界面
- [x] 搜索页面
- [x] 预览页面

### ⏳ 待完成功能
- [ ] 属性基础测试（Property-Based Testing）
- [ ] 完整的功能测试套件
- [ ] 性能优化（缓存、索引优化）
- [ ] UI 增强（Alpine.js 动画和交互）
- [ ] 部署文档和脚本

## 快速开始

### 环境要求
- PHP 8.1+
- Composer 2.x
- Node.js 18+
- MySQL 8.0+ 或 PostgreSQL 13+
- Redis 6.0+
- Meilisearch 1.5+
- Pandoc 2.x+（可选）

### 安装步骤

1. **克隆项目**
```bash
git clone <repository-url>
cd knowledge-base-system
```

2. **安装依赖**
```bash
composer install
npm install
```

3. **配置环境**
```bash
cp .env.example .env
php artisan key:generate
```

4. **配置数据库**
编辑 `.env` 文件，设置数据库连接信息

5. **运行迁移**
```bash
php artisan migrate
```

6. **生成测试数据**（可选）
```bash
php artisan db:seed
```

7. **启动服务**
```bash
# 启动 Laravel 开发服务器
php artisan serve

# 启动队列工作进程
php artisan queue:work

# 启动 Meilisearch
meilisearch --master-key="your-master-key"
```

8. **访问系统**
打开浏览器访问 `http://localhost:8000/admin`

## 配置说明

### 文档转换配置

在 `.env` 文件中配置：

```env
DOCUMENT_CONVERSION_DRIVER=pandoc
PANDOC_PATH=/usr/local/bin/pandoc
CONVERSION_TIMEOUT=300
```

### Meilisearch 配置

```env
MEILISEARCH_HOST=http://127.0.0.1:7700
MEILISEARCH_KEY=your-master-key
SCOUT_DRIVER=meilisearch
```

### 队列配置

```env
QUEUE_CONNECTION=redis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
```

## 测试

### 运行测试

```bash
# 运行所有测试
php artisan test

# 运行特定测试
php artisan test --filter=DocumentAccessScopePropertyTest

# 生成测试覆盖率报告
php artisan test --coverage
```

### 测试数据

使用 Factory 生成测试数据：

```php
// 创建用户
$user = User::factory()->create();

// 创建分组
$group = Group::factory()->create();

// 创建文档
$document = Document::factory()->create([
    'type' => 'global',
]);
```

## 部署

详细的部署指南请参考 [DEPLOYMENT.md](./DEPLOYMENT.md)

## 贡献指南

请参考 [CONTRIBUTING.md](./CONTRIBUTING.md)

## 许可证

本项目采用 MIT 许可证

## 联系方式

如有问题或建议，请联系项目维护者。

---

**最后更新**：2025-12-05
**版本**：1.0.0