# 统一反馈管理系统

**Repository Path**: bw616/UnifiedFeedback

## Basic Information

- **Project Name**: 统一反馈管理系统
- **Description**: 一个轻量级、易接入的反馈收集与管理系统，旨在为个人开发者和中小型团队提供统一的反馈处理中心。支持多应用接入、邮件通知、状态流转及数据可视化。
- **Primary Language**: NodeJS
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-08-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: 反馈管理, Vue, Nestjs

## README

# 统一反馈管理系统 (Unified Feedback System)

![License](https://img.shields.io/badge/license-MIT-blue.svg)
![NestJS](https://img.shields.io/badge/backend-NestJS-red.svg)
![Vue 3](https://img.shields.io/badge/frontend-Vue%203-green.svg)
![TypeScript](https://img.shields.io/badge/language-TypeScript-blue.svg)

一个轻量级、易接入的反馈收集与管理系统，旨在为个人开发者和中小型团队提供统一的反馈处理中心。支持 Web / 小程序多端接入、多应用管理、邮件通知、状态流转及数据可视化。

---

## ✨ 核心特性 (Features)

- **多应用管理**：为不同项目生成独立的 AppID 和 Secret，实现逻辑隔离。
- **安全反馈提交**：API 接口支持 HMAC-SHA256 签名校验 (`api-sign.guard.ts`)，绑定请求体并防重放。
- **反馈生命周期**：支持从"待处理"到"处理中"、"已解决"或"已驳回"的完整流转。
- **自动化通知**：集成邮件服务 (Nodemailer)，当收到新反馈时自动触达管理员。
- **可视化看板**：直观展示反馈趋势及处理进度。
- **Web 一键接入**：提供即插即用的 Web SDK 挂件。
- **小程序接入**：支持微信小程序（后端转发 / 签名直传 / 纯前端直连演示方案），见 [MINIPROGRAM.md](integration/MINIPROGRAM.md)。
- **现代化 UI**: 基于 Vue 3 + UnoCSS 的极致体验。

## ⚙️ 功能列表 (Function List)

| 模块 | 功能点 | 说明 |
| :--- | :--- | :--- |
| **应用管理** | 多应用创建 | 支持创建无限个应用，每个应用生成独立的 AppID/Secret |
| | 密钥重置 | 随时重置 AppSecret，保障安全 |
| **反馈收集** | Web SDK | 原生 JS 编写，无依赖，支持自定义主题色 |
| | 小程序 | 自研反馈页 + 业务后端转发/签名，或演示用纯前端直连 |
| | API 签名 | HMAC-SHA256（绑定 body/query + nonce 防重放） |
| | 环境采集 | Web SDK 自动采集 UserAgent、屏幕分辨率、URL、JS 报错信息 |
| **反馈处理** | 状态流转 | 待处理 -> 处理中 -> 已解决/已驳回 |
| | 邮件通知 | 收到反馈通知管理员；管理员回复通知用户 |
| | 历史记录 | 记录每一条反馈的处理时间轴 |
| **数据看板** | 趋势统计 | 近 7 天/30 天反馈数量趋势图 |
| | 分布统计 | 按反馈类型（Bug/建议）和状态分布统计 |

## 🔄 系统使用流程 (Workflow)

1.  **部署系统**：使用 Docker 或源码部署本项目。
2.  **创建应用**：登录管理后台，在"应用管理"中新建一个应用，获取 `AppID` 和 `AppSecret`。
3.  **选择接入方式**：
    - **Web**：业务后端实现签名接口，页面引入 [Web SDK](integration/web-sdk/README.md)。
    - **小程序**：按 [小程序接入指南](integration/MINIPROGRAM.md) 选择方案 A（推荐）/ B / C（仅演示）。
4.  **收集反馈**：用户在网站或小程序中提交反馈。
5.  **处理反馈**：管理员收到邮件通知，登录后台查看详情并回复。
6.  **闭环**：用户收到邮件回复，问题解决。

## 📸 界面预览 (Screenshots)

<!-- 请在此处上传并替换为实际截图 -->
<div align="center">
    <img src="./images/0.png" alt="Dashboard" width="100%"/>
    <p><em>数据仪表盘：直观展示反馈趋势与分布</em></p>
</div>

<br/>

<div align="center">
    <img src="./images/1.png" alt="Feedback List" width="100%"/>
    <p><em>反馈管理：高效处理与回复用户反馈</em></p>
</div>


## 🛠️ 技术栈 (Tech Stack)

### 后端 (Backend)
- **框架**: [NestJS](https://nestjs.com/) (Node.js)
- **语言**: TypeScript
- **ORM**: [Prisma](https://www.prisma.io/)
- **数据库**: MySQL 8.0 (Prisma)
- **认证**: Passport + JWT
- **邮件服务**: Nodemailer

### 前端 (Frontend)
- **框架**: [Vue 3](https://vuejs.org/) (Composition API)
- **构建工具**: [Vite](https://vitejs.dev/)
- **状态管理**: [Pinia](https://pinia.vuejs.org/)
- **UI 库**: [UnoCSS](https://unocss.dev/) + 自研组件 + [ECharts](https://echarts.apache.org/)

## 🚀 快速开始 (Quick Start)

### 方式一：使用 Docker (推荐)

一键启动整个服务（包含 MySQL 8.0、后端 API 和前端管理后台）：

```bash
docker-compose up -d --build
```

访问地址：
- **管理后台**: `http://localhost`
- **后端 API**: `http://localhost:3000`

可通过环境变量覆盖 MySQL 账号（默认库名 `feedback_system`，用户 `feedback` / 密码 `feedback_pass`）。

### 方式二：本地开发 (Local Development)

#### 0. 准备 MySQL 8.0

确保本机已安装并启动 MySQL 8.0，然后创建数据库与用户（示例）：

```sql
CREATE DATABASE feedback_system CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'feedback'@'localhost' IDENTIFIED BY 'feedback_pass';
GRANT ALL PRIVILEGES ON feedback_system.* TO 'feedback'@'localhost';
-- 本地 `prisma migrate dev` 需要创建影子库的权限
GRANT CREATE, DROP ON *.* TO 'feedback'@'localhost';
FLUSH PRIVILEGES;
```

#### 1. 后端 (Backend)

```bash
cd backend

# 复制环境变量示例（按需修改 DATABASE_URL）
cp .env.example .env

# 安装依赖
npm install

# 初始化数据库 (MySQL 8.0)
npx prisma migrate dev
npx prisma db seed

# 启动开发服务
npm run start:dev
```

#### 2. 前端 (Frontend)

```bash
cd frontend

# 安装依赖
npm install

# 启动开发服务
npm run dev
```

## 📂 项目结构 (Project Structure)

```
.
├── backend/          # NestJS 后端服务
│   ├── src/          # 源代码
│   ├── prisma/       # 数据库模型与迁移
│   └── ...
├── frontend/         # Vue 3 管理后台
│   ├── src/          # 源代码
│   └── ...
├── integration/      # 集成示例与 SDK
│   ├── web-sdk/      # 原生 JS Web SDK（仅 H5）
│   ├── MINIPROGRAM.md # 小程序接入指南
│   └── ...
├── docs/             # 项目文档
└── docker-compose.yml
```

## 📚 文档 (Documentation)

- [API 文档](docs/api.md)
- [需求规格说明书](docs/requirements.md)
- [SDK 集成指南](integration/GUIDE.md)
- [小程序接入指南](integration/MINIPROGRAM.md)

## 🤝 贡献 (Contributing)

欢迎提交 Issue 和 Pull Request！详情请查看 [CONTRIBUTING.md](CONTRIBUTING.md)。

## 📄 许可证 (License)

本项目基于 [MIT License](LICENSE) 开源。