f80b3b634c
## 严重问题
- order_timeout: 超时条件方向写反（`start_time < TIMESTAMPADD(HOUR,10,NOW())` 等价于
`start_time < NOW()+10h`，条件恒真）→ 活跃订单会被当超时单提前结掉。改为
`TIMESTAMPADD(HOUR, ?, start_time) < NOW()`，并补"刚建单不命中/超期命中"双向断言
- C1 device-server 连接池可被未验签的报文 dev_id 顶替（覆盖式 insert + 断连无条件 remove）：
改为 conn_id 归属模型 —— 唯一连接标识、remove_if/touch/is_authenticated 均带 conn 归属校验、
接管时用 oneshot 信号主动驱逐旧连接、每条上行前用 is_owner 复核持有者身份
- C2 POST /api/devices/{imei}/command 零归属校验 + act 自由字符串 + 把 IMEI 塞进协议 id：
补 scope_guard 归属校验 + act 白名单 + id 从 params 显式取（拒绝 15 位 IMEI）
- 非总管理员权限集恒为空（user_roles 从不写入且无分配入口）→ 全站 403：
user_roles 为空时按 users.role 回退内置角色权限 + 建/改用户幂等同步映射（仅角色变化时同步）
## 订单生命周期并发正确性
- finalize_order 先取电量累加器后抢结束权 → off/bat_out 成对到达时 energy 被写 0：
改为先原子抢占（WHERE compartment_id=? AND status=0 ORDER BY id DESC LIMIT 1），
抢到者才 take_and_reset 取电量；抢不到直接返回且不碰累加器
- 建单"先查后插"无锁无唯一约束 → 同仓体两笔活跃单：
条件插入（INSERT ... SELECT ... WHERE NOT EXISTS）+ 按仓体进程内锁
+ DB 层 active_flag 生成列 + UNIQUE 唯一索引（幂等迁移，有重复则记 ERROR 跳过，绝不阻断启动）
- handle_bat_out: updated==0 时不再复位占用；通道登记删除改为 battery_id 一致才删；
新增 should_finalize_bat_out 挡住"迟到 bat_out 结束新单"
- 电压/电流加量程夹取（0–100000 mV/mA 之外按 0 计并 WARN），防位翻转导致积分暴增
## 协议/契约
- spec 绝不可能是 "0000"（生产 42/68 台拓扑为空）：新增 build_spec 三级兜底
（真实拓扑 → cabinets.cell×6 → 6×6），兜底生效记 WARN 报出拓扑数据
- /api/cabinets/realtime-status 改读真实字段（原来读的设备链路从不写的旧字段，恒返回 idle/空），
用 derive_channel_view 推导旧字段以保持响应字段名不变；修掉"把通道号当板号"的幽灵板问题
- 小程序通道详情/PC 详情改读通道 Hash（弃用无写入方的 compartment:status:{id}），
取不到返回 null 而非假的 0；补 voltage/current/temp/batt_status/pow_status
- 反馈列表补权限码 operation_log:view + status 筛选真正落到 SQL
- 小程序柜温换算（29800 曾被显示成 29800°C）；签名注释 7→8 位；msg_id 序列化省略 null；
parse_compartment_id 与 status_post 补板号 1–15/通道 1–8 量程校验（不再写 board:0 垃圾 key）
## 文档
- docs/柜控板固件对接文档.md：确立数值口径统一规则（hex 字节流=原始硬件单位·平台换算；
JSON 数值字段=平台单位·设备换算）、修正 A.5.3 的 id 说明、作废变更记录原位标注（不删历史）、
spec 表述改为"按拓扑现算+兜底、恒 4 位不会是 0000"、修复文首 7 项表格被引用块切断丢表头、
修正 §10 误引 channels[].channel、写明无电池兜底阈值与 #16 风险
## 运维加固（服务器侧，非代码）
- 关闭 MySQL/Redis 公网暴露：nginx stream 由 0.0.0.0 改为只监听 127.0.0.1 + ZeroTier
- worker_shutdown_timeout 30s（原先每次 reload 泄漏永不退出的 worker）
- 测试证书改指向 app 证书（原测试证书 9 天后过期且无续期机制）；补测试环境 uploads 目录；.env 0600
## 验收
- cargo check 两服务 0 error / 0 warning；cargo test api 88 + device 22 全过
- 路由 79 → 79 逐条一致；web tsc 干净
- 端到端联调（测试环境）13/13，订单结算与重构前逐字段一致；唯一索引已由迁移真实建出
- 生产已部署并验证：服务 active、health 200、ERROR 0、消费链路正常、迁移已建索引
充电柜矩阵系统 (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），零报错零警告