12451
|
8ae55e9ca3
|
feat(meter): 整柜日用电量统计接口（电表读数口径，与 energy_stats 严格分离）
## 背景
上一提交把 `status_post.cabinet.meter`（柜级电表读数，Wh）落库并只在读数变化时留痕
（`cabinet_meter_readings`），数据源已就绪。本提交基于它做**整柜日用电量**统计。
## ⛔ 与 energy_stats 的关系：两套口径，严禁混用
| | 数据源 | 口径 |
|---|---|---|
| **本模块** `meter_stats` | `cabinet_meter_readings`（电表读数） | **整柜实际用电**（硬件计量、含非充电损耗） |
| `energy_stats` | `charge_records`（订单结算） | **单订单充电量**（平台 `V×I×Δt` 积分的估算值） |
电表读数天然含待机/风扇/变换器损耗，且是硬件计量；订单电量是估算。两者数值必然不一致，
**谁也不替代谁**。`energy_stats` 的"今日/本月能耗"是订单口径；要"整柜每天用多少度"必须走本接口。
## 计算口径
`当日用电量 = 当日最后一条读数 − 当日之前最近一条读数`
注意是"当日**之前**最近一条"，不是"当日第一条"—— 否则同日多次读数会把当天早段的用电漏掉。
## 三个语义坑（都处理了，都有单测）
1. **离线整天 = 无数据，不是 0**：当天一条读数都没有 ⇒ 该日**不出现在结果里**。
渲染成 0 度等于告诉用户"这天没用一度电"，而事实是"不知道"。
2. **跨多日 ⇒ 标 `covers_multiple_days`**：前值距当日首读超过 1 天（柜子离线了几天）⇒
差值实际覆盖多天，直接标"当日用电"会高估。
3. **读数变小 ⇒ 标 `meter_reset_or_replaced`**：差值为负，这不是"负用电量"，
而是电表被更换或清零 —— 必须标记，绝不当成用电量展示。
另外：**首日无前值 ⇒ `usage_wh` 不出现**（`no_baseline`），也是"无数据"不是 0。
## 汇总口径
`summary.total_wh` 只累加**可信**的日用电 —— `no_baseline`（无对比）与
`meter_reset_or_replaced`（差值非法）都不计入，否则总数会被一个换表日的巨大负值污染。
同时给出 `counted_days`（实际计入）与 `days_with_data`（有读数，含被排除的）。
## 为什么用 Rust 纯函数而不是全 SQL 算
三个语义坑都需要条件分支，SQL 里写会变成一层套一层的 `CASE WHEN`，难读也难单测。
这里 SQL 只负责取数（区间读数 + 区间**之前**最近一条作基准），判定交给
`compute_daily_usage` 纯函数 —— 可完整单测，包括三个坑各自的用例。
## 接口
`GET /api/cabinets/{id}/meter-usage?start=&end=`（闭区间，`YYYY-MM-DD`，缺省最近 30 天，最多 366 天）
权限 `device:view` + `scope_guard::verify_cabinet_ownership`（组织隔离 + 数据范围）。
## 实测（测试环境真实 HTTPS，临时超管账号+自签 JWT，用完即删）
造 5 条读数（day1=1000 / day2=1100,1300 / day3 离线 / day4=1500 / day5=1200）：
```
2026-03-01 end=1000 usage=None flags=['no_baseline']
2026-03-02 end=1300 usage=300 flags=[]
2026-03-04 end=1500 usage=200 flags=['covers_multiple_days']
2026-03-05 end=1200 usage=-300 flags=['meter_reset_or_replaced']
summary: total_wh=500 (300+200，换表日不计), counted_days=2, days_with_data=4
⇒ 三个坑全部生效，03-03 缺席，汇总正确
```
## 判据自证能失败
撤掉"跳过区间前基准读数"那段（**我先前真实踩过的 bug**：不跳过则 `idx` 卡在基准上，
首日整天读数取不到）→ 3 个测试 **FAILED**；还原 → 9 passed。
## 验收
- `cargo check --all-targets`：**0 error / 0 warning**（两服务）
- `cargo test --bin pms-api`：**204 passed**（195 + 9 条新单测）
- web `npm run typecheck`：exit 0
- `device_status_parse` 16/16、`rssi_signal` 9/9
- 结构漂移：**无漂移**（两库 159 列 / 0 TIMESTAMP）
- `schema_alignment_e2e --env dev`：通过；`tcp_e2e_smoke`：**18/18**
- 路由：**81** 条 / **94** 对（新增 1 条，`docs/tech/API.md` 计数已同步 80→81、93→94）
- 已发布测试与生产（生产 0 ERROR、域名 401/200、消费链探测通过）
## 文档
- `docs/tech/API.md`：新增接口详情（含 flags 表格、离线≠0、汇总口径），更新路由计数
- `AGENTS.md`：数据模型节补"两套电量口径严禁混用" + 三个语义坑
- `tasks/002`：标记日用电量统计已完成
|
2026-09-20 06:38:53 +08:00 |
|
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 |
|