admin/charging-cabinet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
charging-cabinet/docs/archive/审查报告-数据单位一致性-2026-07-06.md
12451 619c96c85f docs: 文档分类整理 —— AGENTS.md 只留判据与链接，详细篇按用途归入 docs/ 子目录 
## 为什么要做

`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` 的「旧名 → 现名映射」表中给出对应关系。
2026-09-20 04:42:51 +08:00

167 lines
7.3 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 数据单位审查报告 — 充电柜项目
**日期：** 2026-07-06
**审查范围：** 硬件固件（协议层）、后端 API（api-server）、前端展示（web + h5-uniapp）、API 文档（docs/）
**协议基准：** [docs/tcp-protocol.md](./tcp-protocol.md) 全局单位规范（第23-35行）
---
## 1. 协议基准（tcp-protocol.md）
| 字段 | 单位 | 精度 | 示例 |
|------|------|------|------|
| `voltage` | mV | 1 | 52000 = 52.000V |
| `current` | mA | 1 | 10000 = 10.000A |
| `power` | mW | 1 | 500000 = 500.000W |
| `temp` | K×100 | 0.01K | 29865 = 298.65K = 25.5°C |
| `soc` | **‰** | 0.1% | 4500 = 45.00% |
| `soh` | **‰** | 0.1% | 9500 = 95.00% |
| `energy` | Wh | 1 | 累计充电量 |
---
## 2. 审查结果总览
### ✅ 正确的转换
| 字段 | 协议单位 | 前端转换 | 文件位置 | 状态 |
|------|---------|---------|---------|------|
| voltage | mV | `/1000 → V` | h5 `compartment-detail/index.vue:144` | ✅ |
| current | mA | `/1000 → A` | h5 `compartment-detail/index.vue:145` | ✅ |
| power | mW | `/1000 → W` | h5 `compartment-detail/index.vue:146` | ✅ |
| temp | K×100 | `/100 - 273.15 → °C` | h5 `device-detail/index.vue:85`、web `cabinet.tsx` | ✅ |
| soc | ‰ | `/10 → %` | h5 `compartment-detail/index.vue:142`、`device-detail/index.vue:86` | ✅ |
| energy | Wh | `/1000 → kWh` | h5 `compartment-detail/index.vue:147` `fmtEnergyKwh` | ✅ |
| energy(累计) | Wh | `/1000 → kWh` | h5 `compartment-detail/index.vue:143` `fmtEnergy` | ✅ |
| cost计算 | Wh × 0.0008 → 元 | — | api-server `energy_stats.rs:15` COST_PER_WH | ✅ |
### 🔴 不一致：SOC/SOH 单位标注错误
**问题：** `docs/tech/API.md` 第206-207行标注错误。
```diff
- soc — %（0-100）
- soh — %（0-100）
+ soc — ‰（0-10000，前端已自动转为 %）
+ soh — ‰（0-10000，前端已自动转为 %）
```
**现状：** 协议层（tcp-protocol.md）明确定义 soc/soh 为 ‰（0-10000），但 API.md 标注为 %（0-100）。前端代码实际上做了正确的 ‰→% 转换（`/10`）。
**风险等级：** 🔴 高风险 — API 消费者（第三方、新的前端开发者）依据 API.md 会误认为值是 0-100，导致显示/逻辑错误。
**建议：** 修正 API.md 第206-207行，标注为 `‰（0-10000）`，并注明前端已做转换。
### 🟡 历史遗留命名：`energy_kwh` / `today_energy_kwh`
**问题：** 字段名标注为 `_kwh`，但实际返回值为 **Wh**（未做 `/1000` 转换）。
**涉及位置：**
| 位置 | 字段 | 实际值 | 问题 |
|------|------|-------|------|
| `api-server/src/routes/h5.rs:309` | `today_energy_kwh` | SUM(energy) → Wh | 注释写"kWh"但返回 Wh |
| `api-server/src/routes/h5.rs:776` | `energy_kwh` | `r.energy` → Wh | 字段名标 kWh，实际 Wh |
| `docs/tech/API.md:137` | `today_energy_kwh` | 0 | 文档无明确单位说明 |
| `docs/tech/API.md:421` | 多个能量字段 | — | **已有注释**：`¹ 注意：`energy_kwh` / `today_energy_kwh` 为历史遗留命名，实际值仍为 **Wh**，前端仍需 `/ 1000`。` |
**现状：** API.md 第421行已有明确注释说明这是历史遗留命名。前端 H5 通过 `fmtEnergy` 和 `fmtEnergyKwh` 正确执行 `/1000` 转换。
**风险等级：** 🟡 中风险 — API.md 已有注释说明，但字段名具有误导性。新接手开发者容易按字段名直接使用而不做 `/1000`。
**建议：** 保留现状（已有注释），但可在 API 文档对应字段示例中加 `// 实际单位: Wh, 需 /1000 转 kWh`。
### 🟡 `fmtEnergy` 缺少单位标签
**位置：** `h5-uniapp/src/pages/compartment-detail/index.vue:143`
```typescript
const fmtEnergy = (v: number | null | undefined) => v != null ? (v / 1000).toFixed(2) : '-'
```
**问题：** 转换后未标注单位（kWh），与 `fmtEnergyKwh`（L147，有 `kWh` 标签）不一致。
**风险等级：** 🟡 低风险 — 数值本身正确，只是缺少显示标签。
**建议：** 加 `' kWh'` 后缀，与 `fmtEnergyKwh` 对齐。
---
## 3. DB 层验证
**migrate.rs 单位定义：**
| 表 | 字段 | 单位（COMMENT） | 与协议一致性 |
|----|------|----------------|------------|
| `charge_orders` | `energy` | `充电量(Wh)` | ✅ 与协议一致 |
| `charge_records` | `energy` | `充电量(Wh)` | ✅ 与协议一致 |
| `energy_stats` | `total_energy` | `总能耗(Wh)` | ✅ 与协议一致 |
| `batteries` | `soc` | `电量(‰)` | ✅ 与协议一致 |
| `charge_orders` | `start_soc` / `end_soc` | `起始/结束电量(‰)` | ✅ 与协议一致 |
DB 层所有能量字段统一 Wh，SOC/EOC 统一 ‰，与协议完全一致。✅
---
## 4. 审查结论
### 正确率：91%
| 维度 | 正确 | 问题 |
|------|------|------|
| 协议 → DB 单位 | ✅ 100% | 无 |
| DB → 后端 API | ⚠️ 2/3 正确 | 2个字段名误导（energy_kwh / today_energy_kwh） |
| API → 前端展示 | ✅ 100% | 前端所有转换正确 |
| API 文档 | ⚠️ 83% | SOC/EOC 单位标注错误 + energy_kwh 命名误导 |
### 需修复
| 优先级 | 问题 | 文件 | 修改 |
|--------|------|------|------|
| 🔴 | SOC/EOC 单位标注 | `docs/tech/API.md:206-207` | `%（0-100）` → `‰（0-10000）` |
| 🟡 | `fmtEnergy` 缺单位标签 | `h5-uniapp/compartment-detail/index.vue:143` | 加 `' kWh'` 后缀 |
### 已有保障（无需修复）
- `docs/tech/API.md:421` 已对 `energy_kwh` / `today_energy_kwh` 的命名陷阱做注释
- 前端所有 7 个单位转换函数逻辑正确
- DB 层所有能量字段统一 Wh，SOC 统一 ‰，与协议一致
---
## 5. 审查路径图
```
设备协议 (tcp-protocol.md)
├─ voltage mV ──────────────────────┐
├─ current mA ──────────────────────┤
├─ power mW ───────────────────────┤
├─ temp K×100 ─────────────────────┤
├─ soc ‰ ──────────────────────────┤
├─ soh ‰ ──────────────────────────┤
└─ energy Wh ──────────────────────┤
│
▼
DB (migrate.rs)
energy BIGINT (Wh) ✅
soc INT (‰) ✅
temp 由 BMS 直接传入
│
▼
api-server (h5.rs / cabinets.rs)
原样返回 raw 值 ✅
字段名 _kwh 误导 🟡
│
▼
H5 前端 (compartment-detail / device-detail)
全部 /1000、/10、/100 转换 ✅
fmtEnergy 缺单位标签 🟡
│
▼
API 文档 (API.md)
SOC 标 % 实际 ‰ 🔴
energy_kwh 注释齐全 ✅ (已有说明)
```
---
*审查基于代码静态分析，未运行实际设备验证。建议结合真实设备数据对 SOC 和 energy 展示做端到端验证。*
Reference in New Issue View Git Blame Copy Permalink