pre-merge-checklist

合并前检查清单

适用场景

在以下情况下启用此技能：

• 批准拉取请求前进行审查
• 准备合并自己的 PR
• 合并前确认所有自动化检查均已通过
• 审查已获批准但尚未合并的 PR
• 处理完审查反馈后进行最终验证

输出： 将结果写入 pre-merge-report.md，标明每项检查的通过/失败状态及阻塞问题。

请勿在以下情况下使用此技能：

• 深入安全审查（使用 code-review-security）
• 编写实现代码（使用 python-backend-expert 或 react-frontend-expert）
• 架构决策（使用 system-architecture）
• 创建端到端测试（使用 e2e-testing）

说明

自动化检查（按顺序执行）

按以下顺序运行自动化检查。每项检查都必须通过后才能进行下一项。使用 scripts/run-all-checks.sh 一次性执行所有检查。

1. Lint 和格式检查

Python（ruff）：

# Check linting
ruff check app/ tests/

# Check formatting
ruff format --check app/ tests/

# Auto-fix (if needed before commit)
ruff check --fix app/ tests/
ruff format app/ tests/

TypeScript/React（eslint + prettier）：

# Check linting
npx eslint 'src/**/*.{ts,tsx}' --max-warnings 0

# Check formatting
npx prettier --check 'src/**/*.{ts,tsx}'

# Auto-fix (if needed)
npx eslint 'src/**/*.{ts,tsx}' --fix
npx prettier --write 'src/**/*.{ts,tsx}'

通过标准：

• Lint 错误数为零（仅在有合理说明时容许警告）
• 所有文件的格式一致
• 使用 # noqa 或 eslint-disable 时，必须附有说明原因的注释

2. 类型检查

Python（mypy）：

mypy app/ --strict --no-error-summary

TypeScript：

npx tsc --noEmit

使用 scripts/type-check.sh 依次运行两项检查并输出报告。

通过标准：

• 修改的文件中类型错误数为零
• 新增的 type: ignore 或 @ts-ignore 均有合理说明
• 正确使用泛型类型（不得泄漏 Any）

3. 测试

Python：

pytest tests/ -q --tb=short

React：

npm test -- --run --reporter=verbose

通过标准：

• 所有测试均通过（失败数为零）
• 跳过的测试均有关联的问题/工单
• 新代码有对应的测试

4. 覆盖率

Python：

pytest --cov=app --cov-report=term-missing --cov-fail-under=80

React：

npx vitest run --coverage --coverage.thresholds.lines=80

通过标准：

• 总体覆盖率 >= 80%
• 新代码覆盖率 >= 90%
• 所有关键路径均有覆盖（身份验证、付款、数据变更）

5. 安全扫描

# Python dependencies
pip-audit --requirement requirements.txt

# npm dependencies
npm audit --audit-level=high

# Custom code scan (if code-review-security skill is available)
python scripts/security-scan.py --path app/ --output-dir ./security-results

通过标准：

• 依赖项中没有严重或高危漏洞
• 代码扫描中没有严重问题
• 所有新增端点均经过身份验证检查

---

人工审查清单

自动化检查通过后，按以下类别手动审查 PR。

代码质量

• 命名： 变量、函数和类的名称清晰且具有描述性
• 函数： 每个函数只做一件事；函数长度不超过 50 行
• DRY： 没有应提取为共享函数的重复逻辑
• 注释： 复杂逻辑均有说明；没有遗留已注释掉的代码
• 导入： 没有未使用的导入；导入顺序合理（标准库、第三方、本地）
• 常量： 没有魔法数字或字符串；使用命名常量或枚举
• 日志： 新功能在适当的级别记录了恰当的日志

测试

• 覆盖率： 新代码有测试（根据需要编写单元测试和/或集成测试）
• 边界情况： 测试覆盖正常路径、错误路径和边界条件
• 测试名称： 测试名称能说明场景和预期结果
• 测试隔离： 测试之间相互独立，且不依赖执行顺序
• 稳定性： 测试未使用硬编码延迟或依赖特定环境的路径
• 工厂： 测试数据使用工厂，而非硬编码的固定数据

类型安全

• 无 Any： 返回类型和参数均有正确类型标注（没有绕过类型检查的方式）
• 空值安全： 已处理可选值（空值检查、默认值）
• Schema 验证： API 输入使用 Pydantic schema（Python）或 Zod（React）
• 泛型类型： 集合使用正确的泛型（list[User]，而不是 list）

错误处理

• 优雅处理错误： 所有错误路径都返回有意义的消息
• HTTP 状态码： 使用正确的状态码（未找到时使用 404，冲突时使用 409 等）
• 错误边界： React 组件针对异步故障设置了错误边界
• 重试逻辑： 外部服务调用会进行带退避的重试（适用时）
• 无静默失败： 捕获的异常会记录日志，而非被静默吞掉

向后兼容性

• API 契约： 不会破坏现有 API 响应结构
• 数据库迁移： 迁移可逆且不会造成破坏
• 功能标志： 破坏性变更由功能标志控制
• 弃用： 移除的功能在前一个版本中已发出弃用警告
• 配置： 不会新增缺少文档说明的必需环境变量

文档

• API 文档： 新端点已记录（通过 FastAPI 提供的 OpenAPI/Swagger）
• README： 如果新增了依赖项或步骤，则已更新设置说明
• 迁移说明： 数据库迁移包含描述性注释
• ADR： 已记录重要的架构决策（如适用）

性能

• N+1 查询： 没有 N+1 数据库查询模式（使用预加载）
• 分页： 列表端点使用基于游标的分页
• 索引： 新的查询模式有相应的数据库索引支持
• 包体积： 前端没有新增不必要的大型依赖项

无障碍访问

• 语义化 HTML： 使用了正确的 HTML 元素（button、nav、main 等）
• ARIA 标签： 交互元素具有无障碍标签
• 键盘导航： 新 UI 元素可通过键盘访问
• 颜色对比度： 文本符合 WCAG 2.1 AA 对比度要求

使用 scripts/accessibility-check.sh 运行自动化无障碍检查。

---

失败处理流程

检查失败时，请遵循以下升级流程：

自动化检查失败：

1. 在 PR 中修复问题
2. 推送修复并重新运行检查
3. 在所有自动化检查通过前，不要合并

人工审查发现问题：

1. 添加审查评论，说明发现的问题
2. 在 PR 中请求修改
3. 作者处理反馈后重新审查

按严重程度采取措施：

发现类型	操作	可否豁免？
Lint/格式错误	合并前修复	否
类型错误	合并前修复	否
测试失败	合并前修复	否
覆盖率低于阈值	补充测试或说明理由	可以，需技术负责人批准
安全问题（严重/高危）	合并前修复	否
安全问题（中危/低危）	修复或创建后续任务	可以，需提供任务引用
无障碍访问违规	修复或创建后续任务	可以，需说明理由
性能问题	在 PR 中讨论，可延后处理	可以，需技术负责人批准

豁免流程

如果必须豁免某项检查：

1. 记录原因，在 PR 评论中说明豁免为何可以接受
2. 获得明确批准，由技术负责人或资深工程师批准
3. 创建后续任务，以解决根本问题
4. 添加代码注释，在豁免位置引用该任务

# OVERRIDE: Coverage below 80% for this module. See TICKET-1234.
# Approved by @tech-lead on 2024-01-15.
# Reason: Legacy code migration in progress; full coverage planned for Sprint 12.

以下情况绝不允许豁免：

• 严重安全漏洞
• 测试损坏
• 会掩盖错误的类型错误

示例

运行所有检查

# Run the full check suite
./scripts/run-all-checks.sh --output-dir ./check-results

# Run only type checks
./scripts/type-check.sh --output-dir ./check-results

# Run accessibility checks
./scripts/accessibility-check.sh --output-dir ./check-results

快速 PR 审查工作流

1. 在本地拉取分支
2. 运行 ./scripts/run-all-checks.sh --output-dir ./pr-review
3. 检查自动化结果文件
4. 按照上方的人工检查清单逐项检查
5. 留下审查评论或批准

输出文件

将结果写入 pre-merge-report.md：

# Pre-Merge Report: [PR Title]

## Status: READY TO MERGE | BLOCKING ISSUES

## Automated Checks

| Check | Status | Details |
|-------|--------|---------|
| Linting (ruff) | PASS | No issues |
| Type check (mypy) | PASS | No errors |
| Tests (pytest) | PASS | 142 passed, 0 failed |
| Coverage | PASS | 85% (threshold: 80%) |
| Frontend lint | PASS | No issues |
| Frontend types | PASS | No errors |

## Manual Checks

- [x] Code follows project patterns
- [x] Tests cover new functionality
- [x] No breaking API changes
- [ ] Documentation updated (BLOCKING)

## Blocking Issues

1. README needs update for new CLI flag

## Recommendation
Address documentation before merge.