core_wing_web/docs/API接口说明-反馈功能.md

# 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}` 查看反馈详情