# 智慧饮水管理系统

**Repository Path**: smart-ev-iot/smart-water-system

## Basic Information

- **Project Name**: 智慧饮水管理系统
- **Description**: 校园直饮水物联网管理系统，基于RuoYi-Vue框架开发，集饮水机终端管控、水质监测（TDS）、刷卡取水、数据统计、远程运维于一体，实现校园饮水“人-机-水”全链路智慧管理。
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 34320
- **Created**: 2026-08-26
- **Last Updated**: 2026-08-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

<h1 align="center">智慧饮水管理系统</h1>
<h4 align="center">Smart Water System · 基于 RuoYi 前后端分离架构</h4>

<p align="center">
  <img src="https://img.shields.io/badge/Spring%20Boot-4.0.3-brightgreen.svg" alt="Spring Boot"/>
  <img src="https://img.shields.io/badge/JDK-17-blue.svg" alt="JDK"/>
  <img src="https://img.shields.io/badge/Vue-2.6-green.svg" alt="Vue"/>
  <img src="https://img.shields.io/badge/版本-3.9.2-orange.svg" alt="Version"/>
</p>

## 项目简介

智慧饮水管理系统（SWSM）是一套面向校园、企业等场景的饮水机集中监控与管理平台。系统通过 **MQTT** 与饮水机终端通信，实现水质监测、设备控制、饮水记录统计、故障报警等功能，并提供完善的后台权限管理与运维能力。

本项目基于 [RuoYi-Vue](https://gitee.com/y_project/RuoYi-Vue) v3.9.2 二次开发，保留若依原有的用户权限、日志监控、代码生成等基础能力，并扩展了饮水业务模块。

## 技术栈

| 层次 | 技术 |
| :--- | :--- |
| 后端框架 | Spring Boot 4.0.3、Spring Security、MyBatis |
| 前端框架 | Vue 2、Element UI、Vuex、Vue Router |
| 认证 | JWT + Redis |
| 数据库 | MySQL 8.x、Druid 连接池 |
| 设备通信 | MQTT（EMQX）、Netty TCP |
| 其他 | Quartz 定时任务、SpringDoc API 文档、ECharts |

## 项目结构

```
smart-water-system/
├── smart-water-system-master-admin/    # Web 服务入口（启动类 SwsmApplication）
├── smart-water-system-master-common/   # 通用工具、常量、注解
├── smart-water-system-master-framework/# 安全、Redis、数据源等框架配置
├── smart-water-system-master-system/   # 系统管理（用户、角色、菜单等）
├── smart-water-system-master-quartz/   # 定时任务
├── smart-water-system-master-generator/# 代码生成器
├── swsm-swsm/                          # 智慧饮水业务模块（MQTT、设备、水质等）
├── start-vue/                          # 前端 Vue 项目
├── doc/                                # 项目文档
│   ├── 需求分析规格书.md
│   └── 接口文档.md
└── sql/
    └── data.sql                        # 数据库初始化脚本
```

## 项目文档

| 文档 | 说明 |
| :--- | :--- |
| [需求分析规格书](doc/需求分析规格书.md) | 业务需求、功能范围、验收标准 |
| [接口文档](doc/接口文档.md) | HTTP API、MQTT 设备通信协议 |

## 业务功能

### 饮水业务

| 模块 | 说明 |
| :--- | :--- |
| 饮水机设备 | 设备注册、位置、工作状态、在线心跳、温度阈值配置 |
| 实时水质 | 接收并展示设备上报的 TDS、温度等实时数据 |
| 水质历史 | 历史水质数据查询与统计 |
| 饮水记录 | 用户取水记录采集与查询 |
| 设备报警 | 故障（Error）与警告（Warning）事件记录与处理 |
| 设备控制日志 | 远程控制指令（开关、复位等）下发记录 |
| 巡检记录 | 设备巡检维护记录 |
| 断网缓存 | 设备离线期间数据补传缓存 |
| 系统参数配置 | 业务相关参数维护 |

### 系统管理（继承若依）

用户管理、角色管理、菜单管理、部门管理、岗位管理、字典管理、参数管理、通知公告、操作日志、登录日志、在线用户、定时任务、代码生成、服务监控、缓存监控、连接池监控等。

## MQTT 通信

系统通过 MQTT Broker（默认 `tcp://localhost:1883`）与饮水机终端交互，主题规则如下：

| 主题 | 方向 | 说明 |
| :--- | :--- | :--- |
| `water/data/{deviceId}` | 设备 → 服务端 | 水质数据上报 |
| `water/alert/{deviceId}` | 设备 → 服务端 | 报警/故障上报 |
| `water/drink/{deviceId}` | 设备 → 服务端 | 饮水记录上报 |
| `water/heartbeat/{deviceId}` | 设备 → 服务端 | 设备心跳 |
| `water/cache/{deviceId}` | 设备 → 服务端 | 断网缓存补传 |
| `water/control/{deviceId}` | 服务端 → 设备 | 控制指令下发 |

MQTT 相关配置见 `application.yml` 中的 `spring.mqtt` 节点。

## 环境要求

- JDK 17+
- Maven 3.6+
- MySQL 8.x
- Redis
- Node.js 14+（前端开发）
- MQTT Broker（推荐 [EMQX](https://www.emqx.io/)）

> 编码规范：项目源码与文档统一使用 **UTF-8** 编码。IDE 请设置 File Encoding 为 UTF-8；数据库使用 `utf8mb4` 字符集。

## 快速开始

### 1. 初始化数据库

```sql
CREATE DATABASE swsm DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_general_ci;
```

导入项目根目录下的 `sql/data.sql` 到 `swsm` 数据库。

### 2. 修改配置

编辑 `smart-water-system-master-admin/src/main/resources/application-druid.yml`，配置 MySQL 连接信息：

```yaml
spring:
  datasource:
    druid:
      master:
        url: jdbc:mysql://localhost:3306/swsm?...
        username: root
        password: 你的密码
```

按需修改 `application.yml` 中的 Redis、MQTT 等配置。

### 3. 启动后端

```bash
# 在项目根目录
mvn clean install

# 启动 admin 模块
cd smart-water-system-master-admin
mvn spring-boot:run
```

后端默认端口：**8080**

### 4. 启动前端

```bash
cd start-vue
npm install
npm run dev
```

前端默认端口：**80**（可在 `vue.config.js` 中修改）

### 5. 访问系统

- 前端地址：http://localhost
- 后端接口：http://localhost:8080
- API 文档：http://localhost:8080/swagger-ui.html
- Druid 监控：http://localhost:8080/druid（账号/密码见 `application-druid.yml`）

默认管理员账号：**admin / admin123**

## 端口说明

| 服务 | 默认端口 | 说明 |
| :--- | :--- | :--- |
| HTTP API | 8080 | Spring Boot Web 服务 |
| 前端 Dev Server | 80 | Vue 开发服务器 |
| Netty TCP | 8888 | 设备 TCP 通信（可选） |
| MQTT | 1883 | EMQX Broker |

## 致谢

本项目基于开源框架 [RuoYi-Vue](https://gitee.com/y_project/RuoYi-Vue) 构建，感谢若依团队提供的优秀基础框架。

若依官方文档：http://doc.ruoyi.vip