---
name: pr-review-rules
description: "团队 PR 规范与 AI Code Review 标准。适用于所有代码提交提报与 AI 自动化 Review 辅助过程。"
globs: ["*"]
alwaysApply: true
updated: 2026-05-22
---

# 团队 PR 规范与 AI Code Review 标准

> [!IMPORTANT]
> 代码评审（Code Review）是保障团队工程健康度的最后防线。无论是提交 Pull Request (PR) 编写描述，还是使用 AI 工具进行代码自动审查，AI 助手和开发人员都必须严格遵循本规范中所声明的标准模板与拦截提纲。

## 1. 适用场景

适用于生成 Git 提交说明（Commit Message）、Pull Request 提报说明，或在开发团队内部启用 AI 进行自动化代码走查（Automated CR）的场景。

## 2. 操作规则

### 2.1 PR 提报说明核心要素
AI 助手在协助生成 PR 描述时，必须默认提供并丰富以下三个核心板块的内容：
1. **变更背景与目的 (Why & What)**：清晰阐明为什么做这个改动，解决了什么问题，以及对现有逻辑做出了哪些高维度的更改。
2. **实现技术细节 (Technical Implementation)**：说明架构变更、核心类/函数的引入关系，以及是否涉及配置或数据库变更。
3. **验证证据 (Verification & Evidence)**：提供单元测试覆盖结果、关键路径测试截图/日志，以及上线后的灰度观察建议。

### 2.2 AI Code Review 拦截走查提纲
当 AI 被用作 Code Review 助手时，必须对以下高频安全及质量隐患执行严格扫描并拦截：
1. **边界安全性**：检查是否有未捕获的 Null 引用（空指针）、数组越界、或者未捕获的 Promise 错误。
2. **性能隐患**：是否有不必要的循环内调用数据库、未关闭的文件流/套接字、重复多次的组件渲染。
3. **质量指标**：是否缺失配套单元测试，命名是否符合规范，是否存在硬编码参数（Magic Number/Strings）。

## 3. 禁止事项

- 严禁提交“Fix bug”、“Update”等没有任何业务和技术解释的“一句话式”模糊 Commit 与 PR 说明。
- 严禁对安全红线（密钥明文、未过滤SQL拼装等）做任何让步放行。

## 4. 验证方式

- **PR 提交前校验**：确认 PR 描述包含变更背景、实现细节和验证证据；如果项目维护 `CHANGELOG.md` 或变更集文件，应同步更新。测试无法运行或覆盖率未达标时，必须在 PR 描述中说明原因、风险和替代验证方式。

## 5. 标准 PR 描述模板示例

```markdown
## 📝 1. 变更目的 (What & Why)
- **解决问题**：修复了用户在多进程高并发场景下重复购买商品，导致库存超卖出现负数的重大 Bug。
- **改动范围**：在商品购买扣减库存逻辑层引入 Redis 分布式排他锁锁，保障扣减库存行为具有并发原子性。

## ⚙️ 2. 技术实现细节 (Technical Highlights)
- 引入 `RedisDistributedLock` 包装类，提供 `tryLock(key, timeout)` 与 `unlock(key)` 原子接口。
- 对商品服务中的扣减库存服务进行重构，应用分布式排他锁，锁粒度精确至单个商品 ID。
- 重构了在锁获取失败时的自动回退/重试间隔算法。

## 🧪 3. 验证与证据证明 (Verification Proofs)
- **单元测试**：
  - 新增 `ProductServiceConcurrentTest` 用例，模拟 100 个并发线程同时争抢单一库存商品。
  - 测试结果：100% 通过，成功拦截了超卖现象，库存数扣减精确无误。
- **本地性能测试**：
  - 在 Redis 压力测试环境下，分布式锁加锁释放锁平均耗时为 1.2ms，完全满足核心支付链路吞吐要求。
```