# 用户反馈系统（Feedback System）

> **负责人**: FFOA 开发团队  
> **模块标识**: `platform_feedback`  
> **状态**: 🟢 Active  
> **最后更新**: 2026-01-07

---

## 📋 文档导航

| 文档 | 状态 | 最后更新 |
|------|------|---------|
| [产品需求文档](./01-prd.md) | ✅ | 2026-01-07 |
| [用户场景](./02-user-journey.md) | ✅ | 2026-01-06 |
| [架构设计](./03-architecture.md) | ✅ | 2026-01-07 |
| [状态机](./04-state-machine.md) | ✅ | 2026-01-06 |
| [UI 交互规范](./05-ui-interaction-spec.md) | ✅ | 2026-01-06 |
| [数据模型](./06-data-model.md) | ✅ | 2026-01-07 |
| [API 文档](./07-api.md) | ✅ | 2026-01-07 |
| [错误码](./08-error-codes.md) | ✅ | 2026-01-06 |
| [测试场景](./09-test-scenarios.md) | ✅ | 2026-01-07 |
| [E2E 测试规范](./10-e2e-test-spec.md) | ✅ | 2026-01-07 |
| [变更日志](./99-changelog.md) | ✅ | 2026-01-07 |

**状态说明**:
- ✅ Completed/Approved - 已完成并通过评审
- 🚧 In Progress/Draft - 编写中
- ❌ Not Started - 未开始
- 📝 Need Update - 需要更新
- 📋 Planned - 已规划待执行

---

## 📌 概述

用户反馈系统为 FFOA 平台提供统一的用户反馈收集和管理功能，支持用户快速提交问题反馈和功能建议，管理员可以集中管理和处理这些反馈。

### 核心功能

1. **反馈提交** - 用户可在任意页面通过悬浮按钮提交反馈
2. **我的反馈** - 用户可查看自己提交的反馈及处理状态
3. **反馈管理** - 管理员可查看、筛选、搜索所有反馈
4. **状态管理** - 管理员可更新反馈状态、添加备注和回复

### 业务价值

- 提供统一的用户反馈渠道
- 快速收集产品问题和改进建议
- 帮助产品团队了解用户需求
- 提升用户参与感和满意度

---

## 🏗️ 技术信息

### 代码位置

- **前端**:
  - `frontend/src/features/feedback/components/FeedbackButton.tsx` - 反馈入口按钮
  - `frontend/src/features/feedback/components/FeedbackModal.tsx` - 反馈提交弹窗
  - `frontend/src/app/(modules)/feedback/_pages/MyFeedbackPage.tsx` - 我的反馈页
  - `frontend/src/app/settings/feedback/page.tsx` - 反馈管理页
  - `frontend/src/services/api/feedback.ts` - 反馈 API 客户端
- **后端**: `backend/src/modules/feedback/`
- **数据库**: `platform_feedback` Schema

### API 端点

- **Base URL**: `/api/v1/feedbacks`
- **主要接口**: 
  - 反馈提交和查询
  - 状态更新和回复
  - 统计数据
- **总计**: 10+ 个接口

### 技术栈

- **前端**: Next.js 14 + TypeScript + Tailwind CSS + shadcn/ui
- **后端**: NestJS + Prisma + PostgreSQL
- **附件处理**: 后端仅记录附件 URL（上传由外部完成）

---

## 🔗 相关模块

- [用户与组织架构](../organization/README.md) - 用户身份依赖
- [权限系统](../permissions/README.md) - 权限控制

---

## 🚀 快速开始

### 用户使用

1. 点击页面右下角的反馈按钮
2. 选择反馈类型
3. 填写标题和详细描述
4. （可选）填写附件 URL
5. 点击提交

### 管理员使用

1. 进入「设置」→「反馈管理」
2. 查看反馈列表
3. 点击反馈查看详情
4. 更新状态、添加备注或回复

---

## 📊 反馈类型

| 类型 | 说明 | 代码 |
|------|------|------|
| 问题反馈 | 系统 Bug、功能异常 | `BUG` |
| 功能建议 | 新功能请求 | `FEATURE` |
| 改进建议 | 现有功能的改进建议 | `IMPROVEMENT` |
| 其他 | 其他类型反馈 | `OTHER` |

---

## 📈 处理状态

| 状态 | 说明 | 代码 |
|------|------|------|
| 待处理 | 新提交，等待管理员处理 | `PENDING` |
| 处理中 | 管理员已开始处理 | `IN_PROGRESS` |
| 已解决 | 问题已解决或建议已采纳 | `RESOLVED` |
| 已关闭 | 不处理/无效/重复 | `CLOSED` |

---

## 🧪 测试

- [测试场景](./09-test-scenarios.md)
- [E2E 测试规范](./10-e2e-test-spec.md)

---

## ✅ 文档一致性校验清单

- 功能状态以代码实现为准（前后端与 API 列表一致）
- region 来源：服务层继承用户 metadata.region，数据库默认值为 CN
- 统计接口已实现：`GET /feedbacks/stats` 前后端一致
- `byPriority.UNSET` 表示 `priority` 为空值（非枚举）
- 测试报告路径统一为 `testing/reports/{module}-{YYYY-MM-DD}-{type}-report.md`

**快速自检命令**:
```bash
rg -n "feedbacks/stats|UNSET|待开发|规划中" docs/modules/feedback
```

---

## 📚 详细文档

- [产品需求文档](./01-prd.md) - 完整功能需求、用户故事、验收标准
- [架构设计](./03-architecture.md) - 技术实现方案、数据模型
- [API 文档](./07-api.md) - 接口定义、请求响应、错误码

---

## 👥 贡献者

- **创建者**: FFOA Team
- **维护者**: Backend Team

---

**创建时间**: 2025-12-08  
**更新时间**: 2026-01-07  
**状态**: 🟢 文档已完成，代码已实现  
**版本**: v1.0.4