┌─────────────────────────────────────────────────────────────┐
│                     Code Review 完整流程                      │
└─────────────────────────────────────────────────────────────┘
 
Author（写代码的人）                 Reviewer（审查的人）
      │                                    │
      │ ① 开发分支                          │
      │    git checkout -b feature/xxx     │
      │                                    │
      │ ② 编写代码                          │
      │    写功能 + 自测                    │
      │                                    │
      │ ③ 提交 PR                          │
      │    填写 PR 描述                     │
      │───────────────────────────────────>│
      │                                    │ ④ 审查代码
      │                                    │    看 Diff + 检查清单
      │                                    │
      │                                    │ ⑤ 给出反馈
      │<───────────────────────────────────│    Approve / Changes / Comment
      │                                    │
      │ ⑥ 修改代码（如果需要）               │
      │    根据 Review 意见修改             │
      │    推送新提交                        │
      │───────────────────────────────────>│
      │                                    │ ⑦ 再次审查
      │                                    │    确认修改正确
      │                                    │
      │                                    │ ⑧ Approve
      │<───────────────────────────────────│
      │                                    │
      │ ⑨ 合并代码                          │
      │    Merge PR                        │
      │                                    │
      ▼                                    ▼

## PR 描述模板（Author 填写）
 
### 本次改动
- 功能：[简述做了什么]
- 影响范围：[哪些模块被改了]
- 关联 Issue：[如果有，填写 Issue 号]
 
### 自测情况
- ✅ 本地功能测试通过
- ✅ lint 检查通过
- ✅ 单元测试通过（如有）
- ⚠️ 注意事项：[需要 Reviewer 关注的点]
 
### 截图/演示
[如果有 UI 改动，贴截图]

步骤 1：看 PR 描述
        ↓ 了解改动的背景和目的
        
步骤 2：看 Diff 概览
        ↓ git diff --stat 或 GitHub/GitLab 的文件列表
        
步骤 3：逐文件审查
        ↓ 重点文件详细看，次要文件快速浏览
        
步骤 4：运行代码（必要时）
        ↓ 本地拉代码跑一遍
        
步骤 5：给出反馈
        ↓ Approve / Request Changes / Comment

## ✅ 好的 PR 描述示例
 
### 功能说明
新增用户登录页面，支持手机号 + 验证码登录。
 
### 改动文件
- `src/pages/Login.tsx` — 新增登录页面
- `src/api/auth.ts` — 新增登录 API
- `src/hooks/useAuth.ts` — 新增认证 Hook
 
### 自测情况
- ✅ 手机号登录流程正常
- ✅ 验证码倒计时正常
- ✅ 错误提示显示正常
- ✅ lint + test 通过
 
### 需要关注
- 验证码 API 有 60 秒冷却时间，测试时注意
- 登录成功后的跳转逻辑，请重点看一下
 
### 截图
[登录页面截图]

## ❌ 差的 PR 描述示例
 
修复了一些问题，改了几个文件。
 
（Reviewer 心里：？？？）

## React 组件审查清单
 
- [ ] 组件职责是否单一（一个组件只做一件事）
- [ ] Props/State 是否最小化（不需要的数据不传）
- [ ] 是否有 useEffect/useWatch 的正确清理
- [ ] 事件处理函数命名是否规范（handleXxx）
- [ ] 条件渲染是否正确（&& 与 ? 的使用）
- [ ] 列表渲染是否有 key（且 key 是否正确）
- [ ] 是否有性能优化（memo、useMemo、useCallback）

## API 请求审查清单
 
- [ ] 是否有 loading 状态
- [ ] 是否有错误处理
- [ ] 是否有请求取消（页面卸载时）
- [ ] 是否有重复请求防护（防抖/节流）
- [ ] 响应数据是否校验（null 检查）
- [ ] 是否有请求缓存（必要时）

## CSS 样式审查清单
 
- [ ] 是否有硬编码颜色/尺寸（应使用变量）
- [ ] 是否有响应式设计（必要时）
- [ ] 是否有性能问题（避免复杂选择器）
- [ ] 是否有命名规范（BEM/其他）
- [ ] 是否有 z-index 冲突风险

// Login.tsx
import React, { useState } from 'react';
 
function Login() {
  const [phone, setPhone] = useState('');
  const [code, setCode] = useState('');
  
  const handleSubmit = async () => {
    const res = await fetch('/api/login', {
      method: 'POST',
      body: JSON.stringify({ phone, code })
    });
    const data = await res.json();
    if (data.success) {
      window.location.href = '/home';
    }
  };
  
  return (
    <div>
      <input value={phone} onChange={e => setPhone(e.target.value)} />
      <input value={code} onChange={e => setCode(e.target.value)} />
      <button onClick={handleSubmit}>登录</button>
    </div>
  );
}

## Review 反馈
 
### 🔴 必须修改（Request Changes）
 
1. **错误处理缺失**
   ```tsx
   // 问题：fetch 没有 catch，请求失败时用户无感知
   const handleSubmit = async () => {
     const res = await fetch('/api/login', { ... });
     // ❌ 没有 try-catch 或 catch
   };
   
   // 建议：
   const handleSubmit = async () => {
     try {
       const res = await fetch('/api/login', { ... });
       if (!res.ok) throw new Error('请求失败');
       const data = await res.json();
       if (data.success) {
         window.location.href = '/home';
       } else {
         // ✅ 显示错误提示
         alert(data.message || '登录失败');
       }
     } catch (err) {
       alert('网络错误，请重试');
     }
   };

 
### 场景 2：Review 一个列表渲染优化
 
**Author 提交的代码：**
 
```tsx
// UserList.tsx
function UserList({ users }) {
  return (
    <div>
      {users.map(user => (
        <div key={user.id}>
          <span>{user.name}</span>
          <span>{user.age}</span>
          <button onClick={() => deleteUser(user.id)}>删除</button>
        </div>
      ))}
    </div>
  );
}

## Review 反馈
 
### ✅ 基本正确
- key 使用正确（user.id）
- 渲染逻辑清晰
 
### 🟡 建议优化
 
1. **大列表性能问题**
   ```tsx
   // 问题：如果 users 有 1000+ 条，会有性能问题
   
   // 建议：使用虚拟列表（react-window 或 react-virtualized）
   import { FixedSizeList } from 'react-window';
   
   function UserList({ users }) {
     const Row = ({ index, style }) => (
       <div style={style}>
         <span>{users[index].name}</span>
         <span>{users[index].age}</span>
         <button onClick={() => deleteUser(users[index].id)}>删除</button>
       </div>
     );
     
     return (
       <FixedSizeList
         height={400}
         itemCount={users.length}
         itemSize={50}
       >
         {Row}
       </FixedSizeList>
     );
   }

 
### 场景 3：Review 一个 API 封装
 
**Author 提交的代码：**
 
```ts
// api.ts
export async function getUser(id: string) {
  const res = await fetch(`/api/user/${id}`);
  return res.json();
}
 
export async function updateUser(id: string, data: any) {
  const res = await fetch(`/api/user/${id}`, {
    method: 'PUT',
    body: JSON.stringify(data)
  });
  return res.json();
}

## Review 反馈
 
### 🔴 必须修改
 
1. **类型定义缺失**
   ```ts
   // 问题：data 是 any，没有类型约束
   
   // 建议：
   interface User {
     name: string;
     age: number;
     email?: string;
   }
   
   export async function updateUser(id: string, data: Partial<User>) {
     ...
   }

 
---
 
## 五、团队落地
 
### 5.1 小团队如何开始 Code Review？
 
**从零开始，分三阶段：**
 
#### 阶段 1：自愿尝试（第 1-2 周）
 
| 做法 | 目的 |
|------|------|
| 只要求重要功能提交 PR | 降低门槛，不强制 |
| Reviewer 自愿认领 | 避免分配压力 |
| 只给 Comment，不给 Request Changes | 鼓励性反馈 |
| 每周复盘一次 | 收集问题，调整规则 |
 
#### 阶段 2：强制执行（第 3-4 周）
 
| 做法 | 目的 |
|------|------|
| 所有代码必须走 PR | 养成习惯 |
| 每个 PR 必须有 Reviewer Approve | 确保质量 |
| Request Changes 正常使用 | 问题必须修改 |
| 制定 Review 检查清单 | 标准化流程 |
 
#### 阶段 3：成熟阶段（1 个月后）
 
| 做法 | 目的 |
|------|------|
| 自动化检查先行（lint、test） | 减少人工检查 |
| Review 时间纳入工作量计算 | 避免 Review 成为负担 |
| 建立 Review 积分/奖励 | 激励积极性 |
| 定期 Review 复盘会议 | 持续改进 |
 
### 5.2 PR 大小控制
 
**小型团队的特殊问题：PR 太大。**
 
| PR 大小 | Review 效果 | 建议 |
|---------|------------|------|
| < 200 行 | 快速看完，质量高 | ✅ 理想大小 |
| 200-500 行 | 需要时间，但可控 | ⚠️ 可以接受 |
| 500-1000 行 | 很难仔细看完 | ❌ 建议拆分 |
| > 1000 行 | 几乎无法有效 Review | ❌ 必须拆分 |
 
**拆分 PR 的方法：**
 
```markdown
## 大 PR 拆分示例
 
原 PR：新增用户模块（1000+ 行）
  - 用户列表页面
  - 用户详情页面
  - 用户编辑页面
  - 用户 API
  - 用户 Hook
 
拆分后：
  PR 1：用户 API + Hook（200 行）
  PR 2：用户列表页面（300 行）
  PR 3：用户详情页面（250 行）
  PR 4：用户编辑页面（250 行）

## Review 积压处理
 
问题：PR 提交 3 天了还没人审
 
解决方案：
1. 每日站会提醒："今天有 3 个 PR 待审，请认领"
2. 自动提醒：PR 超过 24 小时未审，自动发消息提醒
3. Review 积分：快速 Review 有积分奖励
4. 强制要求：每人每天至少审 1 个 PR（或轮值）

## Hotfix PR 处理流程
 
1. 直接创建 hotfix 分支，快速修复
2. 提交 PR，标注 [HOTFIX]
3. 资深立即 Review（30 分钟内）
4. Review 通过后立即合并
5. 合并后复盘：为什么需要 hotfix？如何避免？

## 意见分歧处理
 
1. Author 解释代码设计的原因
2. Reviewer 解释建议的理由
3. 双方讨论，找到最佳方案
4. 如无法达成一致，请团队资深或 Leader 判定
5. 最终结果记录在 PR 中，作为团队经验

# .github/pull_request_template.md（PR 模板）
 
## 功能说明
[本次改动的内容]
 
### 改动文件
- [文件列表]
 
### 自测情况
- [ ] 功能测试通过
- [ ] lint 检查通过
- [ ] 单元测试通过（如有）
 
### 需要关注
[需要 Reviewer 关注的点]
 
### 截图
[如有 UI 改动]

// .eslintrc.json（Lint 配置）
{
  "extends": ["eslint:recommended", "plugin:react/recommended"],
  "rules": {
    "no-unused-vars": "error",
    "react-hooks/exhaustive-deps": "warn"
  }
}

// .husky/pre-commit（提交前自动检查）
{
  "hooks": {
    "pre-commit": "npm run lint && npm run test"
  }
}

P0 必查：逻辑正确 + 安全问题
P1 建议：性能 + 错误处理
P2 优化：可读性 + 风格 + 结构

< 200 行：理想
200-500：可控
500-1000：建议拆分
> 1000：必须拆分

对事不对人
解释原因 + 给方案
鼓励学习

阶段 1：自愿尝试（低门槛）
阶段 2：强制执行（养成习惯）
阶段 3：成熟阶段（自动化 + 激励）

# 创建分支
git checkout -b feature/xxx
 
# 查看 Diff
git diff                  # 未提交的改动
git diff main             # 当前分支与 main 的差异
git diff --stat           # 改动统计
 
# 提交 PR（GitHub）
git push origin feature/xxx
# 然后在 GitHub 网页创建 PR
 
# 更新 PR（根据 Review 修改后）
git add .
git commit -m "fix: 根据 Review 修改"
git push origin feature/xxx

# 查看 PR 列表
gh pr list
 
# 查看 PR 详情
gh pr view 123
 
# Approve PR
gh pr review 123 --approve
 
# Request Changes
gh pr review 123 --request-changes -b "问题描述"
 
# Comment
gh pr review 123 --comment -b "建议内容"
 
# 合并 PR
gh pr merge 123