# 12.3 Git 提交规范

:::tip 概述
提交遵循 Conventional Commits（前端工程内置 commitlint + husky 校验）。规范的提交信息支撑自动生成变更日志与可追溯的历史。
:::

## 提交格式（Conventional Commits）

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

<body>
<footer>
```

示例：

```text
feat(user): 用户列表支持职级筛选

- querySchemas 新增 levelId 选择器
- UserPageReq 增加 levelId 字段并接入 EqFields

Closes #123
```

## type 类型

| type | 含义 |
|------|------|
| feat | 新功能 |
| fix | 缺陷修复 |
| docs | 文档 |
| style | 格式（不影响逻辑） |
| refactor | 重构（非新功能非修复） |
| perf | 性能优化 |
| test | 测试 |
| build | 构建/依赖 |
| ci | CI 配置 |
| chore | 杂项 |
| revert | 回滚 |

## scope 建议（对齐模块）

```text
后端：user/role/menu/dept/…（模块名）/ middleware/hooks/generator/migrator/base
前端：api/views/store/router/components…
其他：config/docs/ui…
```

## 提交纪律

```text
1. 一个提交一件事（功能/修复不混杂重构）
2. 提交前本地过门禁：go build/vet/gofmt + go test；pnpm type:check/eslint
3. 生成器产物与手工修改分开提交（或提交信息注明）
4. 破坏性变更（改名/删字段/改枚举值）提交信息标注 BREAKING CHANGE:
5. 敏感信息（密钥/密码/个人数据）严禁入仓
6. 中文提交信息（团队约定）subject 不超 50 字
```

## 分支与合并

```text
main        可发布主干（保护分支，PR + CI 必过 + review）
feature/*   功能（从 main 切）
fix/*       修复
hotfix/*    紧急修复（快速通道，双人确认）
release/*   发布分支（打 tag）

合并策略：PR 合并（禁止直接 push main）；冲突在 feature 分支 rebase 解决
```

## hook 保障

```text
前端：husky + lint-staged（提交时 lint/格式化）+ commitlint（信息格式校验）
后端：gofmt/vet 经 CI 门禁（可加 pre-commit hook）
```

## 好的提交 vs 差的提交

```text
✅ feat(job): 任务模块支持暂停恢复接口
✅ fix(auth): 修复 refresh 轮换旧令牌未拉黑的重放风险
✅ chore(generator): overwrite 开关默认 false

❌ update                      （无类型无内容）
❌ 修改了一些东西                 （不可追溯）
❌ fix: fix fix fix              （无信息量）
❌ 一次提交跨 30 个文件混杂多主题  （无法回滚单个变更）
```