feat: 初始化知识库系统项目
- 实现基于 Laravel 11 和 Filament 3.X 的文档管理系统 - 添加用户认证和分组管理功能 - 实现文档上传、分类和权限控制 - 集成 Word 文档自动转换为 Markdown - 集成 Meilisearch 全文搜索引擎 - 实现文档在线预览功能 - 添加安全日志和审计功能 - 完整的简体中文界面 - 包含完整的项目文档和部署指南 技术栈: - Laravel 11.x - Filament 3.X - Meilisearch 1.5+ - Pandoc 文档转换 - Redis 队列系统 - Pest PHP 测试框架
This commit is contained in:
Knowledge Base System
316
CONTRIBUTING.md
Normal file
316
CONTRIBUTING.md
Normal file
@@ -0,0 +1,316 @@
|
||||
# 贡献指南
|
||||
|
||||
感谢你考虑为知识库系统做出贡献！
|
||||
|
||||
## 行为准则
|
||||
|
||||
本项目遵循贡献者公约行为准则。参与本项目即表示你同意遵守其条款。
|
||||
|
||||
## 如何贡献
|
||||
|
||||
### 报告 Bug
|
||||
|
||||
如果你发现了 bug，请创建一个 issue 并包含以下信息：
|
||||
|
||||
- **清晰的标题和描述**
|
||||
- **重现步骤**
|
||||
- **预期行为**
|
||||
- **实际行为**
|
||||
- **环境信息**（PHP 版本、Laravel 版本、操作系统等）
|
||||
- **相关日志或截图**
|
||||
|
||||
### 提出新功能
|
||||
|
||||
如果你有新功能的想法：
|
||||
|
||||
1. 先在 Discussions 中讨论
|
||||
2. 确保功能符合项目目标
|
||||
3. 创建详细的功能请求 issue
|
||||
|
||||
### 提交代码
|
||||
|
||||
#### 开发流程
|
||||
|
||||
1. **Fork 项目**
|
||||
```bash
|
||||
# 在 GitHub 上 fork 项目
|
||||
git clone https://github.com/your-username/knowledge-base-system.git
|
||||
cd knowledge-base-system
|
||||
```
|
||||
|
||||
2. **创建分支**
|
||||
```bash
|
||||
git checkout -b feature/your-feature-name
|
||||
# 或
|
||||
git checkout -b fix/your-bug-fix
|
||||
```
|
||||
|
||||
3. **安装依赖**
|
||||
```bash
|
||||
composer install
|
||||
npm install
|
||||
cp .env.example .env
|
||||
php artisan key:generate
|
||||
```
|
||||
|
||||
4. **进行更改**
|
||||
- 编写代码
|
||||
- 添加测试
|
||||
- 更新文档
|
||||
|
||||
5. **运行测试**
|
||||
```bash
|
||||
php artisan test
|
||||
```
|
||||
|
||||
6. **提交更改**
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "feat: 添加新功能描述"
|
||||
```
|
||||
|
||||
7. **推送到 GitHub**
|
||||
```bash
|
||||
git push origin feature/your-feature-name
|
||||
```
|
||||
|
||||
8. **创建 Pull Request**
|
||||
- 在 GitHub 上创建 PR
|
||||
- 填写 PR 模板
|
||||
- 等待代码审查
|
||||
|
||||
#### 提交信息规范
|
||||
|
||||
使用语义化提交信息：
|
||||
|
||||
- `feat:` 新功能
|
||||
- `fix:` Bug 修复
|
||||
- `docs:` 文档更新
|
||||
- `style:` 代码格式（不影响代码运行）
|
||||
- `refactor:` 重构
|
||||
- `test:` 测试相关
|
||||
- `chore:` 构建过程或辅助工具的变动
|
||||
|
||||
示例：
|
||||
```
|
||||
feat: 添加文档批量上传功能
|
||||
|
||||
- 支持同时上传多个文档
|
||||
- 添加进度条显示
|
||||
- 更新相关文档
|
||||
|
||||
Closes #123
|
||||
```
|
||||
|
||||
#### 代码规范
|
||||
|
||||
1. **PHP 代码**
|
||||
- 遵循 PSR-12 编码标准
|
||||
- 使用 Laravel Pint 格式化代码
|
||||
```bash
|
||||
./vendor/bin/pint
|
||||
```
|
||||
|
||||
2. **JavaScript 代码**
|
||||
- 使用 2 空格缩进
|
||||
- 使用单引号
|
||||
- 添加适当的注释
|
||||
|
||||
3. **命名规范**
|
||||
- 类名：PascalCase
|
||||
- 方法名：camelCase
|
||||
- 变量名：camelCase
|
||||
- 常量：UPPER_SNAKE_CASE
|
||||
|
||||
4. **注释**
|
||||
- 为复杂逻辑添加注释
|
||||
- 使用 PHPDoc 注释公共方法
|
||||
- 注释使用中文
|
||||
|
||||
#### 测试要求
|
||||
|
||||
- 所有新功能必须包含测试
|
||||
- Bug 修复应包含回归测试
|
||||
- 确保所有测试通过
|
||||
- 保持测试覆盖率 ≥ 80%
|
||||
|
||||
测试类型：
|
||||
- **单元测试**：测试独立的类和方法
|
||||
- **功能测试**：测试完整的用户流程
|
||||
- **属性测试**：使用 Property-Based Testing
|
||||
|
||||
#### 文档要求
|
||||
|
||||
如果你的更改影响到：
|
||||
|
||||
- **API**：更新 `docs/API_REFERENCE.md`
|
||||
- **配置**：更新 `docs/DEPLOYMENT.md`
|
||||
- **功能**：更新 `README.md` 和 `docs/PROJECT_OVERVIEW.md`
|
||||
- **使用方法**：添加或更新相关指南
|
||||
|
||||
### Pull Request 检查清单
|
||||
|
||||
在提交 PR 之前，请确保：
|
||||
|
||||
- [ ] 代码遵循项目的编码规范
|
||||
- [ ] 所有测试通过
|
||||
- [ ] 添加了必要的测试
|
||||
- [ ] 更新了相关文档
|
||||
- [ ] 提交信息清晰且符合规范
|
||||
- [ ] PR 描述清楚说明了更改内容
|
||||
- [ ] 没有合并冲突
|
||||
|
||||
### 代码审查
|
||||
|
||||
所有提交都需要经过代码审查：
|
||||
|
||||
- 至少一位维护者批准
|
||||
- 所有讨论都已解决
|
||||
- CI 检查通过
|
||||
|
||||
审查者会关注：
|
||||
- 代码质量
|
||||
- 测试覆盖率
|
||||
- 文档完整性
|
||||
- 性能影响
|
||||
- 安全问题
|
||||
|
||||
## 开发环境设置
|
||||
|
||||
### 必需软件
|
||||
|
||||
- PHP 8.1+
|
||||
- Composer 2.x
|
||||
- Node.js 18+
|
||||
- MySQL 8.0+ 或 PostgreSQL 13+
|
||||
- Redis 6.0+
|
||||
- Meilisearch 1.5+
|
||||
|
||||
### 本地开发
|
||||
|
||||
1. **配置数据库**
|
||||
```env
|
||||
DB_CONNECTION=mysql
|
||||
DB_HOST=127.0.0.1
|
||||
DB_PORT=3306
|
||||
DB_DATABASE=knowledge_base_dev
|
||||
DB_USERNAME=root
|
||||
DB_PASSWORD=
|
||||
```
|
||||
|
||||
2. **运行迁移**
|
||||
```bash
|
||||
php artisan migrate
|
||||
php artisan db:seed
|
||||
```
|
||||
|
||||
3. **启动服务**
|
||||
```bash
|
||||
# 终端 1：Laravel 服务器
|
||||
php artisan serve
|
||||
|
||||
# 终端 2：队列工作进程
|
||||
php artisan queue:work
|
||||
|
||||
# 终端 3：Meilisearch
|
||||
meilisearch --master-key="dev-key"
|
||||
|
||||
# 终端 4：前端构建（开发模式）
|
||||
npm run dev
|
||||
```
|
||||
|
||||
4. **创建测试用户**
|
||||
```bash
|
||||
php artisan make:filament-user
|
||||
```
|
||||
|
||||
### 调试技巧
|
||||
|
||||
1. **使用 Laravel Telescope**（如果安装）
|
||||
```bash
|
||||
composer require laravel/telescope --dev
|
||||
php artisan telescope:install
|
||||
php artisan migrate
|
||||
```
|
||||
|
||||
2. **查看日志**
|
||||
```bash
|
||||
tail -f storage/logs/laravel.log
|
||||
```
|
||||
|
||||
3. **使用 Tinker**
|
||||
```bash
|
||||
php artisan tinker
|
||||
```
|
||||
|
||||
4. **调试队列任务**
|
||||
```bash
|
||||
php artisan queue:work --verbose
|
||||
```
|
||||
|
||||
## 项目结构
|
||||
|
||||
```
|
||||
knowledge-base-system/
|
||||
├── app/
|
||||
│ ├── Filament/ # Filament 资源和页面
|
||||
│ ├── Http/ # 控制器
|
||||
│ ├── Jobs/ # 队列任务
|
||||
│ ├── Models/ # Eloquent 模型
|
||||
│ ├── Observers/ # 模型观察者
|
||||
│ ├── Policies/ # 授权策略
|
||||
│ └── Services/ # 业务逻辑服务
|
||||
├── config/ # 配置文件
|
||||
├── database/ # 迁移和种子
|
||||
├── docs/ # 项目文档
|
||||
├── resources/ # 视图和前端资源
|
||||
├── tests/ # 测试文件
|
||||
└── .kiro/specs/ # 功能规格文档
|
||||
```
|
||||
|
||||
## 常见问题
|
||||
|
||||
### 如何添加新的服务类？
|
||||
|
||||
1. 在 `app/Services/` 创建服务类
|
||||
2. 添加必要的方法和注释
|
||||
3. 在 `docs/API_REFERENCE.md` 中添加文档
|
||||
4. 编写单元测试
|
||||
|
||||
### 如何添加新的 Filament 资源？
|
||||
|
||||
1. 使用 Artisan 命令生成资源
|
||||
```bash
|
||||
php artisan make:filament-resource ModelName
|
||||
```
|
||||
|
||||
2. 配置表单和表格
|
||||
3. 添加必要的策略
|
||||
4. 更新中文翻译
|
||||
|
||||
### 如何添加新的队列任务？
|
||||
|
||||
1. 创建 Job 类
|
||||
```bash
|
||||
php artisan make:job JobName
|
||||
```
|
||||
|
||||
2. 实现 `handle()` 方法
|
||||
3. 添加错误处理
|
||||
4. 编写测试
|
||||
|
||||
## 获取帮助
|
||||
|
||||
如果你需要帮助：
|
||||
|
||||
- 查看 [文档](docs/)
|
||||
- 在 [Discussions](https://github.com/your-repo/discussions) 中提问
|
||||
- 加入我们的社区频道
|
||||
|
||||
## 许可证
|
||||
|
||||
通过贡献代码，你同意你的贡献将在 MIT 许可证下发布。
|
||||
|
||||
---
|
||||
|
||||
再次感谢你的贡献！🎉
|
||||
Reference in New Issue
Block a user