# 12.3 Git 提交规范

:::tip 概述
统一的 Git 提交规范有助于代码审查、版本管理和自动化工具集成。前端工程提供了 commitlint 配置（`ui/commitlint.config.js`，依赖中含 husky / lint-staged），按其规范提交可通过自动化校验。
:::

## Commit Message 格式

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

<body>
```

:::info 中文友好
`ui/commitlint.config.js` 的 `headerPattern` 支持中文 type、全角括号与全角冒号，如 `新增(用户): 导入导出功能` 也可通过校验；建议仍统一使用下述标准 type。头部最长 108 字符。
:::

## Type 类型

以 `ui/commitlint.config.js` 的 `type-enum` 为准：

| type | 说明 | 示例 |
|------|------|------|
| `feat` | 新功能 | `feat(user): 新增用户导入导出功能` |
| `fix` | 修复 Bug | `fix(login): 修复验证码过期后仍可使用的问题` |
| `perf` | 性能优化 | `perf(dict): 增加字典缓存减少数据库查询` |
| `style` | 代码格式（不影响功能） | `style: 统一代码缩进` |
| `docs` | 文档 | `docs: 更新 API 接口文档` |
| `test` | 测试 | `test: 添加用户模块单元测试` |
| `refactor` | 重构 | `refactor(service): 优化分页查询性能` |
| `build` | 构建 | `build: 升级 Vite 构建配置` |
| `ci` | CI 配置 | `ci: 补充后端 Pint 检查步骤` |
| `chore` | 杂项/工具 | `chore: 更新 Composer 依赖` |
| `revert` | 回滚 | `revert: 回滚 feat(user) 导入功能` |
| `wip` | 进行中 | `wip(user): 导入导出开发中` |
| `workflow` | 工作流 | `workflow: 调整分支保护规则` |
| `types` | 类型定义 | `types: 补充前端 API 类型声明` |
| `release` | 发版 | `release: v1.2.0` |

## Scope 范围

| scope | 说明 |
|-------|------|
| `user` | 用户模块 |
| `role` | 角色模块 |
| `menu` | 菜单模块 |
| `dict` | 字典模块 |
| `job` | 定时任务 |
| `auth` | 认证授权 |
| `upload` | 文件上传 |
| `generator` | 代码生成器 |
| `config` | 配置 |
| `deploy` | 部署 |

## 示例

```bash
# -----------------------------------------------------------------------------
# 新功能（feat）
# -----------------------------------------------------------------------------
# -m → 指定提交信息（单行简短描述）
git commit -m "feat(article): 新增文章管理模块"

# -----------------------------------------------------------------------------
# 修复 Bug（fix）
# -----------------------------------------------------------------------------
git commit -m "fix(login): 修复密码错误时未记录登录日志的问题"

# -----------------------------------------------------------------------------
# 文档更新（docs）
# -----------------------------------------------------------------------------
git commit -m "docs: 补充多数据库部署文档"

# -----------------------------------------------------------------------------
# 重构（refactor）
# -----------------------------------------------------------------------------
git commit -m "refactor(service): 统一删除前校验逻辑"

# -----------------------------------------------------------------------------
# 性能优化（perf）
# -----------------------------------------------------------------------------
git commit -m "perf(dict): 增加请求级缓存减少重复查询"
```

## 注意事项

:::warning 禁止事项
- 不要提交调试代码（`console.log`、`dd()`、`dump`、`var_dump`）
- 不要提交敏感信息（密码、密钥、Token、`.env`）
- 不要提交 IDE 配置文件（`.idea/`、`.vscode/`）
- 一个 commit 只做一件事
:::

## .gitignore

项目根目录 `.gitignore` 关键规则：

```gitignore
# =============================================================================
# .gitignore — Git 版本控制忽略规则（摘自项目根目录，含说明）
# =============================================================================
# 匹配的文件不会被 git track（不会提交到仓库）
# =============================================================================

# -----------------------------------------------------------------------------
# 环境配置与备份（包含数据库密码、JWT 密钥等敏感信息 — 绝不能提交）
# -----------------------------------------------------------------------------
.env
.env.backup
.env.production

# -----------------------------------------------------------------------------
# 运行时与依赖（自动生成/体积庞大，通过 composer install、npm install 重建）
# -----------------------------------------------------------------------------
/vendor
/node_modules
/storage/*.key
/storage/pail
/public/build
/public/hot

# -----------------------------------------------------------------------------
# IDE 与系统文件（每个开发者的环境不同 — 不应互相影响）
# -----------------------------------------------------------------------------
/.idea
/.vscode
/.fleet
/.nova
/.zed
.DS_Store
Thumbs.db

# -----------------------------------------------------------------------------
# 测试与工具缓存
# -----------------------------------------------------------------------------
*.log
/.phpunit.cache
.phpunit.result.cache
.phpactor.json
```

:::info 前端依赖
前端依赖忽略规则由 `ui/node_modules`（`.gitignore` 中 `/node_modules` 对应各前端包目录）覆盖，`pnpm-lock.yaml` **必须提交**（保证依赖版本一致）。
:::