acf549c43c
- 实现基于 Laravel 11 和 Filament 3.X 的文档管理系统 - 添加用户认证和分组管理功能 - 实现文档上传、分类和权限控制 - 集成 Word 文档自动转换为 Markdown - 集成 Meilisearch 全文搜索引擎 - 实现文档在线预览功能 - 添加安全日志和审计功能 - 完整的简体中文界面 - 包含完整的项目文档和部署指南 技术栈: - Laravel 11.x - Filament 3.X - Meilisearch 1.5+ - Pandoc 文档转换 - Redis 队列系统 - Pest PHP 测试框架
139 lines
7.3 KiB
Markdown
139 lines
7.3 KiB
Markdown
# 代码仓库整理需求文档
|
||
|
||
## 简介
|
||
|
||
本文档定义了对现有知识库系统代码仓库进行整理和优化的需求。系统是一个基于 Laravel 11 和 Filament 3.X 构建的企业级文档管理平台，当前已实现核心功能，需要对代码结构、文档和配置进行系统性整理，以提高可维护性和可扩展性。
|
||
|
||
## 术语表
|
||
|
||
- **知识库系统（Knowledge Base System）**：本项目的主系统，用于管理和检索文档
|
||
- **代码仓库（Code Repository）**：存储项目源代码、配置和文档的 Git 仓库
|
||
- **目录结构（Directory Structure）**：项目文件和文件夹的组织方式
|
||
- **Laravel**：PHP Web 应用框架
|
||
- **Filament**：基于 Laravel 的管理面板框架
|
||
- **Meilisearch**：全文搜索引擎
|
||
- **Composer**：PHP 依赖管理工具
|
||
- **PSR-4**：PHP 自动加载标准
|
||
|
||
## 需求
|
||
|
||
### 需求 1：目录结构规范化
|
||
|
||
**用户故事**：作为开发者，我希望项目目录结构清晰规范，以便快速定位和理解代码组织方式。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 开发者查看项目根目录 THEN 系统 SHALL 提供清晰的目录结构文档说明每个主要目录的用途
|
||
2. WHEN 新文件需要添加到项目 THEN 系统 SHALL 提供明确的目录分类规则指导文件放置位置
|
||
3. WHEN 检查 app 目录 THEN 系统 SHALL 按照 Laravel 最佳实践组织所有应用代码
|
||
4. WHEN 检查服务类 THEN 系统 SHALL 将所有业务逻辑服务统一放置在 app/Services 目录
|
||
5. WHEN 检查测试文件 THEN 系统 SHALL 确保测试目录结构与源代码目录结构对应
|
||
|
||
### 需求 2：文档完整性和一致性
|
||
|
||
**用户故事**：作为新加入的开发者，我希望有完整准确的文档，以便快速了解项目并开始贡献代码。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 开发者阅读 README.md THEN 系统 SHALL 提供项目概述、快速开始指南和核心功能说明
|
||
2. WHEN 开发者需要部署系统 THEN 系统 SHALL 提供详细的部署文档包含所有环境配置步骤
|
||
3. WHEN 开发者需要了解 API THEN 系统 SHALL 提供完整的 API 参考文档说明所有公共服务方法
|
||
4. WHEN 文档中引用配置项 THEN 系统 SHALL 确保配置项名称与实际代码一致
|
||
5. WHEN 文档描述功能特性 THEN 系统 SHALL 确保描述与当前实现的功能匹配
|
||
|
||
### 需求 3：配置文件管理
|
||
|
||
**用户故事**：作为系统管理员，我希望配置文件清晰易懂，以便正确配置和部署系统。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 管理员查看 .env.example THEN 系统 SHALL 包含所有必需的配置项并提供清晰的注释说明
|
||
2. WHEN 配置文件包含敏感信息 THEN 系统 SHALL 确保这些文件在 .gitignore 中被正确排除
|
||
3. WHEN 系统使用自定义配置 THEN 系统 SHALL 在 config 目录中创建独立的配置文件
|
||
4. WHEN 配置项有默认值 THEN 系统 SHALL 在配置文件中明确标注默认值
|
||
5. WHEN 配置项之间有依赖关系 THEN 系统 SHALL 在注释中说明依赖关系
|
||
|
||
### 需求 4：依赖管理规范
|
||
|
||
**用户故事**：作为开发者，我希望项目依赖清晰明确，以便正确安装和更新依赖包。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 检查 composer.json THEN 系统 SHALL 明确区分生产依赖和开发依赖
|
||
2. WHEN 检查 package.json THEN 系统 SHALL 列出所有前端依赖及其用途
|
||
3. WHEN 添加新依赖 THEN 系统 SHALL 在文档中说明该依赖的作用和必要性
|
||
4. WHEN 依赖包有版本要求 THEN 系统 SHALL 使用语义化版本约束
|
||
5. WHEN 系统依赖外部服务 THEN 系统 SHALL 在文档中明确说明外部服务的版本要求
|
||
|
||
### 需求 5：代码组织和命名规范
|
||
|
||
**用户故事**：作为开发者，我希望代码遵循一致的命名和组织规范，以便提高代码可读性和可维护性。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 创建新的服务类 THEN 系统 SHALL 使用 Service 后缀并放置在 app/Services 目录
|
||
2. WHEN 创建新的策略类 THEN 系统 SHALL 使用 Policy 后缀并放置在 app/Policies 目录
|
||
3. WHEN 创建新的观察者类 THEN 系统 SHALL 使用 Observer 后缀并放置在 app/Observers 目录
|
||
4. WHEN 创建新的任务类 THEN 系统 SHALL 放置在 app/Jobs 目录并实现 ShouldQueue 接口
|
||
5. WHEN 命名类和方法 THEN 系统 SHALL 遵循 PSR-12 编码规范
|
||
|
||
### 需求 6：测试文件组织
|
||
|
||
**用户故事**：作为开发者，我希望测试文件组织清晰，以便快速找到和运行相关测试。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 检查测试目录 THEN 系统 SHALL 将单元测试放置在 tests/Unit 目录
|
||
2. WHEN 检查测试目录 THEN 系统 SHALL 将功能测试放置在 tests/Feature 目录
|
||
3. WHEN 测试需要测试数据 THEN 系统 SHALL 将测试固件放置在 tests/fixtures 目录
|
||
4. WHEN 测试文件命名 THEN 系统 SHALL 使用 Test 后缀并与被测试的类名对应
|
||
5. WHEN 运行测试 THEN 系统 SHALL 提供清晰的测试输出显示通过和失败的测试
|
||
|
||
### 需求 7：版本控制和忽略规则
|
||
|
||
**用户故事**：作为开发者，我希望版本控制配置合理，以便只跟踪必要的文件。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 检查 .gitignore THEN 系统 SHALL 排除所有生成的文件和目录
|
||
2. WHEN 检查 .gitignore THEN 系统 SHALL 排除所有包含敏感信息的文件
|
||
3. WHEN 检查 .gitignore THEN 系统 SHALL 排除所有依赖包目录
|
||
4. WHEN 检查 .gitignore THEN 系统 SHALL 排除所有 IDE 特定的配置文件
|
||
5. WHEN 检查 .gitignore THEN 系统 SHALL 保留必要的示例配置文件
|
||
|
||
### 需求 8：脚本和自动化工具
|
||
|
||
**用户故事**：作为开发者，我希望有便捷的脚本工具，以便快速执行常见任务。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 需要启动开发环境 THEN 系统 SHALL 提供一键启动脚本
|
||
2. WHEN 需要运行测试 THEN 系统 SHALL 在 composer.json 中定义测试脚本
|
||
3. WHEN 需要代码格式化 THEN 系统 SHALL 提供格式化脚本使用 Laravel Pint
|
||
4. WHEN 需要验证安装 THEN 系统 SHALL 提供验证脚本检查所有依赖和配置
|
||
5. WHEN 脚本执行失败 THEN 系统 SHALL 提供清晰的错误信息和解决建议
|
||
|
||
### 需求 9：存储目录结构
|
||
|
||
**用户故事**：作为系统管理员，我希望存储目录结构清晰，以便管理上传的文件和生成的内容。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 文档上传 THEN 系统 SHALL 将原始文档存储在 storage/app/private/documents 目录按日期分层
|
||
2. WHEN 文档转换完成 THEN 系统 SHALL 将 Markdown 文件存储在 storage/app/private/markdown 目录按日期分层
|
||
3. WHEN 检查存储目录 THEN 系统 SHALL 在每个存储子目录中包含 .gitignore 文件
|
||
4. WHEN 系统需要临时文件 THEN 系统 SHALL 使用 storage/app/temp 目录并定期清理
|
||
5. WHEN 检查存储权限 THEN 系统 SHALL 确保 storage 目录及其子目录具有正确的写入权限
|
||
|
||
### 需求 10：规格文档管理
|
||
|
||
**用户故事**：作为项目经理，我希望功能规格文档组织良好，以便跟踪功能开发进度。
|
||
|
||
#### 验收标准
|
||
|
||
1. WHEN 检查规格目录 THEN 系统 SHALL 将所有功能规格放置在 .kiro/specs 目录
|
||
2. WHEN 创建新功能规格 THEN 系统 SHALL 为每个功能创建独立的子目录
|
||
3. WHEN 功能规格包含多个文档 THEN 系统 SHALL 包含 requirements.md、design.md 和 tasks.md
|
||
4. WHEN 规格文档更新 THEN 系统 SHALL 确保文档之间的引用保持一致
|
||
5. WHEN 功能开发完成 THEN 系统 SHALL 在规格文档中标记完成状态
|