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 7d2b57d021 docs: 澄清"唯一 TCP 协议文档"并隔离硬件总线协议；删除已完成任务、摘出未结待办 
## 起因

用户提问：**"我们不是有一个 tcp 协议权威文档了吗？为啥还有其他 tcp 协议文档"** ——
查证后确认：**权威文档只有一份**，但目录布局让人容易误判，且**我上一轮的搬迁引入了一处断链**。

## 一、查证结果：全仓只有一份 TCP 协议文档

按"是否同时出现 `auth_str`/`status_post`/`bat_in` 等 act 名"全仓扫描，含协议内容的只有：

| 文件 | act 命中 | 性质 |
|---|---:|---|
| `docs/protocol/柜控板固件对接文档.md` | 171 | ⭐ **唯一权威 TCP 协议规格** |
| `docs/tech/API.md` | 14 | HTTP 接口文档，TCP 章节**只有一句指回权威文档的链接** |
| `AGENTS.md` / `数据模型.md` / `小程序用户端.md` | 13 / 8 / 3 | 规则与存储说明，非协议规格 |
| `docs/archive/项目深度分析报告-2026-07-06.md` | 1 | 历史归档 |

⇒ **没有任何第二份 TCP 协议文档。** 用户看到的"另一份"应是下面二者之一（都已处理）：

### 1. `docs/protocol/1TN协议标准_*` —— **不是 TCP 协议**

它是**仓控板 ↔ 翌工电源的 RS485 总线协议**（另一条物理链路）。与 TCP 权威文档同放
`protocol/`，名字又像"协议标准"，极易被当成第二份平台协议。
**已移到新目录 `docs/hardware/`**（硬件侧总线协议），并在两处都写明"**不是**平台 TCP 协议"。

**结果：`docs/protocol/` 下有且仅有一个文件** —— 一眼就能确认"只有一份"。

### 2. `tasks/001-TCP协议对齐与安全修复.md`（66 KB）—— 是任务记录，不是协议文档

文件名含"TCP协议"，且 66 KB。它已被完整处理（见下节）。

## 二、删除已完成的任务文件，并摘出真正的未结待办

`tasks/` **已 gitignore（`.gitignore:27`），是本地草稿区、从不入库**。

`tasks/001` 的 A~AH **全部 ✅ 已完成**，但其**状态头写着"待排期（未开始编码）"** —— 是错的。
按「已完成的任务文件及时清理」，**已删除**；删前把**唯一两项未结**摘成
`tasks/002-未结待办-协议待确认项与长函数重构.md`：

1. **`energy` 数据源待硬件答复**（协议待确认第 13 项，阻塞中）+ 关联的第 16 项；
2. **长函数重构**（已授权未开工）。

> ⚠️ **顺带纠正 001 的两处数字**（实测后才发现，**不能沿用**）：
> - 001 记"23 个函数超 80 行"—— **当前实测只有 8 个**（本会话多轮重构已拆掉大部分）；
> - 001 记 `migrate.rs::run` 已从 280 拆到 **46 行** —— **拆分本身没被回退**
>   （`SCHEMA_SQL` 确在 L20、`run` 内 0 个 `CREATE TABLE`），但后续每轮迁移改动都往 `run` 里追加
>   （`LEGACY_COLUMN_TARGETS` 对齐、`ensure_active_order_unique`、列注释对齐……），
>   **它又长回 174 行，重新成为全仓最长函数** —— 这是一次**重构回归**，已列为第一优先。
> - 实测脚本随 002 一起留在 `tasks/`（该目录不入库，避免下次重新发明）。

## 三、修复我上一轮搬迁引入的断链（1 处真缺陷 + 1 处机械替换误伤）

搬迁脚本只覆盖了 `docs/<name>` 与 `../<name>` 两种形态，**没覆盖三种情况**，已全部修好并加了体检：

| 位置 | 问题 | 修复 |
|---|---|---|
| `docs/tech/API.md` | 同级相对链接 `](柜控板固件对接文档.md)` 因文件被移走而断链 | → `](../protocol/柜控板固件对接文档.md)` |
| `docs/tech/数据模型.md` | 我的替换把 **markdown 链接目标** `](docs/API.md)` 也换成了 `docs/tech/API.md` ⇒ 解析成 `docs/tech/docs/tech/API.md` | 显示文字保留可读路径，**链接目标改回 `API.md`** |
| `docs/archive/审查报告…md` | 指向当时已删除的 `./tcp-protocol.md`（历史事实） | 归档**保留原文**，顶部加**归档横幅 + 旧名→现名映射表** |

**新增体检方法并实测能发现问题**：遍历 `docs/**/*.md` 的所有相对链接、逐个还原路径判存在性。
修完后复跑 → 只剩归档那一处（按设计保留），已用横幅给出映射。

> 📌 教训（已写进 `docs/README.md` 维护约定）：**移动文档后必须做链接体检**，
> 不能只做字符串替换 —— 同级相对链接、以及"写在链接目标里的仓库相对路径"都会被漏掉。

## 四、文档地图同步更新

`docs/README.md` 新增：
- 顶部**「关于到底有几份 TCP 协议文档」**专节：直接回答，并列出"三份内部件何时被删"的历史；
- `hardware/` 目录说明；
- `protocol/` 明确标注 **⛔ 不要在这里放第二份协议文档**（要补充就改那一份并升版本号）。

`AGENTS.md` 项目结构同步加 `hardware/` 一行。
2026-09-20 04:55:28 +08:00

180 lines
7.9 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），**不代表现状，不可作为依据**
>
> 结论、路径、字段名都是**当时**的。文中引用的旧文档名与现名对应关系：
>
> | 文中旧名 | 现位置 |
> |---|---|
> | `docs/tcp-protocol.md` | `docs/protocol/柜控板固件对接文档.md`（**唯一权威**，已升到 v1.1.1） |
> | `docs/API.md` | `docs/tech/API.md` |
> | `docs/开发文档.md` | `docs/archive/开发文档.md` |
>
> 当前口径一律以 **`AGENTS.md`**（平台侧实现）+ **`docs/protocol/柜控板固件对接文档.md`**（设备协议）为准。
> 文档分类总览见 `docs/README.md`。
# 数据单位审查报告 — 充电柜项目
**日期：** 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