oneapp_docs/app_car/clr_wallbox.md

# 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，提供了完整的充电设备通信和管理能力。通过标准化的协议支持、稳定的数据处理和完善的安全机制，为充电基础设施的数字化管理提供了可靠的技术支撑。模块具有良好的扩展性和兼容性，能够适应不同厂商的充电设备和多样化的部署环境。