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
304
docs/PROJECT_OVERVIEW.md
Normal file
304
docs/PROJECT_OVERVIEW.md
Normal file
@@ -0,0 +1,304 @@
|
||||
# 知识库系统项目概览
|
||||
|
||||
## 项目简介
|
||||
|
||||
知识库系统是一个基于 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
|
||||
Reference in New Issue
Block a user