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

5 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
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
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
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