知识库系统

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

✨ 功能特性

📄 文档管理

• 多格式支持：支持 .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. 克隆项目

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

2. 安装依赖

composer install
npm install

3. 配置环境

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

编辑 .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. 运行迁移

php artisan migrate

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

php artisan db:seed

6. 创建管理员账户

php artisan make:filament-user

7. 编译前端资源

npm run build

8. 启动服务

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

# Laravel 开发服务器
php artisan serve

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

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

9. 访问系统

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

📚 文档

• 项目概览 - 系统架构和功能详解
• 部署指南 - 生产环境部署步骤
• API 参考 - 服务类和方法文档
• Meilisearch 配置 - 搜索引擎配置说明
• 文档转换指南 - 转换功能配置
• 安全日志 - 安全审计功能说明

🔧 配置

Meilisearch 配置

在 .env 文件中配置：

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

文档转换配置

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

队列配置

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

测试类型

• 单元测试：测试独立的类和方法
• 功能测试：测试完整的用户流程
• 属性测试：使用 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 文件。

🙏 致谢

感谢以下开源项目：

• Laravel - 优雅的 PHP 框架
• Filament - 强大的管理面板
• Meilisearch - 快速搜索引擎
• Pandoc - 通用文档转换器
• Tailwind CSS - 实用优先的 CSS 框架

📞 联系方式

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

---

开发状态: 🚧 活跃开发中

最后更新: 2025-12-05

版本: 1.0.0