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

API 接口说明 - 问题反馈功能

问题反馈相关接口

1. 创建反馈

接口地址: POST /feedback

请求头:

Authorization: your-token（可选，支持匿名提交）

请求参数:

{
  "feedbackType": "功能建议",      // 问题类型（必填）
  "title": "希望增加夜间模式",      // 问题标题（必填）
  "content": "详细描述...",        // 问题描述（可选）
  "contact": "user@example.com"   // 联系方式（可选）
}

响应示例:

{
  "code": 200,
  "message": "反馈提交成功",
  "data": null
}

说明:

• 支持匿名提交，如果已登录会自动关联用户ID
• 问题类型建议：功能建议、Bug反馈、使用问题、其他
• 联系方式用于后续沟通，建议填写邮箱或手机号
• 反馈默认状态为"待处理"

---

2. 查询当前用户的反馈列表

接口地址: GET /feedback/my

请求头:

Authorization: your-token

响应示例:

{
  "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}

响应示例:

{
  "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

响应示例:

{
  "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

响应示例:

{
  "code": 200,
  "message": "状态更新成功",
  "data": null
}

说明:

• 不需要登录
• 用于管理员更新反馈处理状态
• 状态说明：
  • 0: 待处理
  • 1: 处理中
  • 2: 已完成
  • 3: 已关闭

---

6. 删除反馈

接口地址: DELETE /feedback/{id}

响应示例:

{
  "code": 200,
  "message": "删除成功",
  "data": null
}

说明:

• 不需要登录
• 用于管理员删除反馈

---

数据库说明

反馈表结构

建表 SQL: src/main/resources/db/feedback.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} 查看反馈详情