Files

Knowledge Base System acf549c43c feat: 初始化知识库系统项目

- 实现基于 Laravel 11 和 Filament 3.X 的文档管理系统
- 添加用户认证和分组管理功能
- 实现文档上传、分类和权限控制
- 集成 Word 文档自动转换为 Markdown
- 集成 Meilisearch 全文搜索引擎
- 实现文档在线预览功能
- 添加安全日志和审计功能
- 完整的简体中文界面
- 包含完整的项目文档和部署指南

技术栈:
- Laravel 11.x
- Filament 3.X
- Meilisearch 1.5+
- Pandoc 文档转换
- Redis 队列系统
- Pest PHP 测试框架

2025-12-05 14:44:44 +08:00

22 KiB

Raw Permalink Blame History

实施计划

1. 初始化 Laravel 项目和安装 Filament
- 创建新的 Laravel 项目或在现有项目中安装 Filament 3.X
- 配置数据库连接
- 安装 Filament 中文语言包
- 配置应用语言为简体中文
- 需求：8.1, 8.2, 8.3, 8.4, 8.5
2. 创建数据库迁移和模型
2.1 创建 groups 表迁移和 Group 模型
- 编写迁移文件创建 groups 表（id, name, description, timestamps）
- 创建 Group 模型并定义关联关系
- 需求：5.1
2.2 创建 group_user 中间表迁移
- 编写迁移文件创建 group_user 表（id, group_id, user_id, timestamps）
- 添加外键约束和唯一索引
- 需求：5.2
2.3 更新 User 模型添加分组关联
- 在 User 模型中添加 groups() 关联方法
- 添加 uploadedDocuments() 和 downloadLogs() 关联方法
- 需求：5.2
2.4 创建 documents 表迁移和 Document 模型
- 编写迁移文件创建 documents 表（包含所有必需字段和索引）
- 创建 Document 模型并定义 fillable 属性
- 定义与 Group、User 的关联关系
- 需求：1.2, 2.1, 2.2, 2.4
2.5 创建 download_logs 表迁移和 DownloadLog 模型
- 编写迁移文件创建 download_logs 表
- 创建 DownloadLog 模型并定义关联关系
- 需求：4.3
2.6 运行迁移创建数据库表
- 执行 php artisan migrate 命令
- 验证所有表和索引创建成功
- 需求：所有数据模型相关需求
3. 实现文档权限查询作用域
3.1 在 Document 模型中实现 accessibleBy 作用域
- 编写 scopeAccessibleBy 方法实现权限过滤逻辑
- 包含全局文档和用户分组的专用文档
- 排除其他分组的专用文档
- 需求：3.1, 3.2, 3.3, 3.4
3.2 编写属性测试验证权限过滤逻辑
- 属性 7：用户文档列表权限过滤
- 属性 8：其他分组文档隔离
- 验证需求：3.1, 3.2, 3.3, 3.4
3.3 实现 global 和 dedicated 查询作用域
- 编写 scopeGlobal 方法过滤全局文档
- 编写 scopeDedicated 方法过滤专用文档
- 需求：2.3, 6.2
4. 创建 DocumentService 服务类
4.1 实现文档上传方法
- 编写 uploadDocument 方法处理文件上传
- 验证文件格式（.doc 或 .docx）
- 存储文件到指定位置
- 创建数据库记录
- 实现事务处理确保一致性
- 需求：1.1, 1.2, 1.4, 1.5
* 4.2 编写属性测试验证文件上传逻辑
- 属性 1：文件格式验证
- 属性 2：文档存储完整性
- 属性 3：上传事务一致性
- 验证需求：1.1, 1.2, 1.4, 1.5
4.3 实现文档访问权限验证方法
- 编写 validateDocumentAccess 方法
- 检查用户是否有权访问指定文档
- 需求：4.1, 4.2, 7.1, 7.2
4.4 实现文档下载方法
- 编写 downloadDocument 方法
- 验证用户权限
- 返回文件流式响应
- 需求：4.1, 4.4
* 4.5 编写属性测试验证文档下载
- 属性 9：有权限文档可下载
- 属性 10：无权限文档访问拒绝
- 属性 12：文档下载往返一致性
- 验证需求：4.1, 4.2, 4.4
4.6 实现下载日志记录方法
- 编写 logDownload 方法
- 记录用户、文档、时间和 IP 地址
- 需求：4.3
* 4.7 编写属性测试验证下载日志
- 属性 11：下载日志记录
- 验证需求：4.3
5. 创建 DocumentPolicy 策略类
5.1 实现文档策略的各种权限方法
- 编写 viewAny、view、create、update、delete 方法
- 编写 download 方法验证下载权限
- 实现基于分组的权限判断逻辑
- 需求：3.1, 3.4, 4.1, 4.2, 7.1, 7.2
* 5.2 编写单元测试验证策略逻辑
- 测试各种权限场景（有权限、无权限、边缘情况）
- 测试全局文档和专用文档的权限差异
- 需求：3.1, 3.4, 4.1, 4.2
6. 创建 Filament 资源 - GroupResource
6.1 创建 GroupResource 基础结构
- 使用 Filament 命令生成 GroupResource
- 配置中文导航标签和标题
- 需求：5.1, 8.1, 8.2
6.2 定义 Group 表单字段
- 添加名称字段（必填，中文标签）
- 添加描述字段（可选，中文标签）
- 配置验证规则
- 需求：5.1, 8.2
6.3 定义 Group 表格列
- 添加 ID、名称、描述、创建时间列
- 配置中文列标题
- 添加搜索和排序功能
- 需求：5.1, 8.4
6.4 添加用户关系管理器
- 创建 RelationManager 管理分组成员
- 配置用户添加和移除功能
- 使用中文标签
- 需求：5.2, 5.3, 5.4
* 6.5 编写属性测试验证分组管理
- 属性 13：分组数据持久化
- 属性 14：用户分组关联
- 属性 15：分组分配授予权限
- 属性 16：分组移除撤销权限
- 验证需求：5.1, 5.2, 5.3, 5.4
7. 创建 Filament 资源 - DocumentResource
7.1 创建 DocumentResource 基础结构
- 使用 Filament 命令生成 DocumentResource
- 配置中文导航标签和标题
- 需求：1.1, 8.1, 8.2
7.2 定义 Document 表单字段
- 添加标题字段（必填，中文标签）
- 添加描述字段（可选，中文标签）
- 添加文件上传字段（限制 .doc 和 .docx 格式）
- 添加类型选择字段（全局/专用，中文选项）
- 添加分组选择字段（当类型为专用时必填）
- 配置验证规则
- 需求：1.1, 1.4, 2.1, 2.2, 8.2
7.3 实现文件上传处理逻辑
- 在表单中集成 DocumentService 的上传方法
- 处理文件验证和存储
- 显示中文成功/错误消息
- 需求：1.1, 1.2, 1.3, 1.4, 8.3
* 7.4 编写属性测试验证专用文档分组要求
- 属性 4：专用文档必须关联分组
- 验证需求：2.2
7.5 定义 Document 表格列
- 添加标题、类型、分组、上传者、上传时间列
- 配置中文列标题
- 使用中文日期格式
- 添加搜索功能
- 需求：3.5, 8.4, 8.5
7.6 实现表格查询权限过滤
- 在 getEloquentQuery 方法中应用 accessibleBy 作用域
- 确保用户只能看到有权限的文档
- 需求：3.1, 3.2, 3.3, 3.4
7.7 添加文档下载操作
- 创建自定义 Action 用于下载文档
- 集成 DocumentService 的下载方法
- 验证权限并记录日志
- 使用中文按钮标签
- 需求：4.1, 4.2, 4.3, 8.2
7.8 添加筛选器
- 添加类型筛选器（全局/专用，中文标签）
- 添加分组筛选器（中文标签）
- 添加上传者筛选器
- 需求：6.2, 6.3, 8.2
* 7.9 编写属性测试验证搜索和筛选
- 属性 18：关键词搜索匹配
- 属性 19：分类筛选准确性
- 属性 20：分组筛选准确性
- 属性 21：组合筛选交集
- 验证需求：6.1, 6.2, 6.3, 6.5
8. 更新 UserResource 添加分组管理
8.1 在 UserResource 中添加分组关系管理器
- 创建 RelationManager 管理用户所属分组
- 配置分组添加和移除功能
- 使用中文标签
- 需求：5.2, 5.3, 5.4
8.2 在用户表单中添加分组选择字段
- 添加多选分组字段
- 配置中文标签
- 需求：5.2
9. 配置文件存储
9.1 配置 documents 存储磁盘
- 在 config/filesystems.php 中添加 documents 磁盘配置
- 设置为 private 可见性
- 需求：1.2, 4.4
9.2 创建文档存储目录
- 创建 storage/app/documents 目录
- 配置适当的权限
- 需求：1.2
10. 实现安全日志记录
10.1 创建安全日志记录功能
- 创建 SecurityLog 模型和迁移（可选）
- 或使用 Laravel 日志系统记录安全事件
- 记录未授权访问尝试
- 需求：7.3
* 10.2 编写属性测试验证安全日志
- 属性 24：未授权访问日志记录
- 验证需求：7.3
10.3 在 DocumentPolicy 中集成安全日志
- 在权限验证失败时记录日志
- 包含用户信息、文档信息和时间戳
- 需求：7.3
11. 实现分组删除级联处理
11.1 在 Group 模型中添加删除事件监听器
- 使用 Model Events 监听 deleting 事件
- 处理关联的专用文档（设置 group_id 为 null 或删除）
- 需求：5.5
* 11.2 编写属性测试验证级联处理
- 属性 17：分组删除级联处理
- 验证需求：5.5
12. 配置 Filament 面板中文化
12.1 配置应用语言设置
- 在 config/app.php 中设置 locale 为 zh_CN
- 配置 fallback_locale
- 需求：8.1, 8.2, 8.3, 8.4, 8.5
12.2 发布和配置 Filament 语言文件
- 发布 Filament 语言文件
- 自定义翻译文本以符合业务需求
- 需求：8.1, 8.2, 8.3, 8.4
12.3 配置日期时间格式
- 在 Filament 配置中设置中文日期格式
- 配置 Carbon 使用中文语言
- 需求：8.5
* 12.4 编写属性测试验证中文化
- 属性 26：错误消息中文化
- 属性 27：日期格式中文化
- 验证需求：8.3, 8.5
13. 创建测试工厂（Factories）
13.1 创建 GroupFactory
- 生成随机分组名称和描述
- 使用 Faker 生成中文文本
- 需求：测试数据生成
13.2 创建 DocumentFactory
- 生成随机文档数据
- 支持生成全局和专用文档
- 关联随机分组和上传者
- 需求：测试数据生成
13.3 创建 DownloadLogFactory
- 生成随机下载日志数据
- 关联随机文档和用户
- 需求：测试数据生成
14. 编写剩余的属性测试
* 14.1 编写全局文档访问属性测试
- 属性 5：全局文档对所有用户可见
- 验证需求：2.3
* 14.2 编写文档分类持久化属性测试
- 属性 6：文档分类持久化
- 验证需求：2.4
* 14.3 编写权限检查属性测试
- 属性 22：权限检查验证用户和分组
- 属性 23：数据返回前权限验证
- 验证需求：7.1, 7.2
* 14.4 编写数据隔离属性测试
- 属性 25：查询结果数据隔离
- 验证需求：7.4
15. 编写功能测试
* 15.1 编写文档上传流程测试
- 测试管理员上传全局文档
- 测试管理员上传专用文档
- 测试上传无效格式文件被拒绝
- 需求：1.1, 1.2, 1.4, 2.1, 2.2
* 15.2 编写权限控制流程测试
- 测试用户查看自己分组的专用文档
- 测试用户无法查看其他分组的专用文档
- 测试用户可以查看所有全局文档
- 需求：3.1, 3.2, 3.3, 3.4
* 15.3 编写分组管理流程测试
- 测试创建分组并分配用户
- 测试用户从分组移除后失去权限
- 测试删除分组后文档状态
- 需求：5.1, 5.2, 5.3, 5.4, 5.5
* 15.4 编写搜索和筛选流程测试
- 测试按关键词搜索文档
- 测试按分类筛选文档
- 测试组合多个筛选条件
- 需求：6.1, 6.2, 6.3, 6.5
16. 配置错误处理和验证消息
16.1 自定义验证错误消息
- 在语言文件中添加自定义验证消息
- 确保所有消息使用简体中文
- 需求：8.3
16.2 实现全局异常处理
- 在 Handler.php 中自定义异常响应
- 为不同类型的错误返回友好的中文消息
- 需求：错误处理策略
16.3 配置文件上传限制
- 在 php.ini 或 .htaccess 中配置上传大小限制
- 在表单验证中添加文件大小验证
- 显示中文错误提示
- 需求：1.1, 错误处理
17. 性能优化
17.1 添加数据库索引
- 验证所有必要的索引已创建
- 使用 EXPLAIN 分析查询性能
- 需求：性能考虑
17.2 实现查询优化
- 在 Filament 资源中使用 Eager Loading
- 避免 N+1 查询问题
- 需求：性能考虑
17.3 配置缓存
- 配置 Redis 缓存驱动
- 缓存用户分组信息
- 缓存文档元数据
- 需求：性能考虑
18. 创建种子数据（Seeders）
18.1 创建演示数据 Seeder
- 创建示例用户
- 创建示例分组
- 创建示例文档
- 建立关联关系
- 需求：开发和演示
18.2 运行 Seeder 生成测试数据
- 执行 php artisan db:seed
- 验证数据正确生成
- 需求：开发和演示
19. 安装和配置 Meilisearch
19.1 安装 Meilisearch 服务
- 安装 Meilisearch 服务器（Docker 或本地安装）
- 配置 Meilisearch 主密钥
- 启动 Meilisearch 服务
- 需求：10.1, 12.1
19.2 安装 Laravel Scout 和 Meilisearch 驱动
- 安装 laravel/scout 包
- 安装 meilisearch/meilisearch-php 包
- 发布 Scout 配置文件
- 需求：10.1, 12.1
19.3 配置 Scout 和 Meilisearch
- 在 .env 中配置 Meilisearch 连接信息
- 在 config/scout.php 中配置索引设置
- 配置可过滤、可排序和可搜索属性
- 需求：10.1, 12.1
20. 添加文档转换功能的数据库字段
20.1 创建数据库迁移添加新字段
- 添加 markdown_path 字段（varchar 500）
- 添加 markdown_preview 字段（text）
- 添加 conversion_status 字段（enum）
- 添加 conversion_error 字段（text）
- 添加相应的索引
- 需求：9.1, 9.2
20.2 运行迁移更新数据库
- 执行 php artisan migrate
- 验证新字段创建成功
- 需求：9.1, 9.2
20.3 更新 Document 模型
- 添加新字段到 fillable 数组
- 添加 Searchable trait
- 实现 toSearchableArray 方法
- 实现 shouldBeSearchable 方法
- 添加 getMarkdownContent 辅助方法
- 需求：9.2, 12.2
21. 安装和配置文档转换工具
21.1 选择并安装转换工具
- 安装 Pandoc（推荐）或 phpoffice/phpword 包
- 验证 Pandoc 可执行文件路径
- 测试转换功能是否正常
- 需求：9.1
21.2 创建文档转换配置文件
- 创建 config/documents.php 配置文件
- 配置转换驱动（pandoc 或 phpword）
- 配置转换超时时间
- 配置队列名称
- 需求：9.1
21.3 配置 markdown 存储磁盘
- 在 config/filesystems.php 中添加 markdown 磁盘
- 设置为 private 可见性
- 创建 storage/app/private/markdown 目录
- 需求：9.2
22. 实现 DocumentConversionService
22.1 创建 DocumentConversionService 类
- 创建服务类文件
- 实现 convertToMarkdown 方法（调用 Pandoc 或 PHPWord）
- 实现 saveMarkdownToFile 方法
- 实现 getMarkdownPreview 方法（提取前 500 字符）
- 需求：9.1, 9.2
22.2 实现转换队列任务
- 创建 ConvertDocumentToMarkdown Job
- 在 Job 中调用 DocumentConversionService
- 实现转换成功后的处理逻辑
- 实现转换失败后的错误处理
- 需求：9.1, 9.3
22.3 实现 queueConversion 方法
- 创建队列任务分发方法
- 更新文档状态为 'processing'
- 分发到 documents 队列
- 需求：9.1
* 22.4 编写属性测试验证文档转换
- 属性 28：文档上传触发转换
- 属性 29：Markdown 内容持久化
- 属性 30：转换失败不影响文档可用性
- 属性 31：原始文档保留
- 属性 32：文档更新重新转换
- 验证需求：9.1, 9.2, 9.3, 9.4, 9.5
23. 集成文档转换到上传流程
23.1 更新 DocumentService 的 uploadDocument 方法
- 在文档保存成功后调用 queueConversion
- 设置初始 conversion_status 为 'pending'
- 确保事务正确处理
- 需求：9.1
23.2 更新 DocumentResource 表单
- 在表格中显示转换状态
- 添加转换状态的中文标签
- 添加转换状态筛选器
- 需求：9.1
23.3 处理文档更新时的重新转换
- 在文档更新时检测文件是否变更
- 如果文件变更，触发重新转换
- 删除旧的 Markdown 文件
- 需求：9.5
24. 实现 DocumentSearchService
24.1 创建 DocumentSearchService 类
- 创建服务类文件
- 实现 search 方法（使用 Scout 搜索）
- 实现 filterByUserPermissions 方法
- 实现 prepareSearchableData 方法
- 需求：10.1, 10.2, 10.3
24.2 实现索引管理方法
- 实现 indexDocument 方法（读取 Markdown 文件并索引）
- 实现 updateDocumentIndex 方法
- 实现 removeDocumentFromIndex 方法
- 处理 Meilisearch 操作失败的情况
- 需求：12.1, 12.3, 12.4, 12.5
24.3 集成索引到文档生命周期
- 在转换完成后自动索引文档
- 在文档更新时更新索引
- 在文档删除时移除索引
- 使用模型事件或观察者模式
- 需求：12.1, 12.3, 12.4
* 24.4 编写属性测试验证搜索功能
- 属性 33：搜索匹配 Markdown 内容
- 属性 34：搜索覆盖多个字段
- 属性 35：搜索结果权限过滤
- 属性 36：搜索结果包含必需信息
- 验证需求：10.1, 10.2, 10.3, 10.4
* 24.5 编写属性测试验证索引管理
- 属性 40：转换完成触发索引
- 属性 41：索引数据完整性
- 属性 42：文档更新同步索引
- 属性 43：文档删除移除索引
- 属性 44：索引失败不影响文档保存
- 验证需求：12.1, 12.2, 12.3, 12.4, 12.5
25. 创建搜索页面
25.1 创建 Filament 自定义页面 - SearchPage
- 使用 Filament 命令生成自定义页面
- 配置中文导航标签
- 添加到导航菜单
- 需求：10.1
25.2 实现搜索表单
- 添加搜索关键词输入框
- 添加文档类型筛选器
- 添加分组筛选器
- 配置中文标签和占位符
- 需求：10.1, 10.5
25.3 实现搜索结果展示
- 创建搜索结果表格或列表
- 显示文档标题、内容片段、类型、上传时间
- 添加下载原始文档操作（不提供 Markdown 预览）
- 实现分页
- 使用中文标签
- 需求：10.4
25.4 集成 DocumentSearchService
- 在页面中调用搜索服务
- 应用用户权限过滤
- 处理空搜索关键词
- 显示中文提示信息
- 需求：10.1, 10.3, 10.5
26. 实现 MarkdownRenderService
26.1 安装 Markdown 渲染库
- 安装 league/commonmark 包
- 或安装其他 Markdown 渲染库
- 需求：11.1, 11.2
26.2 创建 MarkdownRenderService 类
- 创建服务类文件
- 实现 render 方法（Markdown 转 HTML）
- 实现 sanitize 方法（清理 HTML，防止 XSS）
- 实现 extractPreview 方法（提取摘要）
- 需求：11.1, 11.2
26.3 配置 Markdown 渲染选项
- 配置支持的 Markdown 扩展（表格、代码高亮等）
- 配置 HTML 清理规则
- 配置代码高亮样式
- 需求：11.2
* 26.4 编写属性测试验证 Markdown 渲染
- 属性 38：Markdown 渲染正确性
- 验证需求：11.2
27. 实现文档 Markdown 预览功能（仅在文档管理中）
27.1 在 DocumentResource 中添加 Markdown 预览操作
- 在文档列表和详情页添加"预览 Markdown"按钮
- 创建自定义 Action 用于预览 Markdown 内容
- 验证用户权限
- 使用中文按钮标签（如"预览 Markdown"）
- 注意：其他地方（如搜索结果）只提供下载原始文档功能
- 需求：11.1, 11.3
27.2 创建 Markdown 预览页面
- 创建独立的预览页面或使用 Filament 模态框
- 显示渲染后的 Markdown HTML
- 添加下载原始 Word 文档按钮
- 使用响应式布局，支持移动端查看
- 需求：11.1, 11.5
27.3 实现预览控制器方法
- 创建控制器方法处理预览请求
- 验证用户权限（使用 DocumentPolicy）
- 读取 Markdown 文件并使用 MarkdownRenderService 渲染
- 处理 Markdown 内容为空的情况（显示提示并提供下载按钮）
- 返回渲染后的 HTML 视图
- 需求：11.1, 11.3, 11.4
* 27.4 编写属性测试验证预览功能
- 属性 37：有权限文档可预览
- 属性 39：无权限文档预览拒绝
- 验证需求：11.1, 11.3
28. 编写功能测试 - 文档转换和搜索
* 28.1 编写文档转换流程测试
- 测试上传文档后自动触发转换
- 测试转换完成后 Markdown 文件存在
- 测试转换失败时文档仍可用
- 测试更新文档时重新转换
- 需求：9.1, 9.2, 9.3, 9.5
* 28.2 编写全文搜索流程测试
- 测试搜索 Markdown 内容中的关键词
- 测试搜索结果遵循权限控制
- 测试搜索多个字段（标题、描述、内容）
- 测试空搜索关键词的处理
- 需求：10.1, 10.2, 10.3, 10.5
* 28.3 编写文档预览流程测试
- 测试有权限用户可以预览
- 测试无权限用户无法预览
- 测试 Markdown 正确渲染为 HTML
- 测试预览页面包含下载按钮
- 需求：11.1, 11.2, 11.3, 11.5
* 28.4 编写 Meilisearch 索引流程测试
- 测试文档转换后自动索引
- 测试文档更新时同步索引
- 测试文档删除时移除索引
- 测试索引失败不影响文档保存
- 需求：12.1, 12.3, 12.4, 12.5
29. 检查点 - 确保转换和搜索功能正常
- 运行所有新增的测试
- 手动测试文档上传和转换流程
- 手动测试搜索功能
- 手动测试预览功能
- 验证 Meilisearch 索引正常工作
- 如有问题请咨询用户
- 需求：9.1-9.5, 10.1-10.5, 11.1-11.5, 12.1-12.5
30. 最终检查点 - 确保所有测试通过
- 运行所有单元测试、属性测试和功能测试
- 验证测试覆盖率达到目标
- 修复任何失败的测试
- 如有问题请咨询用户
- 需求：所有需求
31. 文档和部署准备
31.1 更新 README 文档
- 添加文档转换和搜索功能说明
- 添加 Meilisearch 安装和配置步骤
- 添加 Pandoc 安装说明
- 更新使用说明
- 使用简体中文编写
- 需求：部署和配置
31.2 更新环境配置示例
- 在 .env.example 中添加 Meilisearch 配置项
- 添加文档转换配置项
- 添加必要的配置项注释
- 需求：部署和配置
31.3 更新部署脚本
- 添加 Meilisearch 服务启动步骤
- 添加队列工作进程启动步骤
- 添加 Markdown 存储目录创建步骤
- 包含数据库迁移步骤
- 包含文件权限配置
- 需求：部署和配置

22 KiB Raw Permalink Blame History Unescape Escape

实施计划

22 KiB

Raw Permalink Blame History