# 知识库系统

基于 Laravel 11 和 Filament 3.X 构建的企业级文档管理平台，支持 Word 文档上传、自动转换为 Markdown、全文搜索和基于分组的权限控制。

[![Laravel](https://img.shields.io/badge/Laravel-11.x-red.svg)](https://laravel.com)
[![Filament](https://img.shields.io/badge/Filament-3.x-orange.svg)](https://filamentphp.com)
[![PHP](https://img.shields.io/badge/PHP-8.1+-blue.svg)](https://php.net)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

## ✨ 功能特性

### 📄 文档管理
- **多格式支持**：支持 .doc 和 .docx 格式的 Word 文档上传
- **智能分类**：
  - 全局知识库：所有用户可访问
  - 专用知识库：仅特定分组用户可访问
- **安全下载**：支持原始文档下载，自动记录下载日志
- **在线预览**：Markdown 格式在线预览，无需下载

### 🔄 自动转换
- **异步处理**：使用 Laravel Queue 异步转换文档
- **多引擎支持**：支持 Pandoc 或 PHPWord 作为转换引擎
- **状态跟踪**：实时显示转换状态（待处理、处理中、已完成、失败）
- **容错机制**：转换失败不影响文档正常使用

### 🔍 全文搜索
- **快速搜索**：集成 Meilisearch 提供毫秒级搜索响应
- **多字段搜索**：同时搜索标题、描述和文档内容
- **智能过滤**：搜索结果自动应用权限过滤
- **高级筛选**：支持按类型、分组、上传者等条件筛选

### 🔐 权限控制
- **灵活分组**：用户可以属于多个分组
- **细粒度控制**：
  - 全局文档：所有用户可访问
  - 专用文档：只有所属分组用户可访问
- **多层验证**：在查询、下载、预览等操作中强制执行权限
- **安全审计**：记录所有未授权访问尝试

### 🎨 用户界面
- **现代化设计**：基于 Filament 3.X 的美观管理界面
- **完整中文化**：所有界面元素使用简体中文
- **响应式布局**：完美支持桌面和移动设备
- **直观操作**：简洁的操作流程，降低学习成本

## 🚀 快速开始

### 环境要求

- PHP 8.1 或更高版本
- Composer 2.x
- Node.js 18+ 和 npm
- 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
```

编辑 `.env` 文件，配置数据库连接：
```env
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=knowledge_base
DB_USERNAME=your_username
DB_PASSWORD=your_password
```

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

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

6. **创建管理员账户**
```bash
php artisan make:filament-user
```

7. **编译前端资源**
```bash
npm run build
```

8. **启动服务**

在不同的终端窗口中运行：

```bash
# Laravel 开发服务器
php artisan serve

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

# Meilisearch（如果本地安装）
meilisearch --master-key="your-master-key"
```

9. **访问系统**

打开浏览器访问：`http://localhost:8000/admin`

## 📚 文档

- [项目概览](docs/PROJECT_OVERVIEW.md) - 系统架构和功能详解
- [部署指南](docs/DEPLOYMENT.md) - 生产环境部署步骤
- [API 参考](docs/API_REFERENCE.md) - 服务类和方法文档
- [Meilisearch 配置](docs/MEILISEARCH_SETUP.md) - 搜索引擎配置说明
- [文档转换指南](docs/DOCUMENT_CONVERSION_GUIDE.md) - 转换功能配置
- [安全日志](docs/security-logging.md) - 安全审计功能说明

## 🔧 配置

### Meilisearch 配置

在 `.env` 文件中配置：

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

### 文档转换配置

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

### 队列配置

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

详细配置说明请参考 [部署指南](docs/DEPLOYMENT.md)。

## 🧪 测试

### 运行测试

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

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

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

### 测试类型

- **单元测试**：测试独立的类和方法
- **功能测试**：测试完整的用户流程
- **属性测试**：使用 Property-Based Testing 验证核心逻辑

## 📦 技术栈

### 后端
- **Laravel 11.x** - PHP Web 应用框架
- **Filament 3.X** - 管理面板框架
- **Laravel Scout** - 全文搜索集成
- **Meilisearch** - 快速搜索引擎
- **Pandoc** - 文档格式转换工具

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

### 数据库
- **MySQL 8.0+** 或 **PostgreSQL 13+**
- **Redis** - 缓存和队列

### 开发工具
- **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/     # 原始文档存储
│           └── markdown/      # Markdown 文件存储
├── tests/                     # 测试文件
└── .kiro/
    └── specs/                 # 功能规格文档
```

## 🤝 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📝 更新日志

### v1.0.0 (2025-12-05)

#### 已实现功能
- ✅ 用户认证和授权
- ✅ 用户分组管理
- ✅ 文档上传和存储
- ✅ 文档分类（全局/专用）
- ✅ 基于分组的权限控制
- ✅ 文档下载和日志记录
- ✅ Word 文档自动转换为 Markdown
- ✅ 异步队列处理转换任务
- ✅ Meilisearch 全文搜索集成
- ✅ 文档 Markdown 在线预览
- ✅ 搜索结果权限过滤
- ✅ 安全日志记录
- ✅ Filament 管理面板
- ✅ 完整中文界面

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

## 🔒 安全

如果发现安全漏洞，请发送邮件至 security@example.com，我们会及时处理。

请勿在公开的 issue 中报告安全问题。

## 📄 许可证

本项目采用 MIT 许可证。详情请参阅 [LICENSE](LICENSE) 文件。

## 🙏 致谢

感谢以下开源项目：

- [Laravel](https://laravel.com) - 优雅的 PHP 框架
- [Filament](https://filamentphp.com) - 强大的管理面板
- [Meilisearch](https://www.meilisearch.com) - 快速搜索引擎
- [Pandoc](https://pandoc.org) - 通用文档转换器
- [Tailwind CSS](https://tailwindcss.com) - 实用优先的 CSS 框架

## 📞 联系方式

- **问题反馈**: 请在 GitHub Issues 中提交
- **功能建议**: 欢迎在 GitHub Discussions 中讨论

---

**开发状态**: 🚧 活跃开发中

**最后更新**: 2025-12-05

**版本**: 1.0.0