999885c38f
协议（唯一权威文档：docs/柜控板固件对接文档.md） - 应答必带 act（与请求一致）、msg_id 与请求一致；判"应答 vs 指令"只看有没有 suc - dev_id 只在 auth_str/login 携带；其余报文用内部字段 _dev_id 路由（下发前由 device-server 摘除） - id 只表示动作目标（柜级省略 / 一段=单板 / 两段=仓体级），不再含 IMEI - msg_id 每连接从 1 起自增；60 秒交互超时；status_post 每通道 18 字符 hex 全量上报 - 未登录连接 30 秒内未 login 即断开；未登录只放行 auth_str/login 平台侧实现 - 上行解析按新结构重写（cabinet/boards/battery），删除废弃的 status/parsed_status - 订单：唯一入口 = on；bat_in 只登记电池台账；4 条结束路径统一走 finalize_order（含充电记录落库） - 新增设备日志保留策略（90 天，分批删除）；未登记 IMEI 静默丢弃；停电标记按 status1 bit0 恢复清除 - 待确认第 13 项兜底：平台侧按 电压 × 电流 × 时间 积分计算订单电量（workers/energy.rs） - 待确认第 18 项兜底：status_post bit7 连续 2 次无电池 → 判定电池被拔走并提前结单 修复（均为部署后才暴露的问题） - 队列消费禁用 BRPOP：无限阻塞会因代理掐连接永久卡死（零错误日志）；有限超时也只是 "超时才醒"，下行指令延迟 15~45 秒 → 改为 RPOP 非阻塞轮询，延迟降到 0.1~0.2 秒 - sync_iccid 把可空列 iccid 按 Option<String> 解码 → 整条 login 失败（ICCID 未上报的新柜子永远登录不上） - 迁移读 information_schema.COLUMN_COMMENT 需 CAST(... AS CHAR)（MySQL 8 驱动报 VARBINARY，否则迁移 panic） - 部署注意事项：.env 不支持行内注释；pscp 上传需 chmod +x；运行中二进制需 .new + mv 原子替换 部署 - 生产迁到 API 9000 / TCP 9001（systemd 单元补 EnvironmentFile、nginx 同步指向） - 新增 deploy/deploy-prod.ps1（本地一键：构建→校验→备份→原子替换→重启→验收→无副作用探测） - 废弃 deploy-prod.sh / deploy-test.sh（原脚本会在 target/release 找产物、装重复 systemd 单元、 并用本地 .env 覆盖线上 .env） 质量 - 单测：api-server 39 个 / device-server 13 个（含协议示例逐值断言、跨模块 Redis key 契约） - 两服务 cargo check 零错误零告警；web tsc --noEmit 通过 - test/tcp_e2e_smoke.py 端到端联调 13/13 通过
109 lines
5.5 KiB
Markdown
109 lines
5.5 KiB
Markdown
# 充电柜矩阵系统 (Power Matrix System / PMS)
|
||
|
||
产品名：安知充（anzhizhichong），品牌名：艾动智能
|
||
|
||
## 项目简介
|
||
|
||
36仓体直流电瓶车充电柜，仓数不固定：1柜控板+N仓控板，每仓控板管6仓，最小6仓。
|
||
|
||
## 技术栈
|
||
|
||
- **后端**：Rust + Axum
|
||
- **前端**：React + Arco Design Pro（管理端）
|
||
- **微信小程序用户端**：uni-app + Vue 3（构建目标 mp-weixin）
|
||
- **数据库**：MySQL（阿里云RDS）
|
||
- **缓存**：Redis（阿里云Redis）
|
||
- **设备通讯**：TCP长连接（柜控板4G模块，Air780E Cat.1）
|
||
|
||
## 项目结构
|
||
|
||
```
|
||
charging-cabinet/
|
||
├── tasks/ # 任务文件（opencode执行）
|
||
├── docs/ # 开发文档、协议文档
|
||
├── software/
|
||
│ ├── api-server/ # Rust API服务
|
||
│ ├── device-server/ # Rust TCP设备服务
|
||
│ ├── web/ # React管理端前端
|
||
│ └── h5-uniapp/ # 微信小程序用户端（uni-app + Vue 3，构建目标 mp-weixin）
|
||
├── hardware/ # 硬件资料（原理图/PCB等）
|
||
├── deploy/ # 部署配置
|
||
└── test/ # 测试用例/报告
|
||
```
|
||
|
||
> 本仓库不存放技能库（skills）。开发期技能从全局技能目录加载（`~/.dsh/skills`、`~/.agents/skills`），请勿在仓库内重新 vendor。
|
||
|
||
## 部署架构
|
||
|
||
| 环境 | 域名 | 说明 |
|
||
|------|------|------|
|
||
| 正式环境 | app.anzhizhichong.com | 后台管理 + API服务 |
|
||
| 测试环境 | test.anzhizhichong.com | 测试环境 |
|
||
|
||
**服务器**：CentOS Stream 9
|
||
|
||
**内部服务**：
|
||
- Gitea: https://app.anzhizhichong.com/doc/
|
||
- 文档Wiki: https://app.anzhizhichong.com/doc/anzhizhichong/charging-cabinet/wiki/
|
||
|
||
## 服务架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ API服务 (api-server) — 主服务 │
|
||
│ - HTTP API（后台管理 + 小程序）端口: 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 设备通讯协议
|
||
|
||
> 完整协议文档见 **[docs/柜控板固件对接文档.md](docs/柜控板固件对接文档.md)**（v1.1，唯一权威 TCP 文档）
|
||
|
||
- TCP 长连接，空闲 60 秒/充电 15 秒上报
|
||
- 所有设备上报消息平台都会回复 `{"act":"<同请求>","msg_id":N,"suc":1}` 确认
|
||
- 响应扁平化，不加 `data` 包裹
|
||
- 签名机制：`SHA256(dev_id + auth_str + timestamp)`，取 `hex[56..64]`，**8 位**小写十六进制
|
||
- `id` 字段：仓体级 `IMEI-板-通道`，柜级 `IMEI`
|
||
- 全局整数单位：voltage mV, current mA, temp K×100, soc ‰
|
||
|
||
**11 条指令：** login / auth_str / status_post / pow_fail / bat_in / bat_out / on / off / open / pow_on / pow_off / reset
|
||
|
||
完整请求/响应示例、字段表、签名自测向量、超时与自愈流程 → [docs/柜控板固件对接文档.md](docs/柜控板固件对接文档.md)
|
||
|
||
- 任务需求写到 `tasks/` 目录的md文件
|
||
- 通过Agent子代理包裹opencode执行，异步通知
|
||
- 质量约束模板固定追加到每个任务文件
|
||
- 完成代码后执行对应栈静态校验（Rust→cargo check，TS→tsc --noEmit），零报错零警告
|