540 lines
12 KiB
Markdown
540 lines
12 KiB
Markdown
# 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 | 查看统计 |
|
||
|