# MQTT 智能充电机器人系统 - 开发方案

## 1. 引言

本文档旨在为 "MQTT 智能充电机器人系统" 提供详细的开发方案。该方案基于已确认的需求文档 (`requirements.md`) 和技术选型，旨在指导后端平台的开发工作。项目目标是构建一个稳定、可扩展的后端服务，用于管理用户、调度充电机器人、处理充电业务逻辑，并通过 MQTT 与机器人硬件进行通信。

## 2. 系统架构概览

系统采用典型的 **前后端分离 + 物联网 (IoT)** 架构：

*   **后端平台 (本项目核心)**: 基于 Spring Boot，负责业务逻辑处理、数据持久化、用户认证授权、与 MQTT Broker 交互。
*   **MQTT Broker**: 外部公共服务（如 EMQX），作为消息中间件，负责平台与机器人之间的消息传递。**需要用户提供具体的连接信息和认证凭据。**
*   **充电机器人 (硬件)**: 基于 ESP32-CAM，负责执行指令、采集状态、通过 MQTT 与 Broker 通信。**本项目不涉及硬件的具体开发。**
*   **前端应用 (可选)**: Web 或 App，通过调用后端 API 与系统交互。**本项目不包含前端开发。**

**关键技术栈:**

*   **后端**: Spring Boot 2.7.0, Java 1.8
*   **数据访问**: MyBatis-Plus, MySQL
*   **缓存**: Redis (用于 Session 管理等)
*   **消息队列**: MQTT (使用 Eclipse Paho Java Client)
*   **API 文档**: Knife4j

## 3. 开发阶段与模块划分

我们将开发过程划分为以下几个主要阶段/模块：

**阶段一：基础架构与用户管理**

1.  **环境配置**: 确认 JDK, Maven, MySQL, Redis 环境。
2.  **数据库初始化**:
    *   根据 `requirements.md` 中的设计，创建数据库 `mqtt_charging_system` (或使用现有 `my_db` 并调整)。
    *   编写并执行 SQL DDL 脚本，创建 `user`, `charging_robot`, `parking_spot`, `charging_session`, `activation_code` 表（详细见第 4 节）。
3.  **用户模块实现**:
    *   创建 `User` 实体类 (`model/entity/User.java`)，包含余额、角色等字段。
    *   创建 `UserMapper` 接口 (`mapper/UserMapper.java`)。
    *   创建 `UserService` 接口及实现 (`service/UserService.java`, `service/impl/UserServiceImpl.java`)，包含用户注册、查询、余额更新等方法。
    *   实现密码存储：使用 Spring Security 的 `BCryptPasswordEncoder` 对密码进行加密。在 `config` 包下配置 `PasswordEncoder` Bean。
    *   创建 `UserController` (`controller/UserController.java`)，提供登录接口。
4.  **认证与授权**:
    *   实现登录接口 `/api/user/login`。
    *   登录成功后，使用 Spring Session (已配置为 Redis 存储) 存储用户会话信息。
    *   后续请求通过 Session 进行用户身份验证。
    *   实现简单的基于角色的访问控制：在需要权限的 Controller 方法或 Service 方法上，通过检查当前登录用户的 `role` 字段进行判断。可以创建一个简单的 AOP 切面或直接在方法内判断。

**阶段二：MQTT 集成**

1.  **配置 MQTT 连接**:
    *   在 `application.yml` 中添加 MQTT Broker 的 `url`, `username`, `password`, 以及用于命令和状态的 `commandTopic`, `statusTopic` 基础路径。**这些值需要用户提供。**
    *   创建 `MqttProperties.java` (`config/properties/MqttProperties.java`) 类，使用 `@ConfigurationProperties` 读取配置。
2.  **实现 MQTT 客户端**:
    *   创建 `MqttConfig.java` (`config/MqttConfig.java`)。
    *   配置 `MqttConnectOptions` Bean，设置用户名、密码、自动重连、清理会话等。
    *   配置 `MqttClient` Bean，并在应用启动后连接到 Broker。
    *   **重点**: 实现 `MqttCallbackExtended` 接口，处理连接成功 (`connectComplete`)、连接丢失 (`connectionLost`)、消息到达 (`messageArrived`) 事件。
    *   在 `connectComplete` 中，订阅状态 Topic (`robot/status/+`)。`+` 是通配符，用于接收所有机器人的状态。
    *   在 `connectionLost` 中，记录日志并依赖 Paho 客户端的自动重连机制。
    *   在 `messageArrived` 中，将接收到的消息（JSON 字符串）传递给专门的消息处理服务。
3.  **实现消息发布与处理**:
    *   创建 `RobotTaskService.java` (`service/RobotTaskService.java`) 用于管理 `robot_task` 表的 CRUD 和状态检查。
    *   创建 `MqttService.java` (`service/MqttService.java`)。
    *   提供 `sendCommand(String robotId, String commandType, String payloadJson, Long sessionId)` 方法：
        *   **调用 `RobotTaskService` 检查 `robotId` 是否有状态为 `SENT` 的任务。如果有，则不允许发送，直接返回错误或特定状态。**
        *   如果允许发送，**调用 `RobotTaskService` 在 `robot_task` 表创建 `PENDING` 状态的任务记录。**
        *   构造实际的 MQTT Topic (`robot/command/{robotId}`)
        *   调用 Paho 客户端的 `publish` 方法发送 MQTT 消息。
        *   **发送成功后，立即调用 `RobotTaskService` 将对应任务状态更新为 `SENT` 并记录 `sent_time`。**
    *   创建 `MqttMessageHandler.java` (`service/MqttMessageHandler.java` 或类似名称)。
    *   提供 `handleStatusUpdate(String topic, String payload)` 方法，由 `MqttCallback` 的 `messageArrived` 调用。
    *   在此方法中：
        *   解析 `topic` 获取 `robotId`。
        *   使用 Gson (或 Jackson) 将 `payload` (JSON) 解析为 `RobotStatusDTO`。
        *   **根据收到的状态，调用 `RobotTaskService` 查找并更新对应的 `SENT` 任务状态为 `ACKNOWLEDGED_SUCCESS` 或 `ACKNOWLEDGED_FAILURE`，记录 `ack_time`。**
        *   **在任务状态更新成功后**，再根据 DTO 中的 `status` 字段，调用相应的业务逻辑（如 `ChargingService` 更新机器人状态、处理充电完成事件等）。

**阶段三：核心充电业务逻辑**

1.  **机器人与车位管理**:
    *   创建 `ChargingRobot` 和 `ParkingSpot` 实体、Mapper、Service、Controller。
    *   提供基础的 CRUD 接口供管理员使用（可选，根据 `requirements.md`）。
    *   `ChargingRobotService` 需要包含更新机器人状态（如 `idle`, `moving`, `charging`, `error`）和位置的方法。
2.  **充电会话管理**:
    *   创建 `ChargingSession` 实体、Mapper、Service。
3.  **充电流程实现**:
    *   创建 `ChargingController.java` (`controller/ChargingController.java`)。
    *   实现 `/api/charging/request` 接口：
        *   接收用户请求（包含 `spotId`）。
        *   验证用户登录状态和余额。
        *   调用 `ChargingRobotService` 查找可用机器人。
        *   **调用 `MqttService.sendCommand` 发送 `move_to_spot` 指令 (该方法内部会检查任务表并创建任务记录)。如果返回错误（机器人忙），则告知用户。**
        *   （可选）创建或更新 `ChargingSession` 记录为 `pending` 或 `robot_moving` 状态。
    *   在 `MqttMessageHandler` 中处理状态更新：
        *   **首先更新 `robot_task` 表状态。**
        *   `arrived_at_spot` (确认 `move_to_spot` 成功后): 更新机器人DB状态，**调用 `MqttService.sendCommand` 发送 `start_charge` 指令。**
        *   `charging` (确认 `start_charge` 可能隐含的响应，或只是状态更新): 记录开始时间，更新 `ChargingSession`。
        *   `charge_complete` (确认充电结束，可能是主动上报或响应 `stop_charge`): 记录结束时间、时长，**触发计费**，更新用户余额，更新 `ChargingSession`。
        *   `error`: 记录错误，更新机器人和 `ChargingSession` 状态。
    *   实现 `/api/charging/stop` 接口（用户手动停止）：
        *   **调用 `MqttService.sendCommand` 发送 `stop_charge` 指令。**
        *   后续处理逻辑依赖于 `charge_complete` 或 `error` 消息的处理。
4.  **计费逻辑**:
    *   在 `UserService` 或单独的 `BillingService` 中实现计费方法。
    *   根据 `ChargingSession` 的总时长和预设的单价计算费用。
    *   调用 `UserService` 更新用户余额 (注意并发安全，可使用数据库行锁或乐观锁)。

**阶段四：激活码与完善**

1.  **激活码模块**:
    *   创建 `ActivationCode` 实体、Mapper、Service。
    *   实现激活码生成逻辑（管理员功能，可在 Service 中提供）。
    *   创建 `ActivationCodeController.java` (`controller/ActivationCodeController.java`)。
    *   实现 `/api/codes/redeem` 接口：接收激活码，验证有效性，调用 `UserService` 更新用户余额，将激活码标记为已使用。
2.  **API 文档**:
    *   在所有 Controller 和 DTO 上添加 Knife4j (Swagger) 注解 (`@Api`, `@ApiOperation`, `@ApiModelProperty` 等)。
3.  **测试**:
    *   编写单元测试 (JUnit) 覆盖 Service 层核心逻辑。
    *   进行接口测试（使用 Postman 或类似工具）。
    *   **难点**: MQTT 交互的测试，可能需要 Mock `MqttClient` 或搭建本地 MQTT Broker 进行集成测试。
4.  **错误处理与日志**:
    *   完善全局异常处理 (`GlobalExceptionHandler.java`)。
    *   在关键业务点添加详细日志（使用 SLF4j）。
    *   **新增：实现任务超时处理逻辑。**
        *   创建 `TaskTimeoutHandler.java` (`service/TaskTimeoutHandler.java` 或类似名称)。
        *   使用 `@Scheduled` 注解创建一个定时任务，定期执行。
        *   在定时任务中，调用 `RobotTaskService` 查找状态为 `SENT` 且超时的任务。
        *   对于超时的任务，更新其状态为 `TIMED_OUT`，记录错误信息。
        *   根据业务需要，可能需要同步更新关联的 `charging_robot` 和 `charging_session` 的状态。

## 4. 数据库 Schema (初步 DDL)

```sql
-- 用户表
CREATE TABLE `user` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID',
  `username` VARCHAR(255) NOT NULL UNIQUE COMMENT '用户名',
  `password` VARCHAR(255) NOT NULL COMMENT '密码 (加密存储)',
  `role` VARCHAR(50) NOT NULL DEFAULT 'user' COMMENT '角色 (user/admin)',
  `balance` DECIMAL(10, 2) NOT NULL DEFAULT 0.00 COMMENT '账户余额',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `is_deleted` TINYINT(1) DEFAULT 0 COMMENT '逻辑删除标志 (0:未删, 1:已删)'
) COMMENT='用户表';

-- 充电机器人表
CREATE TABLE `charging_robot` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID',
  `robot_id` VARCHAR(100) NOT NULL UNIQUE COMMENT '机器人唯一标识符 (对应MQTT clientId)',
  `status` VARCHAR(50) DEFAULT 'idle' COMMENT '状态 (idle, moving, charging, error, offline)',
  `location` VARCHAR(255) COMMENT '当前位置描述 (如 base, near_P001, P001)',
  `battery_level` INT COMMENT '电量百分比',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `is_deleted` TINYINT(1) DEFAULT 0 COMMENT '逻辑删除标志'
) COMMENT='充电机器人表';

-- 车位表
CREATE TABLE `parking_spot` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID',
  `spot_id` VARCHAR(100) NOT NULL UNIQUE COMMENT '车位唯一标识符',
  `location_desc` VARCHAR(255) COMMENT '位置描述',
  `status` VARCHAR(50) DEFAULT 'available' COMMENT '状态 (available, occupied, maintenance)',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
  `is_deleted` TINYINT(1) DEFAULT 0 COMMENT '逻辑删除标志'
) COMMENT='车位表';

-- 充电记录表
CREATE TABLE `charging_session` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID',
  `user_id` BIGINT NOT NULL COMMENT '用户ID',
  `robot_id` VARCHAR(100) NOT NULL COMMENT '机器人ID',
  `spot_id` VARCHAR(100) NOT NULL COMMENT '车位ID',
  `start_time` DATETIME COMMENT '充电开始时间',
  `end_time` DATETIME COMMENT '充电结束时间',
  `duration_seconds` INT COMMENT '总充电时长 (秒)',
  `cost` DECIMAL(10, 2) COMMENT '本次消费金额',
  `status` VARCHAR(50) COMMENT '会话状态 (pending, robot_moving, charging, completed, error, cancelled)',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '记录创建时间',
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '记录更新时间'
) COMMENT='充电记录表';

-- 激活码表
CREATE TABLE `activation_code` (
  `id` BIGINT AUTO_INCREMENT PRIMARY KEY COMMENT '主键ID',
  `code` VARCHAR(100) NOT NULL UNIQUE COMMENT '激活码字符串',
  `value` DECIMAL(10, 2) NOT NULL COMMENT '充值金额',
  `is_used` TINYINT(1) DEFAULT 0 COMMENT '是否已使用 (0:未使用, 1:已使用)',
  `user_id` BIGINT COMMENT '使用者ID (使用后)',
  `use_time` DATETIME COMMENT '使用时间',
  `expire_time` DATETIME COMMENT '过期时间 (可选)',
  `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间'
) COMMENT='激活码表';

```
*注：以上 DDL 仅为初步设计，字段类型、长度、索引等可能需要根据实际情况调整。*

## 5. API 设计 (高层规划)

*   **认证**:
    *   `POST /api/user/login`
    *   `POST /api/user/logout` (可选, 使 Session 失效)
*   **用户**:
    *   `GET /api/user/current` (获取当前用户信息，包括余额)
    *   `GET /api/users` (管理员 - 获取用户列表)
*   **充电**:
    *   `POST /api/charging/request` (用户 - 发起充电请求，参数: `spotId`)
    *   `POST /api/charging/stop` (用户 - 请求停止当前充电)
    *   `GET /api/charging/history` (用户 - 查看自己的充电记录)
    *   `GET /api/charging/sessions` (管理员 - 查看所有充电记录)
*   **激活码**:
    *   `POST /api/codes/redeem` (用户 - 使用激活码充值，参数: `code`)
    *   `POST /api/codes` (管理员 - 生成激活码，可选)
*   **管理 (可选)**:
    *   `GET /api/robots`
    *   `POST /api/robots`
    *   `GET /api/spots`
    *   `POST /api/spots`

## 6. MQTT 消息契约

再次强调，`requirements.md` 中定义的 MQTT Topic 和 Payload 结构为 **关键接口**。必须与硬件开发团队 **最终确认并严格遵守** 此约定。任何变动都需要双方同步更新。

## 7. 后续步骤

1.  **等待用户提供**:
    *   MQTT Broker 的详细连接信息 (URL, Port)。
    *   用于指令 (`robot/command/{clientId}`) 和状态 (`robot/status/{clientId}`) Topic 的用户名和密码。
    *   与硬件团队确认最终的 MQTT Topic 和 Payload 结构。
2.  **开始开发**: 在获取 MQTT 信息后，可以并行开始：
    *   **阶段一**: 数据库初始化、用户模块开发、**`robot_task` 相关基础 Service 开发**。
    *   **阶段二**: MQTT 配置、基础连接、订阅实现、**集成 `robot_task` 检查与更新逻辑**、**任务超时处理实现**。
3.  按照开发阶段逐步推进。