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/               # 开发文档、协议文档（API.md、柜控板固件对接文档.md …）
├── deploy/             # 部署配置与脚本
│   ├── nginx/          # Nginx 配置（app / test 两份，与线上一致）
│   ├── *.service       # systemd 单元（pms-api / pms-device × prod·test）
│   ├── deploy-prod.ps1 # 正式环境一键部署（推荐入口）
│   └── deploy-*.sh     # ⛔ 已废弃（执行即报错退出）
├── tools/              # 开发工具
│   ├── db.py           # 数据库工具（默认连测试库 pms_dev）
│   └── db_schema_diff.py # 结构漂移巡检（测试库 vs 生产库 / vs 代码权威 DDL）
├── software/
│   ├── api-server/     # Rust API服务（产物 pms-api）
│   ├── device-server/  # Rust TCP设备服务（产物 pms-device-server）
│   ├── web/            # React管理端前端
│   └── h5-uniapp/      # 微信小程序用户端（uni-app + Vue 3，构建目标 mp-weixin）
├── hardware/           # 硬件资料（原理图/PCB等）
└── test/               # 测试/验收脚本
    ├── tcp_e2e_smoke.py        # TCP 协议端到端（模拟柜控板打测试环境 :3001）
    ├── schema_alignment_e2e.py # 结构对齐端到端（造临时行并自动清理）
    ├── device_status_parse.test.mjs # PC 与小程序状态位解析一致性
    ├── rssi_signal.test.mjs         # PC 与小程序 RSSI 分档一致性（0–99 逐值）
    └── security-hardening/     # 安全加固探针脚本
```

> 本仓库不存放技能库（skills）。开发期技能从全局技能目录加载（`~/.dsh/skills`、`~/.agents/skills`），请勿在仓库内重新 vendor。

## 部署架构

| 环境 | 域名 | API 服务 | TCP 服务 | MySQL | Redis DB | 部署路径 | 前端路径 |
|------|------|----------|----------|-------|----------|----------|----------|
| 正式环境 | app.anzhizhichong.com | `:9000` | `:9001` | `pms` | db5 | `/data/pms` | `/pms/` |
| 测试环境 | test.anzhizhichong.com | `:3000` | `:3001` | `pms_dev` | db6 | `/data/pms_dev` | `/pms/` |

> ⚠️ 两个环境**完全隔离**（独立库 + 独立 Redis DB + 独立端口 + 独立部署目录）。
> ⛔ **绝不要把测试域名的 API 指向生产端口 `:9000`** —— 历史事故：测试 nginx 曾指向当时的生产端口，
> 等于"测试后台在操作生产数据"。判断方法：`test` 域名 `/api/pms/` 返回 **401**（有测试后端）是**对的**；
> 返回 **502** 说明测试后端没起。
> ⚠️ 代码里的默认端口（api `3000` / tcp `3002`）只在**没设环境变量**时生效，线上由 `.env` 的
> `PORT` / `TCP_PORT` 覆盖 —— 以本表为准。

**服务器**：CentOS Stream 9（2核/3.5G/49G），`118.31.119.206`（ZeroTier `10.8.0.252`）

**内部服务**：
- Gitea: https://app.anzhizhichong.com/doc/
- 文档Wiki: https://app.anzhizhichong.com/doc/anzhizhichong/charging-cabinet/wiki/

**部署方式**：本地交叉编译（`cargo zigbuild --release --target x86_64-unknown-linux-gnu`）后传二进制，
**服务器上不装 Rust/Node**（会 OOM）。一键脚本与「部署注意事项」见 `AGENTS.md`「部署与维护」。

## 服务架构

```
┌─────────────────────────────────────────────────────────────┐
│  API服务 (api-server / pms-api) — 主服务                      │
│  - HTTP API（后台管理 + 小程序）端口: 正式 9000 / 测试 3000      │
│  - 业务逻辑处理（验签/存DB/建单结单/告警/能耗）                 │
│  - 节点管理（设备服务注册/心跳）                                │
│  - 后台 Worker：上报消费(RPOP 200ms 轮询) / 回执 / 订单超时 /   │
│    日志清理 / 占用对账                                         │
└─────────────────────────────────────────────────────────────┘
       ↑ Redis LIST device:reports          ↑ Redis LIST device:commands
       │ (设备上报，device-server LPUSH)      │ (平台指令，api-server LPUSH)
       │                                    │ device-server 按 HGET device:{imei} node_id
       │                                    │ 路由到 device:commands:{node_id}
┌─────────────────────────────────────────────────────────────┐
│  设备服务 (device-server / pms-device-server) — 轻量化        │
│  - TCP监听: 正式 9001 / 测试 3001（设备长连接）                │
│  - 只处理通信和指令解析（归属/签名/业务全在 api-server）        │
│  - 不存DB、不验证签名、不处理业务                              │
│  - 节点注册/心跳：Redis `node:{node_id}`（含 ip/tcp_port/       │
│    status/last_heartbeat），TTL = DEVICE_REGISTER_TTL          │
│  - 设备路由：`device:{imei}` 的 `node_id` 字段                  │
└─────────────────────────────────────────────────────────────┘
```

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

**通信流程：**
- **设备上报**：设备 → TCP → 设备服务（`LPUSH device:reports`，带 `LTRIM` 上限）→ API服务 worker 消费
- **平台指令**：API服务（`LPUSH device:commands`）→ 设备服务按 `node_id` 路由 → TCP → 设备
- **指令响应**：设备 → TCP → 设备服务 → Redis LIST → API服务按 `msg_id` + `act` 匹配回执
- **死信**：投递失败的指令进 `device:commands:dead`

> ⚠️ **队列消费一律用 `RPOP` 非阻塞轮询（200ms）+ 空队列 `sleep`，禁止 `BRPOP`** ——
> Redis 经 nginx stream 代理 + 多路复用连接时 `BRPOP` 语义不可靠（`BRPOP 0` 会永久卡死且无日志）。
> 依据：`workers/report_worker.rs` 的 `REDIS_POLL_INTERVAL_MS` 注释。

**节点管理：**
- 设备服务启动时注册到 Redis `node:{node_id}`（并调用 API 的注册接口）
- 每 **60 秒**心跳（`HEARTBEAT_INTERVAL=60`），**180 秒**无心跳视为离线（`DEVICE_REGISTER_TTL=180`，
  线上 `.env` 显式设置；代码默认值是 300，仅在没有该环境变量时生效）
- 支持多节点扩展（当前单节点 `node-1`）

## TCP 设备通讯协议

> TCP 设备通讯协议见 **[docs/柜控板固件对接文档.md](docs/柜控板固件对接文档.md)**（唯一权威，v1.1）。本文不再重复。
> 全局整数单位（voltage mV、current mA、temp K×100、soc ‰）见 [docs/API.md](docs/API.md#数据单位规范)。
> 平台侧 Redis 实时状态的实际存储结构（key/字段/写入时机）见 [AGENTS.md](AGENTS.md#redis-实时状态存储)。

## 开发任务与质量约束

- 任务需求写到 `tasks/` 目录的md文件（编号递增）
- 通过 Agent 子代理包裹 opencode 执行，异步通知
- 质量约束模板固定追加到每个任务文件（模板见 [AGENTS.md](AGENTS.md#质量约束模板)）
- 完成代码后执行对应栈静态校验：**Rust → `cargo check`**，**TS → `npm run typecheck`（即 `tsc -b`）**，零报错零警告
  - ⛔ **不要写 `tsc --noEmit`**：`software/web/tsconfig.json` 是 solution 型（`files: []` + `references`），
    不带 `-b` 时它**一个文件都不编译、直接 exit 0**，是假绿。实测依据见 [AGENTS.md](AGENTS.md#踩过的坑历史教训改动前必读) 「踩过的坑」第 2 条

## 验收与自检

```bash
# 后端：静态校验 + 单测
cd software/api-server   && cargo check --all-targets && cargo test --bin pms-api
cd software/device-server && cargo check --all-targets && cargo test --bin pms-device-server

# 前端：真实类型检查
cd software/web && npm run typecheck

# 结构漂移巡检（改了表结构/迁移必跑）
python tools/db_schema_diff.py
python tools/db_schema_diff.py --vs-ddl

# 端到端
python test/tcp_e2e_smoke.py
python test/schema_alignment_e2e.py --env dev --jwt-secret <JWT_SECRET>

# 两端一致性（PC ↔ 小程序）
node test/device_status_parse.test.mjs
node test/rssi_signal.test.mjs
```

完整验收流程（含自证能失败的要求）见 [AGENTS.md](AGENTS.md#验收流程)。