# 12.5 Git 提交规范

:::tip 必须遵守
提交信息采用约定式格式：`类型(范围): 摘要`。一个提交一个主题，提交前本地过 `make check`。
:::

## 格式

```text
<类型>(<范围>): <摘要，祈使句，不带句号>

<可选正文：动机与取舍>
<可选脚注：关联需求/破坏性说明>
```

示例：

```text
feat(user): 用户导入增加手机号唯一校验
fix(dict): 字典项变更未删除缓存导致显示名滞后
refactor(repo): 基座 SoftDelete 条件参数成对传入
docs(quickstart): 补充 Windows make.bat 说明
```

## 类型

| 类型 | 含义 |
|---|---|
| feat | 新功能 |
| fix | 缺陷修复 |
| refactor | 重构（不改行为） |
| perf | 性能 |
| docs | 文档 |
| test | 测试 |
| build / ci | 构建与流水线 |
| chore | 杂项 |

## 范围

按模块/域命名：user、role、dict、job、upload、router、generator、frontend、deploy...

## 纪律

- **一个提交一个主题**：功能与格式化提交分离（禁大杂烩 diff）
- **提交前**：`make check`（后端改动）/ `pnpm type:check + lint`（前端改动）
- **不提交**：log/、upload/ 运行产物、.env、IDE 配置
- **生成器产物**：与模板改动同一提交（保持可追溯）
- **破坏性变更**（API 契约调整）：提交正文显式标注并同步前端

## 分支建议

```text
main        生产就绪
develop     集成分支
feat/*      功能
fix/*       修复
```

## 相关

- [11.11 CI/CD 与质量门禁](/zh/deploy/ci-cd.html)
- [12.7 代码审查清单](/zh/standards/code-review.html)