124 lines
7.1 KiB
Markdown
124 lines
7.1 KiB
Markdown
# 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)，防止重复发送指令给未响应的机器人。 |