MQTT 智能充电桩系统 - 需求文档

1. 项目概述

本项目旨在开发一个基于 Spring Boot 的 移动式 智能充电管理系统。系统作为后端平台，通过 MQTT 协议与 基于 ESP32-CAM 的充电机器人 硬件设备进行通信，实现远程控制、状态监控以及 调度机器人到指定车位进行充电。同时，系统提供用户管理、充值计费等功能。平台软件不负责机器人底层的导航、避障、循迹等具体算法实现，仅发送高级指令并接收处理后的状态。

2. 功能需求

2.1 用户管理与认证

用户角色: 系统需支持两种用户角色：
- 管理员：拥有系统所有管理权限。
- 普通用户：可进行充电、充值等操作。
用户登录: 提供安全的用户名密码登录机制。
- 区分管理员和普通用户登录接口或逻辑。
用户信息管理 (管理员权限):
- 查看用户列表。
- （可选）添加、编辑、删除用户信息。

2.2 MQTT 集成与设备控制

MQTT 连接:
- 连接至 指定的公共 MQTT 服务器 (如 EMQX，需提供具体地址和端口)。
- 支持为特定的 MQTT 主题（Topic）设置用户名和密码进行认证 (需提供)。
- 配置用于指令下发和状态上报的 Topic。
消息格式:
- 与充电机器人通过 JSON 字符串格式进行消息交互。
设备控制 (平台侧重点):
- 向充电机器人发送 高级控制指令（见 MQTT Topic 规划）。
- 平台 不处理 原始传感器数据（如红外、超声波读数）。
状态接收 (平台侧重点):
- 接收充电机器人上报的 综合状态信息（见 MQTT Topic 规划）。

2.3 智能充电核心业务

充电机器人管理 (管理员权限):
- （可选）添加、查看、管理充电机器人设备信息（如：设备ID、当前状态、位置）。
车位管理 (管理员权限):
- （可选）管理可用的充电车位信息（如：车位ID、位置描述）。
激活码充值:
- 普通用户可以使用激活码为自己的账户充值。
- 系统需验证激活码的有效性，并将对应金额或时长添加到用户账户。
- 需要设计激活码生成和管理机制（管理员）。
充电计费:
- 根据实际充电时长进行计费。
- 需要明确计费单价（例如：元/小时）。
- 充电结束后，从用户账户扣除相应费用。
- 用户账户余额不足时，应有相应处理（如：无法启动充电、自动停止充电）。
充电流程 (平台侧重点):
1. 用户登录系统。
2. 用户 选择目标充电车位 {parkingSpotId}。
3. 用户发起充电请求。
4. 系统检查用户余额。
5. 系统选择一个可用的充电机器人 {robotId} (如果系统管理多个机器人)。
6. 系统通过 MQTT 发送 移动指令 (move_to_spot) 给机器人 {robotId}，目标为车位 {parkingSpotId}。
7. 机器人移动到位后，通过 MQTT 上报 arrived_at_spot 状态。
8. 系统通过 MQTT 发送 启动充电指令 (start_charge) 给机器人。
9. 机器人开始充电并通过 MQTT 上报 charging 状态（及充电时长）。
10. 用户发起停止充电请求或机器人上报 charge_complete / error 状态。
11. 系统通过 MQTT 发送 停止充电指令 (stop_charge) 给机器人。
12. 系统根据 MQTT 上报的 总充电时长 计算费用并扣费。
13. 记录充电日志。

2.4 充电记录

记录用户的充电历史，包括：用户、使用的机器人、充电车位、开始时间、结束时间、充电时长、消费金额。
普通用户可查看自己的充电记录。
管理员可查看所有充电记录。

3. 非功能需求

可用性: 系统应稳定可靠，提供持续服务。
安全性: 用户密码需加密存储；MQTT 通道需进行安全认证；防止未授权访问。
可维护性: 代码结构清晰，遵循高内聚低耦合原则，易于维护和扩展。
性能: 系统应能及时响应用户请求和处理 MQTT 消息。

4. 技术选型（初步）

后端框架: Spring Boot
持久层: MyBatis-Plus
数据库: MySQL
缓存: Redis
MQTT Broker: 外部公共服务 (如 EMQX, 需用户提供实例信息)
MQTT 客户端库: Eclipse Paho MQTT Client
API 文档: Knife4j
数据交换格式: JSON
机器人控制器 (参考): ESP32-CAM

5. MQTT 通道（Topic）规划 (需要用户确认并提供细节)

基础 Topic 结构: (建议)
- 指令下发: robot/command/{clientId}
- 状态上报: robot/status/{clientId}
- 注：{clientId} 通常是认证时使用的客户端ID，可以等同于机器人ID {robotId}，需要与硬件端约定。
指令下发 Topic: robot/command/{clientId} (平台 -> 机器人)
- 认证: 需要 (用户名/密码由用户提供)
- Payload (JSON 示例):
  - 移动到车位: {"action": "move_to_spot", "spotId": "P001"}
  - 开始充电: {"action": "start_charge"}
  - 停止充电: {"action": "stop_charge"}
  - 查询状态: {"action": "query_status"} (可选)
状态上报 Topic: robot/status/{clientId} (机器人 -> 平台)
- 认证: 需要 (用户名/密码由用户提供)
- Payload (JSON 示例):
  - 空闲状态: {"robotId": "R001", "status": "idle", "location": "base", "battery": 95}
  - 移动中: {"robotId": "R001", "status": "moving", "targetSpot": "P001", "battery": 90}
  - 到达车位: {"robotId": "R001", "status": "arrived_at_spot", "spotId": "P001", "battery": 88}
  - 充电中: {"robotId": "R001", "status": "charging", "spotId": "P001", "durationSeconds": 120, "battery": 92}
  - 充电完成: {"robotId": "R001", "status": "charge_complete", "spotId": "P001", "totalDurationSeconds": 3600, "battery": 100}
  - 错误状态: {"robotId": "R001", "status": "error", "errorCode": "NAV_BLOCKED", "message": "Navigation path blocked", "location": "near_P002"}
  - 通用状态响应 (对 query_status): {"robotId": "R001", "status": "idle", "location": "base", "battery": 95}
重要提示: 上述 Topic 结构和 Payload 内容为建议，最终需要与硬件（ESP32）开发侧 详细约定 并统一。平台将根据约定的格式进行开发。

6. 数据库设计 (已精简)

用户表 (user): 包含用户基本信息、密码、角色 (如: admin, user)、账户余额。
充电机器人表 (charging_robot)
车位表 (parking_spot)
充电记录表 (charging_session)
激活码表 (activation_code)
机器人任务表 (robot_task): 用于跟踪发送给机器人的指令及其状态 (pending, sent, acknowledged_success, acknowledged_failure, timed_out)，防止重复发送指令给未响应的机器人。

7.1 KiB Raw Blame History Unescape Escape