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 等负路径，均带正控制以防「匹配零的假绿」。
4.1 KiB
4.1 KiB
代码质量门禁
概述
项目配置了自动化质量门禁，确保代码提交前通过所有质量检查。
质量检查
1. 代码风格检查
工具: ESLint
检查时机: pre-commit hook
检查内容:
- 代码语法错误
- 代码风格规范
- 代码格式化
通过标准: 无错误，无警告
2. 提交信息规范
工具: commitlint
检查时机: commit-msg hook
检查内容:
- 提交信息格式
- 提交类型合法性
通过标准: 符合Conventional Commits规范
提交类型:
feat: 新功能fix: 修复bugdocs: 文档更新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 合并。
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
git commit --no-verify -m "message"
绕过commit-msg hook
git commit --no-verify -m "message"
绕过所有hooks
git commit --no-verify -m "message"
故障排查
ESLint错误
问题: pre-commit hook因ESLint错误失败
解决方案:
- 查看错误详情
- 修复代码或配置
- 运行
npm run lint检查 - 重新提交
commitlint错误
问题: commit-msg hook因提交信息格式错误失败
解决方案:
- 检查提交信息格式
- 使用正确的提交类型
- 重新提交
覆盖率不达标
问题: 覆盖率检查失败
解决方案:
- 查看覆盖率报告
- 补充测试用例
- 重新提交
持续改进
提高覆盖率阈值
随着项目发展，逐步提高覆盖率阈值：
- Phase 1: 70% (当前)
- Phase 2: 75%
- Phase 3: 80%
- Phase 4: 85%
- Phase 5: 90%
添加更多质量检查
未来可以添加：
- 复杂度检查
- 重复代码检查
- 安全漏洞扫描
- 依赖漏洞检查