# Git 提交规范文档

> 本文档规范项目中的 Git 提交信息格式，便于团队协作与版本追溯。

---

## 一、提交信息格式

采用 **Conventional Commits** 规范，格式如下：

```
<类型>[可选范围]: <简短描述>

[可选的详细说明]

[可选的脚注]
```

### 1.1 类型（type）

| 类型       | 说明                     |
| ---------- | ------------------------ |
| `feat`     | 新功能                   |
| `fix`      | 缺陷修复                 |
| `docs`     | 文档变更（README、说明等） |
| `style`    | 代码格式（空格、缩进等，不影响逻辑） |
| `refactor` | 重构（ neither feat nor fix） |
| `perf`     | 性能优化                 |
| `test`     | 测试相关                 |
| `chore`    | 构建、工具、依赖等       |

### 1.2 可选范围（scope）

标明影响模块，便于检索，例如：

- `contract` - 合同管理
- `finance` - 财务管理
- `delivery` - 提货管理
- `inventory` - 库存
- `invoice` - 发票
- `api` - 后端 API
- `frontend` - 前端
- `backend` - 后端

---

## 二、提交示例

### 2.1 新功能

```
feat(contract): 新增合同批量上传功能
feat(finance): 结算管理支持导出 Excel
```

### 2.2 修复

```
fix(api): 修复合同查询接口分页参数错误
fix(frontend): 修复发票列表筛选不生效
```

### 2.3 文档

```
docs: 补充财务管理模块待确认问题
docs(api): 更新合同管理 API 文档
```

### 2.4 重构与优化

```
refactor(invoice): 抽取发票上传公共逻辑
perf(contract): 优化合同列表查询性能
```

### 2.5 其他

```
style: 统一前端代码缩进
chore: 升级 Go 依赖版本
test(finance): 补充结算单单元测试
```

---

## 三、书写建议

1. **标题**：简洁明了，控制在 50 字符内；使用中文，动词开头。
2. **一条提交做一件事**：功能、修复、格式尽量分开提交。
3. **说明可省略**：简单变更可不写正文，复杂逻辑建议补充说明。
4. **关联需求/问题**：如有 Jira/飞书等，可在脚注中写 `Refs: #123`。

---

## 四、反例（应避免）

| 不良示例         | 问题说明               |
| ---------------- | ---------------------- |
| `update`         | 类型不明确，描述含糊   |
| `修改了一些东西` | 没有说明修改了什么     |
| `fix bug`        | 未说明修复的是哪个 bug |
| `WIP`            | 未完成工作不宜直接合并 |

---

## 五、工作流简要

- **main**：生产分支，稳定版本
- **dev**：开发主分支
- **feature/xxx**：功能开发分支
- **fix/xxx**：缺陷修复分支

提交前请先在 `dev` 或对应 feature 分支上开发，完成后再合并到目标分支。