admin/charging-cabinet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
96 Commits 1 Branch 0 Tags
Commit Graph

4 Commits

Author SHA1 Message Date
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
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
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