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

45 Commits

Author SHA1 Message Date
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
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
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
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
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
8d531b34a3 feat: 设备管理页改为左右两列布局 2026-07-02 19:26:23 +08:00
12451
1be7480472 feat: 组织架构树只显示到项目节点，不显示柜子 2026-07-02 19:18:47 +08:00
12451
04a3d31517 fix: 修复auth/me查询SQL，移除不必要的MAX聚合 2026-07-02 19:10:34 +08:00
12451
df44a959f5 fix: BrowserRouter添加basename=/pms，修复无限循环 2026-07-02 18:40:56 +08:00
12451
222ceb4d13 fix: 修复路由路径为相对路径，避免重定向到根目录 2026-07-02 18:34:39 +08:00
12451
9b5789fb75 refactor: H5和WEB前端分离，H5独立项目，扫码路径改为/h5/ 2026-07-02 18:23:13 +08:00
12451
ee330cd149 fix: API_BASE改为/pms/api，修复404问题 2026-07-02 18:10:34 +08:00
12451
d16a0fc545 feat: 重新设计登录页，深色科技风格 2026-07-02 17:56:18 +08:00
12451
b7546ec7d8 fix: 设置vite base为/pms/，修复资源路径问题 2026-07-02 17:53:58 +08:00
12451
c3eed024b6 feat: 柜子详情页添加接触器控制按钮(pow_on/pow_off) 2026-07-02 17:27:32 +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