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

180 lines
7.9 KiB
Markdown
Raw Normal View History

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
> ## ⛔ 本文是**历史归档**（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`。
feat(protocol): TCP v1.1 协议对齐 + 平台侧兜底 + 生产部署修复 协议（唯一权威文档：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 通过
2026-09-19 23:40:46 +08:00
# 数据单位审查报告 — 充电柜项目
**日期：** 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: 文档分类整理 —— 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
**问题：** `docs/tech/API.md` 第206-207行标注错误。
feat(protocol): TCP v1.1 协议对齐 + 平台侧兜底 + 生产部署修复 协议（唯一权威文档：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 通过
2026-09-19 23:40:46 +08:00
```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: 文档分类整理 —— 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
| `docs/tech/API.md:137` | `today_energy_kwh` | 0 | 文档无明确单位说明 |
| `docs/tech/API.md:421` | 多个能量字段 | — | **已有注释**：`¹ 注意：`energy_kwh` / `today_energy_kwh` 为历史遗留命名，实际值仍为 **Wh**，前端仍需 `/ 1000`。` |
feat(protocol): TCP v1.1 协议对齐 + 平台侧兜底 + 生产部署修复 协议（唯一权威文档：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 通过
2026-09-19 23:40:46 +08:00
**现状：** 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 命名误导 |
### 需修复
| 优先级 | 问题 | 文件 | 修改 |
|--------|------|------|------|
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
| 🔴 | SOC/EOC 单位标注 | `docs/tech/API.md:206-207` | `%（0-100）` → `‰（0-10000）` |
feat(protocol): TCP v1.1 协议对齐 + 平台侧兜底 + 生产部署修复 协议（唯一权威文档：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 通过
2026-09-19 23:40:46 +08:00
| 🟡 | `fmtEnergy` 缺单位标签 | `h5-uniapp/compartment-detail/index.vue:143` | 加 `' kWh'` 后缀 |
### 已有保障（无需修复）
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
- `docs/tech/API.md:421` 已对 `energy_kwh` / `today_energy_kwh` 的命名陷阱做注释
feat(protocol): TCP v1.1 协议对齐 + 平台侧兜底 + 生产部署修复 协议（唯一权威文档：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 通过
2026-09-19 23:40:46 +08:00
- 前端所有 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 Copy Permalink