acf549c43c
- 实现基于 Laravel 11 和 Filament 3.X 的文档管理系统 - 添加用户认证和分组管理功能 - 实现文档上传、分类和权限控制 - 集成 Word 文档自动转换为 Markdown - 集成 Meilisearch 全文搜索引擎 - 实现文档在线预览功能 - 添加安全日志和审计功能 - 完整的简体中文界面 - 包含完整的项目文档和部署指南 技术栈: - Laravel 11.x - Filament 3.X - Meilisearch 1.5+ - Pandoc 文档转换 - Redis 队列系统 - Pest PHP 测试框架
316 lines
8.5 KiB
Markdown
316 lines
8.5 KiB
Markdown
# 知识库系统
|
||
|
||
基于 Laravel 11 和 Filament 3.X 构建的企业级文档管理平台，支持 Word 文档上传、自动转换为 Markdown、全文搜索和基于分组的权限控制。
|
||
|
||
[](https://laravel.com)
|
||
[](https://filamentphp.com)
|
||
[](https://php.net)
|
||
[](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
|