log-center/docs/bug-severity-grading-system.md

# Bug 严重等级分级系统

> 文档版本: v1.0
> 创建日期: 2026-02-25
> 用途: AI 自动评估 Bug 严重程度，决定是否需要人工审核

---

## 📊 分级概述

### 等级范围

**1-10 级**，数字越大表示风险越高

| 等级 | 风险级别 | 审核方式 | 典型场景 |
|------|----------|----------|----------|
| **10** | 🔴 极高风险 | 必须人工审核 | 支付、认证、数据泄露 |
| **9** | 🔴 极高风险 | 必须人工审核 | 核心业务逻辑 |
| **8** | 🟠 高风险 | 人工审核（默认阈值） | 复杂业务流程 |
| **7** | 🟠 高风险 | 人工审核 | 数据库操作 |
| **6** | 🟡 中风险 | 自动合并 | 一般业务逻辑 |
| **5** | 🟡 中风险 | 自动合并 | API 参数验证 |
| **4** | 🟢 低风险 | 自动合并 | 非关键功能 |
| **3** | 🟢 低风险 | 自动合并 | UI 显示问题 |
| **2** | 🔵 极低风险 | 自动合并 | 语法错误 |
| **1** | 🔵 极低风险 | 自动合并 | 代码格式 |

### 默认审核阈值

```python
# 配置项
severity_threshold_for_review: int = 8  # ≥8 级需要人工审核
```

---

## 🎯 详细分级标准

### Level 10：极高风险（必须人工审核）

#### 特征

**涉及资金安全：**
- 支付、充值、提现相关代码
- 订单金额计算逻辑
- 优惠券、折扣计算
- 余额、积分操作

**涉及数据安全：**
- 用户认证（登录、注册、Token）
- 权限控制（admin 权限、角色管理）
- 敏感数据加密/解密
- 数据库备份/恢复

**系统稳定性：**
- 可能导致服务不可用
- 可能导致系统崩溃
- 数据库连接池管理

#### 示例

```python
# ❌ 极高风险：支付金额计算错误
def calculate_order_price(items):
    total = 0
    for item in items:
        total += item.price * item.quantity  # Bug: 未考虑优惠券
    return total

# ❌ 极高风险：权限验证绕过
def admin_required(func):
    def wrapper(request):
        # Bug: 缺少权限检查
        return func(request)
    return wrapper
```

#### AI 判定输出示例

```json
{
  "severity_level": 10,
  "severity_label": "极高风险",
  "risk_category": "资金安全",
  "reasoning": [
    "涉及订单金额计算逻辑",
    "错误可能导致用户支付金额错误",
    "修改了 payment_service.py 核心支付模块",
    "测试覆盖不足，缺少边界条件测试"
  ],
  "recommendation": "必须人工审核并进行充分测试后才能上线",
  "business_impact": "可能导致财务损失和用户投诉",
  "rollback_difficulty": "困难"
}
```

---

### Level 8-9：高风险（需要人工审核）

#### 特征

**核心业务逻辑：**
- 用户绑定设备流程
- 智能体（Spirit）创建/修改
- 设备状态流转（in_stock → out_stock → bound）
- 批次管理逻辑

**数据一致性：**
- 数据库事务处理
- 外键关联操作
- 批量更新操作
- 数据迁移脚本

**复杂业务流程：**
- 多步骤业务流程
- 涉及多个模块交互
- 状态机流转逻辑

#### 示例

```python
# ⚠️ 高风险：设备绑定逻辑
def bind_device_to_user(device_id, user_id):
    device = Device.objects.get(id=device_id)
    # Bug: 未检查设备是否已被绑定
    device.owner_id = user_id
    device.status = "bound"
    device.save()

# ⚠️ 高风险：批量更新
def batch_update_devices(device_ids, **kwargs):
    # Bug: 缺少事务保护
    for device_id in device_ids:
        device = Device.objects.get(id=device_id)
        for key, value in kwargs.items():
            setattr(device, key, value)
        device.save()
```

#### AI 判定输出示例

```json
{
  "severity_level": 8,
  "severity_label": "高风险",
  "risk_category": "核心业务逻辑",
  "reasoning": [
    "修改了设备绑定流程，属于核心业务",
    "未充分检查边界条件（设备已绑定的情况）",
    "修改涉及 Device 模型的状态流转",
    "测试用例覆盖了基本场景，但缺少异常场景测试"
  ],
  "recommendation": "建议人工审核业务逻辑，并补充异常场景测试",
  "business_impact": "可能导致设备重复绑定或状态异常",
  "rollback_difficulty": "中等"
}
```

---

### Level 5-7：中风险（自动合并，但需关注）

#### 特征

**一般业务逻辑：**
- 非核心功能的实现
- API 参数验证和错误处理
- 数据查询和过滤逻辑
- 边界条件处理

**API 层问题：**
- 请求参数验证
- 响应格式化
- 错误码定义
- 分页逻辑

#### 示例

```python
# 🟡 中风险：参数验证
def get_user_devices(request):
    user_id = request.GET.get("user_id")
    # Bug: 未验证 user_id 格式
    devices = Device.objects.filter(owner_id=user_id)
    return JsonResponse({"devices": list(devices.values())})

# 🟡 中风险：错误处理
def create_spirit(name, avatar):
    # Bug: 缺少异常捕获
    spirit = Spirit.objects.create(name=name, avatar=avatar)
    return spirit
```

#### AI 判定输出示例

```json
{
  "severity_level": 6,
  "severity_label": "中风险",
  "risk_category": "API 参数验证",
  "reasoning": [
    "修改了 API 参数验证逻辑",
    "未影响核心业务流程",
    "测试覆盖充分，包含边界条件",
    "修改范围小，仅涉及单个 API 端点"
  ],
  "recommendation": "可以自动合并，建议后续监控生产环境日志",
  "business_impact": "可能导致参数错误时返回不友好的错误信息",
  "rollback_difficulty": "容易"
}
```

---

### Level 3-4：低风险（自动合并）

#### 特征

**UI 和展示：**
- 前端显示问题
- 错误提示文案
- 日志输出格式

**非关键功能：**
- 辅助工具函数
- 测试代码修复
- 文档更新

#### 示例

```python
# 🟢 低风险：日志输出
def process_data(data):
    # Bug: 日志格式错误
    logger.info(f"Processing data: {data}")  # 修复：添加时间戳
    return process(data)

# 🟢 低风险：错误提示
def validate_input(value):
    if not value:
        # Bug: 错误提示不友好
        raise ValueError("Invalid input")  # 修复：改为 "请输入有效的值"
```

#### AI 判定输出示例

```json
{
  "severity_level": 3,
  "severity_label": "低风险",
  "risk_category": "日志和提示",
  "reasoning": [
    "仅修改了日志输出格式",
    "不影响业务逻辑",
    "不涉及数据操作",
    "测试通过"
  ],
  "recommendation": "可以自动合并，无需人工审核",
  "business_impact": "无明显影响",
  "rollback_difficulty": "容易"
}
```

---

### Level 1-2：极低风险（自动合并）

#### 特征

**语法和格式：**
- Import 语句错误
- 拼写错误
- 代码格式问题（空格、换行）
- 注释错误

**构建和依赖：**
- requirements.txt 更新
- Dockerfile 格式修复
- CI/CD 配置优化

#### 示例

```python
# 🔵 极低风险：Import 错误
# Bug: from django.contrib.auth import User
from django.contrib.auth.models import User  # 修复

# 🔵 极低风险：拼写错误
def get_devcie_list():  # Bug: devcie → device
    pass
```

#### AI 判定输出示例

```json
{
  "severity_level": 1,
  "severity_label": "极低风险",
  "risk_category": "语法错误",
  "reasoning": [
    "仅修复了 import 语句",
    "不涉及业务逻辑",
    "属于纯语法问题",
    "测试全部通过"
  ],
  "recommendation": "自动合并，无风险",
  "business_impact": "无",
  "rollback_difficulty": "容易"
}
```

---

## 🤖 AI 分级判断实现

### Claude 评估 Prompt 模板

**文件位置：** `log_center/repair_agent/prompts/severity_assessment.txt`

```markdown
你是一个 Bug 严重等级评估专家。请根据以下信息评估 Bug 的严重等级（1-10 级）。

## Bug 信息

**错误类型:** {error_type}
**错误消息:** {error_message}
**文件路径:** {file_path}
**堆栈信息:**
```
{stack_trace}
```

**修复内容:**
- 修改文件: {modified_files}
- 代码 Diff:
```diff
{diff}
```

**测试结果:** {test_passed}

## 评估标准

### Level 10（极高风险）
- 涉及支付、充值、提现等资金交易
- 涉及用户认证、权限控制的核心逻辑
- 可能导致数据泄露或安全漏洞
- 可能导致系统崩溃或服务不可用
- **关键词:** payment, auth, security, admin, permission, password, token, encrypt, decrypt

### Level 8-9（高风险）
- 核心业务逻辑错误（设备绑定、智能体管理）
- 数据库事务处理错误
- 复杂业务流程错误
- 影响多个模块的错误
- **关键词:** bind, device, spirit, transaction, batch, workflow, state_machine

### Level 5-7（中风险）
- 一般业务逻辑错误
- API 参数验证错误
- 非关键功能的错误
- **关键词:** validate, filter, query, api, endpoint

### Level 3-4（低风险）
- UI 显示问题
- 日志输出错误
- 测试代码错误
- **关键词:** ui, display, log, test, format

### Level 1-2（极低风险）
- 语法错误（import、拼写）
- 代码格式问题
- 注释错误
- **关键词:** import, syntax, format, comment, typo

## 判断依据

请综合考虑以下因素：

1. **业务重要性** (权重 30%)
   - 是否涉及核心业务流程？(设备管理、智能体、用户绑定)
   - 是否影响用户核心功能？

2. **安全风险** (权重 30%)
   - 是否涉及敏感数据？(用户信息、Token)
   - 是否涉及资金相关？(虽然当前项目可能不涉及)
   - 是否可能导致权限绕过？

3. **影响范围** (权重 20%)
   - 影响多少用户？(全部/部分/极少数)
   - 影响多少模块？(单模块/多模块)
   - 是否影响数据一致性？

4. **修复质量** (权重 10%)
   - 测试是否充分？
   - 修复方案是否合理？
   - 是否引入新的风险？

5. **回滚难度** (权重 10%)
   - 如果出错，回滚是否容易？
   - 是否涉及数据迁移？

## 输出格式

请严格按照以下 JSON 格式输出（在最后一行）：

```json
{
  "severity_level": <1-10 的整数>,
  "severity_label": "<极低风险|低风险|中风险|高风险|极高风险>",
  "risk_category": "<资金安全|数据安全|核心业务逻辑|一般业务|UI展示|语法问题|其他>",
  "reasoning": [
    "<理由1：为什么判定为该级别>",
    "<理由2：关键风险点>",
    "<理由3：测试覆盖情况>",
    "<理由4：建议>"
  ],
  "recommendation": "<是否建议人工审核的具体说明>",
  "key_files": ["<核心修改文件列表>"],
  "business_impact": "<对业务的影响描述，50字以内>",
  "rollback_difficulty": "<容易|中等|困难>"
}
```

**重要提示：**
- 如果涉及 `payment`, `auth`, `admin`, `permission` 等关键词，最低 8 级
- 如果修改了 `models.py` 且涉及核心业务模型（Device, Spirit, User），最低 7 级
- 如果测试失败或测试覆盖不足，等级 +1
- 如果只是语法错误（ImportError, SyntaxError）且测试通过，最高 2 级

请立即开始评估，最后一行输出完整的 JSON。
```

---

## 💻 完整技术实现代码

### 文件清单

```
log_center/repair_agent/
├── agent/
│   ├── claude_service.py    # 新增 assess_bug_severity() 方法
│   ├── core.py               # 修改修复流程，集成分级判断
│   └── git_manager.py        # 新增 merge_pull_request() 方法
├── models/
│   └── bug.py                # RepairReport 增加严重等级字段
├── config/
│   └── settings.py           # 新增分级相关配置
└── prompts/
    └── severity_assessment.txt  # Claude 评估 Prompt
```

### 详细代码实现

见主文档：[bug-repair-workflow-optimization.md](./bug-repair-workflow-optimization.md) 中的 "技术实施" 章节

---

## 📊 修复报告示例

### 高风险 Bug 修复报告

```json
{
  "error_log_id": 123,
  "project_id": "rtc_backend",
  "status": "PENDING_REVIEW",
  "severity_level": 9,
  "severity_label": "高风险",
  "risk_category": "核心业务逻辑",
  "severity_reasoning": [
    "修改了设备绑定流程 (bind_device_to_user)，属于核心业务",
    "涉及 Device 模型的状态流转 (in_stock → bound)",
    "未充分检查边界条件（设备已被其他用户绑定的情况）",
    "测试覆盖了基本场景，但缺少冲突场景测试"
  ],
  "recommendation": "建议人工审核业务逻辑，补充异常场景测试后再合并",
  "business_impact": "可能导致设备重复绑定，影响用户使用",
  "rollback_difficulty": "中等",
  "modified_files": ["apps/device/views.py", "apps/device/models.py"],
  "test_passed": true,
  "pr_url": "https://gitea.xxx/rtc/rtc_backend/pulls/45"
}
```

### 低风险 Bug 修复报告

```json
{
  "error_log_id": 124,
  "project_id": "rtc_backend",
  "status": "MERGED",
  "severity_level": 2,
  "severity_label": "极低风险",
  "risk_category": "语法问题",
  "severity_reasoning": [
    "仅修复了 import 语句路径错误",
    "不涉及任何业务逻辑",
    "属于纯语法问题 (ImportError)",
    "测试全部通过"
  ],
  "recommendation": "可以自动合并，无需人工审核",
  "business_impact": "无",
  "rollback_difficulty": "容易",
  "modified_files": ["apps/device/serializers.py"],
  "test_passed": true,
  "pr_url": "https://gitea.xxx/rtc/rtc_backend/pulls/46",
  "auto_merged": true
}
```

---

## 🔄 完整工作流程

```
┌─────────────────────────────────────────────────────────┐
│ 1. Agent 扫描发现 Bug                                     │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│ 2. AI 修复代码 (Claude Code CLI)                         │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│ 3. 运行测试                                               │
│    ├─ 测试通过 → 继续                                    │
│    └─ 测试失败 → 下一轮重试                              │
└─────────────────────────────────────────────────────────┘
                        ↓
┌─────────────────────────────────────────────────────────┐
│ 4. AI 评估严重等级 (1-10)                                │
│    - 分析错误类型                                        │
│    - 评估业务影响                                        │
│    - 检查修改范围                                        │
│    - 综合判定等级                                        │
└─────────────────────────────────────────────────────────┘
                        ↓
                    判定等级？
                    ↙         ↘
    ┌──────────────┐         ┌──────────────┐
    │ ≥8 级（高风险）│         │ <8 级（低风险）│
    └──────────────┘         └──────────────┘
            ↓                         ↓
    ┌──────────────┐         ┌──────────────┐
    │ 创建 PR       │         │ 创建 PR       │
    │ 标注高风险    │         │ 标注低风险    │
    └──────────────┘         └──────────────┘
            ↓                         ↓
    ┌──────────────┐         ┌──────────────┐
    │ 状态 →        │         │ 自动合并 PR   │
    │ PENDING_REVIEW│         └──────────────┘
    └──────────────┘                 ↓
            ↓                 ┌──────────────┐
    ┌──────────────┐         │ 状态 → MERGED │
    │ 等待人工审核  │         └──────────────┘
    └──────────────┘                 ↓
            ↓                         │
    ┌──────────────┐                 │
    │ 人工点击 Merge│                 │
    └──────────────┘                 │
            ↓                         │
    ┌──────────────┐                 │
    │ 状态 → MERGED │◀────────────────┘
    └──────────────┘
            ↓
    ┌──────────────┐
    │ CI/CD 部署    │
    └──────────────┘
            ↓
    ┌──────────────┐
    │状态 → DEPLOYED│
    └──────────────┘
```

---

## 📈 预期效果

### 效率提升

| 场景 | 当前方式 | 优化后 |
|------|----------|--------|
| **低风险 Bug (1-7级)** | 每个都需人工审核 | 自动合并，秒级完成 |
| **高风险 Bug (8-10级)** | 人工审核 | 人工审核（保持不变） |
| **整体效率** | 100% 人工介入 | 70% 自动处理 + 30% 人工审核 |

### 预估比例（基于典型项目）

```
低风险 Bug (1-7级):  约 70%  → 自动合并
高风险 Bug (8-10级): 约 30%  → 人工审核
```

### 人工工作量

```
假设每天 20 个 Bug：
- 优化前：20 个 × 3 分钟/个 = 60 分钟
- 优化后：6 个 × 3 分钟/个 = 18 分钟

节省时间：70%
```

---

## ⚙️ 配置示例

```python
# .env 或 settings.py

# Bug 严重等级评估
SEVERITY_THRESHOLD_FOR_REVIEW=8     # ≥8 级需要人工审核
ENABLE_AUTO_MERGE=true               # 启用低风险 PR 自动合并

# 严格模式（可选）
STRICT_MODE=false                    # true: ≥6 级就需审核
```

---

## 📋 FAQ

### Q1: AI 评估等级不准确怎么办？

**A:** 有以下保障措施：
1. **阈值可调整**：默认 ≥8 级需审核，可根据实际情况调整为 6 或 7
2. **人工复核**：在 Web 界面可以看到 AI 的判定理由，如果不合理可以手动调整
3. **持续优化**：收集误判案例，优化 Prompt 模板
4. **保守策略**：当 AI 无法评估时，默认设为 6 级（中风险），偏向安全

### Q2: 自动合并的 PR 出错了怎么办？

**A:**
1. **快速回滚**：在 Gitea 可以一键 revert commit
2. **降级处理**：临时关闭自动合并，所有 PR 都需人工审核
3. **监控告警**：部署后持续监控错误日志，发现问题立即回滚

### Q3: 能否针对不同项目设置不同的阈值？

**A:** 可以！配置支持项目级覆盖：

```python
# 默认阈值
severity_threshold_for_review: int = 8

# 项目级覆盖
project_severity_thresholds: dict = {
    "rtc_backend": 7,  # 后端更谨慎
    "rtc_web": 8,      # 前端正常
    "airhub_app": 9,   # 移动端更宽松
}
```

---

## 🎯 下一步

1. ✅ **实施 Phase 1**：实现 AI 分级评估功能
2. ✅ **测试验证**：运行 50+ Bug 修复，验证分级准确性
3. ✅ **调优阈值**：根据实际情况调整默认阈值
4. ✅ **上线监控**：部署后持续监控自动合并的 PR 质量

---

**维护信息：**
- 创建：2026-02-25
- 作者：AI + 开发团队
- 审核：待审核