# 充电柜矩阵系统 (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 配置镜像（nginx.conf 主配置 + app / test，共三份，与线上逐字节一致） │ ├── *.service # systemd 单元（pms-api / pms-device × prod·test） │ ├── deploy-prod.ps1 # 正式环境一键部署（推荐入口） │ └── deploy-*.sh # ⛔ 已废弃（执行即报错退出） ├── tools/ # 开发工具 │ ├── db.py # 数据库工具（默认连测试库 pms_dev；需先起 SSH 隧道） │ ├── dev-tunnel.ps1 # 开发机 SSH 隧道（127.0.0.1:13306/16379 → 阿里云 RDS/Redis） │ └── 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` 会永久卡死且无日志）； > 该 stream 转发已于 **2026-09-20 移除**（服务侧现直连阿里云 Redis，开发机走 `tools/dev-tunnel.ps1` 隧道）， > 但**轮询约定不变**。 > 依据：`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 # 两端一致性（PC ↔ 小程序） node test/device_status_parse.test.mjs node test/rssi_signal.test.mjs ``` 完整验收流程（含自证能失败的要求）见 [AGENTS.md](AGENTS.md#验收流程)。