12451
|
c1b44b6e23
|
feat(web): 能耗页新增「整柜日用电量（电表读数口径）」区块
后端 `GET /api/cabinets/{id}/meter-usage` 上一提交已上线，本提交把它接到既有的
能耗管理页（`/energy`）—— 用户指出已有能源统计页面，无需新建页面。
## 区块内容
- 柜子下拉（复用 `/cabinets/options`，支持搜索）+ 表格（日期 / 电表末读数 / 当日用电 / 数据质量）
- 分页 15 条/页，未选柜子时提示"请先选择柜子"（而不是显示空表格）
- 表格下方一行区间合计（kWh），并注明"无基准与电表更换日不计入"
## ⛔ 与页面既有区块的区别（必须让用户看见，不能混）
区块顶部加了一条 Alert 常驻说明：
> 本区块是电表读数口径（整柜实际用电，硬件计量、含非充电损耗）；
> 上方卡片与排行是订单电量口径（平台按 V×I×Δt 积分的估算值）。
> 两者数值必然不一致，不可互相替代。
## 三个语义坑在前端的落地（与后端 flags 一一对应）
| flags | 前端渲染 |
|---|---|
| `no_baseline` | 当日用电显示 **`-`**（**不是 0**） |
| `covers_multiple_days` | 数据质量列显示"覆盖多日"（warning 色） |
| `meter_reset_or_replaced` | 当日用电显示 **`-`**，数据质量列显示"电表更换/清零"（danger 色） |
数据质量列正常时显示"正常"。`flags` 与文案的映射收在 `METER_FLAG_META` 常量表里，
**新增 flag 必须同步该表**（否则会渲染成空白标签）。
## 验证
- `npm run typecheck`：**exit 0**
- **自证能失败**：植入未定义变量 `meterFlagNoSuchVar` → `TS2304` / **exit 2**；还原 → exit 0
> 附：第一次自证我选错了判据（把接口的 `usage_wh?` 改成必填），typecheck 不报错 ——
> 因为接口数据源是 `any`，类型由我自己声明的接口决定，改必填确实不冲突。
> 换成编译期必错的未定义变量后才验证成功。**是判据选错，不是工具假绿。**
- `npm run build`：exit 0（产物 572 KB / 6 个文件）
- 后端全量验收仍绿：`cargo check` 0 告警、`cargo test` **204 passed**、
`device_status_parse` 16/16、`rssi_signal` 9/9、结构漂移无
- **端到端**（临时超管账号 + 自签 JWT，用完即删）：造 5 条读数打真实 HTTPS，
断言前端渲染所需的每个字段都在、`flags` 取值与 `METER_FLAG_META` 的 key 一一对应、
三个语义坑全部生效、汇总 500 正确 ⇒ **exit 0**
- 已发布：测试 + 生产（web 产物时间戳与本地构建一致 `00:19:40`，
生产 0 ERROR、域名 401/200；测试环境 nginx reload 后三服务 active）
|
2026-09-21 00:25:11 +08:00 |
|
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
|
ad6c32b709
|
docs(protocol): 补 meter 字段的平台侧落地情况（已落库 + 变化留痕=抄表记录）
协议 §5.3 的 cabinet.meter 字段表原本只写了要求「平台原样存库」。现补上落地情况：
- 已落 cabinets.meter_wh / meter_at（最新读数）
- 已在 cabinet_meter_readings 表**只在读数变化时**追加留痕（即抄表记录，可直接算日用电量）
- 并注明此前只写 Redis（TTL 300s）⇒ 上报即被清掉、历史不可回溯，属实现缺口
- 明确 meter（整柜累计电能）与 energy（单订单充电量，协议无此字段）不是一回事
实测证据：4 次同值上报只在留痕表留下 1 行；读数由 125500 改为 125600 后新增 1 行且 cabinets.meter_wh 同步。
|
2026-09-20 05:55:53 +08:00 |
|
12451
|
f3e733eaec
|
docs: 电表读数落库的文档同步（AGENTS.md/数据模型 21->22 张表；tasks/002 标记已实现）
- AGENTS.md 与 docs/tech/数据模型.md：21 -> 22 张表，补 cabinet_meter_readings 说明（抄表留痕：只在读数变化时追加，cabinets.meter_wh 冗余最新值）
- tasks/002：电表项由「待确认是否实现」改为「已实现」并列出实测证据（4 次同值只留 1 行、改值新增 1 行）
- 生产已发布并核验：22 张表、结构漂移 0、0 ERROR
|
2026-09-20 05:55:37 +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
|
fe8436f114
|
test(e2e)+docs: 补上「平台侧积分电量」的**真实**端到端断言（此前只断言 suc=1）
## 起因
用户要求「`energy` 先实现自己积分，硬件能提供时再去掉」。**核实后：该积分早已实现**，
本轮真正缺的是**验证** —— 而且发现一个假覆盖。
## 核实结果：积分早已落地（不是新功能）
- **实现**：`software/api-server/src/workers/energy.rs`（12.9 KB / 8 个单测）——
每次 `status_post` 按 `mWh = mV × mA × Δt / 3_600_000`（Δt 固定 60 秒）累加到
**通道级** Redis 累加器（Lua 原子累加 + 最高温跟踪 + 连续无电池计数），
建单 `reset`、结算 `take_and_reset` → 写 `charge_orders.energy` 与 `charge_records.energy`；
- **协议文档也已标注落地**：`docs/protocol/柜控板固件对接文档.md`「待确认事项」第 13 项
写的是 **✅ 已落地（兜底方案已生效）**，并给出"硬件若能提供则平台改取硬件值"的口径；
- **`tasks/002` 把它记为「⏸ 阻塞中（等硬件答复）」是过时的** —— 已更正，并写明
"硬件给值后怎么撤"：**单一入口 `energy::accumulate`**，落库字段/记录生成/前端展示都不用动。
## 本轮补的真东西：把假覆盖变成真验证
`test/tcp_e2e_smoke.py` 第 ⑥ 步标题一直写着"验证平台侧积分电量"，
**但只断言了 `suc=1`，从未检查电量值** —— 典型的"看起来验证了、其实没验证"。
新增第 ⑨ 步：`off` 结算后**读测试库**，断言：
1. `charge_orders.energy` == **由负载常量推导的期望值**
（`CHARGING`=54.00V/8.00A × 60s × 3 次 ⇒ 21600 mWh ⇒ **22 Wh**）；
2. 已生成 `charge_records`，且其 `energy` 与订单**一致**（同一积分值写两处，分叉即为缺陷）；
3. `max_temperature` 被积分路径一并跟踪（29800 K×100）。
**实测结果（测试环境，18/18 通过、exit 0）**：
```
订单 id=58 status=1 energy=22Wh | 记录 energy=22Wh 最高温=29800K×100 | 期望=22Wh
```
**已自证能失败**：把 `CHARGING` 的电流由 8.00A 改为 4.00A（改**真实负载**而非期望值）
→ 实测 `11Wh ≠ 22Wh` → **FAILED / exit 1**；还原 → 18/18 通过。
## 顺带修掉一个"误导性红"
连续跑第 6 次本脚本会撞上 `auth_str` 的**「同一 IMEI 5 次 / 5 分钟」频率限制**（协议 §5.1），
于是第 ① 步被限流、后续 12 条断言**级联失败**，输出看起来像"登录/建单/结算全坏了"。
现第 ① 步即识别 `err == "rate limit exceeded"`，**明确说明是重复运行所致、不是功能缺陷**，
并提示 `systemctl restart pms-api-test` 清零进程内计数器，以 **exit 2（环境问题）**结束。
> 这个坑我实际踩到了：一度以为改动引入了回归，按「踩过的坑」第 7 条的思路先怀疑夹具/测量方式，
> 才定位到是限流。
## 退出码
新增"未验证"档：**读不到测试库 ⇒ exit 2**（需要 SSH 隧道），
**绝不当成通过**；有断言失败仍优先 exit 1。
## 验收
- `cargo check --all-targets`：0 error / 0 warning（本轮未改 Rust 代码）；
- `cargo test --bin pms-api`：**189 passed**；
- `python tools/db_schema_diff.py`：**无漂移**；
- `test/schema_alignment_e2e.py --env dev`：全部通过 exit 0；
- `test/tcp_e2e_smoke.py`：**18/18 exit 0**（含新增 5 条积分断言）；
- **发布**：本轮只改测试脚本与文档，**无需重新发布**；且实测生产与测试运行的是
**逐字节相同的二进制**（api `f7e075a4a7a5983ebfe9b641e3d211cfdf7154361627858cbe68737211ff0f95`），
即测试环境验证的积分链路**就是生产在跑的那份**。
## 文档
- `AGENTS.md` 验收流程第 5 项：注明该脚本现已含电量断言（**需要 SSH 隧道**）、
以及 `auth_str` 限流的注意事项；
- `tasks/002`（不入库）：把 `energy` 从"阻塞中"更正为"已实现 + 已端到端验证"，
并保留"硬件给值后如何撤"的口径。
|
2026-09-20 05:37:21 +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
|
401f84bda6
|
chore: 清掉误入库的 agent 工具记忆目录与 Vite 模板 README（内容先按主题归位）
## 起因
用户问"现在确定所有文档都是按分类存放没重复和过期内容了吧" ——
**不能凭感觉答"是"**，于是做了一次针对**已跟踪文件**的体检（重复/断链/过期陈述三维度）。
第一轮体检结果：重复 0 组、断链 0 处，但**又扫出 3 处该处理的东西**。
## 一、`.workbuddy/memory/` —— 另一个 agent 工具的记忆目录被误入库
3 个文件（`MEMORY.md` / `2026-07-02.md` / `2026-07-07.md`），**全仓零引用**，
最后一次"提交"是搭车进 `feat(protocol): TCP v1.1 协议对齐` 这类无关提交 ——
与之前那几张误提交的图片同一模式。
- ⚠️ `2026-07-02.md` 里含一处**生图 API Key 片段**（`sk-ib7i...M2z`）；
- `.gitignore` 里 `.codebuddy/` 早有，但 `.workbuddy/` **漏了** ⇒ 才被顺手提交进来。
### 处理：内容先归位，再删目录（不是一删了之）
按 `docs/README.md` 已确立的原则"**过时就删；仍有价值的归到正确的类**"，
把 `MEMORY.md` 里仍有价值的三类内容分别落位：
| 内容 | 归到哪 | 为什么 |
|---|---|---|
| UI 颜色系统 / 背景容器 / 36 仓通道卡布局 | **`docs/tech/小程序用户端.md`** 新增「附：UI 设计规范（视觉口径，改动界面前必读）」 | 这是页面视觉口径，属小程序文档 |
| Ardot `batch_edit` 的 `fills`/`strokes`/`cornerRadius` 写法坑 + 设计稿 7 屏 ID | **`docs/compound-notes/2026-07-ardot-batch-edit-属性写法.md`** | 工具特有的单点教训，正是 compound-notes 的定义 |
| "开发前必须确认需求"、"生产环境须授权"、落地页明亮风格偏好 | **`AGENTS.md` 新增「操作规则」小节** | 项目级规则，须常驻加载 |
然后把 `.workbuddy/` 从版本控制移除并**加入 `.gitignore`**（连同 `.opencode/`、`.codegraph/`），
堵住同一个坑再犯。
## 二、`software/web/README.md` —— 建站模板残留
23 行里 9 行是 Vite/plugin-react/Oxlint 的模板话术（英文、与项目无关）。
`api-server` / `device-server` / `h5-uniapp` 三个工程**都没有** README —— 构建方式统一在
`AGENTS.md` 与 `docs/tech/部署手册.md` 里。⇒ **删除**。
## 三、一个我自己的误判（已纠正，记录以免后人重复）
我一度怀疑 `docs/tech/API.md` 接口表"少 12 行"（我数出 68 行，而 `mod.rs` 有 80 个 `.route(`）。
复核发现 **`API.md` 自己写明了计数约定**："一行 = 一次 `.route(...)` 注册，共 80 行；
展开后 93 对" —— 而我的正则 `^\|\s*(GET|POST)\s*\|` **漏掉了 `| GET / POST |` 这种链式写法**。
用能匹配链式的正则重数 = **正好 80** ⇒ **`API.md` 是准确的，我的怀疑是错的**。
## 校验（只扫 git 已跟踪文件）
- 已跟踪文件 **217**（原 221 → 删 3 个工具记忆 + 1 个模板 README）；
- 文档内容重复：**0 组**；
- 已跟踪 md 的本地链接：**0 断链**；
- `.workbuddy` 已跟踪文件数 = 0、工作区已不存在。
## 仍**刻意保留**的（不是遗漏）
- `生产环境.txt`：**唯一凭据清单**且被 `docs/tech/小程序用户端.md` 引用为密钥记录处 ——
上一提交已把"不入代码仓库"这句与事实矛盾的表述改准；是否改走 `.gitignore`+密码管理器由你定。
- `docs/README.md` 的「旧名→现名映射」表 / 处置记录 / 自证方法：**必须**出现旧名，属预期。
- `docs/compound-notes/TEMPLATE.md`（94 B）：新建笔记的模板，给该目录提供格式约束。
- `tasks/002-未结待办-*.md`：两项未结（`energy` 等硬件答复、长函数重构），
`tasks/` 本身已 gitignore、不入库。
|
2026-09-20 05:04:53 +08:00 |
|
12451
|
a03c163c1d
|
chore: 清理过时与误提交产物；取消 archive/（过时就删，历史交给 git）
## 起因
用户问"历史留痕？看看有没有过时的和无用的东西可以删除" ——
**不该把"归档"当免检区**。逐项查证后：确认了 3 类该删的、1 类归错类的、1 个不能删的。
## 一、删除：被"顺手 git add"误带进无关提交的产物
用 `git log --diff-filter=A` 追来历，发现它们**根本不是有意提交的**：
| 文件 | 来历 | 判据 |
|---|---|---|
| `换电柜用锂电池充电器1TN标准通信协议 - RS485 V1.0(1).pdf` | `652bde4`（nginx 路由修复） | 与 `docs/hardware/1TN协议标准_苏州翌工电源_V1.0.pdf` **MD5 完全相同**（`B723A1FC…`）—— 纯重复 |
| `package.json` + `package-lock.json` | `652bde4`（同上） | 唯一依赖 `html-docx-js`，**全仓无任何脚本引用**（当次把合同 md 转 docx 的一次性工具残留） |
| `9b0d3b8a…jpg` / `d6e6add1…png` / `ea4410ba…jpg` | `8bc7812`（"23 个函数拆分"）/ `999885c`（协议对齐） | **零引用**，且混在与图片毫无关系的重构提交里 —— 误提交的截图 |
## 二、归错类（**不是过时，所以不删**）：`开发文档.md` → `hardware/硬件与系统设计文档.md`
原本被塞进 `archive/`，但通读目录后确认它含**硬件设计内容**，这些在 `AGENTS.md`/`docs/tech/` 里**没有**：
硬件架构、仓控/柜控主板设计、指示灯状态机、充电控制逻辑（握手/双模式/动态调整/无协议模式）、
BMS 协议适配、安全防护联动、性能指标、第三方服务配置。
⇒ 它是**归错类而非过时**：**硬件部分仍是权威参考**，只有第 7 章（软件平台）被现行文档取代。
已在 `docs/README.md` 写明"两者冲突时软件口径以 `AGENTS.md` 为准"。
## 三、删除：两份 2026-07-06 报告（**问题已全部解决**）
逐条核对了它们"发现的问题"，**无一条仍然成立**：
| 报告 | 当时的问题 | 现状 |
|---|---|---|
| 深度分析报告 | 敏感信息泄露（AGENTS.md 明文密码） | 已成 `AGENTS.md` 的**明示豁免**条目 |
| | 目录名不一致（可能用 taro，需确认） | 已确认 `h5-uniapp`，无 taro |
| | `test/` 目录缺失 | `test/` 已存在且有 7 项验收脚本 |
| | 温度单位不一致（K×100 vs 0.1°C） | 已统一为 K×100 |
| 数据单位审查报告 | SOC/SOH 单位标注错误 | `API.md` 早已重写；该报告基准 `tcp-protocol.md` 已不存在 |
## 四、**不删**：`生产环境.txt`（并修掉自相矛盾的表述）
它是**唯一凭据清单**（阿里云账号/小程序 AppSecret/腾讯地图 key/SSL AccessKey 都在其中），
且被 `docs/tech/小程序用户端.md` 明确引用为"密钥记录处"。
但原文写着"仅记录在内网 Git 仓库 `生产环境.txt`，**不入代码仓库**"—— **与事实矛盾**
（`git ls-files` 实测它**已入库**）。已改为准确表述：只记录在该文件、**绝不写进任何源码/.env**、
**不要删除**（新凭据追加到那里，不要散落别处）。
> 🔐 **留给你的决定**：该文件含大量明文凭据。现策略与 `AGENTS.md`「明文密码」豁免一致（内网仓库），
> 若要收紧，建议把它加入 `.gitignore` 并另存到密码管理器 —— 但这会改变 agent 的直连方式，故未擅自改。
## 五、取消 `archive/` 目录本身
**不再设归档**。理由：被删内容在 **git 历史里完整可查**（`git log -- <原路径>`），
归档的"留痕"价值因此为零，却持续制造"这文件还算不算依据"的歧义。
已把该结论写进 `docs/README.md` 的维护约定：**过时就删；仍有价值的归到正确的类。**
## 六、其他归位
- `营业执照.jpg`（主体资质，小程序/备案用）→ `docs/contract/`
- 根目录现在只剩 5 个必要文件：`.gitignore` / `AGENTS.md` / `README.md` / `opencode.json` / `生产环境.txt`
## 校验
- docs 相对链接 **0 断链**（搬迁引入的 2 处已在上一提交修好，本次复检通过）；
- 已删除文件的残留引用：**仅剩 `docs/README.md` 的处置记录/映射表**（旧名必须出现，属预期）；
- `cargo check --all-targets` 两服务零 error/warning（本次只动文档与仓库清理，未碰源码逻辑）。
|
2026-09-20 05:00:29 +08:00 |
|
12451
|
7d2b57d021
|
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 |
|
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
|
471b61d277
|
fix(test)+fix(deploy)+docs: 探针状态语义反转修复、退出码补齐、文档校订
1) probe_export.py：任务状态语义**搞反了**（导出成功也会被判失败）
- download_tasks.status 的权威语义是 0 排队 / 1 处理中 / **2 完成** / 3 失败
（db/migrate.rs:225 列注释；写入侧 charge_records.rs::mark_task_completed 写的就是 2）。
- 该脚本此前**等 status == 1（处理中）当成功、把 status == 2（完成）判成"导出失败"**
—— 典型假红。已按权威语义订正，并与另外两处**本来就正确**的口径对齐：
web/src/pages/charge-records/DownloadCenter.tsx::statusText、
test/schema_alignment_e2e.py（等 status in (2,3) 再断言 == 2）。
- 同批修正退出码分类：账号缺 charge_record:export（403）由 exit 1 改为
**exit 2「未验证」** —— 本项要验证的是"降权成 pms 后能否往 exports/ 落盘"，
没权限根本走不到那一步，报 1 是**把夹具缺陷说成产品缺陷**（误报与假绿同样有害）。
- 允许用 PMS_PROBE_PHONE / PMS_PROBE_PASSWORD 换成有权限的账号。
- **C 项结论（由落盘物证直接判定，不依赖该脚本）**：测试环境
exports/充电记录__-.xlsx 5559 B、生产同类产物 5457 B，属主均为 pms:pms；
两环境 exports/uploads 目录均 pms:pms，两 api-server 单元均 User=pms/Group=pms
⇒ 降权进程确实能落盘。已在 README 写明并给出取证依据。
2) deploy-prod.ps1 的退出码（此前失败的探针只打印 ❌ 就继续，脚本仍以 0 退出）
- 消费链路探测失败（exit 1）现在**记入失败清单**并以 exit 1 收尾；
"未验证"（隧道没起）默认仍不计失败（环境问题会误报），
但新增 **-StrictVerify** 开关供 CI/无人值守使用，打开即 exit 1。
- 好处：把这条从"打印了 ❌ 却 exit 0"（仓库第 8 条假绿）里摘出来。
3) 统一退出码 0/1/2 落地到本批脚本，并对每个失败路径实测取证：
- test/tcp_e2e_smoke.py：13/13 通过（含未登录业务报文被静默丢弃）；先复位夹具再跑。
- test/security-hardening/ 新增 verdict.py 判据容器（未跟踪 → 本次入库）；
4 个探针全部按失败→exit 1 改造，并各实测过失败路径。
- 实测结果（2026-09-20 发布后回归）：smoke_prod 4/4 exit 0、
probe_prod 5/5 exit 0、probe_upload 6/6 exit 0。
4) 工具与文档
- tools/db.py 默认库由**生产 pms 改为测试 pms_dev**（可用 PMS_MYSQL_DB 覆盖，
切生产时打印醒目警告）—— "以为在测测试库、实际打生产"的隐患。
- tools/db_schema_diff.py：连不上必须是 exit 2，绝不伪装成"无漂移"的 0。
- 新增 tools/dev-tunnel.ps1（入库，SSH 隧道；口令走 PMS_SSH_PASSWORD 环境变量），
配套 tools/dev-tunnel-run.ps1 自愈启动器**保持 gitignore**（内含口令）。
- deploy/nginx/nginx.conf 镜像随线上同步（移除 stream 转发；与线上逐字节一致）。
- AGENTS.md / README.md：补「踩过的坑」第 7/8 条（掐断上游管道会杀被测进程、
打印 ❌ 却 exit 0 是假绿）、退出码约定、本地开发改 SSH 隧道、
在线判据口径订正、order_timeout 守门补齐、小程序 vue-tsc 门禁与其抓到的两个真 BUG。
发布验收（本次统一发布，按 device→api 顺序）：
- 测试环境与生产环境四服务 active，端口 9000/9001/3000/3001 正确，ERROR 均为 0；
- 生产迁移按判据 grep '更新列注释' 实测对齐 cabinets.status 列注释；
- 结构漂移 python tools/db_schema_diff.py = 0 处漂移 / exit 0（--vs-ddl 两库同样 0）；
- schema_alignment_e2e --env dev 全部通过 exit 0；
- 生产域名 /api/pms/cabinets -> 401、/pms/ -> 200；消费链路探测通过。
|
2026-09-20 04:31:42 +08:00 |
|
12451
|
aa02cd4e58
|
fix(mp): 接入 vue-tsc 真类型检查并修掉它抓出的两个真实缺陷
小程序端此前**没有任何类型门禁**：tsc 不检查 .vue，而 9 个页面全是 .vue，
npm run build:mp-weixin 只验语法不验类型。接入 vue-tsc 后立刻抓到 17 个错误，
其中两个是真 BUG：
1. me/index.vue：写 const user = authStore.user 之后又写 user.value ——
Pinia setup store 对外已把 ref 解包，user.value 恒为 undefined
⇒ **头像上传成功后写回 store 的那行是空操作**（要等冷启动才显示新头像）；
且直接取值是快照、丢掉响应式。改为 computed(() => authStore.user)，模板无需改动。
2. api/index.ts：CompartmentDetail 漏了后端确实会返回的 temp
（routes/h5.rs 的 COMPARTMENT_REALTIME_FIELDS 第 6 项，有单测守门）
⇒ compartment-detail 页读 data.temp 报 TS2339。已按后端契约补上。
其余 12 处是宿主全局 wx 未声明（@dcloudio/types 只声明跨端 uni），
在 env.d.ts 里**只声明实际用到的两个 API**（刻意不写 [k:string]:any，
否则等于把这一层检查关掉）。
顺带清理：
- 删除死页面 pages/devices/index.vue（不在 pages.json、无任何跳转引用，grep 确认）；
- 删除仓控板「在线/离线」徽标：cabin_boards.status **全后端没有任何写入方**
（生产库实测取值只有 0），该徽标恒定显示"离线"，属对用户的谎报；
协议层面也没有"仓控板在线"这个概念（TCP 长连接的是柜控板，按 IMEI 标识）。
按「柜的就显示到柜子」+「不显示推不出来的状态」去掉，并在类型上加禁止说明。
已按仓库铁律自证门禁能失败：植入 export const probe: number = 'x' → exit 2；撤销 → exit 0。
|
2026-09-20 04:31:42 +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
|
9e8826e6f8
|
fix(deploy): 生产/测试改直连阿里云（nginx stream 转发只服务本地开发）
- 起因：生产 .env 走 127.0.0.1:6379/3306，而这两个端口是 nginx 在监听 ⇒ 生产实际经由
"给开发用的转发层"：reload nginx 会同时切断四个服务连接（实测每次 4 条 broken pipe ERROR），
且生产的库/缓存通路依赖 stream{} 配置（配错则 nginx 起不来、整平台连不上库）
- 改动：/data/pms 与 /data/pms_dev 的 .env 改为直连 rm-...mysql.rds / r-...redis.rds（改前已备份）
- 实测：裸 TCP 可达、python3 直接说 Redis 协议读写成功、mysql 客户端直连查询成功
（柜子 68/组织 46/版本 8.0.36）、连接目标均为阿里云 IP、health 200、端点回归通过；
reload nginx 后生产连接数 5→5 不变、生产与测试 ERROR 均为 0（改造前必产生 4 条）
- AGENTS.md 明确：nginx stream 转发只为本地开发，服务侧一律直连
|
2026-09-20 03:40:51 +08:00 |
|
12451
|
a904f5ff11
|
docs: 修正 AGENTS.md 限流描述的事实错误 + 补全限流 location/zone 清单
- scan_abstract_zone 只挂在 location /api/pms/cabinets/abstract/（前缀匹配不命中 scan/）；
/api/cabinets/scan/{id} 需登录、无 token 恒 401、不构成枚举信号，无需限流
（实测：scan 60 连发 = 401x60/429x0；abstract 同法 = 404x23/429x37）
- Nginx配置节的限流清单补上 abstract location 与第 4 个 zone scan_abstract_zone
- 新增经验：写"某 zone 覆盖某某路径"必须按 location 前缀语义核对并附实测 429 清单，
不要按 zone 名字推断（scan_abstract_zone 这名字极易误导）
|
2026-09-20 03:24:34 +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
|
4e752953b0
|
chore: 清理误入库的临时产物（.tmp-* 代理工作目录、部署脚本输出）并加入 .gitignore
|
2026-09-20 02:45:08 +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
|
6b562ae286
|
chore(web): 修复失效的类型检查命令（tsconfig 是 solution 文件， sc --noEmit 空跑=假绿）→ 新增 typecheck 脚本用 tsc -b；并收尾前端契约修复（路由守卫/分页/查询竞态/类型补全）
|
2026-09-20 00:44:35 +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
|
9829e9dcb1
|
chore(h5): 移除项目内 vendored 技能库及锁文件
删除 software/h5-uniapp/.agents/skills 与 software/h5-uniapp/agent/skills（各 629 文件，来源 uni-helper/skills 的 Vue/uni-app 技能包），并删除 skills-lock.json。两份技能库内容除 9 个 SKILL.md 的前置元数据格式外完全重复，属仓库内冗余副本；开发期技能改由全局技能目录加载。
|
2026-09-14 13:33:37 +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
|
c598400a28
|
fix: H5 API 路径去除重复 /h5/ 前缀
|
2026-07-03 04:52:47 +08:00 |
|
12451
|
2b8fd10619
|
docs: 更新文档 - H5 技术栈改为 uni-app，添加 tar.gz 部署规则
|
2026-07-03 04:50:01 +08:00 |
|
12451
|
e90da20e82
|
feat: H5 用户端 uni-app 重写（替换 Taro）
- 使用 uni-app + Vue 3 + Composition API 重写 H5 用户端
- 6 个页面：登录、首页、设备列表、设备详情、仓体详情、个人中心
- Pinia 状态管理 + API 层封装
- TabBar 导航（首页/设备/我的）
- 已构建并部署到服务器 /data/pms/h5/
- 登录页渲染正常，布局完整
|
2026-07-03 04:10:46 +08:00 |
|
12451
|
6b97cd78ad
|
fix: H5 白屏 - index.html 预加载脚本添加根路径默认路由到登录页
|
2026-07-03 03:01:29 +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
|
8a2e2ffc2b
|
fix: 修复树节点点击选择逻辑，支持多级组织
|
2026-07-02 21:38:50 +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
|
c2c70be3b3
|
feat: 卡片添加地址字段，中文名字，优化布局
|
2026-07-02 20:37:24 +08:00 |
|
12451
|
da9296a407
|
fix: 简化右列布局，使用flex column
|
2026-07-02 20:00:57 +08:00 |
|
12451
|
0de202d87c
|
fix: 添加width:100%确保右列正确填充
|
2026-07-02 19:58:43 +08:00 |
|
12451
|
5515cad8f8
|
fix: 修复右列横向滚动问题，设置minWidth:0和overflow
|
2026-07-02 19:50:29 +08:00 |
|
12451
|
42dd54a255
|
fix: 删除CabinetGrid重复的设备列表标题
|
2026-07-02 19:48:06 +08:00 |
|
12451
|
52e392f831
|
feat: 添加数据库工具tools/db.py，更新AGENTS.md
|
2026-07-02 19:44:23 +08:00 |
|