zhangxiang
43d1a7af38
对齐 novavis AGENTS.md §27，逐项按本仓实测改写，不照抄不存在的命令： - scripts/check-pr-checklist.sh：三种模式（模板结构 / 单 PR 文件 / --pr-dir 扫描） 与退出码 0/1/2 保持同源；模板根改为按脚本自身位置解析并保留 AGENT_PROJECT_DIR 覆写；修上游 --pr-dir 的参数解析缺陷（for arg in "$@" 内 shift 不消费值， 目录会被再当成 PR 文件），改 while+shift - .gitea/PULL_REQUEST_TEMPLATE.md：30 项 checklist 全部换成本仓真实门禁命令 （type-check / lint / test:unit / test:coverage 阈值 / Playwright / visual / check:contrast / check:headings / lighthouse / test:security:headers），并补 CMS 字段-需重跑 seed 声明、:3000 旧预览不作数、暗黑 token、动效 180–280ms、 品牌红触达、数字 basis 口径等本仓专有约束 - 文档同源：docs/development/quality-gates.md 新增「提交与 PR 流程」权威副本 （AGENTS.md 被 .gitignore 排除，不可依赖）、CLAUDE.md 补 Submission Flow 节 门禁自检：脚本 bash -n 通过；11 个用例覆盖三模式 + 缺节/缺文件/子项不足/非 PR 文件/未知选項/--quiet 等负路径，均带正控制以防「匹配零的假绿」。
194 lines
4.1 KiB
Markdown
194 lines
4.1 KiB
Markdown
# 代码质量门禁
|
||
|
||
## 概述
|
||
|
||
项目配置了自动化质量门禁，确保代码提交前通过所有质量检查。
|
||
|
||
## 质量检查
|
||
|
||
### 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）
|
||
|
||
**检查内容**:
|
||
- 类型错误
|
||
- 类型推断
|
||
|
||
**通过标准**: 无类型错误
|
||
|
||
## 提交与 PR 流程（PR-First）
|
||
|
||
`dev` / `main` 只接收来自功能分支的 PR，执行顺序固定：**同步 dev → rebase → push → PR 门禁 → rebase 合并**。
|
||
|
||
```bash
|
||
git fetch origin dev && git rebase origin/dev # 必须以 origin/dev 为准，本地 dev 可能已陈旧
|
||
git push -u origin <feature-branch> # rebase 改写哈希后仅用 --force-with-lease，禁裸 --force
|
||
bash scripts/check-pr-checklist.sh <PR描述文件> # 未通过不得创建 PR
|
||
```
|
||
|
||
- PR 模板：`.gitea/PULL_REQUEST_TEMPLATE.md`（三节：全链路检查 / 测试分层检查 / 质量门禁）。
|
||
- 门禁校验：模板三节完整 + checklist 子项 ≥ 20 + 描述文件所有子项已勾选；不适用项**仍须勾选**并注明 `N/A：理由`。
|
||
- 功能分支合并方式统一选 Gitea 的 **Rebase**（保持线性历史），不选 Create merge commit。
|
||
- 破坏性/共享状态动作（seed 重跑、DB 写入、force push、合并、删分支、部署）须单独取得授权，不夹带在常规变更里。
|
||
|
||
> 注：`AGENTS.md` 被 `.gitignore` 排除（由 `next dev` 再生），本节是该流程在版本库中的权威副本。
|
||
|
||
## 如何绕过质量门禁
|
||
|
||
⚠️ **警告**: 仅在紧急情况下绕过质量门禁
|
||
|
||
### 绕过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)
|