# 统一反馈管理系统

**Repository Path**: bw616/UnifiedFeedback

## Basic Information

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

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-13
- **Last Updated**: 2026-04-05

## 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)

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

---

## ✨ 核心特性 (Features)

- **多应用管理**：为不同项目生成独立的 AppID 和 Secret，实现逻辑隔离。
- **安全反馈提交**：API 接口支持签名校验 (`api-sign.guard.ts`)，防止恶意刷接口。
- **反馈生命周期**：支持从"待处理"到"处理中"、"已解决"或"已驳回"的完整流转。
- **自动化通知**：集成邮件服务 (Nodemailer)，当收到新反馈时自动触达管理员。
- **可视化看板**：直观展示反馈趋势、类型分布及处理进度。
- **无缝集成**：提供即插即用的 Web SDK 挂件，一行代码接入。
- **现代化 UI**: 基于 Vue 3 + UnoCSS 的极致体验。

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

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

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

1.  **部署系统**：使用 Docker 或源码部署本项目。
2.  **创建应用**：登录管理后台，在"应用管理"中新建一个应用，获取 `AppID` 和 `AppSecret`。
3.  **配置后端**：在你的业务后端实现签名接口（使用 `AppSecret` 计算签名），供前端 SDK 调用。
4.  **接入 SDK**：在你的网站 HTML 中引入 SDK 代码，配置 `AppID` 和签名接口地址。
5.  **收集反馈**：用户点击网站右下角按钮提交反馈。
6.  **处理反馈**：管理员收到邮件通知，登录后台查看详情并回复。
7.  **闭环**：用户收到邮件回复，问题解决。

## 📸 界面预览 (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/)
- **数据库**: SQLite (默认，开发便捷) / MySQL (生产环境推荐)
- **认证**: Passport + JWT
- **邮件服务**: Nodemailer

### 前端 (Frontend)
- **框架**: [Vue 3](https://vuejs.org/) (Composition API)
- **构建工具**: [Vite](https://vitejs.dev/)
- **状态管理**: [Pinia](https://pinia.vuejs.org/)
- **UI 库**: [Element Plus](https://element-plus.org/) + [UnoCSS](https://unocss.dev/)
- **可视化**: [ECharts](https://echarts.apache.org/)

## 🚀 快速开始 (Quick Start)

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

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

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

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

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

#### 1. 后端 (Backend)

```bash
cd backend

# 复制环境变量示例
cp .env.example .env

# 安装依赖
npm install

# 初始化数据库 (SQLite)
npx prisma migrate dev

# 启动开发服务
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 SDK
│   └── ...
├── docs/             # 项目文档
└── docker-compose.yml
```

## 📚 文档 (Documentation)

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

## 🤝 贡献 (Contributing)

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

## 📄 许可证 (License)

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