evo-BMS/README_INTEGRATION.md

# EvoBMS MyBatis-Plus 和 MQTT 集成说明

## 概述

本项目已成功集成了 MyBatis-Plus 和 MQTT 功能，为 EVO 电池管理系统提供了强大的数据持久化和实时通信能力。

## MyBatis-Plus 集成

### 1. 依赖配置

已在 `pom.xml` 中添加以下依赖：
- `mybatis-plus-boot-starter`: MyBatis-Plus 核心依赖
- `mybatis-plus-generator`: 代码生成器
- `freemarker`: 模板引擎

### 2. 配置文件

在 `application.yml` 中添加了 MyBatis-Plus 配置：
```yaml
mybatis-plus:
  mapper-locations: classpath*:mybatis/**/*Mapper.xml
  type-aliases-package: com.evobms.project.**.domain
  global-config:
    db-config:
      id-type: AUTO
      field-strategy: NOT_NULL
      logic-delete-field: delFlag
      logic-delete-value: 2
      logic-not-delete-value: 0
```

### 3. 核心功能

#### 3.1 实体类注解
- `@TableName`: 指定表名
- `@TableId`: 主键配置
- `@TableLogic`: 逻辑删除
- `@Version`: 乐观锁

#### 3.2 Mapper 接口
继承 `BaseMapper<T>` 获得基础 CRUD 操作：
```java
@Mapper
public interface BmsDeviceMapper extends BaseMapper<BmsDevice> {
    // 自定义方法
}
```

#### 3.3 Service 层
继承 `IService<T>` 和 `ServiceImpl<M, T>`：
```java
public interface IBmsDeviceService extends IService<BmsDevice> {}

@Service
public class BmsDeviceServiceImpl extends ServiceImpl<BmsDeviceMapper, BmsDevice> 
    implements IBmsDeviceService {}
```

### 4. 示例代码

#### BmsDevice 实体类
位置：`src/main/java/com/evobms/project/bms/domain/BmsDevice.java`

包含完整的 BMS 设备属性，使用了 MyBatis-Plus 注解。

#### 数据库表
执行 `sql/bms_device.sql` 创建示例表和数据。

## MQTT 集成

### 1. 依赖配置

已添加 MQTT 相关依赖：
- `spring-integration-mqtt`: Spring Integration MQTT 支持
- `org.eclipse.paho.client.mqttv3`: Eclipse Paho MQTT 客户端

### 2. 配置文件

在 `application.yml` 中添加了 MQTT 配置：
```yaml
mqtt:
  host: tcp://localhost:1883
  clientId: evobms-client
  username: 
  password: 
  connectionTimeout: 30
  keepAliveInterval: 60
  subscribeTopic: evobms/+/data
  publishTopic: evobms/command
```

### 3. 核心组件

#### 3.1 MqttConfig 配置类
位置：`src/main/java/com/evobms/framework/config/MqttConfig.java`

提供了：
- MQTT 客户端工厂配置
- 消息接收通道
- 消息发送通道
- 消息处理器

#### 3.2 MqttService 服务类
位置：`src/main/java/com/evobms/project/bms/service/MqttService.java`

提供了：
- 发送 MQTT 消息
- 处理设备数据
- 设备控制命令
- 设备状态查询

### 4. 使用示例

#### 发送消息
```java
@Autowired
private MqttService mqttService;

// 发送设备控制命令
mqttService.sendDeviceCommand("BMS001", "STATUS_QUERY");

// 发送自定义消息
mqttService.sendMessage("evobms/test", "Hello MQTT");
```

#### 接收消息
消息会自动通过配置的消息处理器处理，支持设备数据自动更新。

## API 接口

### BmsDeviceController

位置：`src/main/java/com/evobms/project/bms/controller/BmsDeviceController.java`

提供了完整的 RESTful API：

- `GET /bms/device/list` - 查询设备列表
- `GET /bms/device/{deviceId}` - 获取设备详情
- `POST /bms/device` - 新增设备
- `PUT /bms/device` - 修改设备
- `DELETE /bms/device/{deviceIds}` - 删除设备
- `PUT /bms/device/status` - 批量更新状态
- `POST /bms/device/queryStatus/{deviceCode}` - 查询设备状态
- `POST /bms/device/restart/{deviceCode}` - 重启设备
- `POST /bms/device/config/{deviceCode}` - 配置设备
- `POST /bms/device/mqtt/send` - 发送 MQTT 消息
- `GET /bms/device/statistics` - 获取统计信息

## 使用建议

### 1. MyBatis-Plus 最佳实践

1. **实体类设计**：
   - 使用合适的注解标注字段
   - 继承 BaseEntity 获得公共字段
   - 合理使用逻辑删除和乐观锁

2. **查询优化**：
   - 使用 QueryWrapper 构建复杂查询
   - 合理使用分页插件
   - 避免 N+1 查询问题

3. **代码生成**：
   - 使用 MyBatis-Plus 代码生成器快速生成基础代码
   - 自定义模板适应项目需求

### 2. MQTT 最佳实践

1. **主题设计**：
   - 使用层次化主题结构：`evobms/{deviceCode}/{dataType}`
   - 合理使用通配符订阅

2. **消息格式**：
   - 使用 JSON 格式传输数据
   - 包含时间戳和设备标识

3. **错误处理**：
   - 实现消息重试机制
   - 记录通信日志
   - 处理连接断开重连

### 3. 安全考虑

1. **数据库安全**：
   - 使用参数化查询防止 SQL 注入
   - 合理设置数据库权限

2. **MQTT 安全**：
   - 配置用户名密码认证
   - 使用 TLS 加密传输
   - 限制主题访问权限

## 扩展功能

### 1. 数据监控
- 实时设备状态监控
- 历史数据分析
- 告警机制

### 2. 设备管理
- 设备注册和注销
- 固件升级
- 参数配置

### 3. 数据分析
- 电池性能分析
- 故障预测
- 能耗统计

## 故障排除

### 常见问题

1. **MyBatis-Plus 相关**：
   - 检查实体类注解配置
   - 确认 Mapper 扫描路径
   - 验证数据库连接配置

2. **MQTT 相关**：
   - 检查 MQTT 服务器连接
   - 确认主题订阅配置
   - 验证消息格式

### 日志配置

在 `application.yml` 中调整日志级别：
```yaml
logging:
  level:
    com.evobms: debug
    com.baomidou.mybatisplus: debug
    org.springframework.integration.mqtt: debug
```

## 总结

通过集成 MyBatis-Plus 和 MQTT，EvoBMS 系统具备了：
- 强大的数据持久化能力
- 实时的设备通信功能
- 完整的 RESTful API
- 灵活的扩展机制

这为构建现代化的电池管理系统提供了坚实的技术基础。