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
|
cf9a521b31
|
feat(cabinets): 柜子详情接口透出最新电表读数（meter_wh / meter_at）
协议 §5.3 的 `cabinet.meter`（柜级电表读数，Wh）已落库（`cabinets.meter_wh` / `meter_at`，
变化留痕见 `workers/meter.rs`），本提交把它透出到 `GET /api/cabinets/{id}` 的响应里。
## 做法
沿用**同一个函数里 `project_name` 的既有模式**单查一次，**不给 `CabinetBasicRow` 加字段**：
该结构体有**两个**取数点（列表 L129 / 详情 L592），且其上方注释明确写着
「字段必须与 `CabinetBasicRow` 一一对应」—— 加字段要同步两处 SELECT，耦合更大、风险更高。
- ⚠️ `null` = **从未上报过**，与「读数为 0」是两回事（前端必须区分，别渲染成 0 度）；
- 查询失败降级为 `null`，不让详情接口整体失败（与 `project_name` 同口径）。
## 实测（测试环境真实 HTTPS 请求）
临时超管账号 + 自签 HS256 JWT（用测试环境 `.env` 的 `JWT_SECRET`），**用完即删**：
```
库中：cabinet_id=1 meter_wh=125600 meter_at=2026-09-19 21:54:30
接口：meter_wh=125600 meter_at='2026-09-19T21:54:30'
⇒ 逐字一致
```
## 判据自证能失败
把 `should_record` 简化成朴素写法 `prev != current`（即**会把"字段缺失"当成 0 记录**的那版）
→ `test_missing_meter_is_never_recorded` **FAILED**；还原 → 6 passed。
## 验收
- `cargo check --all-targets`：0 error / 0 warning
- `cargo test --bin pms-api`：**195 passed**
- `cd software/web && npm run typecheck`：exit 0
- `node test/device_status_parse.test.mjs`：16/16；`node test/rssi_signal.test.mjs`：9/9
- 路由数：**80**
- `python test/schema_alignment_e2e.py --env dev`：通过（exit 0）
- 已发布**测试与生产**（生产：服务 active、0 ERROR、域名 401/200、消费链探测通过）
|
2026-09-20 06:00:30 +08:00 |
|
12451
|
e8d7442377
|
feat(meter): 柜级电表读数落库 + 变化留痕（协议 §5.3 要求"平台原样存库"，此前只写 Redis）
## 背景：协议一直有上报，是平台没存
`status_post.cabinet.meter`（电表读数，单位 **Wh**，硬件最小刻度 0.1 度电）在协议 §5.3 里
字段表写得很明确：**「平台原样存库、不再 ×100」**（`docs/protocol/柜控板固件对接文档.md` L565），
报文示例（L535）也一直带着它。
但实现侧此前**只写 Redis**（`device:{imei}` 的 `meter`，TTL 300 秒）⇒ 每 60 秒报一次、
**5 分钟后被清掉**，整柜累计电能在平台侧等于不存在、历史无法回溯。
本提交补上落库 —— 属**履约**，不是新增协议内容。
## 改动
1. **新表 `cabinet_meter_readings`**（`cabinet_id` / `reading_wh` / `collected_at`，FK→cabinets，
索引 `(cabinet_id, id)`）+ **`cabinets.meter_wh` / `meter_at`**（最新读数，供列表/详情廉价读取）。
2. **新模块 `workers/meter.rs`**：
- `should_record(prev, current)` —— **纯函数判据**，且**真正承担生产判据**（不是只给单测用）；
- `record_if_changed(pool, imei, meter_wh)` —— 读上次值 → 纯函数判定 → 带 `WHERE ... <> ?`
的 UPDATE 做**并发认领** → 认领成功才追加留痕行（2~3 次往返，且读数未变时 0 次写入）。
3. **`status_post` 接线**：`meter` 改为按 `Option` 解析，**区分「字段缺失」与「值为 0」**
（原先 `unwrap_or(0)` 会把缺失当 0 落库，等于在序列里插进凭空的零值）。
Redis 那条路径口径不变（缺失即 0），不影响既有实时状态契约。失败只记 WARN。
## 为什么"只在变化时记一条"
`status_post` 固定 60 秒一次 ⇒ 68 柜约 **9.8 万行/天**；而电表读数**只在有电量消耗时才变**。
只记变化 ⇒ 写入量与真实用电事件成正比，且"变化"本身就是要留的信息
（等价于抄表系统的**抄表事件**）。读数**变小也记**（换表/清零/回绕属真实事件，必须留痕），
但不在此做任何补差推算 —— 口径仍是**宁可少算、不可虚增**。
## 单测（6 条，全过）
`test_missing_meter_is_never_recorded`（⛔ 缺失绝不落库成 0）、
`test_first_reading_is_recorded_as_baseline`、`test_unchanged_reading_is_not_recorded`、
`test_changed_reading_is_recorded_including_decrease`、
`test_absent_and_zero_are_treated_differently`（**反证**：缺失与 0 处置必须不同）、
`test_update_guard_sql_shape`（变化闸门与占位符个数守门）。
## 顺带被两个既有守门拦下（都是它们正常工作，责任在我）
1. `test_schema_sql_energy_columns_comment_unit_is_wh` 的 `!SCHEMA_SQL.contains("kWh")`：
我的新表注释写了"硬件0.1kWh×100"命中了禁词。**守卫意图正确**（防有人把列标成 kWh
而实际存 Wh），故**改自己的措辞**（改述为"最小刻度 0.1 度电=100Wh"），**不放宽守卫**。
2. `EXPECTED_TABLE_COUNT` 21 → 22（断言消息本就写着"新增/删除表时请同步更新本断言"）。
## 验收
- `cargo check --all-targets`：**0 error / 0 warning**
- `cargo test --bin pms-api`：**195 passed**（189 + 6 条新单测，未减少）
|
2026-09-20 05:52:17 +08:00 |
|
12451
|
9e935fdda9
|
refactor(api-server): 8 个超 80 行函数全部拆分完毕（行为零改动）+ 补 171 条 SQL 快照守门断言
## 结果
| 函数 | 前 | 后 | 拆出的 helper |
|---|---:|---:|---|
| `db/migrate.rs::run` | 174 | 20 | `apply_schema` / `align_column_metadata` / `create_indexes_and_columns` / `align_legacy_structures` / `seed_defaults` |
| `routes/auth.rs::login` | 95 | 77 | `login_guard` |
| `workers/report_worker.rs::handle_auth_str` | 88 | 70 | `deliver_auth_str` |
| `middleware/auth.rs::auth_middleware` | 87 | 71 | `load_effective_scope` |
| `routes/h5.rs::get_compartment_detail` | 87 | 65 | `build_compartment_detail_response` |
| `workers/report_worker.rs::settle_finished_order` | 85 | 71 | `write_back_order_energy` |
| `routes/charge_orders.rs::list_charge_orders` | 84 | 61 | `append_order_filters` |
| `routes/cabinets.rs::get_cabinet_detail` | 83 | 74 | `ensure_cabinet_access` |
**全仓超 80 行的生产函数：0 个**（重构前 8 个）。`routes/mod.rs` 的 `.route(` 仍 **80**。
## 怎么保证"行为零改动"：机械验证器，不是靠人眼
新增本地工具 `.git/verify_refactor.py`（不入库），对每个文件给出三条判据：
1. **被移除的非注释代码行 = 0** —— 即原可执行语句**全部还在**
（搬进 helper 的行仍存在，故不计为移除；只有真正被改写/删掉的行才会出现）；
2. 新增的非注释代码行**只有脚手架**（函数签名/花括号/`Ok(())`/调用/`let` 绑定/尾表达式）；
3. 文件内 `r#"..."#` **SQL 字面量逐条与 HEAD 相同**。
7 个文件**全部通过三条**（被移除均为 0；`cabinets.rs` 12 条、`h5.rs` 27 条、
`migrate.rs` 7 条、`middleware/auth.rs` 3 条 SQL 字面量逐条一致）。
> ⚠️ **这个验证器本身被自证抓出过一个假绿**：早期版本用反斜杠路径调
> `git show HEAD:<path>`，失败后"跳过并返回通过"——等于什么都没查。
> 已修：路径强制正斜杠；**已跟踪文件取不到 HEAD 内容时判为"验证器失效/本项未验证"并 exit 1**。
> 实测植入 `VARCHAR(20)→VARCHAR(30)` 后 exit 1 且列出被移除行。
## 补 171 条 SQL 快照守门断言
这些 handler **原本没有任何测试覆盖**（tasks/002 的风险结论）。
新增 `routes/mod.rs::sql_snapshot_guards`：从 7 个文件**程序化提取**全部含 SQL 的字面量，
用 `include_str!` 把源文件本身作为被测对象 —— **SQL 文本/字段顺序/`?` 占位符一旦被改，测试立即失败**
（覆盖 `auth.rs` 5 + `cabinets.rs` 27 + `charge_orders.rs` 14 + `h5.rs` 52 +
`middleware/auth.rs` 18 + `report_worker.rs` 27 + `migrate.rs` 28）。
> ⚠️ **第一版守门断言也是假绿，靠自证发现**：提取规则只收"以 `SELECT` 开头"的字面量，
> 于是 `charge_orders.rs` 只捕到 2 条，**恰恰漏掉与 `.bind` 顺序一一对应的
> `" AND cabinet_id = ?"` 等片段** —— 我把 SQL 改了一个字符，断言却仍然通过。
> 已放宽为正则（含 `?` 且以 SQL 子句开头 / 含 SQL 关键字），该文件覆盖 2 → 14 条。
> 重新自证：改字符 → **FAILED 并打印出错片段**；还原 → 通过。
## 顺带修掉两处"由我自己的判据逼出来的代码退化"
子代理如实报告：它们为迁就验证器**过窄**的 SCAFFOLD 正则，做了两处不该做的让步 ——
这是判据塑造代码，必须纠正：
1. `append_order_filters` 被写成**体内无 `await` 的 `async fn`**（`clippy::unused_async` 的典型告警）
→ 改为同步 `fn`，调用点去掉 `.await`；
2. `ensure_cabinet_access` / `login_guard` 的签名被压成**单行 113+ 字符**
→ 恢复常规多行格式。
验证器的 SCAFFOLD 正则同步放宽（支持多行签名/形参行、普通与非 await 调用、裸标识符尾表达式），
放宽后 7 个文件复检仍全过。
## 验收
- `cargo check --all-targets`：**0 error / 0 warning**；
- `cargo test --bin pms-api`：**189 passed**（基线 182 + 7 条守门，**未减少**）；
- 长函数：**0 个**；路由：**80 条**；
- 错误处理口径逐条保留（`?` 上抛 vs 只记 `ERROR` 未互换），已在各 helper 的
`///` 文档注明来源与口径；`middleware/auth.rs` 的组织隔离/`user_scopes` 语义（
未配置=不限制、总管理员豁免、失败安全退回"不限制"）**逐字未改**。
|
2026-09-20 05:22:56 +08:00 |
|
12451
|
86a52ce293
|
refactor(api-server): 拆分 db/migrate.rs::run（174 → 20 行），行为零改动
`run` 在 2026-09 被拆过一次（280 → 46 行，把建表 SQL 抽成 `const SCHEMA_SQL`），
但后续每一轮迁移改动都往它里面追加（`LEGACY_COLUMN_TARGETS` 列对齐、
`ensure_active_order_unique`、各处列注释对齐……），**它又长回 174 行**，重新成为全仓最长函数。
## 改法：按"迁移阶段"切五个私有函数，顺序与容错口径逐条保留
| 阶段 | 内容 | 容错口径 |
|---|---|---|
| `apply_schema` | 执行 `SCHEMA_SQL` 建表 | ⛔ 上抛（表不在，后续无从谈起） |
| `align_column_metadata` | `abstract_id` 可空化 + 5 处列注释对齐 | 混合：`abstract_id`/`cabinets.status` 只记 ERROR，其余 4 条上抛（**逐条保留原口径**） |
| `create_indexes_and_columns` | `create_indexes` / `ensure_energy_report_indexes` / `add_columns_if_not_exists` | 第 1、3 条上抛，第 2 条（纯性能优化）只记 ERROR |
| `align_legacy_structures` | `align_legacy_columns` / `ensure_active_order_unique` | 均只记 ERROR（业务侧已有兜底） |
| `seed_defaults` | `seed_permissions` / `seed_roles` | ⛔ 上抛（没权限码平台等于不可用） |
`run` 本体只剩 5 行调用 + 收尾日志。**顺序即依赖顺序**，与拆分前逐条一致。
## 大段解释性注释：上移为 `///` 文档，不是删除
`align_column_metadata` 一度仍有 123 行 —— 但**里面全是解释性注释**（为什么
`compartments.status` 旧注释是错的、`cabinets.status` 为什么不是"在线"、
`charge_orders.status` 的 `2` 为何保留不用）。
这些说明**逐字上移到该函数的 `///` 文档**（rustdoc 同样渲染、读者同样能看到），
函数体因此降到 80 行以内 —— **零信息损失**。
## 验证（三条机械判据，全部可复跑）
新增验证器 `.git/verify_refactor.py`（本地工具，不入库），对任意文件证明"只搬代码、未改语义"：
1. **被移除的非注释代码行 = 0** —— 即所有原可执行语句都还在（本次实测 0 种）；
2. 新增的非注释代码行**只有脚手架** —— 实测仅 5 个 `async fn` 签名 + 5 个 `}` +
5 个 `Ok(())` + 5 条调用语句；
3. 文件内 `r#"..."#` **SQL 字面量逐条与 HEAD 相同** —— 实测 7 条全同。
> ⚠️ 这个验证器**先被我自己的自证抓出过一个假绿**：早期版本用反斜杠路径调
> `git show HEAD:<path>`，失败后"跳过并返回通过" —— 等于什么都没查。
> 已修：git 路径强制正斜杠；已跟踪文件取不到 HEAD 内容时**判为"验证器失效/本项未验证"并 exit 1**，
> 绝不当成通过。并实测：植入 `VARCHAR(20)→VARCHAR(30)` 后 **exit 1 且列出被移除的代码行**。
- `cargo check --all-targets`：零 error / 零 warning；
- `cargo test --bin pms-api`：**182 passed**（与基线一致，未减少）；
- 长函数总数：**8 → 7**（`migrate.rs::run` 已消除）。
其余 7 个（`hooks.rs::login` 95、`report_worker.rs::handle_auth_str` 88、
`middleware/auth.rs::auth_middleware` 87、`h5.rs::get_compartment_detail` 87、
`report_worker.rs::settle_finished_order` 85、`charge_orders.rs::list_charge_orders` 84、
`cabinets.rs::get_cabinet_detail` 83）沿用同一套改法与验证判据继续处理。
|
2026-09-20 05:13:08 +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 |
|
12451
|
c3a3ea7c3a
|
fix(api)+fix(device): 状态取值收敛、超时方向守门补齐、在线判据口径订正
1) cabinets.status 写入侧收敛（此前 body.status 是 i8，0/99/-1 都能落库）
- create_cabinet 的 INSERT **显式写 status = 1**，不再依赖列默认值 0：
冻结口径是「2 = 禁用，其余 = 启用」，但列默认会产生第二种"启用"表示，
任何按 status = 1 做的统计都会悄悄漏掉新建柜子（见「踩过的坑」第 5 条）。
- PUT /api/cabinets/:id/status 增加白名单 {1,2}，抽成纯函数 is_valid_cabinet_status
并配守门单测（i8 全量遍历断言，杜绝"只挡住我知道的那几个"）。
白名单校验放在**鉴权之后**：越权恒 403，不会因参数非法而先返回 400
（否则 400/403 的差异会变成"该柜子是否存在"的探测信号）。
- 已实测自证：把白名单放宽成 [0,1,2] → 用例 FAILED / exit 101；还原 → 通过。
- 生产库实测 68 台**全部已是 status=1**，故无需数据迁移。
2) order_timeout.rs 的超时方向守门（此前只在文档里留了「遗留」标记）
- 选单 SQL 抽成常量 EXPIRED_ORDER_SCAN_SQL；
- 补 3 个单测：SQL 文本方向断言（含**反证**写反形态）+ 纯函数孪生体双向断言
（刚建 5 分钟不命中 / 超 10 小时 1 分钟命中 / 差 1 分钟不命中 + 反证）+ 常量合理性。
- Why：本文件与 report_worker.rs 是**等价但写法不同**的超时判据
（那边绑负数、这边把 start_time 往前推），修好一边而另一边没有守门 = 漏网；
方向写反**零报错、零日志、单测全绿**，只会静默提前结单、提前结算电量。
- 已实测自证：反写成 start_time < TIMESTAMPADD(HOUR, ?, NOW())
→ test_expired_order_scan_sql_points_backwards FAILED / exit 101；还原 → 3 passed。
3) device-server 的在线判据注释订正（原文与代码事实不符）
- 原文称在线键 device:{imei} "在验签前就会被写" —— **逐行核对后确认是错的**：
online=1 只由 api-server 的 report_worker 在 handle_login 的
sign == expected_sign 分支内（mark_device_online）以及 handle_status_post
（write_device_state，该 act 已被登录门控挡住）写入；handle_auth_str 不写 online。
- 真正不能拿它判下发的原因是另一条：它的 TTL 语义是"最近 300 秒收到过任意报文"，
断连后仍存活最多 5 分钟 ⇒ 会出现"管理端显示已下发成功、设备实际收不到"。
- 另注：server.rs::update_device_route 在 auth_str/login **到达时**写 node_id 并
EXPIRE 300 —— 只刷 TTL、不写 online；与协议 §2.3 一致，故保留，但同样说明
该键不能当"可下发"判据。
验收：api cargo check --all-targets 零 error/零 warning，单测 182 passed；
device 30 passed；两产物交叉编译通过，已按 device→api 顺序发布到测试与生产。
|
2026-09-20 04:31:42 +08:00 |
|
12451
|
61adcdeaf9
|
fix(security)+fix(api)+docs: 越权面修复、登录门控与状态语义对齐、文档全面校对
- 越权面（全部 before/after 实测可复现，10 条）：cabinets/filter 的 project_id/organization_id
参数分支越权（客户可拿对方向柜全字段）、organization-tree 返回全量组织树、
cabin-boards/compartments/cabinets 三个 options 无归属校验、batteries 无归属（改为经
charge_orders→cabinets→projects 间接归属）、feedback 跨组织读且能改他人状态、
GET /downloads/{id} 漏 user_id 过滤（跨用户元数据泄露）、
POST /downloads/cleanup 全局删除所有组织导出（改客户侧只清自己）、
/api/nodes/* 仅需登录（客户可读内网 IP 并注销节点）→ 收紧 role_level>=2；
/api/devices/stats 同样收紧；新增共享闸门 auth::require_super_admin
- TCP 登录门控：下行投递改为"登录前白名单"（PRE_LOGIN_ALLOWED_ACTS），与上行同一规则
- 60 秒超时对齐协议：挂起项 TTL 120→60 + 值内嵌 deadline 精确判窗 + 超时 WARN（兼容老格式）
- 下发前在线判据改连接级认证标记 device:authed:{imei}（消除"管理端显示成功、设备收不到"）
⚠️ device-server 与 api-server 必须同批发布
- 协议对齐：auth_str 登记校验提到限流之前、build_spec Topology 分支 clamp(15/8)、
行号引用改小节引用、修 3 处错引小节
- 状态语义：compartments.status 只表占用，充满/故障由通道状态派生；柜级 status1/status2
与开门按钮（柜级独立动作不联动）；列注释对齐（cabinets.status 补 2=禁用、
charge_orders.status 标注 2 保留未使用）
- 假绿单测修复：超时 SQL 抽常量 + 纯函数孪生体双向断言（方向写反必红）
- RSSI 两端统一为同源纯函数 5 档（小程序显示随之变化）+ test/rssi_signal.test.mjs
- nginx：扫码入口 abstract 限流（zone=scan_abstract_zone 30r/m burst=20）+ 主配置仓库镜像
- 文档：AGENTS.md 新增「踩过的坑」7 条教训 + 部署注意事项 11 条 + 文档口径优先级；
docs/API.md 接口总表 80 条与 mod.rs 逐条一致、Redis 契约按代码重写、9 处事实错误修正；
权威协议文档 v1.1.1（协议行为未变，仅修订文档自身的错误/矛盾/缺失）
|
2026-09-20 03:23:00 +08:00 |
|
12451
|
ee92102f3c
|
feat(scope)+fix(db)+feat(security): 数据范围(项目级)生效、库列类型对齐、安全加固、状态位分层展示、能耗实时聚合
- user_scopes 由"假开关"做成生效：粒度到项目级（组织隔离 ∧ 项目∈范围，取交集）；未配置=不限制（逐字向后兼容）；
总管理员豁免；脏数据保守忽略不锁死；配置期校验存在性+归属；逐接口叠加（列表/详情/写操作/Excel 导出落 scope_project_ids）；
前端新增"数据范围"弹窗入口。顺带修 GET /api/charge-orders 此前完全没有组织隔离（跨租户泄露）、
GET /api/projects/{id}/cabinets 的 500
- 数据库列类型系统性对齐：扫描并修复 pms_dev 32 项 / pms 18 项漂移（时间列统一 DATETIME，sqlx NaiveDateTime 只兼容 DATETIME）；
DECIMAL→BIGINT 与列注释口径拉平；修复生产 GET /api/charge-orders、GET /api/device-logs 必然 500 的根因；
恢复 7 张表丢失的 updated_at ON UPDATE（行为变化，已记入 AGENTS.md）；修正 SCHEMA_SQL 前向引用（空库建表必崩）；
新增 tools/db_schema_diff.py（漂移检查，退出码可接部署前置）与 test/schema_alignment_e2e.py
- 安全加固四项：上传去 .svg + 魔数嗅探（堵存储型 XSS）；登录失败锁定(5次/15分)+challenge 限流+并发闸门+验证码容差收紧；
服务降权 root→pms；nginx 安全头 + limit_req + CORS 白名单收敛
- TCP 连接登录门控（上行+下行同一规则）：login 前只放行 auth_str/login（PRE_LOGIN_ALLOWED_ACTS）
- 状态位按归属层级展示：柜级 status1/status2 显示在柜子（含柜门 + 开门按钮，独立动作不联动业务）、
仓体级 batt_status/pow_status 显示在仓体；两端解析函数同源同名
- 能耗报表改实时聚合 charge_records（原 energy_stats 全表只读不写导致报表恒 0）+ 补复合索引
- 组织可见性：新增 GET /api/my-organizations（工厂全量、客户仅本组织）
- 仓体 status 仅表占用，充满/故障由 Redis 通道状态派生
- 订单/占用/队列运维缺口：h5 建单漏单、214 仓体自愈、device:reports 上限、死信 TTL、LimitNOFILE、
每日 mysqldump + 回滚点保留 5 次
- 文档：AGENTS.md 补层级可见性/数据范围/状态位约定/数据库工具/行为变化；docs/API.md 删除废弃 TCP 章节、接口总表对齐 mod.rs
|
2026-09-20 02:44:51 +08:00 |
|
12451
|
db1264953a
|
fix(ops): 恢复能力与运维缺口修复（建表顺序/备份/建单漏单/214仓体/队列上限/NOFILE）
## 恢复能力（此前实际为 0）
- migrate.rs 的 SCHEMA_SQL 存在前向引用：charge_orders 建表引用其后才创建的 compartments
→ 全新空库必然报 MySQL 1824，而 main.rs 是 .expect("数据库迁移失败") + Restart=always
→ 无限崩溃循环。修正为把 cabin_boards/compartments 移到 cabinets 之后
（只挪位置、21 条语句字符数完全一致；实测旧版 20/21 → 新版 21/21，
并用真实二进制在全新空库跑通、建出 21 表 153 列）
- 新增每日备份 deploy/backup-db.sh + deploy/pms-backup.cron：
pms 与 pms_dev 各一份，--single-transaction --routines --triggers，单库 dump（无 USE/CREATE DATABASE，
演练可安全恢复到临时库），.part 原子 mv、gzip -t 校验、记录表数与精确行数、保留 7 天、flock 防重叠、
任一库失败则跳过清理并 exit 1（避免失败时误删旧备份）。cron 已真实触发验证；
恢复演练：21 表逐表行数一致（1339=1339）后清理无残留
- migrate.rs 每次启动无条件 ALTER cabinets.abstract_id 改为先查 information_schema 再决定，
实测老库触发 1 次、后续启动 0 次
## 订单与占用
- h5.rs start_charge：校验顺序改为 权限→归属→设备启用→设备在线→建单→下发（原为先建单后校验，
设备离线时会留下幽灵单）；取不到 bat_in 登记（48h TTL 过期）时不再跳过建单，改为按未知电池建单
（与设备侧 handle_device_on 兜底一致）—— 此前会导致整段会话无订单/无记录/无电量
- report_worker.rs 新增无订单却标占用的兜底复位（优先按通道 batt_status bit7，拿不到状态时按
超过 12 小时未更新），并已幂等清零生产历史遗留下的 214 行；两库复查均为 0
## 队列与资源上限
- device-server：device:reports 加 LPUSH→LLEN→LTRIM 0 199999→LLEN 的 pipeline 与越界 WARN
（此前无上限：68 柜停 8 天、1000 柜停 13 小时即打满 1GB Redis，且会连累同实例既有生产平台）
- 死信队列加 LTRIM 0 9999 + EXPIRE 7 天，写入时 WARN 带累计死信数
- 两服务各加 600s 一次的队列深度 INFO 日志（可观测性）
- 4 个 systemd 单元（仓库 + 线上已安装）加 LimitNOFILE=65535（原软限制 1024，约 1000 柜即 accept 失败）
## 文档
- docs/API.md：接口总表 71 → 79 条并与 mod.rs 的 79 次 .route( 注册双向比对一致；
修正 system:log（种子里不存在的权限码）→ operation_log:view、登出 GET→POST、能耗导出 → energy:export；
补齐 21 个未记录接口；新增"列表响应包装"与"关键数值字段单位"两节
## 超长函数
- report_worker.rs handle_bat_out 100→63、ensure_charge_order 88→68；users.rs update_user 81→45
（纯重构：字符串字面量多重集零差异，allow/unwrap/expect/panic 计数不变）
## 验收
- cargo check 两服务 0 error/0 warning；cargo test api 90 + device 22 全过
- 前端真实类型检查 npm run typecheck（= tsc -b；原 `tsc --noEmit` 因 tsconfig 是 solution 文件而空跑=假绿）
- 端到端联调（测试环境）13/13；生产已部署并验证：服务 active、health 200、ERROR 0、
消费链路正常、214 仓体清零、唯一索引在位
|
2026-09-20 01:21:17 +08:00 |
|
12451
|
f80b3b634c
|
fix: 五角度审查后的安全/正确性/契约修复（含 order_timeout 反条件、连接接管、权限兜底）
## 严重问题
- order_timeout: 超时条件方向写反（`start_time < TIMESTAMPADD(HOUR,10,NOW())` 等价于
`start_time < NOW()+10h`，条件恒真）→ 活跃订单会被当超时单提前结掉。改为
`TIMESTAMPADD(HOUR, ?, start_time) < NOW()`，并补"刚建单不命中/超期命中"双向断言
- C1 device-server 连接池可被未验签的报文 dev_id 顶替（覆盖式 insert + 断连无条件 remove）：
改为 conn_id 归属模型 —— 唯一连接标识、remove_if/touch/is_authenticated 均带 conn 归属校验、
接管时用 oneshot 信号主动驱逐旧连接、每条上行前用 is_owner 复核持有者身份
- C2 POST /api/devices/{imei}/command 零归属校验 + act 自由字符串 + 把 IMEI 塞进协议 id：
补 scope_guard 归属校验 + act 白名单 + id 从 params 显式取（拒绝 15 位 IMEI）
- 非总管理员权限集恒为空（user_roles 从不写入且无分配入口）→ 全站 403：
user_roles 为空时按 users.role 回退内置角色权限 + 建/改用户幂等同步映射（仅角色变化时同步）
## 订单生命周期并发正确性
- finalize_order 先取电量累加器后抢结束权 → off/bat_out 成对到达时 energy 被写 0：
改为先原子抢占（WHERE compartment_id=? AND status=0 ORDER BY id DESC LIMIT 1），
抢到者才 take_and_reset 取电量；抢不到直接返回且不碰累加器
- 建单"先查后插"无锁无唯一约束 → 同仓体两笔活跃单：
条件插入（INSERT ... SELECT ... WHERE NOT EXISTS）+ 按仓体进程内锁
+ DB 层 active_flag 生成列 + UNIQUE 唯一索引（幂等迁移，有重复则记 ERROR 跳过，绝不阻断启动）
- handle_bat_out: updated==0 时不再复位占用；通道登记删除改为 battery_id 一致才删；
新增 should_finalize_bat_out 挡住"迟到 bat_out 结束新单"
- 电压/电流加量程夹取（0–100000 mV/mA 之外按 0 计并 WARN），防位翻转导致积分暴增
## 协议/契约
- spec 绝不可能是 "0000"（生产 42/68 台拓扑为空）：新增 build_spec 三级兜底
（真实拓扑 → cabinets.cell×6 → 6×6），兜底生效记 WARN 报出拓扑数据
- /api/cabinets/realtime-status 改读真实字段（原来读的设备链路从不写的旧字段，恒返回 idle/空），
用 derive_channel_view 推导旧字段以保持响应字段名不变；修掉"把通道号当板号"的幽灵板问题
- 小程序通道详情/PC 详情改读通道 Hash（弃用无写入方的 compartment:status:{id}），
取不到返回 null 而非假的 0；补 voltage/current/temp/batt_status/pow_status
- 反馈列表补权限码 operation_log:view + status 筛选真正落到 SQL
- 小程序柜温换算（29800 曾被显示成 29800°C）；签名注释 7→8 位；msg_id 序列化省略 null；
parse_compartment_id 与 status_post 补板号 1–15/通道 1–8 量程校验（不再写 board:0 垃圾 key）
## 文档
- docs/柜控板固件对接文档.md：确立数值口径统一规则（hex 字节流=原始硬件单位·平台换算；
JSON 数值字段=平台单位·设备换算）、修正 A.5.3 的 id 说明、作废变更记录原位标注（不删历史）、
spec 表述改为"按拓扑现算+兜底、恒 4 位不会是 0000"、修复文首 7 项表格被引用块切断丢表头、
修正 §10 误引 channels[].channel、写明无电池兜底阈值与 #16 风险
## 运维加固（服务器侧，非代码）
- 关闭 MySQL/Redis 公网暴露：nginx stream 由 0.0.0.0 改为只监听 127.0.0.1 + ZeroTier
- worker_shutdown_timeout 30s（原先每次 reload 泄漏永不退出的 worker）
- 测试证书改指向 app 证书（原测试证书 9 天后过期且无续期机制）；补测试环境 uploads 目录；.env 0600
## 验收
- cargo check 两服务 0 error / 0 warning；cargo test api 88 + device 22 全过
- 路由 79 → 79 逐条一致；web tsc 干净
- 端到端联调（测试环境）13/13，订单结算与重构前逐字段一致；唯一索引已由迁移真实建出
- 生产已部署并验证：服务 active、health 200、ERROR 0、消费链路正常、迁移已建索引
|
2026-09-20 00:36:37 +08:00 |
|
12451
|
8bc7812733
|
refactor(api-server): 23 个超 80 行函数拆分为 ≤80 行（纯重构，行为不变）
拆分范围（14 个文件）：migrate / users / operation_logs / energy_stats / charge_records /
batteries / device_logs / auth / captcha / main / routes::mod / h5 / cabinet_tree / report_worker
手法：长 SQL 抽模块级 const、拼装与映射与校验抽私有 fn、路由按业务域拆 Router 再 merge、
Excel 导出按"取数/表头/逐行/收尾"分阶段、连续代码块原样搬移+传参。
行为不变的证据：
- 路由 79 → 79 条逐条比对一致（路径+handler+方法链；中间件/CORS/with_state 作用域保持）
- 字符串字面量多重集比对：11 个文件唯一集合完全一致；report_worker 零差异（435 条字面量全等）
- 关键契约计数不变：CAST 14→14、AS SIGNED 4→4、COALESCE 6→6；SQL 文本与 Redis key 零增删
- 未新增 #[allow] / unwrap / expect / panic；captcha 的 RNG 消耗顺序保持（验证码分布不变）
验收：cargo check 0 error / 0 warning；cargo test --bins 39 passed / 0 failed；全仓已无 >80 行函数。
端到端回归：先部署测试环境跑 TCP 协议联调 13/13，且数据库终态与重构前逐字段一致
（orders.energy=22、start_soc=850、end_soc=1000、records.energy=22.00、max_temp=29800、占用状态正确复位）。
|
2026-09-20 00:01:01 +08:00 |
|
12451
|
999885c38f
|
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:41:09 +08:00 |
|
12451
|
b553c4e519
|
feat: API 统一 + 设备详情补全 + H5 导航优化
- API 路由统一: 移除 /api/h5/，统一 /api/pms/ 入口
- 二进制改名: api-server -> pms-api（与服务名一致）
- nginx: 合并 /api/ + /pms/api/ 为 /api/pms/
- 新增 docs/API.md 接口文档
- 后端: CabinetDetail 增加 rssi/pow_fail/address/soc 等字段
- Redis 管道批量读取仓体实时数据（SOC/电压/电流/功率）
- DB: 所有 TIMESTAMP 列改为 DATETIME（修复类型不匹配）
- 用户管理: 新增创建时间/修改时间列，状态改用 Switch
- 角色管理/用户管理: 操作按钮改为图标
- PC 设备详情: 基本信息补全 RSSI/ICCID/电源/地址
- PC 卡片: 通道统计改用 Lucide 图标，颜色统一
- PC 二维码: canvas 渲染，含编号文字，支持右键下载
- H5: 按 uni-app 规范修正导航（navigateTo 替代 reLaunch）
- H5: 详情页加返回导航条
- H5: 扫码支持摄像头（jsQR）+ ?id= 参数
- H5: 底部 tabBar 在所有页面常显
- H5: 首页统计改为 6 项（设备/通道/空闲/充电/充满/故障）
- H5: 下拉刷新 / 上拉加载
- 产品首页: 添加业务联系
- 文档: 清理过时文件，补充缺失规范章节
|
2026-07-04 04:03:02 +08:00 |
|
12451
|
721df313ee
|
fix: SUM(energy) 用 CAST AS UNSIGNED 转整数避免 DECIMAL 解码错误
|
2026-07-03 10:25:41 +08:00 |
|
12451
|
6b31a61387
|
fix: H5 decimal 类型兼容 - energy 用 String 接收避免 DECIMAL 解码错误
|
2026-07-03 10:20:29 +08:00 |
|
12451
|
4765fc9ead
|
fix: H5 API 修复 + 后端 DECIMAL 类型兼容修复
|
2026-07-03 05:08:44 +08:00 |
|
12451
|
06765f99db
|
feat: H5 用户端 Taro 重写 + 前后端接口对齐修复
- 使用 Taro + React 重写 H5 用户端（替换旧的 React+Vite+H5 实现）
- 6 个页面：登录、首页、设备列表、设备详情、仓体详情、个人中心
- Zustand 状态管理 + API 层封装 11 个接口
- 后端 H5 路由：新增仪表盘/项目/设备/充电控制接口，组织数据隔离
- 扫码入口：/h5/{abstract_id} → 免认证查设备 + 登录后跳转
- 管理端：新增绑定码管理、二维码展示下载、设备绑定/替换 IMEI
- 产品落地页更新（hero-bg + logo 替换）
- 接口对齐修复：修正 action 路径/请求体，DashboardData 和 CabinetItem 字段匹配后端
- 布局兼容性：grid → flex，提升移动浏览器兼容性
- 移除旧 H5 项目 software/h5/
|
2026-07-03 02:45:00 +08:00 |
|
12451
|
7290da8eae
|
feat: 卡片显示真实通道状态统计（空闲/充电/充满/故障）
|
2026-07-02 22:09:19 +08:00 |
|
12451
|
3607701c26
|
feat: 树节点显示设备数量，如 无锡艾动 (15)
|
2026-07-02 21:42:52 +08:00 |
|
12451
|
69faa75310
|
feat: 支持多级组织机构，组织树可展开显示下级
|
2026-07-02 21:32:06 +08:00 |
|
12451
|
2453f680ac
|
refactor: 拆分组织树和设备列表为独立接口，支持按组织/项目筛选
|
2026-07-02 21:20:06 +08:00 |
|
12451
|
e3894cb946
|
fix: cabinet_tree查询添加iccid和address字段
|
2026-07-02 21:14:43 +08:00 |
|
12451
|
ef3250970a
|
fix: CabinetRow添加iccid和address字段，API返回完整数据
|
2026-07-02 21:08:21 +08:00 |
|
12451
|
a9e720fe02
|
feat: 后端返回ICCID，卡片显示IMEI/ICCID换行，状态图标
|
2026-07-02 20:54:37 +08:00 |
|
12451
|
04a3d31517
|
fix: 修复auth/me查询SQL，移除不必要的MAX聚合
|
2026-07-02 19:10:34 +08:00 |
|
12451
|
652bde44c4
|
fix: nginx配置修正Gitea路由 /doc/ 而非 /pms/doc/
|
2026-07-02 15:18:45 +08:00 |
|
12451
|
7a04f6da53
|
chore: 测试/正式环境端口分离，更新部署配置
- API: 测试:3000, 正式:9000
- TCP: 测试:3001, 正式:9001
- 部署路径: /data/pms (正式), /data/pms_dev (测试)
- URL: /pms/ 前缀
- 添加 systemd 服务单元和部署脚本
- 更新 nginx 配置和 AGENTS.md 文档
|
2026-07-02 14:58:47 +08:00 |
|
12451
|
12395ee9e2
|
init: PMS充电柜管理系统源代码
|
2026-07-02 05:38:01 +08:00 |
|