KnowledgeBase/CONTRIBUTING.md

# 贡献指南

感谢你考虑为知识库系统做出贡献！

## 行为准则

本项目遵循贡献者公约行为准则。参与本项目即表示你同意遵守其条款。

## 如何贡献

### 报告 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 许可证下发布。

---

再次感谢你的贡献！🎉