# Bug 管理系统接口文档

## 一、接口清单

| 接口路径               | 方法   | 权限            | 说明         |
| ------------------ | ---- | ------------- | ---------- |
| `/bug/list`        | GET  | `bug:list`    | Bug 列表（分页） |
| `/bug/detail`      | GET  | `bug:detail`  | Bug 详情     |
| `/bug/create`      | POST | `bug:create`  | 创建 Bug     |
| `/bug/update`      | POST | `bug:update`  | 更新 Bug     |
| `/bug/delete`      | POST | `bug:delete`  | 删除 Bug     |
| `/bug/comment/add` | POST | `bug:comment` | 添加评论       |
| `/bug/stats`       | GET  | `bug:stats`   | Bug 统计     |
| `/bug/upload`      | POST | `bug:create`  | 图片上传       |

***

## 二、接口详细说明

### 1. Bug 列表

**GET /bug/list**

查询 Bug 列表，支持多维度筛选。

#### 请求参数

| 参数名                       | 类型     | 必填 | 说明         |
| ------------------------- | ------ | -- | ---------- |
| productId / product\_id   | Number | 否  | 产品 ID      |
| projectId / project\_id   | Number | 否  | 项目 ID      |
| moduleId / module\_id     | Number | 否  | 模块 ID      |
| bugType / bug\_type       | Number | 否  | Bug 类型     |
| severity                  | Number | 否  | 严重程度       |
| priority                  | Number | 否  | 优先级        |
| status                    | Number | 否  | 状态         |
| assigneeId / assignee\_id | Number | 否  | 负责人 ID     |
| keyword                   | String | 否  | 关键词（标题/描述） |
| pageNo / page             | Number | 否  | 页码，默认 1    |
| pageSize / size           | Number | 否  | 每页数量，默认 20 |

#### 响应示例

```json
{
  "code": 20000,
  "message": "success",
  "data": {
    "list": [
      {
        "id": 1,
        "bug_key": "BUG-001",
        "title": "登录页面无法加载",
        "description": "点击登录按钮后页面无响应",
        "bug_type": 1,
        "severity": 1,
        "priority": 1,
        "status": 2,
        "assignee_id": 1,
        "reporter_id": 2,
        "product_id": 1,
        "project_id": 1,
        "module_id": 1,
        "case_id": 101,
        "plan_id": 5,
        "environment": "test",
        "created_time": "2026-05-06 10:00:00",
        "updated_time": "2026-05-06 11:00:00"
      }
    ],
    "total": 1
  }
}
```

***

### 2. Bug 详情

**GET /bug/detail**

查询 Bug 详细信息，包含评论和历史记录。

#### 请求参数

| 参数名        | 类型     | 必填 | 说明     |
| ---------- | ------ | -- | ------ |
| bugId / id | Number | 是  | Bug ID |

#### 响应示例

```json
{
  "code": 20000,
  "message": "success",
  "data": {
    "id": 1,
    "bug_key": "BUG-001",
    "title": "登录页面无法加载",
    "description": "点击登录按钮后页面无响应...",
    "bug_type": 1,
    "severity": 1,
    "priority": 1,
    "status": 2,
    "assignee_id": 1,
    "reporter_id": 2,
    "product_id": 1,
    "project_id": 1,
    "module_id": 1,
    "case_id": 101,
    "plan_id": 5,
    "environment": "test",
    "steps": "1. 打开登录页面\n2. 输入用户名密码\n3. 点击登录",
    "attachments": [],
    "created_time": "2026-05-06 10:00:00",
    "updated_time": "2026-05-06 11:00:00",
    "comments": [
      {
        "id": 1,
        "bug_id": 1,
        "content": "已收到，正在处理",
        "user_id": 1,
        "created_time": "2026-05-06 10:30:00"
      }
    ],
    "history": [
      {
        "id": 1,
        "bug_id": 1,
        "field_name": "status",
        "old_value": "0",
        "new_value": "2",
        "operator_id": 1,
        "created_time": "2026-05-06 10:30:00"
      }
    ]
  }
}
```

***

### 3. 创建 Bug

**POST /bug/create**

创建新的 Bug 报告。

#### 请求参数

| 参数名                     | 类型     | 必填 | 说明          |
| ----------------------- | ------ | -- | ----------- |
| title                   | String | 是  | Bug 标题      |
| description             | String | 否  | Bug 描述      |
| bugType / bug\_type     | Number | 否  | Bug 类型，默认 1 |
| severity                | Number | 否  | 严重程度，默认 2   |
| priority                | Number | 否  | 优先级，默认 2    |
| productId / product\_id | Number | 是  | 产品 ID       |
| projectId / project\_id | Number | 是  | 项目 ID       |
| moduleId / module\_id   | Number | 否  | 模块 ID       |
| caseId / case\_id       | Number | 否  | 关联测试用例 ID   |
| planId / plan\_id       | Number | 否  | 关联测试计划 ID   |
| environment             | String | 否  | 测试环境        |
| steps                   | String | 否  | 复现步骤        |

#### 请求体示例

```json
{
  "title": "登录页面无法加载",
  "description": "点击登录按钮后页面无响应",
  "bugType": 1,
  "severity": 1,
  "priority": 1,
  "productId": 1,
  "projectId": 1,
  "moduleId": 1,
  "environment": "test",
  "steps": "1. 打开登录页面\n2. 输入用户名密码\n3. 点击登录"
}
```

#### 响应示例

```json
{
  "code": 20000,
  "message": "success",
  "data": {
    "id": 1
  }
}
```

***

### 4. 更新 Bug

**POST /bug/update**

更新 Bug 信息。

#### 请求参数

| 参数名                       | 类型     | 必填 | 说明        |
| ------------------------- | ------ | -- | --------- |
| bugId / id                | Number | 是  | Bug ID    |
| title                     | String | 否  | Bug 标题    |
| description               | String | 否  | Bug 描述    |
| bugType / bug\_type       | Number | 否  | Bug 类型    |
| severity                  | Number | 否  | 严重程度      |
| priority                  | Number | 否  | 优先级       |
| status                    | Number | 否  | 状态        |
| assigneeId / assignee\_id | Number | 否  | 负责人 ID    |
| moduleId / module\_id     | Number | 否  | 模块 ID     |
| caseId / case\_id         | Number | 否  | 关联测试用例 ID |
| planId / plan\_id         | Number | 否  | 关联测试计划 ID |
| environment               | String | 否  | 测试环境      |
| steps                     | String | 否  | 复现步骤      |

#### 请求体示例

```json
{
  "bugId": 1,
  "status": 3,
  "assigneeId": 1
}
```

#### 响应示例

```json
{
  "code": 20000,
  "message": "success",
  "data": {
    "id": 1
  }
}
```

***

### 5. 删除 Bug

**POST /bug/delete**

软删除 Bug。

#### 请求参数

| 参数名        | 类型     | 必填 | 说明     |
| ---------- | ------ | -- | ------ |
| bugId / id | Number | 是  | Bug ID |

#### 请求体示例

```json
{
  "bugId": 1
}
```

#### 响应示例

```json
{
  "code": 20000,
  "message": "success",
  "data": {
    "id": 1
  }
}
```

***

### 6. 添加评论

**POST /bug/comment/add**

为 Bug 添加评论。

#### 请求参数

| 参数名        | 类型     | 必填 | 说明     |
| ---------- | ------ | -- | ------ |
| bugId / id | Number | 是  | Bug ID |
| content    | String | 是  | 评论内容   |

#### 请求体示例

```json
{
  "bugId": 1,
  "content": "已收到，正在处理"
}
```

#### 响应示例

```json
{
  "code": 20000,
  "message": "success",
  "data": {
    "id": 1
  }
}
```

***

### 7. Bug 统计

**GET /bug/stats**

获取 Bug 统计信息。

#### 请求参数

| 参数名                     | 类型     | 必填 | 说明    |
| ----------------------- | ------ | -- | ----- |
| productId / product\_id | Number | 否  | 产品 ID |
| projectId / project\_id | Number | 否  | 项目 ID |

#### 响应示例

```json
{
  "code": 20000,
  "message": "success",
  "data": {
    "total": 100,
    "new": 10,
    "pending": 20,
    "in_progress": 30,
    "resolved": 25,
    "closed": 10,
    "rejected": 5,
    "by_severity": {
      "critical": 15,
      "major": 30,
      "medium": 40,
      "minor": 15
    },
    "by_priority": {
      "high": 40,
      "medium": 45,
      "low": 15
    },
    "by_type": {
      "functional": 40,
      "ui": 25,
      "performance": 15,
      "security": 10,
      "compatibility": 10
    }
  }
}
```

***

### 8. 图片上传

**POST /bug/upload**

上传 Bug 相关图片，返回图片访问 URL。

#### 请求参数

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| file | File | 是 | 图片文件 |

#### 支持的文件格式

- png
- jpg / jpeg
- gif
- bmp

#### 调用示例（curl）

```bash
curl -X POST "http://39.170.26.156:8888/it/api/bug/upload" \
  -H "accessToken: your_token" \
  -F "file=@screenshot.png"
```

#### 响应示例

```json
{
  "code": 20000,
  "message": "success",
  "data": {
    "url": "http://39.170.26.156:8888/uploads/bug/bug-20260506100000-abc12345.png"
  }
}
```

#### 错误响应

```json
{
  "code": 40009,
  "message": "未找到上传文件"
}
```

```json
{
  "code": 40009,
  "message": "不支持的文件格式，仅支持：png, jpg, jpeg, gif, bmp"
}
```

***

## 三、枚举值说明

### Bug 类型 (bug\_type)

| 值 | 名称    | 说明         |
| - | ----- | ---------- |
| 1 | 功能缺陷  | 核心功能不能正常工作 |
| 2 | UI 问题 | 界面显示、交互问题  |
| 3 | 性能问题  | 响应慢、资源占用高  |
| 4 | 安全漏洞  | 安全相关问题     |
| 5 | 兼容性问题 | 浏览器/平台兼容问题 |

### 严重程度 (severity)

| 值 | 名称 | 说明        |
| - | -- | --------- |
| 1 | 致命 | 系统崩溃、数据丢失 |
| 2 | 严重 | 核心功能不可用   |
| 3 | 中等 | 功能受限但可用   |
| 4 | 轻微 | 小问题，不影响使用 |

### 优先级 (priority)

| 值 | 名称 | 说明     |
| - | -- | ------ |
| 1 | 高  | 需要立即处理 |
| 2 | 中  | 按计划处理  |
| 3 | 低  | 空闲时处理  |

### 状态 (status)

| 值 | 名称  | 说明            |
| - | --- | ------------- |
| 0 | 新建  | Bug 刚创建，待审核   |
| 1 | 待处理 | 已确认，等待分配      |
| 2 | 进行中 | 已分配，正在修复      |
| 3 | 已解决 | 修复完成，待验证      |
| 4 | 已关闭 | 验证通过，已关闭      |
| 5 | 已拒绝 | 非 Bug 或重复，已拒绝 |

***

## 四、状态流转规则

```
                    ┌─────────────────┐
                    │    0-新建       │
                    └────────┬────────┘
                             │
              ┌──────────────┴──────────────┐
              ▼                             ▼
       ┌─────────────┐              ┌─────────────┐
       │ 1-待处理    │              │ 5-已拒绝    │
       └──────┬──────┘              └─────────────┘
              │
              ▼
       ┌─────────────┐
       │ 2-进行中    │
       └──────┬──────┘
              │
              ▼
       ┌─────────────┐
       │ 3-已解决    │
       └──────┬──────┘
              │
              ▼
       ┌─────────────┐
       │ 4-已关闭    │
       └─────────────┘
```

**转换规则：**

- 新建 → 待处理 / 已拒绝
- 待处理 → 进行中 / 已拒绝
- 进行中 → 已解决 / 待处理
- 已解决 → 已关闭 / 待处理
- 已关闭 → 待处理（重新打开）
- 已拒绝 → 待处理（重新打开）

***

## 五、通用状态码

| 状态码   | 说明           |
| ----- | ------------ |
| 20000 | 成功           |
| 40004 | 未登录或缺少 token |
| 40009 | 参数错误或新增失败    |
| 40011 | 未查询到对应记录     |
| 40012 | 更新或删除失败      |
| 40013 | 权限不足         |

***

## 六、认证方式

所有接口（除登录/注册外）需在请求头携带 `accessToken`：

```bash
curl -H "accessToken: your_token" http://localhost:8081/it/api/bug/list
```

***

## 七、权限配置

| 权限编码        | 权限名称      |
| ----------- | --------- |
| bug:list    | 查看 Bug 列表 |
| bug:detail  | 查看 Bug 详情 |
| bug:create  | 创建 Bug    |
| bug:update  | 更新 Bug    |
| bug:delete  | 删除 Bug    |
| bug:comment | 添加评论      |
| bug:stats   | 查看统计      |