471b61d277
1) probe_export.py：任务状态语义**搞反了**（导出成功也会被判失败）
- download_tasks.status 的权威语义是 0 排队 / 1 处理中 / **2 完成** / 3 失败
（db/migrate.rs:225 列注释；写入侧 charge_records.rs::mark_task_completed 写的就是 2）。
- 该脚本此前**等 status == 1（处理中）当成功、把 status == 2（完成）判成"导出失败"**
—— 典型假红。已按权威语义订正，并与另外两处**本来就正确**的口径对齐：
web/src/pages/charge-records/DownloadCenter.tsx::statusText、
test/schema_alignment_e2e.py（等 status in (2,3) 再断言 == 2）。
- 同批修正退出码分类：账号缺 charge_record:export（403）由 exit 1 改为
**exit 2「未验证」** —— 本项要验证的是"降权成 pms 后能否往 exports/ 落盘"，
没权限根本走不到那一步，报 1 是**把夹具缺陷说成产品缺陷**（误报与假绿同样有害）。
- 允许用 PMS_PROBE_PHONE / PMS_PROBE_PASSWORD 换成有权限的账号。
- **C 项结论（由落盘物证直接判定，不依赖该脚本）**：测试环境
exports/充电记录__-.xlsx 5559 B、生产同类产物 5457 B，属主均为 pms:pms；
两环境 exports/uploads 目录均 pms:pms，两 api-server 单元均 User=pms/Group=pms
⇒ 降权进程确实能落盘。已在 README 写明并给出取证依据。
2) deploy-prod.ps1 的退出码（此前失败的探针只打印 ❌ 就继续，脚本仍以 0 退出）
- 消费链路探测失败（exit 1）现在**记入失败清单**并以 exit 1 收尾；
"未验证"（隧道没起）默认仍不计失败（环境问题会误报），
但新增 **-StrictVerify** 开关供 CI/无人值守使用，打开即 exit 1。
- 好处：把这条从"打印了 ❌ 却 exit 0"（仓库第 8 条假绿）里摘出来。
3) 统一退出码 0/1/2 落地到本批脚本，并对每个失败路径实测取证：
- test/tcp_e2e_smoke.py：13/13 通过（含未登录业务报文被静默丢弃）；先复位夹具再跑。
- test/security-hardening/ 新增 verdict.py 判据容器（未跟踪 → 本次入库）；
4 个探针全部按失败→exit 1 改造，并各实测过失败路径。
- 实测结果（2026-09-20 发布后回归）：smoke_prod 4/4 exit 0、
probe_prod 5/5 exit 0、probe_upload 6/6 exit 0。
4) 工具与文档
- tools/db.py 默认库由**生产 pms 改为测试 pms_dev**（可用 PMS_MYSQL_DB 覆盖，
切生产时打印醒目警告）—— "以为在测测试库、实际打生产"的隐患。
- tools/db_schema_diff.py：连不上必须是 exit 2，绝不伪装成"无漂移"的 0。
- 新增 tools/dev-tunnel.ps1（入库，SSH 隧道；口令走 PMS_SSH_PASSWORD 环境变量），
配套 tools/dev-tunnel-run.ps1 自愈启动器**保持 gitignore**（内含口令）。
- deploy/nginx/nginx.conf 镜像随线上同步（移除 stream 转发；与线上逐字节一致）。
- AGENTS.md / README.md：补「踩过的坑」第 7/8 条（掐断上游管道会杀被测进程、
打印 ❌ 却 exit 0 是假绿）、退出码约定、本地开发改 SSH 隧道、
在线判据口径订正、order_timeout 守门补齐、小程序 vue-tsc 门禁与其抓到的两个真 BUG。
发布验收（本次统一发布，按 device→api 顺序）：
- 测试环境与生产环境四服务 active，端口 9000/9001/3000/3001 正确，ERROR 均为 0；
- 生产迁移按判据 grep '更新列注释' 实测对齐 cabinets.status 列注释；
- 结构漂移 python tools/db_schema_diff.py = 0 处漂移 / exit 0（--vs-ddl 两库同样 0）；
- schema_alignment_e2e --env dev 全部通过 exit 0；
- 生产域名 /api/pms/cabinets -> 401、/pms/ -> 200；消费链路探测通过。
161 lines
9.7 KiB
Markdown
161 lines
9.7 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/ # 开发文档、协议文档（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 <JWT_SECRET>
|
||
|
||
# 两端一致性（PC ↔ 小程序）
|
||
node test/device_status_parse.test.mjs
|
||
node test/rssi_signal.test.mjs
|
||
```
|
||
|
||
完整验收流程（含自证能失败的要求）见 [AGENTS.md](AGENTS.md#验收流程)。
|