From e495011f570ae95a2d1d9c88957b937ec7d4fdde Mon Sep 17 00:00:00 2001 From: ikmkj Date: Wed, 4 Mar 2026 18:40:34 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=B7=BB=E5=8A=A0=E5=8F=8D=E9=A6=88?= =?UTF-8?q?=E7=B3=BB=E7=BB=9F=E5=8A=9F=E8=83=BD=E5=88=86=E6=9E=90=E6=96=87?= =?UTF-8?q?=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 添加未实现的反馈系统功能分析文档，包含需求概述、权限矩阵、数据表设计、业务逻辑、API接口、前端UI设计、实现步骤和关键技术点等详细说明 --- doc/feedback_system_analysis.md | 264 ++++++++++++++++++++++++++++++++ 1 file changed, 264 insertions(+) create mode 100644 doc/feedback_system_analysis.md diff --git a/doc/feedback_system_analysis.md b/doc/feedback_system_analysis.md new file mode 100644 index 0000000..c6036e3 --- /dev/null +++ b/doc/feedback_system_analysis.md @@ -0,0 +1,264 @@ +# 反馈系统功能分析(未实现) + +## 一、需求概述 + +在左侧菜单回收站下方添加一个新的功能模块，包含三个子功能： +- 反馈BUG +- 申请管理 +- 提出意见 + +**访问权限：** 仅登录用户可见和使用 +**处理权限：** 仅ADMIN用户可处理 + +--- + +## 二、用户角色权限矩阵 + +### 普通用户（USER）能做什么 + +| 功能 | 权限 | 说明 | +|------|------|------| +| 查看反馈列表 | ✅ | 仅查看自己提交的反馈 | +| 提交BUG反馈 | ✅ | 创建新的BUG反馈 | +| 提交管理申请 | ✅ | 申请成为管理员 | +| 提出意见建议 | ✅ | 提交产品意见 | +| 编辑自己的反馈 | ✅ | 仅在未处理状态下可编辑 | +| 删除自己的反馈 | ✅ | 仅在未处理状态下可删除 | +| 查看反馈状态 | ✅ | 实时查看处理进度 | +| 处理他人反馈 | ❌ | 无权限 | +| 删除他人反馈 | ❌ | 无权限 | + +### 管理员（ADMIN）能做什么 + +| 功能 | 权限 | 说明 | +|------|------|------| +| 查看所有反馈 | ✅ | 查看全部用户的反馈 | +| 查看反馈详情 | ✅ | 包括用户信息、提交时间等 | +| 处理反馈 | ✅ | 更新状态、添加处理备注 | +| 批准/拒绝申请 | ✅ | 处理管理员申请 | +| 删除反馈 | ✅ | 删除任何反馈 | +| 导出反馈 | ✅ | 导出为CSV/Excel | +| 统计分析 | ✅ | 查看反馈统计信息 | + +--- + +## 三、数据表设计 + +### 1. 反馈表（feedback） + +```sql +CREATE TABLE feedback ( + id BIGINT PRIMARY KEY COMMENT '反馈ID', + user_id BIGINT NOT NULL COMMENT '提交用户ID', + type VARCHAR(20) NOT NULL COMMENT '反馈类型: BUG, ADMIN_REQUEST, SUGGESTION', + title VARCHAR(255) NOT NULL COMMENT '反馈标题', + content LONGTEXT NOT NULL COMMENT '反馈内容', + status VARCHAR(20) DEFAULT 'PENDING' COMMENT '状态: PENDING(待处理), PROCESSING(处理中), RESOLVED(已解决), REJECTED(已拒绝)', + priority VARCHAR(20) DEFAULT 'NORMAL' COMMENT '优先级: LOW, NORMAL, HIGH, URGENT', + + -- 处理信息 + handler_id BIGINT COMMENT '处理人ID', + handler_remark VARCHAR(500) COMMENT '处理备注', + handled_at DATETIME COMMENT '处理时间', + + -- 时间戳 + created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + -- 软删除 + is_deleted TINYINT DEFAULT 0 COMMENT '是否删除', + deleted_at DATETIME COMMENT '删除时间', + deleted_by BIGINT COMMENT '删除人ID', + + INDEX idx_user_id (user_id), + INDEX idx_type (type), + INDEX idx_status (status), + INDEX idx_created_at (created_at) +) COMMENT='用户反馈表'; +``` + +### 2. 管理员申请表（admin_request） + +```sql +CREATE TABLE admin_request ( + id BIGINT PRIMARY KEY COMMENT '申请ID', + user_id BIGINT NOT NULL COMMENT '申请用户ID', + reason VARCHAR(500) NOT NULL COMMENT '申请理由', + status VARCHAR(20) DEFAULT 'PENDING' COMMENT '状态: PENDING(待审核), APPROVED(已批准), REJECTED(已拒绝)', + + -- 审核信息 + reviewer_id BIGINT COMMENT '审核人ID', + review_remark VARCHAR(500) COMMENT '审核备注', + reviewed_at DATETIME COMMENT '审核时间', + + -- 时间戳 + created_at DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + + -- 软删除 + is_deleted TINYINT DEFAULT 0 COMMENT '是否删除', + deleted_at DATETIME COMMENT '删除时间', + deleted_by BIGINT COMMENT '删除人ID', + + INDEX idx_user_id (user_id), + INDEX idx_status (status), + INDEX idx_created_at (created_at) +) COMMENT='管理员申请表'; +``` + +--- + +## 四、业务逻辑设计 + +### 4.1 反馈流程 + +``` +普通用户提交反馈 + ↓ +反馈进入待处理队列 (PENDING) + ↓ +管理员查看反馈 + ↓ +管理员处理反馈 (更新状态、添加备注) + ↓ +用户查看处理结果 +``` + +### 4.2 反馈类型处理 + +| 类型 | 流程 | 特殊处理 | +|------|------|--------| +| BUG | 提交 → 待处理 → 处理中 → 已解决/已拒绝 | 可设置优先级 | +| ADMIN_REQUEST | 提交 → 待审核 → 已批准/已拒绝 | 批准后自动升级用户角色 | +| SUGGESTION | 提交 → 待处理 → 已解决/已拒绝 | 仅供参考 | + +### 4.3 管理员申请特殊处理 + +当管理员批准申请时： +1. 更新 admin_request 表状态为 APPROVED +2. 更新 user 表的 role 字段为 ADMIN +3. 记录审核人和审核时间 +4. 可选：发送通知给申请用户 + +--- + +## 五、API 接口设计 + +### 5.1 普通用户接口 + +``` +POST /api/feedback - 提交反馈 +GET /api/feedback/my - 查看自己的反馈列表 +GET /api/feedback/{id} - 查看反馈详情 +PUT /api/feedback/{id} - 编辑反馈（仅未处理状态） +DELETE /api/feedback/{id} - 删除反馈（仅未处理状态） + +POST /api/admin-request - 提交管理员申请 +GET /api/admin-request/my - 查看自己的申请 +GET /api/admin-request/{id} - 查看申请详情 +``` + +### 5.2 管理员接口 + +``` +GET /api/feedback - 查看所有反馈（分页） +GET /api/feedback/stats - 反馈统计 +PUT /api/feedback/{id}/status - 更新反馈状态 +PUT /api/feedback/{id}/handle - 处理反馈（添加备注） +DELETE /api/feedback/{id} - 删除反馈 + +GET /api/admin-request - 查看所有申请（分页） +PUT /api/admin-request/{id}/approve - 批准申请 +PUT /api/admin-request/{id}/reject - 拒绝申请 +``` + +--- + +## 六、前端UI设计 + +### 6.1 菜单结构 + +``` +左侧菜单 +├── 分类列表 +├── 回收站 +├── 反馈中心 (新增) +│ ├── 反馈BUG +│ ├── 申请管理 +│ └── 提出意见 +└── 系统管理 (仅ADMIN) +``` + +### 6.2 反馈中心页面 + +**普通用户视图：** +- 反馈列表（仅显示自己的） +- 提交新反馈表单 +- 反馈详情和状态查看 +- 编辑/删除按钮（仅未处理状态） + +**管理员视图：** +- 所有反馈列表（可筛选、搜索） +- 反馈统计仪表板 +- 处理反馈表单（更新状态、添加备注） +- 批量操作（删除、导出） + +--- + +## 七、实现步骤 + +### 第一阶段：数据库 +1. 创建 feedback 表 +2. 创建 admin_request 表 +3. 添加索引优化查询 + +### 第二阶段：后端 +1. 创建 Feedback 和 AdminRequest 实体类 +2. 创建 Mapper 和 Service +3. 创建 Controller 和 API 接口 +4. 添加权限控制注解 + +### 第三阶段：前端 +1. 创建反馈中心菜单项 +2. 创建反馈列表页面 +3. 创建反馈提交表单 +4. 创建管理员处理页面 +5. 集成到 SidebarMenu + +### 第四阶段：测试 +1. 单元测试 +2. 集成测试 +3. 权限测试 + +--- + +## 八、关键技术点 + +### 权限控制 +- 使用 @PreAuthorize 注解控制接口访问 +- 在 Service 层验证用户权限 +- 确保用户只能操作自己的反馈 + +### 数据隔离 +- 普通用户查询时自动过滤为自己的反馈 +- 管理员可查看所有反馈 + +### 状态管理 +- 反馈状态流转：PENDING → PROCESSING → RESOLVED/REJECTED +- 申请状态流转：PENDING → APPROVED/REJECTED + +### 审计日志 +- 记录处理人、处理时间、处理备注 +- 支持软删除，保留历史记录 + +--- + +## 九、扩展考虑 + +1. **通知系统** - 反馈被处理时通知用户 +2. **评论功能** - 用户和管理员可在反馈下评论 +3. **附件支持** - 反馈可上传截图或文件 +4. **优先级排序** - BUG 按优先级排序 +5. **导出功能** - 管理员可导出反馈报告 +6. **统计分析** - 反馈类型、状态分布统计 +