@tianyio/quality-helper/templates/configs/docs/代码提交自动化检查机制说明.md

A comprehensive quality helper tool for project scaffolding and management

# 代码提交自动化检查机制说明

## 1. 机制概述

项目在代码提交时会自动执行以下检查：

1. **代码格式化和质量检查** - 使用 Prettier 和 ESLint
2. **TypeScript 类型检查** - 使用 TypeScript 编译器
3. **代码复杂度检测** - 集成在 ESLint 配置中的复杂度规则

## 2. 配置详情

### 2.1 Git Hooks 配置

项目使用 Husky 管理 Git Hooks，在 `.husky/pre-commit`
文件中配置了 pre-commit 钩子：

```bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
lint-staged
```

### 2.2 Lint-Staged 配置

在 `.lintstagedrc` 文件中配置了针对不同文件类型的检查任务：

```json
{
  "*.{js,jsx,ts,tsx,vue,cjs,mjs,cts,mts}": ["eslint --fix", "vue-tsc --noEmit"],
  "*.{css,scss,less,sass,styl}": ["prettier --write"],
  "*.{html,json,jsonc,md,yml,yaml,toml}": ["prettier --write"]
}
```

### 2.3 Commit Message 验证

在 `.husky/commit-msg` 文件中配置了 commit-msg 钩子：

```bash
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
commitlint --edit "$1"
```

使用 Commitlint 验证提交信息格式，配置文件为 `commitlint.config.cjs`。

## 3. 工作流程

### 3.1 代码提交流程

当执行 `git commit` 命令时，会按以下顺序执行检查：

1. **Pre-commit 钩子触发**：
   - 运行 Lint-Staged 检查暂存区文件
   - Prettier 格式化代码
   - ESLint 修复代码问题
2. **Commit-msg 钩子触发**：
   - 验证提交信息格式是否符合规范

### 3.2 检查失败处理

当任何检查失败时，Git 提交会被阻止，开发者需要修复问题后重新提交。

## 4. 配置文件说明

### 4.1 .lintstagedrc

定义了不同文件类型的检查任务：

- **JavaScript/TypeScript/Vue 文件**：ESLint 修复、Prettier 格式化
- **样式文件**：Prettier 格式化
- **其他文本文件**：Prettier 格式化

### 4.2 ESLint 代码质量规则

代码质量检测规则配置在 eslint.config.js 文件中，包括：

```javascript
{
  rules: {
    // 代码质量规则
    'no-console': 'off',
    'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'warn',
    'no-unused-vars': 'off', // 由 TypeScript 处理
    'no-undef': 'off', // 由 TypeScript 处理
    'no-duplicate-imports': 'error',
    'prefer-const': 'error',
    'prefer-template': 'error',

    // 代码复杂度规则
    'max-depth': ['warn', 4],           // 最大嵌套深度
    'max-lines': ['warn', 300],         // 文件最大行数
    'max-lines-per-function': ['warn', 50], // 函数最大行数
    'max-nested-callbacks': ['warn', 3],    // 最大嵌套回调
    'max-params': ['warn', 4],          // 函数最大参数
    'max-statements': ['warn', 10],     // 函数最大语句数
  }
}
```

### 4.3 Commitlint 配置

提交信息验证规则配置在 commitlint.config.cjs 文件中，支持以下提交类型：

- `update` - 新功能
- `defect` - 修复bug
- `docs` - 文档更新
- `style` - 代码格式化
- `refactor` - 重构
- `perf` - 性能优化
- `test` - 测试相关
- `build` - 构建相关
- `ci` - CI/CD相关
- `chore` - 其他杂项
- `revert` - 回滚
- `wip` - 进行中的工作
- `release` - 发布版本
- `hotfix` - 热修复
- `security` - 安全修复

## 5. 使用说明

### 5.1 正常开发流程

1. 编写代码并添加到 Git 暂存区：`git add .`
2. 提交代码：`git commit -m "update: 添加新功能"`
3. 系统自动执行所有检查任务

### 5.2 手动运行检查

```bash
# 运行所有检查
npx lint-staged

# 验证提交信息格式
npx commitlint --from HEAD~1 --to HEAD --verbose
```

### 5.3 跳过检查（不推荐）

在特殊情况下，可以使用 `--no-verify` 参数跳过检查：

```bash
git commit -m "update: 添加新功能" --no-verify
```

## 6. 最佳实践

1. **遵循提交规范**：使用标准的提交类型和格式
2. **保持代码简洁**：遵循代码复杂度规则
3. **及时修复问题**：检查失败时及时修复
4. **定期更新依赖**：保持工具链版本更新

通过这套自动化检查机制，可以确保代码质量和项目稳定性，减少人工代码审查的工作量。