docs: add quality gates documentation

2026-03-24 13:32:01 +08:00
parent 707f125c14
commit c06ac08510
4 changed files with 572 additions and 4 deletions
@@ -0,0 +1,176 @@
+# 代码质量门禁
+
+## 概述
+
+项目配置了自动化质量门禁，确保代码提交前通过所有质量检查。
+
+## 质量检查
+
+### 1. 代码风格检查
+
+**工具**: ESLint
+
+**检查时机**: pre-commit hook
+
+**检查内容**:
+- 代码语法错误
+- 代码风格规范
+- 代码格式化
+
+**通过标准**: 无错误，无警告
+
+### 2. 提交信息规范
+
+**工具**: commitlint
+
+**检查时机**: commit-msg hook
+
+**检查内容**:
+- 提交信息格式
+- 提交类型合法性
+
+**通过标准**: 符合Conventional Commits规范
+
+**提交类型**:
+- `feat`: 新功能
+- `fix`: 修复bug
+- `docs`: 文档更新
+- `style`: 代码格式调整
+- `refactor`: 重构
+- `perf`: 性能优化
+- `test`: 测试相关
+- `chore`: 构建/工具相关
+- `revert`: 回滚提交
+- `build`: 构建相关
+- `ci`: CI/CD相关
+
+**提交信息格式**:
+```
+<type>(<scope>): <subject>
+
+<body>
+
+<footer>
+```
+
+**示例**:
+```
+feat(auth): add JWT authentication
+
+Implement JWT-based authentication with:
+- Token generation
+- Token validation
+- Refresh token mechanism
+
+Closes #123
+```
+
+### 3. 代码覆盖率检查
+
+**工具**: Jest
+
+**检查时机**: 手动运行或CI/CD
+
+**检查内容**:
+- 单元测试覆盖率
+- 分支覆盖率
+- 函数覆盖率
+- 行覆盖率
+- 语句覆盖率
+
+**通过标准**:
+- 分支覆盖率: ≥ 70%
+- 函数覆盖率: ≥ 70%
+- 行覆盖率: ≥ 70%
+- 语句覆盖率: ≥ 70%
+
+### 4. 类型检查
+
+**工具**: TypeScript
+
+**检查时机**: pre-commit hook（通过ESLint）
+
+**检查内容**:
+- 类型错误
+- 类型推断
+
+**通过标准**: 无类型错误
+
+## 如何绕过质量门禁
+
+⚠️ **警告**: 仅在紧急情况下绕过质量门禁
+
+### 绕过pre-commit hook
+
+```bash
+git commit --no-verify -m "message"
+```
+
+### 绕过commit-msg hook
+
+```bash
+git commit --no-verify -m "message"
+```
+
+### 绕过所有hooks
+
+```bash
+git commit --no-verify -m "message"
+```
+
+## 故障排查
+
+### ESLint错误
+
+**问题**: pre-commit hook因ESLint错误失败
+
+**解决方案**:
+1. 查看错误详情
+2. 修复代码或配置
+3. 运行 `npm run lint` 检查
+4. 重新提交
+
+### commitlint错误
+
+**问题**: commit-msg hook因提交信息格式错误失败
+
+**解决方案**:
+1. 检查提交信息格式
+2. 使用正确的提交类型
+3. 重新提交
+
+### 覆盖率不达标
+
+**问题**: 覆盖率检查失败
+
+**解决方案**:
+1. 查看覆盖率报告
+2. 补充测试用例
+3. 重新提交
+
+## 持续改进
+
+### 提高覆盖率阈值
+
+随着项目发展，逐步提高覆盖率阈值：
+- Phase 1: 70% (当前)
+- Phase 2: 75%
+- Phase 3: 80%
+- Phase 4: 85%
+- Phase 5: 90%
+
+### 添加更多质量检查
+
+未来可以添加：
+- 复杂度检查
+- 重复代码检查
+- 安全漏洞扫描
+- 依赖漏洞检查
+
+## 参考资料
+
+- [Conventional Commits](https://www.conventionalcommits.org/)
+- [ESLint文档](https://eslint.org/)
+- [Jest文档](https://jestjs.io/)
+- [Husky文档](https://typicode.github.io/husky/)
+- [lint-staged文档](https://github.com/okonet/lint-staged)