8bc7812733
拆分范围（14 个文件）：migrate / users / operation_logs / energy_stats / charge_records / batteries / device_logs / auth / captcha / main / routes::mod / h5 / cabinet_tree / report_worker 手法：长 SQL 抽模块级 const、拼装与映射与校验抽私有 fn、路由按业务域拆 Router 再 merge、 Excel 导出按"取数/表头/逐行/收尾"分阶段、连续代码块原样搬移+传参。 行为不变的证据： - 路由 79 → 79 条逐条比对一致（路径+handler+方法链；中间件/CORS/with_state 作用域保持） - 字符串字面量多重集比对：11 个文件唯一集合完全一致；report_worker 零差异（435 条字面量全等） - 关键契约计数不变：CAST 14→14、AS SIGNED 4→4、COALESCE 6→6；SQL 文本与 Redis key 零增删 - 未新增 #[allow] / unwrap / expect / panic；captcha 的 RNG 消耗顺序保持（验证码分布不变） 验收：cargo check 0 error / 0 warning；cargo test --bins 39 passed / 0 failed；全仓已无 >80 行函数。 端到端回归：先部署测试环境跑 TCP 协议联调 13/13，且数据库终态与重构前逐字段一致 （orders.energy=22、start_soc=850、end_soc=1000、records.energy=22.00、max_temp=29800、占用状态正确复位）。
充电柜矩阵系统 (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），零报错零警告