# 智能充电桩管理系统 (Charging Pile Management System)

## 1. 项目简介

本项目是一个基于 Spring Boot (后端) 和 Next.js (前端) 构建的智能充电桩管理与计费系统。旨在为用户提供便捷的充电服务，并为管理员提供高效的充电桩、用户及计费管理功能。支持通过 MQTT 协议与充电桩硬件（单片机）进行实时通信和控制。

### 核心功能
*   **用户端**:
    *   用户注册与登录
    *   查看账户余额、充电记录
    *   扫码/输入ID启动充电
    *   停止充电
    *   激活码兑换充值
*   **管理端**:
    *   用户管理（查询、添加、编辑、删除）
    *   充电桩/车位管理（状态监控、添加、编辑、删除）
    *   充电会话管理（查询、监控）
    *   激活码管理（生成、查询、删除）
    *   MQTT通信日志查看（查询、审计所有MQTT消息）
    *   系统概览与统计
*   **硬件交互 (通过 MQTT)**:
    *   充电桩状态上报 (空闲、连接中、充电中、故障等)
    *   远程启动/停止充电指令下发
    *   心跳维持

## 2. 技术栈

*   **后端**: Spring Boot, Spring Security, MyBatis Plus, MySQL, Mosquitto (MQTT Broker), Spring AOP (用于日志)
*   **前端**: 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包名
      ```
    *   **配置文件外部化**: `application.yml` 在打包时已配置为外部化，并会复制到 `target/config/application.yml`。在生产环境部署时，可以将此文件放置于 JAR 包同级目录的 `config` 文件夹下 (例如: `your_app_dir/config/application.yml`)，Spring Boot 将自动加载。或者，您也可以通过 `--spring.config.location` 启动参数来指定外部配置文件的具体路径，例如：`java -jar your_app.jar --spring.config.location=file:/path/to/your/external/application.yml`。
    *   服务默认运行在 `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) 约定

根据后端服务的实际MQTT通信实现，主题约定如下：

#### 4.2.1. 上行消息 (单片机 -> 后端)

所有类型的上行消息，包括设备状态更新、心跳以及对后端指令的执行回执 (ACK)，都统一发送到以下主题：

*   **统一上行主题格式**: `yupi_mqtt_power_project/robot/status/{spotUid}`
    *   `{spotUid}`: 充电桩/车位的唯一标识符 (例如 `ESP32_SPOT_001`，必须与后端系统中注册的设备ID一致)。
*   **消息格式 (Payload)**: JSON。
    消息体结构应与后端 `com.yupi.project.model.dto.mqtt.RobotStatusMessage` 类对应。通过消息体内的字段来区分具体的消息含义。

    **示例 - 常规状态更新或心跳包 (Heartbeat):**
    ```json
    {
      "robotUid": "ESP32_SPOT_001",
      "actualRobotStatus": "IDLE", // 当前设备状态，如 IDLE, CHARGING, COMPLETED, FAULTED
      // 以下为可选的详细状态，根据实际需求和后端处理逻辑添加
      "voltage": 220.5,
      "current": 0.0,
      "power": 0.0,
      "energyConsumed": 1.23, // kWh, 本次或累计，根据业务定义
      "errorCode": 0,         // 设备故障码，0为正常
      "message": "Device operational", // 可选的文本消息
      "activeTaskId": null    // 如果当前正在执行某个任务，可上报任务ID或会话ID
    }
    ```
    *   **心跳频率**: 建议每 30-60 秒发送一次心跳（可以是一个简化的状态更新消息）。

    **示例 - 指令执行回执 (ACK):**
    当单片机执行完后端下发的指令后，应向此统一上行主题发送一个回执消息。
    ```json
    {
      "robotUid": "ESP32_SPOT_001",
      "taskId": "backend_provided_task_id_123", // 后端下发指令时提供的taskId
      "status": "SUCCESS", // 或 "FAILURE"
      "message": "Charging started successfully", // 对指令执行结果的描述
      "errorCode": "0", // 如果失败，提供错误码
      "actualRobotStatus": "CHARGING" // 执行指令后设备的当前状态
      // "activeTaskId": "session_xyz" // 可选，如果与特定会话相关
    }
    ```

#### 4.2.2. 下行指令 (后端 -> 单片机)

后端服务向特定单片机下发指令时，使用以下主题格式。单片机应订阅其自身的这个专属指令主题。

*   **统一下行指令主题格式**: `yupi_mqtt_power_project/robot/command/{spotUid}`
    *   `{spotUid}`: 目标充电桩的唯一标识符。
*   **消息格式 (Payload)**: JSON。
    JSON消息体内部包含了具体的指令类型和所需参数。

    **示例 - 启动充电指令:**
    ```json
    {
      "commandType": "START_CHARGE", // 指令类型
      "taskId": "backend_task_id_for_ack_789", // 供单片机ACK时使用的任务ID
      "sessionId": "session_abc_123"   // 关联的充电会话ID
      // ...其他可能的参数...
    }
    ```

    **示例 - 停止充电指令:**
    ```json
    {
      "commandType": "STOP_CHARGE",
      "taskId": "backend_task_id_for_ack_000"
      // ...其他可能的参数...
    }
    ```
    *   **单片机处理逻辑**: 单片机收到消息后，需解析JSON负载，识别 `commandType`，提取 `taskId` (用于后续ACK)，并获取其他指令参数来执行相应操作。

### 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通信日志模块：
    *   (可选) 进一步优化Payload的展示，例如对JSON格式的Payload进行美化或提供折叠/展开功能。
    *   (可选) 根据实际需求，考虑日志数据的定期归档或清理策略的实现。
*   考虑引入更高级的 MQTT 特性，如QoS、遗嘱消息等。
*   前端 UI/UX 持续打磨，提升用户体验。