From abf14bd42f81ad011cc51ac6672a20203dd38748 Mon Sep 17 00:00:00 2001 From: lingyunxsh Date: Mon, 19 May 2025 09:44:53 +0800 Subject: [PATCH] readme --- README.md | 251 ++++++++++++++++++++++++ springboot-init-main/sql/mqtt_power.sql | 33 +++- 2 files changed, 279 insertions(+), 5 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2320bcc --- /dev/null +++ b/README.md @@ -0,0 +1,251 @@ +# 智能充电桩管理系统 (Charging Pile Management System) + +## 1. 项目简介 + +本项目是一个基于 Spring Boot (后端) 和 Next.js (前端) 构建的智能充电桩管理与计费系统。旨在为用户提供便捷的充电服务，并为管理员提供高效的充电桩、用户及计费管理功能。支持通过 MQTT 协议与充电桩硬件（单片机）进行实时通信和控制。 + +### 核心功能 +* **用户端**: + * 用户注册与登录 + * 查看账户余额、充电记录 + * 扫码/输入ID启动充电 + * 停止充电 + * 激活码兑换充值 +* **管理端**: + * 用户管理（查询、添加、编辑、删除） + * 充电桩/车位管理（状态监控、添加、编辑、删除） + * 充电会话管理（查询、监控） + * 激活码管理（生成、查询、删除） + * 系统概览与统计 +* **硬件交互 (通过 MQTT)**: + * 充电桩状态上报 (空闲、连接中、充电中、故障等) + * 远程启动/停止充电指令下发 + * 心跳维持 + +## 2. 技术栈 + +* **后端**: Spring Boot, Spring Security, MyBatis Plus, MySQL, Mosquitto (MQTT Broker) +* **前端**: Next.js, React, TypeScript, Ant Design, Axios +* **数据库**: MySQL +* **通信协议**: HTTP/HTTPS, MQTT + +## 3. 项目部署与运行 + +### 3.1. 环境准备 +* Java JDK 1.8 或更高版本 +* Maven 3.x +* Node.js 16.x 或更高版本 +* Yarn 或 npm +* MySQL 5.7 或更高版本 +* MQTT Broker (例如 Mosquitto) 已安装并运行 (默认端口 1883) + +### 3.2. 后端服务 (springboot-init-main) +1. **数据库配置**: + * 创建一个数据库 (例如 `charging_system_db`)。 + * 修改 `springboot-init-main/src/main/resources/application.yml` (或对应环境的配置文件) 中的数据库连接信息: + ```yaml + spring: + datasource: + url: jdbc:mysql://localhost:3306/your_database_name?useUnicode=true&characterEncoding=utf-8&serverTimezone=Asia/Shanghai + username: your_db_username + password: your_db_password + ``` +2. **MQTT Broker 配置**: + * 确保 MQTT Broker 正在运行。 + * 在 `application.yml` 中配置 MQTT 连接参数 (如果需要修改默认值或添加认证): + ```yaml + mqtt: + broker-url: tcp://localhost:1883 # 替换为您的 MQTT Broker 地址 + client-id-publisher: backend-publisher-default + client-id-subscriber: backend-subscriber-default + default-topic: "charging/default/topic" # 示例，具体业务主题见单片机对接部分 + # username: your_mqtt_username # 如果 Broker 需要认证 + # password: your_mqtt_password # 如果 Broker 需要认证 + ``` +3. **启动后端服务**: + * 在 `springboot-init-main` 目录下，使用 Maven 运行: + ```bash + mvn spring-boot:run + ``` + * 或者打包成 jar 文件后运行: + ```bash + mvn clean package + java -jar target/springboot-init-main-0.0.1-SNAPSHOT.jar # 注意替换为实际生成的jar包名 + ``` + * 服务默认运行在 `http://localhost:7529` (或您在 `application.yml` 中配置的端口)。 + +### 3.3. 前端应用 (charging_web_app) +1. **安装依赖**: + 在 `charging_web_app` 目录下运行: + ```bash + yarn install + # 或者 + # npm install + ``` +2. **API 代理配置**: + 前端应用通过 Next.js 的代理将 `/api` 请求转发到后端服务。此配置在 `next.config.js` 中： + ```javascript + // next.config.js (示例) + /** @type {import('next').NextConfig} */ + const nextConfig = { + reactStrictMode: true, + async rewrites() { + return [ + { + source: '/api/:path*', + destination: 'http://localhost:7529/api/:path*', // 后端服务地址 + }, + ]; + }, + }; + module.exports = nextConfig; + ``` + 确保 `destination` 指向您后端服务的正确地址和端口。 +3. **启动前端开发服务器**: + ```bash + yarn dev + # 或者 + # npm run dev + ``` + 前端应用默认运行在 `http://localhost:3000`。 + +4. **构建生产版本**: + ```bash + yarn build + yarn start + # 或者 + # npm run build + # npm run start + ``` + +## 4. 单片机 (充电桩硬件) 对接指南 + +智能充电桩硬件需通过 MQTT 协议与本系统的后端服务进行通信。 + +### 4.1. MQTT 连接配置 +* **Broker 地址**: 单片机需配置连接到与后端服务相同的 MQTT Broker (例如 `tcp://your_mqtt_broker_address:1883`)。 +* **Client ID**: 每个充电桩应使用唯一的 Client ID。建议使用充电桩的物理ID或序列号，例如 `charger_spot_001`。 +* **认证**: 如果 MQTT Broker 配置了用户名/密码认证，单片机连接时也需提供。 + +### 4.2. MQTT 主题 (Topics) 约定 + +#### 4.2.1. 状态上报 (单片机 -> 后端) +* **主题格式**: `charging/spot/{spotUid}/status` + * `{spotUid}`: 充电桩/车位的唯一标识符 (必须与后端数据库中 `parking_spot` 表记录的 `uid` 一致)。 +* **消息格式 (Payload)**: JSON + ```json + { + "spotUid": "SPOT001", + "timestamp": "2024-05-19T12:30:00Z", // ISO 8601 UTC + "status": "IDLE", + "voltage": 220.5, + "current": 0.0, + "power": 0.0, + "energyConsumed": 0.0, // 本次充电已用电量 (kWh) + "errorCode": 0, + "errorMessage": "", + "sessionId": null // 可选，充电中则为当前会话ID + } + ``` +* **状态定义 (`status`)**: (根据实际项目枚举调整) + * `IDLE`: 空闲 + * `PLUGGED_IN`: 已插枪 (待启动) + * `AWAITING_START_COMMAND`: (可选) 已扫码，等待后端确认启动 + * `CHARGING`: 充电中 + * `STOPPING`: 停止中 + * `COMPLETED`: 充电完成 + * `FAULTED`: 故障 + +#### 4.2.2. 指令下发 (后端 -> 单片机) +单片机需订阅以下主题以接收指令。 + +* **启动充电指令**: + * **主题格式**: `charging/spot/{spotUid}/command/start` + * **消息格式 (Payload)**: JSON + ```json + { + "commandId": "cmd_uuid_123", + "sessionId": 789, + "userId": 123 + } + ``` + +* **停止充电指令**: + * **主题格式**: `charging/spot/{spotUid}/command/stop` + * **消息格式 (Payload)**: JSON + ```json + { + "commandId": "cmd_uuid_678", + "sessionId": 789, + "reason": "USER_REQUEST" + } + ``` + +#### 4.2.3. 指令执行回执 (单片机 -> 后端, 推荐) +* **主题格式**: `charging/spot/{spotUid}/command/ack` +* **消息格式 (Payload)**: JSON + ```json + { + "commandId": "cmd_uuid_123", + "spotUid": "SPOT001", + "status": "SUCCESS", + "message": "Charging started" + } + ``` + +#### 4.2.4. 心跳 (单片机 -> 后端) +* **主题格式**: `charging/spot/{spotUid}/heartbeat` +* **消息格式 (Payload)**: JSON + ```json + { + "spotUid": "SPOT001", + "timestamp": "2024-05-19T12:35:00Z", + "status": "IDLE" + } + ``` +* **频率**: 例如每 30-60 秒。 + +### 4.3. 单片机开发关键逻辑 +1. **MQTT 初始化与重连机制**。 +2. **订阅指令主题**。 +3. **JSON 指令消息解析**。 +4. **充电启停控制** (继电器等硬件操作)。 +5. **状态监测与实时上报**。 +6. **心跳包定时发送**。 +7. **故障检测与上报**。 +8. **安全性**: 确保 `spotUid` 唯一性；推荐 MQTT 通信使用 TLS/SSL 加密。 + +### 4.4. 示例流程：用户启动充电 +1. 用户在前端 App 请求启动充电桩 `SPOT001`。 +2. 后端服务验证，创建充电会话 `sessionId=789`。 +3. 后端向 MQTT 主题 `charging/spot/SPOT001/command/start` 发布启动指令。 +4. 单片机 `SPOT001` 接收指令，启动充电。 +5. 单片机向 `charging/spot/SPOT001/status` 上报状态 `CHARGING`，包含 `sessionId`。 +6. (可选) 单片机向 `charging/spot/SPOT001/command/ack` 发布成功回执。 +7. 后端更新会话状态，前端界面同步更新。 + +## 5. 项目结构 (简要) + +``` +. 项目根目录 +├── charging_web_app/ # 前端 Next.js 应用 +│ ├── src/ +│ ├── public/ +│ └── package.json +├── springboot-init-main/ # 后端 Spring Boot 应用 +│ ├── src/ +│ │ ├── main/ +│ │ │ ├── java/com/yupi/project/ +│ │ │ └── resources/ +│ │ └── test/ +│ ├── doc/ # 项目文档 (如数据库DDL, 阶段计划等) +│ └── pom.xml +└── README.md # 本文件 +``` + +## 6. 后续工作与展望 +* 完善各模块的单元测试和集成测试。 +* 进一步优化 API 文档和错误处理机制。 +* 根据实际运营需求，增加更细致的统计报表功能。 +* 考虑引入更高级的 MQTT 特性，如QoS、遗嘱消息等。 +* 前端 UI/UX 持续打磨，提升用户体验。 \ No newline at end of file diff --git a/springboot-init-main/sql/mqtt_power.sql b/springboot-init-main/sql/mqtt_power.sql index 155b659..7a6ee64 100644 --- a/springboot-init-main/sql/mqtt_power.sql +++ b/springboot-init-main/sql/mqtt_power.sql @@ -11,12 +11,35 @@ Target Server Version : 50744 File Encoding : 65001 - Date: 17/05/2025 21:14:59 + Date: 18/05/2025 19:54:49 */ SET NAMES utf8mb4; SET FOREIGN_KEY_CHECKS = 0; +-- ---------------------------- +-- Table structure for activation_code +-- ---------------------------- +DROP TABLE IF EXISTS `activation_code`; +CREATE TABLE `activation_code` ( + `id` bigint(20) UNSIGNED NOT NULL AUTO_INCREMENT COMMENT '主键ID', + `code` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NOT NULL COMMENT '激活码字符串，确保全局唯一', + `value` decimal(10, 2) NOT NULL COMMENT '激活码对应的面值（金额）', + `is_used` tinyint(3) UNSIGNED NOT NULL DEFAULT 0 COMMENT '是否已使用：0-未使用，1-已使用', + `user_id` bigint(20) UNSIGNED NULL DEFAULT NULL COMMENT '使用者用户ID (如果已使用)', + `use_time` datetime NULL DEFAULT NULL COMMENT '激活码使用时间 (如果已使用)', + `expire_time` datetime NULL DEFAULT NULL COMMENT '激活码过期时间 (NULL表示永不过期)', + `batch_id` varchar(64) CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci NULL DEFAULT NULL COMMENT '生成批次号，方便管理员追踪管理', + `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', + `update_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', + `is_delete` tinyint(3) UNSIGNED NOT NULL DEFAULT 0 COMMENT '逻辑删除标志：0-未删除，1-已删除', + PRIMARY KEY (`id`) USING BTREE, + UNIQUE INDEX `uk_code`(`code`) USING BTREE COMMENT '激活码唯一索引', + INDEX `idx_user_id`(`user_id`) USING BTREE COMMENT '使用者用户ID索引', + INDEX `idx_expire_time`(`expire_time`) USING BTREE COMMENT '过期时间索引', + INDEX `idx_batch_id`(`batch_id`) USING BTREE COMMENT '批次号索引' +) ENGINE = InnoDB AUTO_INCREMENT = 102 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_unicode_ci COMMENT = '激活码表' ROW_FORMAT = Dynamic; + -- ---------------------------- -- Table structure for charging_robot -- ---------------------------- @@ -34,7 +57,7 @@ CREATE TABLE `charging_robot` ( `is_deleted` tinyint(1) NULL DEFAULT 0 COMMENT '逻辑删除标志 (0:未删, 1:已删)', PRIMARY KEY (`id`) USING BTREE, UNIQUE INDEX `robot_uid`(`robot_uid`) USING BTREE -) ENGINE = InnoDB AUTO_INCREMENT = 1 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_german2_ci COMMENT = '充电机器人表' ROW_FORMAT = Dynamic; +) ENGINE = InnoDB AUTO_INCREMENT = 5 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_german2_ci COMMENT = '充电机器人表' ROW_FORMAT = Dynamic; -- ---------------------------- -- Table structure for charging_session @@ -64,7 +87,7 @@ CREATE TABLE `charging_session` ( `update_time` datetime NULL DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '记录更新时间', `is_deleted` tinyint(1) NULL DEFAULT 0 COMMENT '逻辑删除标志 (0:未删, 1:已删)', PRIMARY KEY (`id`) USING BTREE -) ENGINE = InnoDB AUTO_INCREMENT = 1 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_german2_ci COMMENT = '充电记录表' ROW_FORMAT = Dynamic; +) ENGINE = InnoDB AUTO_INCREMENT = 8 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_german2_ci COMMENT = '充电记录表' ROW_FORMAT = Dynamic; -- ---------------------------- -- Table structure for parking_spot @@ -82,7 +105,7 @@ CREATE TABLE `parking_spot` ( `is_deleted` tinyint(1) NULL DEFAULT 0 COMMENT '逻辑删除标志 (0:未删, 1:已删)', PRIMARY KEY (`id`) USING BTREE, UNIQUE INDEX `spot_uid`(`spot_uid`) USING BTREE -) ENGINE = InnoDB AUTO_INCREMENT = 1 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_german2_ci COMMENT = '车位表' ROW_FORMAT = Dynamic; +) ENGINE = InnoDB AUTO_INCREMENT = 5 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_german2_ci COMMENT = '车位表' ROW_FORMAT = Dynamic; -- ---------------------------- -- Table structure for robot_task @@ -103,7 +126,7 @@ CREATE TABLE `robot_task` ( `is_delete` tinyint(1) NULL DEFAULT 0 COMMENT '逻辑删除标志 (0:未删, 1:已删)', PRIMARY KEY (`id`) USING BTREE, INDEX `idx_robot_status`(`robot_id`, `status`) USING BTREE COMMENT '机器人和状态索引，便于查询' -) ENGINE = InnoDB AUTO_INCREMENT = 1 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_german2_ci COMMENT = '机器人指令任务表' ROW_FORMAT = Dynamic; +) ENGINE = InnoDB AUTO_INCREMENT = 7 CHARACTER SET = utf8mb4 COLLATE = utf8mb4_german2_ci COMMENT = '机器人指令任务表' ROW_FORMAT = Dynamic; -- ---------------------------- -- Table structure for user