# 全面审查工作流示例

本文档展示一个完整的代码审查工作流，包括数据获取、AI 分析、报告生成和评论集成。

## 📋 场景描述

**场景**: Reviewer 需要对一个 PR 进行全面的代码审查，包括代码质量、安全性、性能等多个维度。

**目标**:
1. 获取完整的 PR 代码变更数据
2. 使用 AI 进行多维度代码分析
3. 生成结构化的审查报告
4. 将审查意见添加为 PR 评论

## 🔄 工作流程

```
开始全面审查
  ↓
1. 获取 PR 基本信息
  ├─ 获取 PR 详情
  ├─ 获取变更文件列表
  └─ 获取 diff 内容
  ↓
2. 数据预处理
  ├─ 过滤无关文件
  ├─ 提取代码片段
  └─ 组织分析数据
  ↓
3. AI 代码分析
  ├─ 代码质量检查
  ├─ 安全性检查
  ├─ 性能检查
  └─ 可维护性检查
  ↓
4. 生成审查报告
  ├─ 汇总分析结果
  ├─ 按优先级排序问题
  └─ 生成改进建议
  ↓
5. 输出审查报告
  ├─ 打印 JSON 格式（AI 解析）
  └─ 打印 Markdown 格式（人类阅读）
  ↓
6. （可选）添加评论到 PR
  ↓
完成
```

## 🔧 实施步骤

### 步骤 1：获取 PR 基本信息

```bash
# 1.1 获取 PR 详情
gitlink-cli pr +view --id 123 --format json > pr_info.json

# 1.2 获取变更文件列表
gitlink-cli pr +files --id 123 --format json > pr_files.json

# 1.3 获取 diff 内容
gitlink-cli pr +diff --id 123 --format json > pr_diff.json

# 验证数据获取成功
echo "=== PR 信息 ===" && cat pr_info.json | jq '.ok'
echo "=== 变更文件 ===" && cat pr_files.json | jq '.data.total_files'
echo "=== Diff 大小 ===" && cat pr_diff.json | jq '.data | length'
```

### 步骤 2：数据预处理

```bash
# 2.1 过滤代码文件（排除二进制、配置、文档文件）
cat pr_files.json | jq '.data.files[] |
  select(.filename | test("\\.(go|js|ts|py|java|rb)$"))' > code_files.json

# 2.2 统计代码文件
CODE_FILES_COUNT=$(cat code_files.json | jq 'length')
echo "代码文件数: $CODE_FILES_COUNT"

# 2.3 提取主要变更文件
cat pr_files.json | jq '.data.files |
  map(select(.changes > 10)) |
  sort_by(.changes) | reverse' > main_changes.json
```

### 步骤 3：准备 AI 分析数据

```bash
# 3.1 组织分析数据
cat > analysis_input.json <<EOF
{
  "pr_info": $(cat pr_info.json | jq '.data'),
  "files": $(cat pr_files.json | jq '.data.files'),
  "diff": $(cat pr_diff.json | jq -r '.data.diff')
}
EOF

# 3.2 验证数据格式
cat analysis_input.json | jq '.'
```

### 步骤 4：AI 代码分析（使用 Claude）

**方式 1：使用 Claude Code（推荐）**

```
用户: "请分析 PR #123 的代码变更，检查代码质量、安全性和性能问题"

AI Agent 将：
1. 读取 analysis_input.json
2. 分析代码质量和潜在问题
3. 生成结构化的审查报告
4. 输出 JSON 和 Markdown 格式报告
```

**方式 2：使用 Claude API**

```bash
# 调用 Claude API 进行代码分析
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-3-5-sonnet-20240620",
    "max_tokens": 4096,
    "messages": [
      {
        "role": "user",
        "content": "请分析以下 PR 的代码变更，检查代码质量、安全性和性能问题。输出 JSON 格式的审查报告。\n\nPR 数据：\n'$(cat analysis_input.json)'"
      }
    ]
  }' > analysis_result.json
```

### 步骤 5：生成审查报告

```bash
# 5.1 提取 JSON 报告
cat analysis_result.json | jq -r '.content' > review_report.json

# 5.2 生成 Markdown 报告
cat analysis_result.json | jq -r '.content' > review_report.md

# 5.3 验证报告格式
cat review_report.json | jq '.overall_assessment'
cat review_report.md | head -50
```

### 步骤 6：输出审查报告

```bash
# 6.1 打印概要信息
echo "=== 代码审查报告 ==="
echo "PR ID: $(cat pr_info.json | jq -r '.data.project_issues_index')"
echo "总体评分: $(cat review_report.json | jq -r '.overall_assessment.total_score')/100"
echo "质量评分: $(cat review_report.json | jq -r '.overall_assessment.quality_score')/100"
echo "安全评分: $(cat review_report.json | jq -r '.overall_assessment.security_score')/100"

# 6.2 打印问题列表
echo -e "\n=== 发现的问题 ==="
cat review_report.json | jq -r '.issues[] |
  "\(.severity) - \(.category): \(.file):\(.line)"'

# 6.3 打印优秀实践
echo -e "\n=== 优秀实践 ==="
cat review_report.json | jq -r '.positive_notes[] |
  "⭐ \(.file):\(.line) - \(.description)"'

# 6.4 打印改进建议
echo -e "\n=== 改进建议 ==="
cat review_report.json | jq -r '.recommendations[]' | nl
```

### 步骤 7：（可选）添加评论到 PR

```bash
# 7.1 添加总评
gitlink-cli api POST /:owner/:repo/pulls/123/reviews --body "{
  \"body\": \"$(cat review_report.md)\",
  \"event\": \"COMMENT\"
}"

# 7.2 批量添加行内评论
cat review_report.json | jq -r '.issues[] |
  "gitlink-cli api POST /:owner/:repo/pulls/123/comments --body '"'"'{
    \"body\": \"\(.suggestion)\",
    \"path\": \"\(.file)\",
    \"position\": \(.line)
  }'"'"'"' | bash
```

## 📊 审查报告示例

### JSON 格式报告

```json
{
  "pr_info": {
    "id": 123,
    "title": "Feature: Add user authentication",
    "author": "developer",
    "branch": "feature/auth → main"
  },
  "overall_assessment": {
    "total_score": 75,
    "quality_score": 85,
    "security_score": 60,
    "performance_score": 75,
    "maintainability_score": 80,
    "status": "NEEDS_IMPROVEMENTS"
  },
  "issues": [
    {
      "id": 1,
      "severity": "HIGH",
      "category": "security",
      "file": "src/auth/login.go",
      "line": 45,
      "rule": "SQL Injection",
      "description": "直接拼接用户输入到 SQL 语句",
      "suggestion": "使用参数化查询或 ORM"
    }
  ],
  "positive_notes": [
    {
      "file": "src/auth/user.go",
      "line": 120,
      "description": "优秀的错误处理"
    }
  ],
  "recommendations": [
    "修复 SQL 注入漏洞",
    "添加输入验证",
    "完善单元测试"
  ]
}
```

### Markdown 格式报告

```markdown
# 代码审查报告

## PR 信息
- **PR ID**: 123
- **标题**: Feature: Add user authentication
- **作者**: @developer
- **分支**: feature/auth → main
- **变更**: 3 个文件，+135 / -22 行

## 总体评分: 75/100 ⭐⭐⭐

### 评分详情
- 代码质量: 85/100 ✅
- 安全性: 60/100 ⚠️
- 性能: 75/100 ✅
- 可维护性: 80/100 ✅

## 🔴 高优先级问题（1）

### 1. SQL 注入漏洞
- **文件**: `src/auth/login.go:45`
- **类别**: security
- **问题**: 直接拼接用户输入到 SQL 语句
- **代码**:
  ```go
  query := "SELECT * FROM users WHERE username = '" + username + "'"
  ```
- **建议**: 使用参数化查询或 ORM

## ⭐ 优秀实践（1）

### 1. 优秀的错误处理
- **文件**: `src/auth/user.go:120`
- **描述**: 完善的错误处理和日志记录

## 💡 改进建议

1. 修复 SQL 注入漏洞
2. 添加输入验证
3. 完善单元测试

## 📝 总结

代码整体质量良好，但存在 1 个需要立即修复的安全问题。建议修复后再合并。

**审查结果**: ⚠️ 建议修改后合并

---
*报告生成时间: 2026-06-12 10:30:00 UTC*
*审查工具: gitlink-code-review v1.0.0*
```

## 🎯 审查标准

### 评分标准

| 分数范围 | 等级 | 合并建议 |
|---------|------|---------|
| 90-100 | ⭐⭐⭐⭐⭐ 优秀 | 可以直接合并 |
| 75-89 | ⭐⭐⭐⭐ 良好 | 建议合并 |
| 60-74 | ⭐⭐⭐ 一般 | 需要改进 |
| < 60 | ⭐⭐ 较差 | 不建议合并 |

### 问题优先级

| 优先级 | 图标 | 合并影响 |
|--------|------|---------|
| CRITICAL | 🚨 | 阻止合并 |
| HIGH | 🔴 | 强烈建议修复 |
| MEDIUM | ⚠️ | 建议修复 |
| LOW | ℹ️ | 可选修复 |

## 💡 最佳实践

### 1. 定期审查

- PR 创建后 24 小时内完成初审
- PR 更新后及时审查新代码
- 合并前进行最终审查

### 2. 平衡严格与灵活

- 核心模块严格审查
- 工具函数适度审查
- 文档和配置文件宽松审查

### 3. 建设性反馈

- 指出问题的同时提供解决方案
- 认可优秀的代码实践
- 解释为什么需要修改

## 🔧 自动化脚本

完整的审查脚本：

```bash
#!/bin/bash
# comprehensive-review.sh - 全面代码审查脚本

set -e

PR_ID=${1:-123}
OWNER=${2:-"myuser"}
REPO=${3:-"myrepo"}

echo "=== 开始全面审查 PR #$PR_ID ==="

# 步骤 1：获取数据
echo "步骤 1：获取 PR 数据..."
gitlink-cli pr +view --id $PR_ID --format json > pr_info.json
gitlink-cli pr +files --id $PR_ID --format json > pr_files.json
gitlink-cli pr +diff --id $PR_ID --format json > pr_diff.json

# 步骤 2：验证数据
echo "步骤 2：验证数据..."
if [ "$(cat pr_info.json | jq '.ok')" != "true" ]; then
    echo "错误：无法获取 PR 信息"
    exit 1
fi

# 步骤 3：组织分析数据
echo "步骤 3：组织分析数据..."
cat > analysis_input.json <<EOF
{
  "pr_info": $(cat pr_info.json | jq '.data'),
  "files": $(cat pr_files.json | jq '.data.files'),
  "diff": $(cat pr_diff.json | jq -r '.data.diff')
}
EOF

# 步骤 4：AI 分析
echo "步骤 4：AI 分析（需要 Claude Code 或 API）..."
# 这里调用 AI 分析工具
# claude-code-analyze analysis_input.json > analysis_result.json

# 步骤 5：生成报告
echo "步骤 5：生成审查报告..."
# cat analysis_result.json | jq -r '.content' > review_report.json
# cat analysis_result.json | jq -r '.content' > review_report.md

# 步骤 6：输出报告
echo "步骤 6：输出审查报告..."
# cat review_report.md

echo "=== 审查完成 ==="
```

使用方法：
```bash
chmod +x comprehensive-review.sh
./comprehensive-review.sh 123 myuser myrepo
```

## 📚 相关文档

- [基础审查工作流](basic-review-workflow.md) - 快速代码审查
- [自动审查工作流](auto-review-pr.md) - AI 自动审查
- [代码质量检查](../references/code-review-quality.md) - 质量分析详解
- [安全性检查](../references/code-review-security.md) - 安全分析详解

---

*最后更新: 2026-06-12*
