admin/charging-cabinet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
charging-cabinet/README.md

10 KiB
Raw Blame History

充电柜矩阵系统 (Power Matrix System / PMS)

产品名：安知充（anzhizhichong）

项目简介

36仓体直流电瓶车充电柜，仓数不固定：1柜控板+N仓控板，每仓控板管6仓，最小6仓。

技术栈

  • 后端：Rust + Axum
  • 前端：React + Arco Design Pro
  • 数据库：MySQL（阿里云RDS）
  • 缓存：Redis（阿里云Redis）
  • 设备通讯：TCP长连接（柜控板4G模块，Air780E Cat.1）

项目结构

charging-cabinet/
├── tasks/              # 任务文件（opencode执行）
├── docs/               # 开发文档、协议文档
├── software/
│   ├── server/         # Rust后端
│   └── web/            # React前端
├── hardware/           # 硬件资料（原理图/PCB等）
└── test/               # 测试用例/报告

部署架构

环境 域名 说明
正式环境 app.anzhizhichong.com 后台管理 + API服务
测试环境 test.anzhizhichong.com 测试环境

服务器：CentOS Stream 9

内部服务：

服务架构

┌─────────────────────────────────────────────────────────────┐
│  API服务 (api-server) — 主服务                               │
│  - HTTP API（后台管理 + H5）端口: 3000                       │
│  - 前端轮询刷新（每5秒）                                      │
│  - 业务逻辑处理（验证/存DB/告警）                             │
│  - 节点管理（设备服务注册/心跳）                               │
│  - 后台协程处理Redis队列                                     │
└─────────────────────────────────────────────────────────────┘
         ↑ Redis LIST                      ↑ Redis LIST
         │ device:report:{imei}            │ device:cmd:{imei}
         │ (设备上报)                       │ (平台指令)
         │                                 │
┌─────────────────────────────────────────────────────────────┐
│  设备服务 (device-server) — 轻量化                           │
│  - TCP监听: 3002（设备长连接）                                │
│  - 只处理通信和指令解析                                      │
│  - 不存DB、不验证签名、不处理业务                            │
│  - 注册到API服务（启动/心跳/注销）                           │
│  - Redis连接注册: device:{imei} → {node_id, ip, port}       │
└─────────────────────────────────────────────────────────────┘

核心设计原则：

  1. TCP服务轻量化 — 只处理TCP通信和指令解析，不处理业务逻辑
  2. Redis做缓冲 — 服务间通信用Redis LIST，不用HTTP直接调用
  3. 全异步处理 — 所有指令异步处理，msg_id匹配响应
  4. 协程处理任务 — API服务用tokio::spawn处理Redis队列消息

通信流程：

  • 设备上报：设备 → TCP → 设备服务 → Redis LIST → API服务协程处理
  • 平台指令：API服务 → Redis LIST → 设备服务 → TCP → 设备
  • 指令响应：设备 → TCP → 设备服务 → Redis LIST → API服务匹配msg_id

节点管理：

  • 设备服务启动时注册到API服务
  • 每60秒心跳，180秒无心跳视为离线
  • 支持多节点扩展（当前单节点）

TCP通讯协议

通信规则

  • TCP长连接，无需PING包
  • 空闲1分钟上报，充电15秒上报
  • 超时5000ms
  • JSON去空格回车省流量，LF处理粘包
  • dev_id：IMEI（10进制），sub_device_id：485 ID
  • msg_id：自增会话ID
  • 全局通道号：dev_id-sub_device_id-通道号（如123456789012345-01-6）

签名机制

  • 设备首次连接调 auth_str 接口获取8位安全码（仅一次）
  • sign = SHA256(dev_id + auth_str + timestamp).substring(56, 63)
  • 时间戳秒级，平台校验±60秒

指令清单

动作 方向 id格式 说明
login 设备→平台 无 登录（含sign+timestamp）
auth_str 设备→平台 无 获取安全码（仅首次）
status_post 设备→平台 无 定时上报（rssi+status字典）
pow_fail 设备→平台 无 电源掉电上报（含info区分交直流）
bat_in 设备→平台 IMEI-仓控板-通道 电池插入（含BMS数据，字段待定）
bat_out 设备→平台 IMEI-仓控板-通道 电池拔出
on 双向 IMEI-仓控板-通道 开始充电（平台下发/设备上报）
off 双向 IMEI-仓控板-通道 停止供电（平台手动/设备自动）
open 平台→设备 IMEI 开门
pow_on 平台→设备 IMEI 接触器合闸（恢复380V供电）
pow_off 平台→设备 IMEI 接触器分闸（切断380V供电）
status_get 平台→设备 IMEI-仓控板 查仓板状态
reset 平台→设备 IMEI 或 IMEI-仓控板 重启整柜或仓控板

status_post格式

{
  "act": "status_post",
  "msg_id": 42,
  "dev_id": "123456789012345",
  "rssi": 85,
  "status": {
    "123456789012345-01": "000100020003000400050006",
    "123456789012345-02": "000100020003000400050006"
  }
}
  • key: IMEI-仓控板ID
  • value: 6个通道状态拼接（每通道2字节=4个HEX字符）
  • 平台从key解析仓控板数量

指令详情

login（设备→平台）

设备登录，验证签名。

// 请求
{"act":"login","msg_id":1,"dev_id":"123456789012345","sign":"abc12345","timestamp":1719800000,"h_ver":"1.0.0","s_ver":"1.0.0"}

// 响应
{"suc":1,"msg_id":1,"cell":6}

字段说明：

  • sign — 签名（SHA256(dev_id+auth_str+timestamp)后8位）
  • timestamp — 秒级时间戳（平台校验±60秒）
  • h_ver — 硬件版本
  • s_ver — 软件版本
  • cell — 仓控板数量

auth_str（设备→平台）

获取8位安全码，仅首次连接调用。

// 请求
{"act":"auth_str","msg_id":2,"dev_id":"123456789012345","ccid":"89860000000000000000"}

// 响应
{"suc":1,"msg_id":2,"data":{"auth_str":"abcd1234"}}

字段说明：

  • ccid — SIM卡ICCID号
  • auth_str — 8位随机安全码（仅返回一次）

status_post（设备→平台）

定时上报，空闲60秒/充电15秒。

// 请求
{"act":"status_post","msg_id":10,"dev_id":"123456789012345","rssi":85,"status":{"123456789012345-01":"000100020003000400050006","123456789012345-02":"000100020003000400050006"}}

// 响应
{"suc":1,"msg_id":10}

status字段说明：

  • key: IMEI-仓控板ID
  • value: 6个通道状态拼接（每通道2字节=4个HEX字符）
  • 平台从key解析仓控板数量

pow_fail（设备→平台）

电源掉电上报。

// 请求
{"act":"pow_fail","msg_id":15,"dev_id":"123456789012345","info":"0"}

// 响应
{"suc":1,"msg_id":15}

字段说明：

  • info — 停电类型：0=直流停电(12V掉电)，1=交流停电(380V掉电)

pow_on（平台→设备）

接触器合闸，恢复380V充电电源供电。

// 请求
{"act":"pow_on","msg_id":16,"dev_id":"123456789012345"}

// 响应
{"suc":1,"msg_id":16}

pow_off（平台→设备）

接触器分闸，切断380V充电电源供电。

// 请求
{"act":"pow_off","msg_id":16,"dev_id":"123456789012345"}

// 响应
{"suc":1,"msg_id":16}

bat_in（设备→平台）

电池插入事件，立即上报。

// 请求
{"act":"bat_in","msg_id":20,"id":"123456789012345-01-6","bms":{"soc":45,"voltage":52.3}}

// 响应
{"suc":1,"msg_id":20}

平台处理：

  1. 记录电池信息
  2. 验证电池合规性
  3. 自动下发 on 指令

BMS数据字段待定。

bat_out（设备→平台）

电池拔出事件，立即上报。

// 请求
{"act":"bat_out","msg_id":21,"id":"123456789012345-01-6"}

// 响应
{"suc":1,"msg_id":21}

on（双向）

平台→设备： 开始充电

// 请求
{"act":"on","msg_id":30,"id":"123456789012345-01-6"}

// 响应
{"suc":1,"msg_id":30}

设备→平台： 充电开始确认（自动充电模式）

// 上报
{"act":"on","msg_id":30,"id":"123456789012345-01-6"}

off（双向）

平台→设备： 手动停止充电

// 请求
{"act":"off","msg_id":31,"id":"123456789012345-01-6"}

// 响应
{"suc":1,"msg_id":31}

设备→平台： 充满自动停止

// 上报
{"act":"off","msg_id":31,"id":"123456789012345-01-6"}

open（平台→设备）

开门，只需IMEI。

// 请求
{"act":"open","msg_id":40,"id":"123456789012345"}

// 响应
{"suc":1,"msg_id":40}

错误码63 = 门锁故障。

status_get（平台→设备）

查询仓板状态。

// 请求
{"act":"status_get","msg_id":50,"id":"123456789012345-01"}

// 响应
{"suc":1,"msg_id":50,"data":{"status":"..."}}

reset（平台→设备）

重启整柜或仓控板。

// 重启整柜
{"act":"reset","msg_id":60,"id":"123456789012345"}

// 重启仓控板
{"act":"reset","msg_id":61,"id":"123456789012345-01"}

// 响应
{"suc":1,"msg_id":60}

充电结束原因（平台判断）

平台收到 判断原因
off (设备→平台) normal — 正常充满
off (平台→设备) user_stop — 用户手动停止
bat_out normal — 电池拔出
bat_in (通道已有电池) forced — 新电池插入，旧电池强制结束
超时未响应 timeout — 通信超时

开发规范

  • 任务需求写到 tasks/ 目录的md文件
  • 通过Agent子代理包裹opencode执行，异步通知
  • 质量约束模板固定追加到每个任务文件
  • 完成代码后执行对应栈静态校验（Rust→cargo check，TS→tsc --noEmit），零报错零警告