# 贡献指南

感谢您对 Snapshot 项目的关注！我们欢迎任何形式的贡献。

## 🤝 如何贡献

### 报告问题

如果您发现了 bug 或有功能建议：

1. 检查 [Issues](../../issues) 确保问题未被报告
2. 创建新 Issue，使用合适的模板
3. 提供详细的信息：
   - Bug 报告：复现步骤、预期行为、实际行为、环境信息
   - 功能建议：使用场景、预期效果、可能的实现方案

### 提交代码

#### 开发流程

1. **Fork 仓库**
   ```bash
   # 在 GitHub 上点击 Fork 按钮
   git clone https://github.com/<YOUR_USERNAME>/snapshot.git
   cd snapshot
   ```

2. **创建特性分支**
   ```bash
   git checkout -b feature/AmazingFeature
   # 或修复 bug: git checkout -b fix/bug-description
   ```

3. **进行开发**
   - 遵循代码规范（见下文）
   - 添加必要的测试
   - 更新相关文档

4. **提交更改**
   ```bash
   git add .
   git commit -m "feat: 添加文件批量下载功能"
   ```

5. **推送到分支**
   ```bash
   git push origin feature/AmazingFeature
   ```

6. **创建 Pull Request**
   - 在 GitHub 上创建 PR
   - 填写 PR 模板
   - 等待代码审查

## 📝 代码规范

### 后端 (Java)

**遵循阿里巴巴Java开发规范**

- **命名规范**
  - 类名：PascalCase (例如：`UploadRecordService`)
  - 方法名：camelCase (例如：`getUploadRecordById`)
  - 常量：UPPER_SNAKE_CASE (例如：`MAX_FILE_SIZE`)
  - 包名：全小写 (例如：`com.snapshot.service`)

- **注释规范**
  ```java
  /**
   * 根据ID获取上传记录
   *
   * @param id 上传记录ID
   * @return 上传记录对象，不存在返回null
   * @throws IllegalArgumentException 如果ID为空
   */
  public UploadRecord getUploadRecordById(String id) {
      // 实现代码
  }
  ```

- **异常处理**
  - 使用 `GlobalExceptionHandler` 统一处理异常
  - 自定义异常继承 `RuntimeException`
  - 避免捕获 `Exception` 基类

- **MyBatis 规范**
  - 使用 `@Mapper` 注解
  - SQL 语句放在 XML 文件中
  - 使用参数化查询防止 SQL 注入

### 前端 (Vue.js)

**遵循 Vue 官方风格指南**

- **组件命名**
  ```vue
  <!-- ✅ 推荐 -->
  <script>
  export default {
    name: 'UploadFileList'  // PascalCase
  }
  </script>

  <!-- ❌ 避免 -->
  <script>
  export default {
    name: 'upload-file-list'  // kebab-case
  }
  </script>
  ```

- **Props 定义**
  ```vue
  <script>
  export default {
    props: {
      fileList: {
        type: Array,
        required: true,
        default: () => []
      },
      maxSize: {
        type: Number,
        default: 50 * 1024 * 1024
      }
    }
  }
  </script>
  ```

- **变量命名**
  ```javascript
  // ✅ 推荐
  const uploadRecord = ref(null)
  const MAX_FILE_COUNT = 10

  // ❌ 避免
  const upload_record = ref(null)
  const max_file_count = 10
  ```

- **组件结构**
  ```vue
  <template>
    <!-- 模板内容 -->
  </template>

  <script>
  import { ref, computed, onMounted } from 'vue'

  export default {
    name: 'ComponentName',

    props: { /* ... */ },

    emits: ['update', 'delete'],

    setup(props, { emit }) {
      // 1. 响应式数据
      const count = ref(0)

      // 2. 计算属性
      const doubleCount = computed(() => count.value * 2)

      // 3. 方法
      const increment = () => {
        count.value++
        emit('update', count.value)
      }

      // 4. 生命周期
      onMounted(() => {
        console.log('Component mounted')
      })

      return {
        count,
        doubleCount,
        increment
      }
    }
  }
  </script>

  <style scoped>
  /* 组件样式 */
  </style>
  ```

## 📋 提交信息规范

使用 [约定式提交](https://www.conventionalcommits.org/zh-hans/) 格式：

### 格式

```
<类型>(<范围>): <简短描述>

<详细描述>

<页脚>
```

### 类型

- `feat`: 新功能
- `fix`: Bug 修复
- `docs`: 文档更新
- `style`: 代码格式调整（不影响功能）
- `refactor`: 重构（既不是新功能也不是修复）
- `perf`: 性能优化
- `test`: 添加或修改测试
- `chore`: 构建/工具相关
- `ci`: CI/CD 配置

### 示例

```bash
# 简单提交
git commit -m "feat: 添加文件批量下载功能"

# 详细提交
git commit -m "fix(upload): 修复大文件上传超时问题

- 增加连接超时配置到30分钟
- 添加上传进度重试机制
- 优化内存使用

Closes #123"
```

## ✅ Pull Request 检查清单

提交 PR 前请确认：

- [ ] 代码遵循项目规范
- [ ] 已进行自我审查（self-review）
- [ ] 已添加必要的注释（特别是复杂逻辑）
- [ ] 已更新相关文档
- [ ] 所有测试通过
- [ ] 没有引入新的警告
- [ ] 提交信息符合规范
- [ ] PR 描述清晰，说明了变更内容和原因

## 🧪 测试

### 后端测试

```bash
cd backend
mvn test
```

### 前端测试

```bash
cd frontend
npm run test
```

### E2E 测试

```bash
npm run test:e2e
```

## 📧 联系方式

如有问题：

- GitHub Issues: [../../issues]

## 📄 许可证

提交代码即表示您同意您的贡献将按照项目的 [MIT 许可证](LICENSE) 进行许可。