charging-cabinet/README.md

# 充电柜矩阵系统 (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），零报错零警告