反馈系统后端接口文档
概述
反馈系统用于收集用户对系统功能的意见、建议和问题反馈，支持用户提交反馈、查看反馈列表、回复反馈等功能。
基础信息
- Base URL:
/api/feedback - 数据格式: JSON
- 字符编码: UTF-8
数据结构
反馈对象 (Feedback)
{"id": 1,"name": "张三","email": "zhangsan@example.com","type": "suggestion","content": "建议增加夜间模式功能","source": "autops","status": "pending","created_at": "2024-10-16T10:30:00Z","updated_at": "2024-10-16T10:30:00Z","replies": [{"id": 1,"feedback_id": 1,"author": "管理员","content": "感谢您的建议，我们会考虑在下个版本中加入此功能。","is_admin": true,"created_at": "2024-10-16T14:20:00Z"}]
}
回复对象 (Reply)
{"id": 1,"feedback_id": 1,"author": "管理员","content": "感谢您的建议，我们会考虑在下个版本中加入此功能。","is_admin": true,"created_at": "2024-10-16T14:20:00Z"
}
字段说明
反馈类型 (type)
suggestion: 功能建议bug: 问题反馈question: 使用咨询other: 其他
反馈状态 (status)
pending: 待处理replied: 已回复closed: 已关闭
反馈来源 (source)
autops: 假条生成页面knowledge: 知识库页面cultivation: 修炼页面general: 通用反馈
API 接口
1. 提交反馈
接口地址: POST /api/feedback/
请求参数:
{"name": "张三", // 可选，用户姓名"email": "zhangsan@example.com", // 可选，用户邮箱"type": "suggestion", // 必填，反馈类型"content": "建议增加夜间模式功能", // 必填，反馈内容"source": "autops" // 可选，反馈来源，默认为 "general"
}
响应示例:
{"success": true,"message": "反馈提交成功","data": {"id": 1,"name": "张三","email": "zhangsan@example.com","type": "suggestion","content": "建议增加夜间模式功能","source": "autops","status": "pending","created_at": "2024-10-16T10:30:00Z","updated_at": "2024-10-16T10:30:00Z"}
}
错误响应:
{"success": false,"message": "反馈内容不能为空","code": 400
}
2. 获取反馈列表
接口地址: GET /api/feedback/list
查询参数:
page: 页码，默认为 1pageSize: 每页数量，默认为 10，最大为 100source: 反馈来源，可选type: 反馈类型，可选status: 反馈状态，可选keyword: 搜索关键词，可选（搜索内容和姓名）
请求示例:
GET /api/feedback/list?page=1&pageSize=10&source=autops&type=suggestion
响应示例:
{"success": true,"data": {"list": [{"id": 1,"name": "张三","email": "zhangsan@example.com","type": "suggestion","content": "建议增加夜间模式功能","source": "autops","status": "replied","created_at": "2024-10-16T10:30:00Z","updated_at": "2024-10-16T14:20:00Z","replies": [{"id": 1,"author": "管理员","content": "感谢您的建议，我们会考虑在下个版本中加入此功能。","is_admin": true,"created_at": "2024-10-16T14:20:00Z"}]}],"total": 25,"page": 1,"pageSize": 10,"totalPages": 3}
}
3. 获取反馈详情
接口地址: GET /api/feedback/{id}
路径参数:
id: 反馈ID
响应示例:
{"success": true,"data": {"id": 1,"name": "张三","email": "zhangsan@example.com","type": "suggestion","content": "建议增加夜间模式功能","source": "autops","status": "replied","created_at": "2024-10-16T10:30:00Z","updated_at": "2024-10-16T14:20:00Z","replies": [{"id": 1,"author": "管理员","content": "感谢您的建议，我们会考虑在下个版本中加入此功能。","is_admin": true,"created_at": "2024-10-16T14:20:00Z"}]}
}
4. 获取反馈回复列表
接口地址: GET /api/feedback/{id}/replies
路径参数:
id: 反馈ID
响应示例:
{"success": true,"data": [{"id": 1,"feedback_id": 1,"author": "管理员","content": "感谢您的建议，我们会考虑在下个版本中加入此功能。","is_admin": true,"created_at": "2024-10-16T14:20:00Z"},{"id": 2,"feedback_id": 1,"author": "张三","content": "好的，期待新版本！","is_admin": false,"created_at": "2024-10-16T15:10:00Z"}]
}
5. 回复反馈
接口地址: POST /api/feedback/{id}/reply
路径参数:
id: 反馈ID
请求参数:
{"author": "管理员", // 必填，回复人姓名"content": "感谢您的建议，我们会考虑实现。", // 必填，回复内容"is_admin": true // 可选，是否为管理员回复，默认 false
}
响应示例:
{"success": true,"message": "回复提交成功","data": {"id": 2,"feedback_id": 1,"author": "管理员","content": "感谢您的建议，我们会考虑实现。","is_admin": true,"created_at": "2024-10-16T15:30:00Z"}
}
6. 获取反馈回复显示内容（原有功能）
接口地址: GET /api/feedback/reply
描述: 获取在反馈表单上方显示的公告回复内容
响应示例:
{"success": true,"data": {"data": [{"content": "感谢大家的反馈！\n我们已收到很多宝贵建议，正在积极改进中。\n\n近期将推出以下功能：\n1. 夜间模式\n2. 批量导出\n3. 自定义模板"}]}
}
7. 更新反馈状态
接口地址: PUT /api/feedback/{id}/status
路径参数:
id: 反馈ID
请求参数:
{"status": "replied" // 必填，新状态值
}
响应示例:
{"success": true,"message": "状态更新成功"
}
8. 删除反馈
接口地址: DELETE /api/feedback/{id}
路径参数:
id: 反馈ID
响应示例:
{"success": true,"message": "删除成功"
}
9. 删除回复
接口地址: DELETE /api/feedback/reply/{replyId}
路径参数:
replyId: 回复ID
响应示例:
{"success": true,"message": "回复删除成功"
}
错误码说明
| 错误码 | 说明 |
|---|---|
| 400 | 请求参数错误 |
| 401 | 未授权访问 |
| 403 | 权限不足 |
| 404 | 资源不存在 |
| 422 | 数据验证失败 |
| 500 | 服务器内部错误 |
数据库设计建议
feedback 表
CREATE TABLE feedback (id BIGINT PRIMARY KEY AUTO_INCREMENT,name VARCHAR(100) COMMENT '反馈人姓名',email VARCHAR(255) COMMENT '联系邮箱',type ENUM('suggestion', 'bug', 'question', 'other') NOT NULL COMMENT '反馈类型',content TEXT NOT NULL COMMENT '反馈内容',source VARCHAR(50) DEFAULT 'general' COMMENT '反馈来源',status ENUM('pending', 'replied', 'closed') DEFAULT 'pending' COMMENT '处理状态',created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,INDEX idx_source (source),INDEX idx_type (type),INDEX idx_status (status),INDEX idx_created_at (created_at)
);
feedback_replies 表
CREATE TABLE feedback_replies (id BIGINT PRIMARY KEY AUTO_INCREMENT,feedback_id BIGINT NOT NULL COMMENT '反馈ID',author VARCHAR(100) NOT NULL COMMENT '回复人姓名',content TEXT NOT NULL COMMENT '回复内容',is_admin BOOLEAN DEFAULT FALSE COMMENT '是否为管理员回复',created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,FOREIGN KEY (feedback_id) REFERENCES feedback(id) ON DELETE CASCADE,INDEX idx_feedback_id (feedback_id),INDEX idx_created_at (created_at)
);
feedback_reply_content 表（原有功能）
CREATE TABLE feedback_reply_content (id BIGINT PRIMARY KEY AUTO_INCREMENT,content TEXT NOT NULL COMMENT '回复内容',position ENUM('top', 'bottom', 'left', 'right') DEFAULT 'top' COMMENT '显示位置',is_active BOOLEAN DEFAULT TRUE COMMENT '是否启用',created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
实现注意事项
- 分页性能优化: 大量数据时建议使用游标分页而非偏移分页
- XSS防护: 反馈内容和回复内容需要进行HTML转义
- 敏感词过滤: 建议对用户提交的内容进行敏感词检查
- 频率限制: 对提交反馈的频率进行限制，防止恶意刷屏
- 邮件通知: 可以考虑在收到新反馈或回复时发送邮件通知
- 权限控制: 删除和状态更新操作需要管理员权限
- 数据备份: 定期备份反馈数据，防止重要信息丢失
前端集成示例
// 获取反馈列表
const response = await FeedbackAPI.getFeedbackList({page: 1,pageSize: 10,source: 'autops'
})// 提交回复
await FeedbackAPI.replyFeedback(feedbackId, {author: '张三',content: '谢谢回复',is_admin: false
})