feat: 初始化知识库系统项目
- 实现基于 Laravel 11 和 Filament 3.X 的文档管理系统 - 添加用户认证和分组管理功能 - 实现文档上传、分类和权限控制 - 集成 Word 文档自动转换为 Markdown - 集成 Meilisearch 全文搜索引擎 - 实现文档在线预览功能 - 添加安全日志和审计功能 - 完整的简体中文界面 - 包含完整的项目文档和部署指南 技术栈: - Laravel 11.x - Filament 3.X - Meilisearch 1.5+ - Pandoc 文档转换 - Redis 队列系统 - Pest PHP 测试框架
This commit is contained in:
Knowledge Base System
315
README.md
Normal file
315
README.md
Normal file
@@ -0,0 +1,315 @@
|
||||
# 知识库系统
|
||||
|
||||
基于 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
|
||||
Reference in New Issue
Block a user