619c96c85f
## 为什么要做
`AGENTS.md` 曾达 **90,370 B**，而工作区指令预算是 **65,536 B** —— 系统按**保留头部**截断，
于是**尾部约 25 KB 永远不会被加载**：组织架构、数据模型、TCP 协议、数据单位规范、
微信小程序用户端**全部处于"写了但读不到"的状态**。手册实际上部分失效。
## 一、AGENTS.md 瘦身：90,370 → 60,227 B（余量 5,309 B，尾部不再被截断）
三个**纯参考型大段**整段搬迁到 `docs/tech/`（**内容逐字保留，未删改**），
原位置换成「判据 + 链接」：
| 原 AGENTS.md 章节 | 大小 | 现位置 |
|---|---|---|
| `## 部署与维护` | 17,611 B | `docs/tech/部署手册.md` |
| `## 数据模型` | 12,100 B | `docs/tech/数据模型.md` |
| `## 微信小程序用户端` | 10,262 B | `docs/tech/小程序用户端.md` |
替换后的章节**只留改动前必须先知道的硬约束**（例如：产物名与测试环境落地名不一致、
ETXTBSY 的 `.new`→`stop`→`mv`→`start` 流程、`stream{}` 不可重加、发布顺序 device 先 api 后、
建表顺序即依赖顺序且写错报 MySQL 1824、时间列必须 DATETIME、`cabinets.status` 是配置态不表示在线……），
其余指向详细篇。**判据留在常驻加载的 AGENTS.md，逐项参考移出**。
## 二、docs/ 分类（原 21 个文件平铺 → 五个用途目录）
```
docs/
├── README.md 新增：文档地图（分类/权威性/旧名→现名映射/维护约定）
├── protocol/ 设备协议（冻结，对硬件交付）★唯一权威
│ ├── 柜控板固件对接文档.md
│ └── 1TN协议标准_*.md / *.pdf
├── tech/ 平台技术文档（开发/运维必读）
│ ├── API.md · 数据模型.md · 部署手册.md · 小程序用户端.md
├── contract/ 合同·规格·验收标准（商务依据，不描述实现）
├── compound-notes/ 单点经验笔记（原有）
└── archive/ ⛔ 历史留痕（只读，不代表现状，不可作依据）
├── 开发文档.md（早于现行实现）
└── 审查报告/深度分析报告-2026-07-06
```
- 19 个文件用 `git mv` 迁移（保留历史），3 个未跟踪文件用普通移动；
- **内容零改动**（唯一例外是引用替换），已核验 `docs/tech/API.md` 的 `git diff` 为空。
## 三、全仓引用同步：40 处 / 10 个文件
路径不只出现在文档里，还散落在**源码注释**（`db/migrate.rs`、`routes/cabinets.rs`、
`workers/report_worker.rs`、`tcp/connection.rs`、`h5-uniapp/utils/format.ts`）、
`test/tcp_e2e_smoke.py`、`tasks/001-*.md`、`README.md`、`AGENTS.md` 中，全部同步。
**并已实测校验命令能失败**：往 `docs/tech/API.md` 植入 `<!-- probe: docs/API.md -->`
→ 命中；删除 → 无输出。
> ⚠️ 过程中踩了一个坑并已修：这些 `.md` 多为 **CRLF**，我第一次用 `\n` 正则删除时
> **没匹配上 `\r\n`**，以为删干净了其实残留了一行 —— 靠 `git diff` 非空才发现。
> 已把「CRLF 必须按 `\r?\n` 处理」写进 `docs/README.md` 的维护约定。
## 四、顺带查实的失效引用（归档保留原文，不改写历史）
- `docs/tcp-protocol.md`：仅出现在 2026-07-06 的两份历史报告里（当时的事实）；
- `docs/柜控板-平台TCP接口文档.md`：仅出现在协议文档 **v1.1 变更记录**里
（记录"已删除该内部重复文档"这件事），**不是活链接**，无需修复。
两者已在 `docs/README.md` 的「旧名 → 现名映射」表中给出对应关系。
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/tech/API.md` - API 接口文档（包含请求/响应示例）
|
||
- ✅ `docs/protocol/1TN协议标准_YG20240118-1_V1.0.md` - 电源协议
|
||
|
||
2. **开发文档详细**：
|
||
- ✅ `docs/archive/开发文档.md` - 硬件架构、软件架构、通讯协议设计
|
||
- ✅ `docs/contract/附件一-硬件规格.md` - 柜控主板、仓控主板硬件规格
|
||
- ✅ `docs/contract/附件二-软件规格.md` - 后台管理系统、微信小程序需求
|
||
- ✅ `docs/contract/附件三-交付与验收标准.md` - 交付物清单、验收标准
|
||
|
||
3. **AGENTS.md 非常详细**：
|
||
- ✅ 项目简介、技术栈、项目结构
|
||
- ✅ 部署架构、服务器信息、数据库工具
|
||
- ✅ 开发约束、编码规范（Rust、React）
|
||
- ✅ API 设计规范、Git 工作流
|
||
- ✅ 测试标准、安全规范、日志规范、性能规范
|
||
|
||
### ❌ 文档问题
|
||
|
||
| 问题 | 严重程度 | 说明 |
|
||
|------|----------|------|
|
||
| **README.md 与 AGENTS.md 重复** | 🟢 低 | 两份文档内容有大量重复，维护成本增加 |
|
||
| **合同模板未填写** | 🟢 低 | `docs/contract/开发合同.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/tech/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
|
||
**分析工具**：静态代码分析、文档对比、架构验证
|