299 lines
6.4 KiB
Markdown
299 lines
6.4 KiB
Markdown
# API 接口说明 - 问题反馈功能
|
||
|
||
## 问题反馈相关接口
|
||
|
||
### 1. 创建反馈
|
||
|
||
**接口地址:** `POST /feedback`
|
||
|
||
**请求头:**
|
||
```
|
||
Authorization: your-token（可选，支持匿名提交）
|
||
```
|
||
|
||
**请求参数:**
|
||
```json
|
||
{
|
||
"feedbackType": "功能建议", // 问题类型（必填）
|
||
"title": "希望增加夜间模式", // 问题标题（必填）
|
||
"content": "详细描述...", // 问题描述（可选）
|
||
"contact": "user@example.com" // 联系方式（可选）
|
||
}
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "反馈提交成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**说明:**
|
||
- 支持匿名提交，如果已登录会自动关联用户ID
|
||
- 问题类型建议：功能建议、Bug反馈、使用问题、其他
|
||
- 联系方式用于后续沟通，建议填写邮箱或手机号
|
||
- 反馈默认状态为"待处理"
|
||
|
||
---
|
||
|
||
### 2. 查询当前用户的反馈列表
|
||
|
||
**接口地址:** `GET /feedback/my`
|
||
|
||
**请求头:**
|
||
```
|
||
Authorization: your-token
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": [
|
||
{
|
||
"id": 1,
|
||
"userId": 1,
|
||
"feedbackType": "功能建议",
|
||
"title": "希望增加夜间模式",
|
||
"content": "详细描述...",
|
||
"contact": "user@example.com",
|
||
"status": 0,
|
||
"createTime": "2025-01-01T12:00:00",
|
||
"updateTime": "2025-01-01T12:00:00"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**说明:**
|
||
- 需要登录
|
||
- 返回当前用户提交的所有反馈
|
||
- 按创建时间倒序排序
|
||
|
||
---
|
||
|
||
### 3. 根据ID查询反馈详情
|
||
|
||
**接口地址:** `GET /feedback/{id}`
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"id": 1,
|
||
"userId": 1,
|
||
"feedbackType": "功能建议",
|
||
"title": "希望增加夜间模式",
|
||
"content": "详细描述...",
|
||
"contact": "user@example.com",
|
||
"status": 0,
|
||
"createTime": "2025-01-01T12:00:00",
|
||
"updateTime": "2025-01-01T12:00:00"
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明:**
|
||
- 不需要登录
|
||
- 根据反馈ID查询详情
|
||
|
||
---
|
||
|
||
### 4. 分页查询反馈列表
|
||
|
||
**接口地址:** `GET /feedback/page`
|
||
|
||
**请求参数:**
|
||
```
|
||
current: 当前页码（默认1）
|
||
size: 每页数量（默认10）
|
||
userId: 用户ID（可选，用于筛选指定用户的反馈）
|
||
feedbackType: 问题类型（可选，用于筛选指定类型的反馈）
|
||
status: 状态（可选，用于筛选指定状态的反馈）
|
||
```
|
||
|
||
**请求示例:**
|
||
```
|
||
GET /feedback/page?current=1&size=10&feedbackType=功能建议&status=0
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "success",
|
||
"data": {
|
||
"records": [
|
||
{
|
||
"id": 1,
|
||
"userId": 1,
|
||
"feedbackType": "功能建议",
|
||
"title": "希望增加夜间模式",
|
||
"content": "详细描述...",
|
||
"contact": "user@example.com",
|
||
"status": 0,
|
||
"createTime": "2025-01-01T12:00:00",
|
||
"updateTime": "2025-01-01T12:00:00"
|
||
}
|
||
],
|
||
"total": 100,
|
||
"size": 10,
|
||
"current": 1,
|
||
"pages": 10
|
||
}
|
||
}
|
||
```
|
||
|
||
**说明:**
|
||
- 不需要登录
|
||
- 支持分页和多条件筛选
|
||
- 按创建时间倒序排序
|
||
|
||
---
|
||
|
||
### 5. 更新反馈状态
|
||
|
||
**接口地址:** `PUT /feedback/{id}/status`
|
||
|
||
**请求参数:**
|
||
```
|
||
status: 状态值（0-待处理 1-处理中 2-已完成 3-已关闭）
|
||
```
|
||
|
||
**请求示例:**
|
||
```
|
||
PUT /feedback/1/status?status=1
|
||
```
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "状态更新成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**说明:**
|
||
- 不需要登录
|
||
- 用于管理员更新反馈处理状态
|
||
- 状态说明：
|
||
- 0: 待处理
|
||
- 1: 处理中
|
||
- 2: 已完成
|
||
- 3: 已关闭
|
||
|
||
---
|
||
|
||
### 6. 删除反馈
|
||
|
||
**接口地址:** `DELETE /feedback/{id}`
|
||
|
||
**响应示例:**
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "删除成功",
|
||
"data": null
|
||
}
|
||
```
|
||
|
||
**说明:**
|
||
- 不需要登录
|
||
- 用于管理员删除反馈
|
||
|
||
---
|
||
|
||
## 数据库说明
|
||
|
||
### 反馈表结构
|
||
|
||
**建表 SQL:** `src/main/resources/db/feedback.sql`
|
||
|
||
```sql
|
||
CREATE TABLE `app_feedback` (
|
||
`id` BIGINT(20) NOT NULL AUTO_INCREMENT COMMENT '反馈ID',
|
||
`user_id` BIGINT(20) DEFAULT NULL COMMENT '用户ID',
|
||
`feedback_type` VARCHAR(50) NOT NULL COMMENT '问题类型',
|
||
`title` VARCHAR(200) NOT NULL COMMENT '问题标题',
|
||
`content` TEXT DEFAULT NULL COMMENT '问题描述',
|
||
`contact` VARCHAR(100) DEFAULT NULL COMMENT '联系方式',
|
||
`status` TINYINT(1) DEFAULT 0 COMMENT '处理状态：0-待处理 1-处理中 2-已完成 3-已关闭',
|
||
`create_time` DATETIME DEFAULT NULL COMMENT '创建时间',
|
||
`update_time` DATETIME DEFAULT NULL COMMENT '更新时间',
|
||
PRIMARY KEY (`id`),
|
||
KEY `idx_user_id` (`user_id`),
|
||
KEY `idx_status` (`status`),
|
||
KEY `idx_create_time` (`create_time`)
|
||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='问题反馈表';
|
||
```
|
||
|
||
---
|
||
|
||
## 错误码说明
|
||
|
||
| 错误码 | 说明 |
|
||
|--------|------|
|
||
| 200 | 成功 |
|
||
| 500 | 失败 |
|
||
|
||
---
|
||
|
||
## 开发说明
|
||
|
||
### 代码结构
|
||
|
||
```
|
||
com.corewing.app/
|
||
├── controller/
|
||
│ └── AppFeedbackController.java # 反馈控制器
|
||
├── dto/
|
||
│ └── FeedbackRequest.java # 反馈请求参数
|
||
├── entity/
|
||
│ └── AppFeedback.java # 反馈实体类
|
||
├── mapper/
|
||
│ └── AppFeedbackMapper.java # 反馈Mapper接口
|
||
└── service/
|
||
├── AppFeedbackService.java # 反馈服务接口
|
||
└── impl/
|
||
└── AppFeedbackServiceImpl.java # 反馈服务实现
|
||
```
|
||
|
||
### 功能特性
|
||
|
||
1. **匿名提交** - 支持匿名用户提交反馈，不需要登录
|
||
2. **自动关联** - 已登录用户提交反馈时自动关联用户ID
|
||
3. **状态管理** - 完整的反馈状态流转：待处理 → 处理中 → 已完成/已关闭
|
||
4. **分页查询** - 支持分页和多条件筛选
|
||
5. **MyBatis Plus** - 使用 MyBatis Plus 实现数据持久化
|
||
6. **自动填充** - 创建时间和更新时间自动填充
|
||
|
||
### 权限说明
|
||
|
||
- 所有反馈接口都不需要身份认证
|
||
- `/feedback` 和 `/feedback/**` 已在 Sa-Token 配置中加入白名单
|
||
- 管理员可以通过状态更新和删除接口管理反馈
|
||
|
||
### 使用流程
|
||
|
||
1. **用户提交反馈**
|
||
- 访问 `POST /feedback` 接口
|
||
- 填写问题类型、标题、描述、联系方式
|
||
- 系统自动创建反馈记录
|
||
|
||
2. **查看反馈列表**
|
||
- 已登录用户：访问 `GET /feedback/my` 查看自己的反馈
|
||
- 管理员：访问 `GET /feedback/page` 查看所有反馈
|
||
|
||
3. **处理反馈**
|
||
- 管理员通过 `PUT /feedback/{id}/status` 更新反馈状态
|
||
- 状态流转：待处理 → 处理中 → 已完成
|
||
|
||
4. **查看详情**
|
||
- 通过 `GET /feedback/{id}` 查看反馈详情
|