# Git提交规范

## 概述

 使用 Conventional Commits 规范管理提交信息，确保提交历史清晰可读，便于自动生成变更日志和语义化版本管理。

:::tip Conventional Commits 格式
```
<type>(<scope>): <subject>

<body>

<footer>
```
:::

## 提交类型（type）

| 类型 | 说明 | 示例 |
|------|------|------|
| `feat` | 新功能 | `feat(user): 添加用户导入功能` |
| `fix` | 修复 bug | `fix(auth): 修复 token 过期后未刷新的问题` |
| `docs` | 文档变更 | `docs: 更新部署文档` |
| `style` | 代码格式（不影响逻辑） | `style: 格式化代码缩进` |
| `refactor` | 重构（非新功能非修复） | `refactor(repo): 统一查询方法封装` |
| `perf` | 性能优化 | `perf(query): 优化分页查询性能` |
| `test` | 测试相关 | `test(unit): 添加岗位模块单元测试` |
| `chore` | 构建/工具变更 | `chore: 更新依赖版本` |
| `ci` | CI/CD 变更 | `ci: 添加 GitHub Actions 配置` |
| `revert` | 回滚提交 | `revert: 回滚 feat(user) 提交` |

## 范围（scope）

可选，用于说明影响的模块或组件：

```
feat(user): 用户模块
fix(auth): 认证模块
refactor(repo): Repository 层
feat(api): API 层
docs(deploy): 部署文档
```

## 提交信息示例

### 简单提交

```
feat(position): 添加岗位状态切换接口
fix(captcha): 修复验证码过期时间计算错误
docs: 更新 README 安装说明
```

### 带正文的提交

```
fix(auth): 修复 token 刷新后旧 token 仍有效的问题

旧 token 在刷新后未加入黑名单，导致短时间内可同时使用新旧两个 token。
修复方案：刷新时将旧 token 加入 Redis 黑名单。

Closes #123
```

### 破坏性变更

```
feat(api)!: 统一响应格式，移除 data.code 字段

BREAKING CHANGE: 响应格式从 {data: {code, data}} 变为 {code, data, msg, ok}
前端需同步更新响应处理逻辑。
```

:::warning 破坏性变更
破坏性变更使用 `!` 后缀标记，并在正文或 footer 中说明 `BREAKING CHANGE`。此类变更需在版本号中体现（主版本号 +1）。
:::

## 分支策略

| 分支 | 用途 | 命名格式 | 说明 |
|------|------|---------|------|
| `main` | 主分支（生产） | `main` | 始终保持可发布状态 |
| `master` | 开发主分支 | `master` | 日常开发合并目标 |
| `feature/*` | 功能分支 | `feature/功能名` | 从 master 拉取 |
| `fix/*` | 修复分支 | `fix/问题描述` | 从 master 拉取 |
| `hotfix/*` | 紧急修复 | `hotfix/问题描述` | 从 main 拉取 |

### 分支工作流

```
1. 从 master 创建功能分支
 git checkout -b feature/position-import master

2. 开发完成后提交
 git commit -m "feat(position): 添加岗位 Excel 导入功能"

3. 合并到 master
 git checkout master
 git merge feature/position-import

4. 推送到远程
 git push origin master

5. 生产发布时合并到 main
 git checkout main
 git merge master
 git tag v1.2.0
```

## 版本标签

使用语义化版本号（Semantic Versioning）：

```
v主版本号.次版本号.修订号
v1.2.3

主版本号：破坏性变更
次版本号：新功能（向后兼容）
修订号：Bug 修复
```

```bash
# 创建标签
git tag -a v1.2.0 -m "feat: 添加岗位导入功能"

# 推送标签
git push origin v1.2.0

# 查看标签
git tag -l
```

## .gitignore 配置

```gitignore
# Python
__pycache__/
*.py[cod]
*.egg-info/
dist/
build/
venv/

# 环境配置
.env

# IDE
.idea/
.vscode/
*.swp

# 上传文件
uploads/

# 日志
logs/

# 数据库
*.sqlite3
```

:::tip .env 安全
`.env` 文件包含敏感信息（数据库密码、JWT 密钥等），必须在 `.gitignore` 中排除。各环境的 `.env` 独立管理，不提交到仓库。
:::

## 常用 Git 命令

```bash
# 查看提交历史
git log --oneline -20

# 查看某次提交的变更
git show <commit-hash>

# 撤销工作区修改
git checkout -- <file>

# 撤销暂存
git reset HEAD <file>

# 暂存当前工作
git stash
git stash pop

# 查看分支图
git log --graph --oneline --all
```

## 总结

Git 提交规范采用 Conventional Commits 格式：`type(scope): subject`。常用类型包括 feat/fix/docs/refactor/test/chore。分支策略：main（生产）、master（开发）、feature/fix/hotfix（临时分支）。版本使用语义化标签（v1.2.0）。`.env` 等敏感文件必须排除在仓库之外。