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 通过
充电柜矩阵系统 (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} │
└─────────────────────────────────────────────────────────────┘
核心设计原则：
- TCP服务轻量化 — 只处理TCP通信和指令解析，不处理业务逻辑
- Redis做缓冲 — 服务间通信用Redis LIST，不用HTTP直接调用
- 全异步处理 — 所有指令异步处理，msg_id匹配响应
- 协程处理任务 — API服务用tokio::spawn处理Redis队列消息
通信流程：
- 设备上报：设备 → TCP → 设备服务 → Redis LIST → API服务协程处理
- 平台指令：API服务 → Redis LIST → 设备服务 → TCP → 设备
- 指令响应：设备 → TCP → 设备服务 → Redis LIST → API服务匹配msg_id
节点管理：
- 设备服务启动时注册到API服务
- 每60秒心跳，180秒无心跳视为离线
- 支持多节点扩展（当前单节点）
TCP 设备通讯协议
完整协议文档见 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
- 任务需求写到
tasks/目录的md文件 - 通过Agent子代理包裹opencode执行，异步通知
- 质量约束模板固定追加到每个任务文件
- 完成代码后执行对应栈静态校验（Rust→cargo check，TS→tsc --noEmit），零报错零警告