365 lines
9.1 KiB
Markdown
365 lines
9.1 KiB
Markdown
# CLR Wallbox 充电墙盒服务SDK
|
||
|
||
## 模块概述
|
||
|
||
`clr_wallbox` 是 OneApp 车联网生态中的充电墙盒服务SDK，负责充电墙盒设备的通信协议、数据处理、状态管理和业务逻辑封装等功能。该模块为充电墙盒应用提供底层的设备控制和数据服务能力。
|
||
|
||
### 基本信息
|
||
- **模块名称**: clr_wallbox
|
||
- **版本**: 0.2.14
|
||
- **描述**: 充电墙盒服务SDK
|
||
- **Flutter 版本**: >=2.10.5
|
||
- **Dart 版本**: >=3.0.0 <4.0.0
|
||
|
||
## 功能特性
|
||
|
||
### 核心功能
|
||
1. **设备通信协议**
|
||
- OCPP协议支持
|
||
- Modbus通信协议
|
||
- WebSocket实时通信
|
||
- HTTP RESTful API
|
||
|
||
2. **数据处理服务**
|
||
- 充电数据解析
|
||
- 设备状态处理
|
||
- 配置参数管理
|
||
- 历史数据存储
|
||
|
||
3. **业务逻辑封装**
|
||
- 充电会话管理
|
||
- 计费逻辑处理
|
||
- 安全验证机制
|
||
- 异常处理流程
|
||
|
||
4. **状态监控系统**
|
||
- 实时状态监控
|
||
- 健康状态检查
|
||
- 异常告警处理
|
||
- 性能指标统计
|
||
|
||
## 技术架构
|
||
|
||
### 目录结构
|
||
```
|
||
lib/
|
||
├── clr_wallbox.dart # 模块入口文件
|
||
├── src/ # 源代码目录
|
||
│ ├── protocols/ # 通信协议
|
||
│ ├── services/ # 业务服务
|
||
│ ├── models/ # 数据模型
|
||
│ ├── repositories/ # 数据仓库
|
||
│ ├── processors/ # 数据处理器
|
||
│ └── utils/ # 工具类
|
||
├── test/ # 测试文件
|
||
└── generated/ # 代码生成文件
|
||
```
|
||
|
||
### 依赖关系
|
||
|
||
#### 核心框架依赖
|
||
- `basic_modular: ^0.2.3` - 模块化框架
|
||
- `basic_network: ^0.2.3+4` - 网络通信框架
|
||
- `basic_storage: ^0.2.2` - 本地存储框架
|
||
- `basic_track: ^0.1.3` - 数据埋点
|
||
|
||
#### 工具依赖
|
||
- `json_annotation: ^4.6.0` - JSON序列化
|
||
- `dartz: ^0.10.1` - 函数式编程
|
||
- `freezed_annotation: ^2.0.3` - 数据类注解
|
||
- `path_provider: ^2.1.3` - 文件路径
|
||
- `charset_converter: ^2.1.1` - 字符编码转换
|
||
|
||
## 核心模块分析
|
||
|
||
### 1. 模块入口 (`clr_wallbox.dart`)
|
||
|
||
**功能职责**:
|
||
- SDK对外接口导出
|
||
- 服务初始化配置
|
||
- 依赖注入管理
|
||
|
||
### 2. 通信协议 (`src/protocols/`)
|
||
|
||
**功能职责**:
|
||
- 充电设备通信协议实现
|
||
- 消息编码解码处理
|
||
- 协议版本管理
|
||
- 连接状态维护
|
||
|
||
**主要协议**:
|
||
- `OCPPProtocol` - OCPP充电协议
|
||
- `ModbusProtocol` - Modbus工业协议
|
||
- `WebSocketProtocol` - WebSocket实时协议
|
||
- `HTTPProtocol` - HTTP REST协议
|
||
|
||
**协议特性**:
|
||
- **OCPP 1.6/2.0**: 开放充电点协议
|
||
- **Modbus RTU/TCP**: 工业标准协议
|
||
- **自定义协议**: 厂商特定协议
|
||
- **协议适配**: 多协议统一接口
|
||
|
||
### 3. 业务服务 (`src/services/`)
|
||
|
||
**功能职责**:
|
||
- 充电业务逻辑封装
|
||
- 设备管理服务
|
||
- 用户认证服务
|
||
- 计费结算服务
|
||
|
||
**主要服务**:
|
||
- `ChargingService` - 充电服务
|
||
- `DeviceService` - 设备服务
|
||
- `AuthService` - 认证服务
|
||
- `BillingService` - 计费服务
|
||
- `MonitoringService` - 监控服务
|
||
|
||
### 4. 数据模型 (`src/models/`)
|
||
|
||
**功能职责**:
|
||
- 充电设备数据模型
|
||
- 协议消息模型
|
||
- 业务实体模型
|
||
- 配置参数模型
|
||
|
||
**主要模型**:
|
||
- `WallboxDevice` - 墙盒设备模型
|
||
- `ChargingSession` - 充电会话模型
|
||
- `OCPPMessage` - OCPP消息模型
|
||
- `DeviceStatus` - 设备状态模型
|
||
- `ChargingConfig` - 充电配置模型
|
||
|
||
### 5. 数据仓库 (`src/repositories/`)
|
||
|
||
**功能职责**:
|
||
- 设备数据持久化
|
||
- 充电记录存储
|
||
- 配置信息管理
|
||
- 缓存数据处理
|
||
|
||
**主要仓库**:
|
||
- `DeviceRepository` - 设备数据仓库
|
||
- `SessionRepository` - 会话数据仓库
|
||
- `ConfigRepository` - 配置数据仓库
|
||
- `LogRepository` - 日志数据仓库
|
||
|
||
### 6. 数据处理器 (`src/processors/`)
|
||
|
||
**功能职责**:
|
||
- 协议数据解析
|
||
- 业务数据转换
|
||
- 状态数据处理
|
||
- 异常数据过滤
|
||
|
||
**主要处理器**:
|
||
- `MessageProcessor` - 消息处理器
|
||
- `StatusProcessor` - 状态处理器
|
||
- `DataConverter` - 数据转换器
|
||
- `ExceptionHandler` - 异常处理器
|
||
|
||
### 7. 工具类 (`src/utils/`)
|
||
|
||
**功能职责**:
|
||
- 协议工具方法
|
||
- 数据验证工具
|
||
- 加密解密工具
|
||
- 时间处理工具
|
||
|
||
**主要工具**:
|
||
- `ProtocolUtils` - 协议工具
|
||
- `CryptoUtils` - 加密工具
|
||
- `ValidationUtils` - 验证工具
|
||
- `TimeUtils` - 时间工具
|
||
|
||
## 业务流程
|
||
|
||
### 充电启动流程
|
||
```mermaid
|
||
graph TD
|
||
A[用户请求充电] --> B[设备状态检查]
|
||
B --> C{设备是否可用}
|
||
C -->|否| D[返回设备不可用]
|
||
C -->|是| E[用户身份验证]
|
||
E --> F{验证是否通过}
|
||
F -->|否| G[返回认证失败]
|
||
F -->|是| H[发送充电启动指令]
|
||
H --> I[设备响应处理]
|
||
I --> J{启动是否成功}
|
||
J -->|是| K[创建充电会话]
|
||
J -->|否| L[返回启动失败]
|
||
K --> M[开始充电监控]
|
||
M --> N[记录充电数据]
|
||
N --> O[更新充电状态]
|
||
O --> P{充电是否完成}
|
||
P -->|否| N
|
||
P -->|是| Q[结束充电会话]
|
||
Q --> R[生成充电报告]
|
||
```
|
||
|
||
### OCPP消息处理流程
|
||
```mermaid
|
||
graph TD
|
||
A[接收OCPP消息] --> B[消息格式验证]
|
||
B --> C{格式是否正确}
|
||
C -->|否| D[返回格式错误]
|
||
C -->|是| E[解析消息内容]
|
||
E --> F[识别消息类型]
|
||
F --> G[路由到对应处理器]
|
||
G --> H[执行业务逻辑]
|
||
H --> I[生成响应消息]
|
||
I --> J[序列化响应]
|
||
J --> K[发送响应消息]
|
||
K --> L[记录处理日志]
|
||
```
|
||
|
||
## OCPP协议设计
|
||
|
||
### 消息类型
|
||
1. **核心消息**
|
||
- `Authorize` - 授权验证
|
||
- `StartTransaction` - 开始充电
|
||
- `StopTransaction` - 停止充电
|
||
- `Heartbeat` - 心跳消息
|
||
|
||
2. **状态消息**
|
||
- `StatusNotification` - 状态通知
|
||
- `MeterValues` - 电表数值
|
||
- `BootNotification` - 启动通知
|
||
- `DataTransfer` - 数据传输
|
||
|
||
3. **配置消息**
|
||
- `ChangeConfiguration` - 修改配置
|
||
- `GetConfiguration` - 获取配置
|
||
- `Reset` - 重置设备
|
||
- `UnlockConnector` - 解锁连接器
|
||
|
||
### 消息结构
|
||
```json
|
||
{
|
||
"messageTypeId": 2,
|
||
"uniqueId": "19223201",
|
||
"action": "Heartbeat",
|
||
"payload": {}
|
||
}
|
||
```
|
||
|
||
## 数据存储设计
|
||
|
||
### 本地存储
|
||
1. **设备配置**
|
||
- 设备基本信息
|
||
- 通信参数
|
||
- 充电参数
|
||
- 安全配置
|
||
|
||
2. **充电记录**
|
||
- 充电会话数据
|
||
- 电量消耗记录
|
||
- 时间戳信息
|
||
- 用户信息
|
||
|
||
3. **状态数据**
|
||
- 设备当前状态
|
||
- 错误信息
|
||
- 性能指标
|
||
- 诊断数据
|
||
|
||
### 数据同步
|
||
- **增量同步**: 仅同步变化数据
|
||
- **全量同步**: 定期全量同步
|
||
- **冲突解决**: 数据冲突处理策略
|
||
- **版本控制**: 数据版本管理
|
||
|
||
## 安全机制
|
||
|
||
### 通信安全
|
||
- **TLS加密**: 传输层安全
|
||
- **证书验证**: 设备身份验证
|
||
- **消息签名**: 消息完整性验证
|
||
- **防重放**: 防止重放攻击
|
||
|
||
### 数据安全
|
||
- **敏感数据加密**: 本地数据加密
|
||
- **访问控制**: 数据访问权限
|
||
- **审计日志**: 操作审计记录
|
||
- **安全擦除**: 数据安全删除
|
||
|
||
## 性能优化
|
||
|
||
### 通信优化
|
||
- **连接池**: 复用网络连接
|
||
- **消息批处理**: 批量处理消息
|
||
- **压缩传输**: 数据压缩传输
|
||
- **异步处理**: 非阻塞消息处理
|
||
|
||
### 存储优化
|
||
- **数据压缩**: 存储空间优化
|
||
- **索引优化**: 查询性能优化
|
||
- **缓存策略**: 热点数据缓存
|
||
- **清理机制**: 过期数据清理
|
||
|
||
## 错误处理
|
||
|
||
### 错误分类
|
||
1. **通信错误**
|
||
- 网络连接失败
|
||
- 协议解析错误
|
||
- 超时错误
|
||
- 服务不可用
|
||
|
||
2. **业务错误**
|
||
- 认证失败
|
||
- 参数无效
|
||
- 状态冲突
|
||
- 资源不足
|
||
|
||
3. **系统错误**
|
||
- 内存不足
|
||
- 存储空间不够
|
||
- 系统异常
|
||
- 硬件故障
|
||
|
||
### 处理策略
|
||
- **重试机制**: 自动重试失败操作
|
||
- **降级处理**: 服务降级策略
|
||
- **补偿机制**: 事务补偿处理
|
||
- **告警通知**: 异常情况告警
|
||
|
||
## 测试策略
|
||
|
||
### 单元测试
|
||
- **协议解析测试**: 消息编解码
|
||
- **业务逻辑测试**: 充电流程
|
||
- **数据模型测试**: 序列化反序列化
|
||
- **工具类测试**: 工具方法功能
|
||
|
||
### 集成测试
|
||
- **协议集成测试**: 设备通信
|
||
- **数据库集成测试**: 数据持久化
|
||
- **服务集成测试**: 端到端流程
|
||
- **第三方集成测试**: 外部系统
|
||
|
||
### 兼容性测试
|
||
- **设备兼容性**: 不同厂商设备
|
||
- **协议版本**: OCPP不同版本
|
||
- **网络环境**: 不同网络条件
|
||
- **并发测试**: 多设备并发
|
||
|
||
## 部署和维护
|
||
|
||
### 配置管理
|
||
- **环境配置**: 开发、测试、生产
|
||
- **协议配置**: 协议参数设置
|
||
- **安全配置**: 证书和密钥管理
|
||
- **性能配置**: 性能调优参数
|
||
|
||
### 监控指标
|
||
- **设备在线率**: 设备连接状态
|
||
- **消息处理量**: 消息吞吐量
|
||
- **错误率**: 错误发生频率
|
||
- **响应时间**: 消息处理延迟
|
||
|
||
## 总结
|
||
|
||
`clr_wallbox` 模块作为 OneApp 的充电墙盒服务SDK，提供了完整的充电设备通信和管理能力。通过标准化的协议支持、稳定的数据处理和完善的安全机制，为充电基础设施的数字化管理提供了可靠的技术支撑。模块具有良好的扩展性和兼容性，能够适应不同厂商的充电设备和多样化的部署环境。
|