charging-cabinet

History

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

feat(meter): 柜级电表读数落库 + 变化留痕（协议 §5.3 要求"平台原样存库"，此前只写 Redis）

2026-09-20 05:52:17 +08:00

middleware

refactor(api-server): 8 个超 80 行函数全部拆分完毕（行为零改动）+ 补 171 条 SQL 快照守门断言

2026-09-20 05:22:56 +08:00

routes

feat(meter): 整柜日用电量统计接口（电表读数口径，与 energy_stats 严格分离）

2026-09-20 06:38:53 +08:00

workers

feat(meter): 柜级电表读数落库 + 变化留痕（协议 §5.3 要求"平台原样存库"，此前只写 Redis）

2026-09-20 05:52:17 +08:00