贡献指南

> **文档版本**: v1.0.0
> **创建日期**: 2026-02-12
> **最后更新**: 2026-02-12
> **维护人**: 未来鸟FutureBird码巢企业服务引擎开发组
> **状态**: [最新]

---

# 贡献指南

感谢你对工资表 SAAS 系统项目的关注！欢迎贡献代码、报告问题或提出改进建议。

## 开始协作

### 前置要求

- Node.js 24+ (推荐使用 nvm 或 fnm 管理)
- pnpm 包管理器
- Git
- 基础的前端开发经验 (Next.js, React, TypeScript)

### 环境搭建

```bash
# 1. 克隆仓库
git clone <repository-url>
cd <project-directory>

# 2. 安装依赖
pnpm install

# 3. 启动开发环境
pnpm dev
```

## 开发流程

### 分支策略

- `main` - 生产环境分支
- `develop` - 开发主分支
- `feature/*` - 功能开发分支
- `fix/*` - bug 修复分支
- `refactor/*` - 重构分支

### 提交规范

使用 Conventional Commits 规范：

```
<type>(<scope>): <subject>

<body>

<footer>
```

**Type 类型**：
- `feat`: 新功能
- `fix`: bug 修复
- `docs`: 文档更新
- `style`: 代码格式调整（不影响功能）
- `refactor`: 重构
- `perf`: 性能优化
- `test`: 测试相关
- `chore`: 构建/工具链相关

**示例**：
```
feat(employee): 添加工资条导出功能

- 支持导出为 Excel 和 PDF 格式
- 添加批量导出功能

Closes #123
```

### 开发规范

#### 代码风格
- 使用 TypeScript 类型
- 遵循 ESLint 配置
- 组件使用 PascalCase
- 工具函数使用 camelCase
- 常量使用 UPPER_SNAKE_CASE

#### 组件开发
```tsx
// ✅ 推荐
'use client'

import { useState } from 'react'
import { Button } from '@/components/ui/button'

export function MyComponent() {
  const [isOpen, setIsOpen] = useState(false)

return (
    <div className="p-4">
      <Button onClick={() => setIsOpen(true)}>
        打开
      </Button>
    </div>
  )
}
```

#### API 开发
```tsx
// app/api/example/route.ts
import { NextRequest, NextResponse } from 'next/server'

export async function GET(request: NextRequest) {
  try {
    const data = await fetchData()
    return NextResponse.json({ success: true, data })
  } catch (error) {
    return NextResponse.json(
      { success: false, error: '操作失败' },
      { status: 500 }
    )
  }
}
```

## 测试

### 本地测试
```bash
# 运行开发环境
pnpm dev

# 访问 http://localhost:5000
```

### 构建测试
```bash
# 运行构建测试
pnpm run build

# 启动生产环境测试
pnpm start
```

## 提交 Pull Request

### PR 检查清单

- [ ] 代码通过构建测试 (`pnpm run build`)
- [ ] 遵循代码规范（ESLint 通过）
- [ ] 添加必要的注释
- [ ] 更新相关文档
- [ ] 通过自我测试验证功能正常

### PR 模板

```markdown
## 变更类型
- [ ] 功能
- [ ] Bug 修复
- [ ] 重构
- [ ] 文档
- [ ] 其他：_____

## 变更描述

## 相关 Issue

## 测试说明

## 截图（如适用）

```

## 常见问题

### 依赖安装失败
```bash
# 清理缓存后重试
rm -rf node_modules .next
pnpm install
```

### 构建失败
```bash
# 检查 TypeScript 类型
npx tsc --noEmit

# 检查 ESLint
npx eslint src/
```

### 端口被占用
```bash
# 使用不同端口启动
pnpm dev --port 3001
```

## 获取帮助

- 查看 [README.md](README.md) 了解项目架构
- 查看 [CHANGELOG.md](CHANGELOG.md) 了解版本历史
- 在 Issues 中提问或反馈问题
- 联系项目维护者

## 行为准则

- 尊重所有贡献者
- 建设性地提出反馈
- 关注问题本身，而非个人
- 保持开放和包容的态度