Files
KnowledgeBase/CONTRIBUTING.md
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

317 lines
6.0 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 贡献指南
感谢你考虑为知识库系统做出贡献!
## 行为准则
本项目遵循贡献者公约行为准则。参与本项目即表示你同意遵守其条款。
## 如何贡献
### 报告 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
# 终端 1Laravel 服务器
php artisan serve
# 终端 2队列工作进程
php artisan queue:work
# 终端 3Meilisearch
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 许可证下发布。
---
再次感谢你的贡献!🎉