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