first commit

app_car/clr_wallbox.md

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