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

已实现功能清单

✅ 核心功能

• 用户认证和授权
• 用户分组管理
• 文档上传和存储
• 文档分类（全局/专用）
• 基于分组的权限控制
• 文档下载和日志记录
• 文档搜索和筛选

✅ 高级功能

• Word 文档自动转换为 Markdown
• 异步队列处理转换任务
• Meilisearch 全文搜索集成
• 文档 Markdown 在线预览
• 搜索结果权限过滤
• 安全日志记录

✅ 用户界面

• Filament 管理面板
• 完整中文界面
• 文档管理界面
• 分组管理界面
• 用户管理界面
• 搜索页面
• 预览页面

⏳ 待完成功能

• 属性基础测试（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. 克隆项目

git clone <repository-url>
cd knowledge-base-system

2. 安装依赖

composer install
npm install

3. 配置环境

cp .env.example .env
php artisan key:generate

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

5. 运行迁移

php artisan migrate

6. 生成测试数据（可选）

php artisan db:seed

7. 启动服务

# 启动 Laravel 开发服务器
php artisan serve

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

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

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

配置说明

文档转换配置

在 .env 文件中配置：

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

Meilisearch 配置

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

队列配置

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

测试

运行测试

# 运行所有测试
php artisan test

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

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

测试数据

使用 Factory 生成测试数据：

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

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

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

部署

详细的部署指南请参考 DEPLOYMENT.md

贡献指南

请参考 CONTRIBUTING.md

许可证

本项目采用 MIT 许可证

联系方式

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

---

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