From 7a4fa7cc184b1d2931ab44457d1e604c2864579c Mon Sep 17 00:00:00 2001 From: lizhuoran <625237490@qq.com> Date: Mon, 9 Mar 2026 14:32:03 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=9B=B4=E6=96=B0=20README.md=20?= =?UTF-8?q?=E6=96=87=E6=A1=A3=EF=BC=8C=E5=AE=8C=E5=96=84=E5=8A=9F=E8=83=BD?= =?UTF-8?q?=E6=A8=A1=E5=9D=97=E8=AF=B4=E6=98=8E?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 新增功能模块概览表格 - 添加 SOP 标准作业流程管理说明 - 添加终端配置管理系统说明 - 添加 AI 提示词模板系统说明 - 添加系统设置管理说明 - 添加活动日志审计系统说明 - 更新技术栈版本信息（Laravel 12.x, PHP 8.2+） - 新增 Laravel Octane、Spatie Activity Log、Monaco Editor 等组件说明 - 完善项目结构说明 - 新增常用命令参考（开发、数据库、搜索、缓存等） - 更新部署和配置说明 - 更新版本日志至 v1.0.0 (2026-03-09) - 扩展文档链接列表 --- README.md | 362 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 312 insertions(+), 50 deletions(-) diff --git a/README.md b/README.md index 2c0ad88..054c2ce 100644 --- a/README.md +++ b/README.md @@ -1,59 +1,113 @@ -# 知识库系统 +# 知识库管理系统 -基于 Laravel 11 和 Filament 3.X 构建的企业级文档管理平台，支持 Word 文档上传、自动转换为 Markdown、全文搜索和基于分组的权限控制。 +基于 Laravel 12 和 Filament 3.X 构建的企业级智能知识库管理平台，集成文档管理、SOP 标准作业流程、终端配置管理、AI 提示词模板和系统设置等功能模块，为企业提供全方位的知识管理解决方案。 -[![Laravel](https://img.shields.io/badge/Laravel-11.x-red.svg)](https://laravel.com) +[![Laravel](https://img.shields.io/badge/Laravel-12.x-red.svg)](https://laravel.com) [![Filament](https://img.shields.io/badge/Filament-3.x-orange.svg)](https://filamentphp.com) -[![PHP](https://img.shields.io/badge/PHP-8.1+-blue.svg)](https://php.net) +[![PHP](https://img.shields.io/badge/PHP-8.2+-blue.svg)](https://php.net) [![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE) -## ✨ 功能特性 +## ✨ 核心功能 -### 📄 文档管理 +### 功能模块概览 + +| 模块 | 功能描述 | 状态 | +|------|---------|------| +| 📄 文档管理 | Word 文档上传、转换、预览、搜索 | ✅ 已完成 | +| 📋 SOP 流程 | 标准作业流程模板管理和版本控制 | ✅ 已完成 | +| 🖥️ 终端管理 | 生产终端配置和知识库关联 | ✅ 已完成 | +| 🤖 AI 提示词 | AI 助手提示词模板和变量系统 | ✅ 已完成 | +| ⚙️ 系统设置 | 动态系统配置管理 | ✅ 已完成 | +| 📊 活动日志 | 操作审计和变更追踪 | ✅ 已完成 | +| 👥 用户管理 | 用户和分组权限管理 | ✅ 已完成 | +| 🔍 全文搜索 | Meilisearch 快速搜索 | ✅ 已完成 | + +### 📄 文档管理系统 - **多格式支持**：支持 .doc 和 .docx 格式的 Word 文档上传 - **智能分类**： - 全局知识库：所有用户可访问 - 专用知识库：仅特定分组用户可访问 +- **自动转换**：异步将 Word 文档转换为 Markdown 格式 +- **在线预览**：Markdown 格式在线预览，支持富文本渲染 - **安全下载**：支持原始文档下载，自动记录下载日志 -- **在线预览**：Markdown 格式在线预览，无需下载 +- **全文搜索**：集成 Meilisearch 提供毫秒级搜索响应 -### 🔄 自动转换 -- **异步处理**：使用 Laravel Queue 异步转换文档 -- **多引擎支持**：支持 Pandoc 或 PHPWord 作为转换引擎 -- **状态跟踪**：实时显示转换状态（待处理、处理中、已完成、失败） -- **容错机制**：转换失败不影响文档正常使用 +### 📋 SOP 标准作业流程 +- **模板管理**：创建和管理标准作业流程模板 +- **步骤编排**：支持多步骤流程定义，可设置步骤顺序 +- **交互任务**：支持在步骤中添加交互式任务 +- **版本控制**：自动记录 SOP 模板的版本历史 +- **状态管理**：支持草稿、已发布、已归档等状态 +- **分类标签**：支持按类别、部门、岗位分类管理 +- **导入导出**：支持 SOP 模板的导入和导出功能 -### 🔍 全文搜索 -- **快速搜索**：集成 Meilisearch 提供毫秒级搜索响应 -- **多字段搜索**：同时搜索标题、描述和文档内容 -- **智能过滤**：搜索结果自动应用权限过滤 -- **高级筛选**：支持按类型、分组、上传者等条件筛选 +### 🖥️ 终端配置管理 +- **终端注册**：管理生产现场的终端设备 +- **知识库关联**：为终端配置可访问的知识库，支持优先级设置 +- **提示词配置**：为每个终端配置专属的 AI 提示词模板 +- **配置同步**：支持终端配置的异步同步和状态跟踪 +- **在线状态**：实时监控终端在线状态 +- **工位绑定**：支持终端与工作站的绑定关系 +- **图纸关联**：可为终端关联工位图纸 URL -### 🔐 权限控制 -- **灵活分组**：用户可以属于多个分组 -- **细粒度控制**： +### 🤖 AI 提示词模板 +- **模板库**：预定义多种场景的 AI 提示词模板 + - 通用助手：一般性问答和操作指导 + - 安全专员：安全操作指导和风险提示 + - 故障诊断：设备故障诊断和问题排查 + - 培训教练：新员工培训和操作指导 + - 质量检查：质量控制和检验指导 +- **变量系统**：支持动态变量替换 + - 用户信息：用户名、角色、部门 + - 终端信息：终端名称、编码、工作站 + - 时间信息：当前时间、日期、班次 + - 知识库：关联的知识库列表 +- **实时预览**：支持提示词模板的实时预览和变量替换 +- **变量验证**：自动验证模板中使用的变量是否有效 + +### ⚙️ 系统设置管理 +- **配置分组**：支持按功能模块分组管理系统配置 +- **动态配置**：支持运行时动态修改系统配置 +- **配置缓存**：自动缓存配置提升性能 +- **公开配置**：支持标记配置是否对外公开 +- **配置描述**：为每个配置项提供详细说明 + +### 📊 活动日志审计 +- **操作记录**：自动记录所有重要操作 +- **变更追踪**：详细记录数据变更前后的差异 +- **用户追溯**：记录操作用户和时间信息 +- **批量操作**：支持批量操作的日志记录 +- **日志导出**：支持活动日志的导出功能 +- **差异对比**：可视化展示数据变更的差异 + +### 🔐 权限与安全 +- **用户分组**：用户可以属于多个分组 +- **细粒度权限**： - 全局文档：所有用户可访问 - 专用文档：只有所属分组用户可访问 -- **多层验证**：在查询、下载、预览等操作中强制执行权限 -- **安全审计**：记录所有未授权访问尝试 +- **策略控制**：基于 Laravel Policy 的权限控制 +- **安全日志**：记录所有未授权访问尝试 +- **操作审计**：完整的操作日志和审计追踪 ### 🎨 用户界面 - **现代化设计**：基于 Filament 3.X 的美观管理界面 - **完整中文化**：所有界面元素使用简体中文 - **响应式布局**：完美支持桌面和移动设备 +- **Monaco 编辑器**：集成 Monaco 编辑器支持代码和 Markdown 编辑 - **直观操作**：简洁的操作流程，降低学习成本 ## 🚀 快速开始 ### 环境要求 -- PHP 8.1 或更高版本 +- PHP 8.2 或更高版本 - Composer 2.x - Node.js 18+ 和 npm - MySQL 8.0+ 或 PostgreSQL 13+ - Redis 6.0+ - Meilisearch 1.5+ - Pandoc 2.x+（可选，用于文档转换） +- Laravel Octane（可选，用于高性能部署） ### 安装步骤 @@ -107,19 +161,38 @@ npm run build 8. **启动服务** -在不同的终端窗口中运行： +开发环境有多种启动方式： +**方式一：传统方式（分别启动）** ```bash -# Laravel 开发服务器 +# 终端 1：Laravel 开发服务器 php artisan serve -# 队列工作进程 +# 终端 2：队列工作进程 php artisan queue:work -# Meilisearch（如果本地安装） +# 终端 3：Meilisearch（如果本地安装） meilisearch --master-key="your-master-key" ``` +**方式二：使用 Composer 脚本（推荐）** +```bash +# 一键启动所有服务（使用 concurrently） +composer dev + +# 使用 Octane 启动（高性能） +composer dev-octane +``` + +**方式三：使用 Docker** +```bash +# 启动 Docker 容器 +docker-compose up -d + +# 查看日志 +docker-compose logs -f +``` + 9. **访问系统** 打开浏览器访问：`http://localhost:8000/admin` @@ -131,7 +204,13 @@ meilisearch --master-key="your-master-key" - [API 参考](docs/API_REFERENCE.md) - 服务类和方法文档 - [Meilisearch 配置](docs/MEILISEARCH_SETUP.md) - 搜索引擎配置说明 - [文档转换指南](docs/DOCUMENT_CONVERSION_GUIDE.md) - 转换功能配置 +- [文档预览指南](docs/DOCUMENT_PREVIEW_GUIDE.md) - 预览功能说明 +- [文档搜索指南](docs/DOCUMENT_SEARCH_GUIDE.md) - 搜索功能配置 +- [队列设置](docs/QUEUE_SETUP.md) - 队列系统配置 +- [Octane 安装](docs/OCTANE_INSTALLATION.md) - 高性能服务器配置 +- [Swoole 配置](docs/SWOOLE_CONFIGURATION.md) - Swoole 服务器配置 - [安全日志](docs/security-logging.md) - 安全审计功能说明 +- [Docker 部署](docker/README.md) - Docker 容器化部署指南 ## 🔧 配置 @@ -162,6 +241,17 @@ REDIS_PASSWORD=null REDIS_PORT=6379 ``` +### Octane 配置（可选） + +```env +OCTANE_SERVER=swoole +OCTANE_HTTPS=false +OCTANE_HOST=0.0.0.0 +OCTANE_PORT=8000 +OCTANE_WORKERS=auto +OCTANE_MAX_REQUESTS=500 +``` + 详细配置说明请参考 [部署指南](docs/DEPLOYMENT.md)。 ## 🧪 测试 @@ -177,6 +267,10 @@ php artisan test --filter=DocumentAccessScopePropertyTest # 生成测试覆盖率报告 php artisan test --coverage + +# 运行特定测试套件 +php artisan test tests/Feature +php artisan test tests/Unit ``` ### 测试类型 @@ -185,20 +279,105 @@ php artisan test --coverage - **功能测试**：测试完整的用户流程 - **属性测试**：使用 Property-Based Testing 验证核心逻辑 +## 🚀 常用命令 + +### 开发命令 + +```bash +# 启动开发服务器 +composer dev # 启动所有服务（推荐） +composer dev-octane # 使用 Octane 启动 +php artisan serve # 仅启动 Laravel + +# Octane 相关 +composer octane:start # 启动 Octane +composer octane:stop # 停止 Octane +composer octane:restart # 重启 Octane +composer swoole:start # 使用 Swoole 启动 +composer swoole:watch # Swoole 监听文件变化 + +# 队列相关 +php artisan queue:work # 启动队列工作进程 +php artisan queue:listen # 监听队列 +php artisan queue:restart # 重启队列工作进程 +php artisan queue:failed # 查看失败的任务 +``` + +### 数据库命令 + +```bash +# 迁移 +php artisan migrate # 运行迁移 +php artisan migrate:fresh # 清空数据库并重新迁移 +php artisan migrate:rollback # 回滚迁移 + +# 填充数据 +php artisan db:seed # 运行所有 Seeder +php artisan db:seed --class=SystemSettingSeeder # 运行特定 Seeder + +# 重置数据库 +php artisan migrate:fresh --seed # 重置并填充数据 +``` + +### 搜索索引命令 + +```bash +# 导入搜索索引 +php artisan scout:import "App\Models\Document" + +# 清空搜索索引 +php artisan scout:flush "App\Models\Document" + +# 重建搜索索引 +php artisan scout:flush "App\Models\Document" +php artisan scout:import "App\Models\Document" +``` + +### 缓存命令 + +```bash +# 清除缓存 +php artisan cache:clear # 清除应用缓存 +php artisan config:clear # 清除配置缓存 +php artisan route:clear # 清除路由缓存 +php artisan view:clear # 清除视图缓存 + +# 生成缓存 +php artisan config:cache # 缓存配置 +php artisan route:cache # 缓存路由 +php artisan view:cache # 缓存视图 + +# 清除所有缓存 +php artisan optimize:clear # 清除所有缓存 +``` + +### 用户管理命令 + +```bash +# 创建管理员用户 +php artisan make:filament-user + +# 创建自定义管理员 +php artisan app:create-admin-user +``` + ## 📦 技术栈 ### 后端 -- **Laravel 11.x** - PHP Web 应用框架 +- **Laravel 12.x** - PHP Web 应用框架 - **Filament 3.X** - 管理面板框架 - **Laravel Scout** - 全文搜索集成 +- **Laravel Octane** - 高性能应用服务器 - **Meilisearch** - 快速搜索引擎 - **Pandoc** - 文档格式转换工具 +- **Spatie Activity Log** - 活动日志记录 ### 前端 - **Blade** - Laravel 模板引擎 - **Tailwind CSS** - CSS 框架 - **Alpine.js** - JavaScript 框架（Filament 内置） - **Livewire** - 全栈框架（Filament 内置） +- **Monaco Editor** - 代码编辑器 ### 数据库 - **MySQL 8.0+** 或 **PostgreSQL 13+** @@ -206,41 +385,78 @@ php artisan test --coverage ### 开发工具 - **Pest PHP** - 测试框架 -- **PHPStan** - 静态分析工具 - **Laravel Pint** - 代码格式化工具 +- **Composer** - PHP 依赖管理 +- **npm** - 前端依赖管理 ## 🗂️ 项目结构 ``` knowledge-base-system/ ├── app/ +│ ├── Console/ +│ │ └── Commands/ # Artisan 命令 +│ ├── Exports/ # 数据导出类 │ ├── Filament/ # Filament 资源和页面 -│ │ ├── Pages/ # 自定义页面（搜索） -│ │ └── Resources/ # 资源管理（文档、分组、用户） +│ │ ├── Actions/ # 自定义操作 +│ │ ├── Pages/ # 自定义页面（搜索、系统设置） +│ │ └── Resources/ # 资源管理 +│ │ ├── ActivityLogResource/ # 活动日志 +│ │ ├── DocumentResource/ # 文档管理 +│ │ ├── GroupResource/ # 分组管理 +│ │ ├── SopTemplateResource/ # SOP 模板 +│ │ ├── SystemSettingResource/ # 系统设置 +│ │ ├── TerminalResource/ # 终端管理 +│ │ └── UserResource/ # 用户管理 │ ├── Http/ │ │ └── Controllers/ # 控制器（文档预览） -│ ├── Jobs/ # 队列任务（文档转换） +│ ├── Jobs/ # 队列任务 +│ │ ├── ConvertDocumentToMarkdown.php # 文档转换 +│ │ └── SyncTerminalConfigJob.php # 终端同步 │ ├── Models/ # Eloquent 模型 -│ ├── Observers/ # 模型观察者（文档索引） +│ │ ├── Document.php # 文档 +│ │ ├── Group.php # 分组 +│ │ ├── KnowledgeBase.php # 知识库 +│ │ ├── SopTemplate.php # SOP 模板 +│ │ ├── SystemSetting.php # 系统设置 +│ │ ├── Terminal.php # 终端 +│ │ └── User.php # 用户 +│ ├── Observers/ # 模型观察者 │ ├── Policies/ # 授权策略 │ └── Services/ # 业务逻辑服务 +│ ├── DocumentConversionService.php # 文档转换 +│ ├── DocumentPreviewService.php # 文档预览 +│ ├── DocumentSearchService.php # 文档搜索 +│ ├── PromptTemplateService.php # 提示词模板 +│ ├── SopTemplateService.php # SOP 模板 +│ ├── SystemSettingService.php # 系统设置 +│ └── TerminalSyncService.php # 终端同步 ├── config/ +│ ├── activitylog.php # 活动日志配置 │ ├── documents.php # 文档转换配置 │ ├── filesystems.php # 文件存储配置 +│ ├── octane.php # Octane 配置 +│ ├── prompt_templates.php # 提示词模板配置 +│ ├── prompt_variables.php # 提示词变量配置 │ └── scout.php # Meilisearch 配置 ├── database/ │ ├── factories/ # 测试数据工厂 │ ├── migrations/ # 数据库迁移 │ └── seeders/ # 数据填充 +├── docker/ # Docker 部署文件 ├── docs/ # 项目文档 ├── resources/ │ └── views/ # Blade 视图模板 +│ ├── documents/ # 文档预览视图 +│ └── filament/ # Filament 自定义视图 ├── storage/ │ └── app/ │ └── private/ │ ├── documents/ # 原始文档存储 │ └── markdown/ # Markdown 文件存储 ├── tests/ # 测试文件 +│ ├── Feature/ # 功能测试 +│ └── Unit/ # 单元测试 └── .kiro/ └── specs/ # 功能规格文档 ``` @@ -257,29 +473,72 @@ knowledge-base-system/ ## 📝 更新日志 -### v1.0.0 (2025-12-05) +### v1.0.0 (2026-03-09) -#### 已实现功能 -- ✅ 用户认证和授权 +#### 核心功能模块 +- ✅ 用户认证和授权系统 - ✅ 用户分组管理 -- ✅ 文档上传和存储 -- ✅ 文档分类（全局/专用） -- ✅ 基于分组的权限控制 -- ✅ 文档下载和日志记录 -- ✅ Word 文档自动转换为 Markdown -- ✅ 异步队列处理转换任务 -- ✅ Meilisearch 全文搜索集成 -- ✅ 文档 Markdown 在线预览 -- ✅ 搜索结果权限过滤 +- ✅ 文档管理系统 + - 文档上传和存储 + - 文档分类（全局/专用） + - 基于分组的权限控制 + - 文档下载和日志记录 + - Word 文档自动转换为 Markdown + - 异步队列处理转换任务 + - Meilisearch 全文搜索集成 + - 文档 Markdown 在线预览 + - 搜索结果权限过滤 + +#### 新增功能模块 +- ✅ SOP 标准作业流程管理 + - SOP 模板创建和编辑 + - 多步骤流程定义 + - 交互式任务支持 + - 版本历史记录 + - 状态管理（草稿/已发布/已归档） + - 导入导出功能 + +- ✅ 终端配置管理 + - 终端设备注册和管理 + - 知识库关联配置 + - AI 提示词模板配置 + - 配置同步功能 + - 在线状态监控 + - 工位绑定管理 + +- ✅ AI 提示词模板系统 + - 预定义模板库（5 种场景） + - 动态变量系统 + - 实时预览功能 + - 变量验证机制 + +- ✅ 系统设置管理 + - 配置分组管理 + - 动态配置修改 + - 配置缓存优化 + +- ✅ 活动日志审计 + - 操作记录追踪 + - 变更差异对比 + - 用户操作审计 + - 日志导出功能 + +#### 技术改进 +- ✅ 升级到 Laravel 12.x +- ✅ 集成 Laravel Octane 支持 +- ✅ 集成 Spatie Activity Log +- ✅ 集成 Monaco Editor +- ✅ 完整的测试套件 +- ✅ Docker 容器化部署支持 - ✅ 安全日志记录 - ✅ Filament 管理面板 - ✅ 完整中文界面 #### 待完成功能 -- ⏳ 属性基础测试（Property-Based Testing） -- ⏳ 完整的功能测试套件 - ⏳ 性能优化（缓存、索引优化） -- ⏳ UI 增强（Alpine.js 动画和交互） +- ⏳ UI 增强（动画和交互优化） +- ⏳ 移动端适配优化 +- ⏳ API 接口文档 ## 🔒 安全 @@ -297,8 +556,11 @@ knowledge-base-system/ - [Laravel](https://laravel.com) - 优雅的 PHP 框架 - [Filament](https://filamentphp.com) - 强大的管理面板 +- [Laravel Octane](https://laravel.com/docs/octane) - 高性能应用服务器 - [Meilisearch](https://www.meilisearch.com) - 快速搜索引擎 - [Pandoc](https://pandoc.org) - 通用文档转换器 +- [Spatie Activity Log](https://spatie.be/docs/laravel-activitylog) - 活动日志记录 +- [Monaco Editor](https://microsoft.github.io/monaco-editor/) - 强大的代码编辑器 - [Tailwind CSS](https://tailwindcss.com) - 实用优先的 CSS 框架 ## 📞 联系方式 @@ -308,8 +570,8 @@ knowledge-base-system/ --- -**开发状态**: 🚧 活跃开发中 +**开发状态**: 🚀 稳定版本 -**最后更新**: 2025-12-05 +**最后更新**: 2026-03-09 **版本**: 1.0.0