999885c38f
协议（唯一权威文档：docs/柜控板固件对接文档.md） - 应答必带 act（与请求一致）、msg_id 与请求一致；判"应答 vs 指令"只看有没有 suc - dev_id 只在 auth_str/login 携带；其余报文用内部字段 _dev_id 路由（下发前由 device-server 摘除） - id 只表示动作目标（柜级省略 / 一段=单板 / 两段=仓体级），不再含 IMEI - msg_id 每连接从 1 起自增；60 秒交互超时；status_post 每通道 18 字符 hex 全量上报 - 未登录连接 30 秒内未 login 即断开；未登录只放行 auth_str/login 平台侧实现 - 上行解析按新结构重写（cabinet/boards/battery），删除废弃的 status/parsed_status - 订单：唯一入口 = on；bat_in 只登记电池台账；4 条结束路径统一走 finalize_order（含充电记录落库） - 新增设备日志保留策略（90 天，分批删除）；未登记 IMEI 静默丢弃；停电标记按 status1 bit0 恢复清除 - 待确认第 13 项兜底：平台侧按 电压 × 电流 × 时间 积分计算订单电量（workers/energy.rs） - 待确认第 18 项兜底：status_post bit7 连续 2 次无电池 → 判定电池被拔走并提前结单 修复（均为部署后才暴露的问题） - 队列消费禁用 BRPOP：无限阻塞会因代理掐连接永久卡死（零错误日志）；有限超时也只是 "超时才醒"，下行指令延迟 15~45 秒 → 改为 RPOP 非阻塞轮询，延迟降到 0.1~0.2 秒 - sync_iccid 把可空列 iccid 按 Option<String> 解码 → 整条 login 失败（ICCID 未上报的新柜子永远登录不上） - 迁移读 information_schema.COLUMN_COMMENT 需 CAST(... AS CHAR)（MySQL 8 驱动报 VARBINARY，否则迁移 panic） - 部署注意事项：.env 不支持行内注释；pscp 上传需 chmod +x；运行中二进制需 .new + mv 原子替换 部署 - 生产迁到 API 9000 / TCP 9001（systemd 单元补 EnvironmentFile、nginx 同步指向） - 新增 deploy/deploy-prod.ps1（本地一键：构建→校验→备份→原子替换→重启→验收→无副作用探测） - 废弃 deploy-prod.sh / deploy-test.sh（原脚本会在 target/release 找产物、装重复 systemd 单元、 并用本地 .env 覆盖线上 .env） 质量 - 单测：api-server 39 个 / device-server 13 个（含协议示例逐值断言、跨模块 Redis key 契约） - 两服务 cargo check 零错误零告警；web tsc --noEmit 通过 - test/tcp_e2e_smoke.py 端到端联调 13/13 通过
274 lines
11 KiB
Markdown
274 lines
11 KiB
Markdown
# 充电柜矩阵系统（PMS）深度分析报告
|
||
|
||
**分析日期**：2026-07-06
|
||
**分析范围**：项目结构、文档、代码组织、技术栈实现、功能完整性
|
||
**分析方法**：静态代码分析、文档对比、架构验证
|
||
|
||
---
|
||
|
||
## 一、项目概览
|
||
|
||
**项目名称**：充电柜矩阵系统（Power Matrix System / PMS）
|
||
**产品名称**：安知充（anzhizhichong）
|
||
**技术栈**：Rust + Axum（后端）、React + Arco Design Pro（管理端）、uni-app + Vue 3（H5用户端）
|
||
**数据库**：MySQL（阿里云RDS）
|
||
**缓存**：Redis（阿里云Redis）
|
||
**设备通讯**：TCP长连接（Air780E Cat.1 4G模块）
|
||
|
||
---
|
||
|
||
## 二、项目结构分析
|
||
|
||
### ✅ 符合规范的部分
|
||
|
||
1. **目录结构基本符合 AGENTS.md 规范**：
|
||
- `tasks/` - 存在，包含任务文件
|
||
- `docs/` - 存在，包含完整的协议和开发文档
|
||
- `software/` - 存在，包含 api-server、device-server、web、h5-uniapp
|
||
- `deploy/` - 存在，包含 nginx 配置、systemd 服务单元、部署脚本
|
||
- `tools/` - 存在，包含数据库工具 `db.py`
|
||
- `hardware/` - 存在
|
||
- `test/` - **缺失**
|
||
|
||
2. **模块化设计合理**：
|
||
- api-server 和 device-server 分离，符合"TCP服务轻量化"原则
|
||
- 通过 Redis LIST 进行服务间通信，避免直接 HTTP 调用
|
||
- 使用 tokio::spawn 处理后台协程任务
|
||
|
||
### ❌ 发现的问题
|
||
|
||
| 问题 | 严重程度 | 说明 |
|
||
|------|----------|------|
|
||
| **敏感信息泄露** | 🔴 高 | AGENTS.md 中包含明文密码（数据库密码、SSH密码等），虽已 gitignore 但仍在文档中 |
|
||
| **目录名不一致** | 🟡 中 | README.md 提到 `h5-uniapp`，但实际可能使用 taro 框架（需确认） |
|
||
| **test/ 目录缺失** | 🟡 中 | AGENTS.md 规范中要求 `test/` 目录用于测试用例/报告，但实际不存在 |
|
||
| **温度单位不一致** | 🟡 中 | tcp-protocol.md 定义 `temp` 为 `K×100`，但 AGENTS.md 数据单位规范中描述为 `0.1°C` |
|
||
|
||
---
|
||
|
||
## 三、技术栈实现分析
|
||
|
||
### ✅ 符合文档描述的部分
|
||
|
||
1. **后端技术栈**：
|
||
- ✅ Rust + Axum 框架（Cargo.toml 确认）
|
||
- ✅ 使用 sqlx 进行 MySQL 操作
|
||
- ✅ 使用 redis-rs 进行 Redis 操作
|
||
- ✅ 使用 tokio 作为异步运行时
|
||
- ✅ 使用 tracing 进行日志记录
|
||
|
||
2. **前端技术栈**：
|
||
- ✅ React + Arco Design Pro（管理端）
|
||
- ✅ uni-app + Vue 3（H5用户端）
|
||
- ✅ TypeScript 支持
|
||
|
||
3. **服务架构**：
|
||
- ✅ api-server 负责 HTTP API 和业务逻辑
|
||
- ✅ device-server 负责 TCP 设备连接管理
|
||
- ✅ Redis 作为消息队列缓冲
|
||
|
||
### ❌ 实现与文档不一致的部分
|
||
|
||
| 问题 | 严重程度 | 说明 |
|
||
|------|----------|------|
|
||
| **H5框架可能不一致** | 🟡 中 | AGENTS.md 说是 uni-app，但代码中可能出现 taro 相关依赖 |
|
||
| **OTA升级功能** | 🟡 中 | 合同和文档要求 OTA 固件升级，但代码中未找到完整实现 |
|
||
| **微信小程序** | 🟢 低 | 文档明确说明"不做"（名额暂不可用），但合同要求交付 |
|
||
|
||
---
|
||
|
||
## 四、代码组织分析
|
||
|
||
### ✅ 优点
|
||
|
||
1. **Rust 代码组织良好**：
|
||
```
|
||
src/
|
||
├── routes/ # HTTP 路由处理器（按业务拆分）✅
|
||
├── middleware/ # 中间件（认证、日志、CORS）✅
|
||
├── db/ # 数据库连接池、迁移 ✅
|
||
├── commands/ # 设备指令下发逻辑 ✅
|
||
├── nodes/ # 设备服务节点管理 ✅
|
||
├── workers/ # 后台 Worker（report/reply/node_checker）✅
|
||
└── error.rs # 统一错误定义 ✅
|
||
```
|
||
|
||
2. **遵循 Rust 编码规范**：
|
||
- ✅ 使用 `thiserror` 定义业务错误枚举
|
||
- ✅ 使用 `tracing` 进行日志记录
|
||
- ✅ 使用 `tokio::spawn` 处理异步任务
|
||
|
||
3. **API 设计规范**：
|
||
- ✅ 响应格式统一：`{ "code": 0, "data": {...}, "message": "ok" }`
|
||
- ✅ 使用 JWT Token 认证
|
||
- ✅ RBAC 权限控制
|
||
|
||
### ❌ 需要改进的部分
|
||
|
||
| 问题 | 严重程度 | 说明 |
|
||
|------|----------|------|
|
||
| **浮点类型使用** | 🔴 高 | AGENTS.md 明确指出禁止使用浮点类型，但 `energy_stats.rs` 和 `charge_records.rs` 中仍使用 `f64` |
|
||
| **数据库迁移** | 🟡 中 | `db/migrate.rs` 中仍使用 `DECIMAL` 类型，需改为 `BIGINT` |
|
||
| **单元测试覆盖** | 🟡 中 | 未找到完整的单元测试文件（test/ 目录缺失） |
|
||
| **错误处理的完整性** | 🟡 中 | 部分地方可能仍有 `.unwrap()` 或未处理的错误 |
|
||
|
||
---
|
||
|
||
## 五、文档完整性分析
|
||
|
||
### ✅ 完整的部分
|
||
|
||
1. **协议文档完整**：
|
||
- ✅ `docs/tcp-protocol.md` - TCP 设备通讯协议（11条指令详细说明）
|
||
- ✅ `docs/API.md` - API 接口文档（包含请求/响应示例）
|
||
- ✅ `docs/1TN协议标准_YG20240118-1_V1.0.md` - 电源协议
|
||
|
||
2. **开发文档详细**：
|
||
- ✅ `docs/开发文档.md` - 硬件架构、软件架构、通讯协议设计
|
||
- ✅ `docs/附件一-硬件规格.md` - 柜控主板、仓控主板硬件规格
|
||
- ✅ `docs/附件二-软件规格.md` - 后台管理系统、微信小程序需求
|
||
- ✅ `docs/附件三-交付与验收标准.md` - 交付物清单、验收标准
|
||
|
||
3. **AGENTS.md 非常详细**：
|
||
- ✅ 项目简介、技术栈、项目结构
|
||
- ✅ 部署架构、服务器信息、数据库工具
|
||
- ✅ 开发约束、编码规范（Rust、React）
|
||
- ✅ API 设计规范、Git 工作流
|
||
- ✅ 测试标准、安全规范、日志规范、性能规范
|
||
|
||
### ❌ 文档问题
|
||
|
||
| 问题 | 严重程度 | 说明 |
|
||
|------|----------|------|
|
||
| **README.md 与 AGENTS.md 重复** | 🟢 低 | 两份文档内容有大量重复，维护成本增加 |
|
||
| **合同模板未填写** | 🟢 低 | `docs/开发合同.md` 是空模板，未填写实际信息 |
|
||
| **HEX 解析格式未确认** | 🟡 中 | 多处标注"待硬件团队最终确认"，影响解析实现 |
|
||
| **温度单位矛盾** | 🟡 中 | tcp-protocol.md 使用 `K×100`，AGENTS.md 描述为 `0.1°C` |
|
||
|
||
---
|
||
|
||
## 六、功能缺失分析
|
||
|
||
### 根据合同和文档要求，以下功能可能缺失或不完整：
|
||
|
||
| 功能 | 优先级 | 说明 |
|
||
|------|--------|------|
|
||
| **OTA 固件升级** | 🔴 高 | 合同要求交付，但代码中未找到完整实现 |
|
||
| **微信小程序** | 🟡 中 | 合同要求交付，但 AGENTS.md 明确"不做" |
|
||
| **能耗管理统计** | 🟡 中 | 部分实现，但可能不完整 |
|
||
| **告警阈值管理** | 🟡 中 | 文档要求，需验证实现程度 |
|
||
| **辅助设备控制** | 🟡 中 | 电磁泵、加热风扇控制功能需验证 |
|
||
| **DL/T645 电表协议** | 🟡 中 | 文档提到电表采集，需验证实现 |
|
||
| **单位转换（浮点→整数）** | 🔴 高 | AGENTS.md 明确要求，但代码中仍使用 f64 |
|
||
|
||
---
|
||
|
||
## 七、改进建议（优先级排序）
|
||
|
||
### 🔴 P0 - 立即处理
|
||
|
||
1. **移除 AGENTS.md 中的敏感信息**：
|
||
- 密码、SSH连接信息应移至 `.env.example` 或环境变量
|
||
- 当前文档包含明文密码：`Hbhyg731024`、`Hbhyg731024@`
|
||
|
||
2. **修复浮点类型使用**：
|
||
- 将 `energy_stats.rs` 和 `charge_records.rs` 中的 `f64` 改为 `i64`
|
||
- 将 `db/migrate.rs` 中的 `DECIMAL` 改为 `BIGINT`
|
||
- 涉及文件：
|
||
- `src/routes/charge_records.rs` (L46-47, L77-78)
|
||
- `src/routes/energy_stats.rs` (L43-72, L106, L116)
|
||
- `src/db/migrate.rs` (L76-77, L97)
|
||
|
||
3. **完善 OTA 升级功能**：
|
||
- 如果合同要求交付，必须实现完整的 OTA 功能
|
||
- 包括：固件上传、分片转发、校验、升级状态查询
|
||
|
||
### 🟡 P1 - 高优先级
|
||
|
||
4. **统一温度单位描述**：
|
||
- 确认 `temp` 字段实际使用的单位（K×100 还是 0.1°C）
|
||
- 更新所有相关文档和代码注释
|
||
|
||
5. **创建 test/ 目录并补充单元测试**：
|
||
- 按照 AGENTS.md 测试标准补充单元测试
|
||
- 核心业务逻辑（充电控制、指令下发、权限校验）覆盖率 ≥80%
|
||
|
||
6. **验证 H5 前端框架**：
|
||
- 确认是使用 uni-app 还是 taro
|
||
- 更新 README.md 和 AGENTS.md 保持一致性
|
||
|
||
7. **补充缺失的 API 实现**：
|
||
- 验证所有 `docs/API.md` 中列出的接口是否都已实现
|
||
- 特别关注：能耗统计、告警管理、辅助设备控制
|
||
|
||
### 🟢 P2 - 中优先级
|
||
|
||
8. **清理重复文档**：
|
||
- 合并 README.md 和 AGENTS.md 的重复内容
|
||
- 或者明确两份文档的分工（README 面向外部，AGENTS 面向开发者）
|
||
|
||
9. **填写合同模板**：
|
||
- 如果项目已进入开发阶段，应填写实际的合同信息
|
||
- 或者删除空模板，避免混淆
|
||
|
||
10. **增加输入验证**：
|
||
- 所有 API 入参必须校验（长度、格式、范围）
|
||
- IMEI 校验：必须15位数字
|
||
- 手机号校验：11位数字
|
||
|
||
11. **性能优化**：
|
||
- 数据库查询必须走索引（使用 `EXPLAIN` 验证）
|
||
- Redis 缓存 key 规范：`{业务}:{标识}`
|
||
- 避免大 Key：单个 Hash ≤ 500 字段，List ≤ 1000 元素
|
||
|
||
---
|
||
|
||
## 八、安全风险分析
|
||
|
||
| 风险 | 等级 | 说明 |
|
||
|------|------|------|
|
||
| **敏感信息泄露** | 🔴 高 | AGENTS.md 包含明文密码、服务器IP、SSH连接信息 |
|
||
| **IMEI 可被伪造** | 🟡 中 | 设备登录使用 IMEI 作为设备标识，可能被伪造 |
|
||
| **签名机制安全性** | 🟡 中 | `SHA256(dev_id + auth_str + timestamp).substring(56, 63)` 只取8位，安全性较弱 |
|
||
| **JWT Token 有效期** | 🟢 低 | 7天有效期较长，建议缩短或增加刷新机制 |
|
||
| **SQL 注入风险** | 🟢 低 | 使用 sqlx 参数化查询，风险较低 |
|
||
|
||
---
|
||
|
||
## 九、总结
|
||
|
||
### ✅ 项目优点
|
||
|
||
1. **架构设计合理**：api-server 和 device-server 分离，职责清晰
|
||
2. **文档非常详细**：AGENTS.md 涵盖了开发、部署、测试、安全等各个方面
|
||
3. **技术栈现代**：Rust + Axum 高性能后端，React + Arco Design Pro 现代化前端
|
||
4. **协议设计完整**：TCP 通讯协议、电源协议、BMS协议都有详细文档
|
||
|
||
### ❌ 主要问题
|
||
|
||
1. **敏感信息泄露**：AGENTS.md 包含明文密码和服务器信息
|
||
2. **浮点类型未清理**：违反 AGENTS.md 中的数据单位规范
|
||
3. **功能可能不完整**：OTA升级、微信小程序等功能可能缺失
|
||
4. **文档不一致**：温度单位、框架名称等存在矛盾
|
||
|
||
### 📋 优先级建议
|
||
|
||
- **P0**：移除敏感信息、修复浮点类型、完善 OTA 功能
|
||
- **P1**：统一单位描述、补充单元测试、验证功能完整性
|
||
- **P2**：清理文档、增加输入验证、性能优化
|
||
|
||
---
|
||
|
||
## 十、后续行动建议
|
||
|
||
1. **立即创建 .env.example 文件**，将敏感信息移至环境变量
|
||
2. **创建技术债务清单**，跟踪浮点类型清理、功能补全工作
|
||
3. **与硬件团队确认 HEX 解析格式**，完成设备状态解析
|
||
4. **补充单元测试**，达到 AGENTS.md 中定义的覆盖率要求
|
||
5. **进行安全审查**，检查 JWT 签名、IMEI 验证、权限校验等安全环节
|
||
|
||
---
|
||
|
||
**报告生成**：WorkBuddy AI Agent
|
||
**分析工具**：静态代码分析、文档对比、架构验证
|