ee92102f3c
- user_scopes 由"假开关"做成生效：粒度到项目级（组织隔离 ∧ 项目∈范围，取交集）；未配置=不限制（逐字向后兼容）；
总管理员豁免；脏数据保守忽略不锁死；配置期校验存在性+归属；逐接口叠加（列表/详情/写操作/Excel 导出落 scope_project_ids）；
前端新增"数据范围"弹窗入口。顺带修 GET /api/charge-orders 此前完全没有组织隔离（跨租户泄露）、
GET /api/projects/{id}/cabinets 的 500
- 数据库列类型系统性对齐：扫描并修复 pms_dev 32 项 / pms 18 项漂移（时间列统一 DATETIME，sqlx NaiveDateTime 只兼容 DATETIME）；
DECIMAL→BIGINT 与列注释口径拉平；修复生产 GET /api/charge-orders、GET /api/device-logs 必然 500 的根因；
恢复 7 张表丢失的 updated_at ON UPDATE（行为变化，已记入 AGENTS.md）；修正 SCHEMA_SQL 前向引用（空库建表必崩）；
新增 tools/db_schema_diff.py（漂移检查，退出码可接部署前置）与 test/schema_alignment_e2e.py
- 安全加固四项：上传去 .svg + 魔数嗅探（堵存储型 XSS）；登录失败锁定(5次/15分)+challenge 限流+并发闸门+验证码容差收紧；
服务降权 root→pms；nginx 安全头 + limit_req + CORS 白名单收敛
- TCP 连接登录门控（上行+下行同一规则）：login 前只放行 auth_str/login（PRE_LOGIN_ALLOWED_ACTS）
- 状态位按归属层级展示：柜级 status1/status2 显示在柜子（含柜门 + 开门按钮，独立动作不联动业务）、
仓体级 batt_status/pow_status 显示在仓体；两端解析函数同源同名
- 能耗报表改实时聚合 charge_records（原 energy_stats 全表只读不写导致报表恒 0）+ 补复合索引
- 组织可见性：新增 GET /api/my-organizations（工厂全量、客户仅本组织）
- 仓体 status 仅表占用，充满/故障由 Redis 通道状态派生
- 订单/占用/队列运维缺口：h5 建单漏单、214 仓体自愈、device:reports 上限、死信 TTL、LimitNOFILE、
每日 mysqldump + 回滚点保留 5 次
- 文档：AGENTS.md 补层级可见性/数据范围/状态位约定/数据库工具/行为变化；docs/API.md 删除废弃 TCP 章节、接口总表对齐 mod.rs
99 lines
5.0 KiB
Markdown
99 lines
5.0 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/ # 开发文档、协议文档
|
||
├── 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} │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**核心设计原则：**
|
||
1. **TCP服务轻量化** — 只处理TCP通信和指令解析，不处理业务逻辑
|
||
2. **Redis做缓冲** — 服务间通信用Redis LIST，不用HTTP直接调用
|
||
3. **全异步处理** — 所有指令异步处理，msg_id匹配响应
|
||
4. **协程处理任务** — API服务用tokio::spawn处理Redis队列消息
|
||
|
||
**通信流程：**
|
||
- **设备上报**：设备 → TCP → 设备服务 → Redis LIST → API服务协程处理
|
||
- **平台指令**：API服务 → Redis LIST → 设备服务 → TCP → 设备
|
||
- **指令响应**：设备 → TCP → 设备服务 → Redis LIST → API服务匹配msg_id
|
||
|
||
**节点管理：**
|
||
- 设备服务启动时注册到API服务
|
||
- 每60秒心跳，180秒无心跳视为离线
|
||
- 支持多节点扩展（当前单节点）
|
||
|
||
## TCP 设备通讯协议
|
||
|
||
> TCP 设备通讯协议见 **[docs/柜控板固件对接文档.md](docs/柜控板固件对接文档.md)**（唯一权威，v1.1）。本文不再重复。
|
||
> 全局整数单位（voltage mV、current mA、temp K×100、soc ‰）见 [docs/API.md](docs/API.md#数据单位规范)。
|
||
|
||
- 任务需求写到 `tasks/` 目录的md文件
|
||
- 通过Agent子代理包裹opencode执行，异步通知
|
||
- 质量约束模板固定追加到每个任务文件
|
||
- 完成代码后执行对应栈静态校验（Rust→cargo check，TS→tsc --noEmit），零报错零警告
|