charging-cabinet/docs/archive/审查报告-数据单位一致性-2026-07-06.md

⛔ 本文是历史归档（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 全局单位规范（第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行标注错误。

- 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

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 展示做端到端验证。