Aavi-7582/society-maintenance-tracker
GitHub: Aavi-7582/society-maintenance-tracker
基于 MERN 栈构建的住宅小区维修投诉追踪管理系统，提供居民报修、管理员处理、状态流转记录、逾期检测和邮件通知等完整的物业管理流程支持。
Stars: 0 | Forks: 0
# 社区维护追踪系统
一款全面的全栈 Web 应用程序，旨在简化住宅小区的管理流程。它使居民能够轻松提交维护投诉，并赋予管理员高效追踪、管理和解决问题的能力。
**在线演示：** https://society-frontend-14ht.onrender.com
**后端 API：** https://society-backend-kzvj.onrender.com
**管理员登录：** admin@example.com / AdminPass123
## 技术栈
- **Frontend**：React, Vite, React Router DOM，受 Tailwind 启发的原生 CSS (Glassmorphism UI)
- **Backend**：Node.js, Express.js
- **Database**：MongoDB (Mongoose ORM)
- **Cloud Services**：Cloudinary (图片托管), Nodemailer (邮件通知)
## 设置指南
按照以下步骤在本地运行该项目。
### 1. 前置条件
请确保您已安装以下软件：
- [Node.js](https://nodejs.org/en/)（v16 或更高版本）
- [MongoDB](https://www.mongodb.com/)（本地或 Atlas 集群）
### 2. 安装
克隆代码库并为后端和前端安装依赖项：
```
# Clone 仓库
git clone https://github.com/Aavi-7582/society-maintenance-tracker.git
cd society-maintenance-tracker
# 安装 backend 依赖
cd backend
npm install
# 安装 frontend 依赖
cd ../frontend
npm install
```
### 3. 环境变量
在 `backend` 目录中，使用提供的 `.env.example` 作为模板创建一个 `.env` 文件：
```
PORT=5000
MONGO_URI=mongodb+srv://:@cluster.mongodb.net/Society
JWT_SECRET=your_super_secret_jwt_key
JWT_EXPIRES_IN=7d
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_app_password
OVERDUE_DAYS=5
```
### 4. 运行应用程序
**启动后端服务器：**
```
cd backend
npm start
```
*(运行于 `http://localhost:5000`)*
**启动前端开发服务器：**
```
cd frontend
npm run dev
```
*(运行于 `http://localhost:5174` 或配置的 Vite 端口)*
## 🗄️ 数据库 Schema 概览
### 1. User 模型 (`User`)
- `name` (String, required)
- `email` (String, unique, required)
- `password` (String, hashed)
- `role` (Enum: `resident`, `admin`)
- `flatNo` (String, 居民必填)
### 2. Complaint 模型 (`Complaint`)
- `title` (String, required)
- `description` (String, required)
- `category` (Enum: Plumbing, Electrical, Security 等)
- `priority` (Enum: Low, Medium, High)
- `status` (Enum: OPEN, IN_PROGRESS, RESOLVED)
- `photo` (String, 指向 Cloudinary 的 URL)
- `resident` (ObjectId, ref: 'User')
- `statusHistory` (嵌套对象数组):
- `status` (String)
- `note` (String)
- `actor` (ObjectId, ref: 'User')
- `timestamp` (Date)
### 3. Notice 模型 (`Notice`)
- `title` (String, required)
- `description` (String, required)
- `isImportant` (Boolean, default: false)
- `postedBy` (ObjectId, ref: 'User')
## 📡 API 文档
### 身份验证 (`/api/auth`)
- `POST /register` - 注册新的居民/管理员
- `POST /login` - 验证用户身份并返回 JWT
### 投诉 (`/api/complaints`)
- `POST /` - 创建新投诉（居民）- *支持 `multipart/form-data` 用于上传图片。*
- `GET /my-complaints` - 获取已登录居民的投诉
- `GET /:id` - 获取特定投诉的详情（共享）
### 管理员操作 (`/api/admin`)
- `GET /complaints` - 获取所有投诉（支持 `search`、`status`、`category` 查询）
- `GET /dashboard/stats` - 获取汇总统计信息（Total、Overdue、Category Dist.）
- `PATCH /complaints/:id/status` - 更新状态并追加到历史记录
- `PATCH /complaints/:id/priority` - 更新投诉优先级
### 公告 (`/api/notices`)
- `POST /` - 发布新公告（管理员）
- `GET /` - 获取所有公告（共享）
标签：GNU通用公共许可证, MERN, MITM代理, MongoDB, Node.js, React, Syscalls, 工单系统, 物业管理, 网络研究, 自定义脚本