8025cd831c
## 1. users.name 不再允许 NULL（用户要求） **数据库层加闸**：`name VARCHAR(50) COMMENT '姓名'` → `name VARCHAR(50) NOT NULL DEFAULT '' COMMENT '姓名（选填，为空串表示未填写；⛔ 不允许 NULL）'` 同步三处（AGENTS.md 硬约束）： - `SCHEMA_SQL` 建表语句； - `LEGACY_COLUMN_TARGETS` 加 `("users", "name", "VARCHAR(50) NOT NULL DEFAULT ''")` （老库靠它对齐，`CREATE TABLE IF NOT EXISTS` 不改已存在的表）； - Rust `UserRow.name` / `load_user_for_update` / `persist_user_update` / `log_user_update` 全部 `Option<String>` → `String`； 创建用户时 `input.name.unwrap_or_default().trim()`，**不再可能插 NULL**。 前端 `User.name` 类型同步改为 `string`（空串 = 未填写，界面 `v || '-'` 照常）。 ### 实测（库层） ``` users.name: varchar(50) nullable=NO default='' OK 插空串姓名 → name='' OK 插 NULL → 1048 Column 'name' cannot be null OK（被拒） ``` ## 2. 顺带修掉两个**迁移非幂等**的解析 bug（都是这次上线才暴露的） `ensure_column_type` 的定位是"只有与目标不一致才 ALTER"，但两个归一化缺失让 `users.name` **每次重启都重发一遍 ALTER**（白搭 DDL，大表上还可能触发重建）： | # | 症状 | 根因 | 修法 | |---|---|---|---| | 1 | 日志 `default '' -> ''''` 永远不相等 | `target_default_value` 原样返回带引号的 `''`，而 `information_schema.COLUMN_DEFAULT` 返回**去引用后**的空串 | `.trim_matches('\'')` | | 2 | 日志 `type varchar -> VARCHAR(50)` 永远不相等 | `target_data_type` 返回 `VARCHAR(50)`，而 `information_schema.DATA_TYPE` 只报**裸类型名** `varchar`（长度在 `COLUMN_TYPE`） | 去掉 `(...)` 后缀 | `users.name` 是对齐清单里**第一条带括号长度**的类型，之前的条目都是单词型 （`BIGINT`/`DATETIME`/`TINYINT`），所以这两个 bug 一直没暴露。 ### 幂等已验证 ``` 测试环境：连续重启两次，ALTER users.name 次数 = 0，迁移完成日志 6 条，ERROR 0 生产环境：重启一次， ALTER users.name 次数 = 0，ERROR 0 ``` ## 3. 守门 - `resolve_new_name` 三态单测（未传保持 / 传空清空 / 传非空去空白）—— 已自证能失败； - `target_default_value` 去引号单测 —— 已自证能失败； - `target_data_type` 去括号单测 —— 已自证能失败； - SQL 快照守卫**有意更新**（新增 `users.name` 两条片段）—— 已自证能失败。 ⚠️ 守卫报警是**对的**：我确实改了 SQL，所以显式更新快照，而不是放宽守卫。 ## 4. 数据修复（本次 bug 的实际损害） "表格内分配组织"只传 `organization_id`，命中姓名三态 bug，把生产 **李四 / 王五** 的姓名抹成 NULL。已按用户此前截图还原（`李四`/`王五`）， 组织分配结果保留（org=2）。 ## 验收 - `cargo check --all-targets` 两服务：**0 error / 0 warning** - `cargo test --bin pms-api`：**214 passed** - 已发布测试 + 生产；生产重启后 0 ERROR、迁移幂等、域名 401/200
充电柜矩阵系统 (Power Matrix System / PMS)
产品名：安知充（anzhizhichong），品牌名：艾动智能
项目简介
36仓体直流电瓶车充电柜，仓数不固定：1柜控板+N仓控板，每仓控板管6仓，最小6仓。
技术栈
- 后端：Rust + Axum
- 前端：React + Arco Design Pro（管理端）
- 微信小程序用户端：uni-app + Vue 3（构建目标 mp-weixin）
- 数据库：MySQL（阿里云RDS）
- 缓存：Redis（阿里云Redis）
- 设备通讯：TCP长连接（柜控板4G模块，Air780E Cat.1）
项目结构
charging-cabinet/
├── tasks/ # 任务文件（opencode执行）
├── docs/ # 开发文档、协议文档（API.md、柜控板固件对接文档.md …）
├── deploy/ # 部署配置与脚本
│ ├── nginx/ # Nginx 配置镜像（nginx.conf 主配置 + app / test，共三份，与线上逐字节一致）
│ ├── *.service # systemd 单元（pms-api / pms-device × prod·test）
│ ├── deploy-prod.ps1 # 正式环境一键部署（推荐入口）
│ └── deploy-*.sh # ⛔ 已废弃（执行即报错退出）
├── tools/ # 开发工具
│ ├── db.py # 数据库工具（默认连测试库 pms_dev；需先起 SSH 隧道）
│ ├── dev-tunnel.ps1 # 开发机 SSH 隧道（127.0.0.1:13306/16379 → 阿里云 RDS/Redis）
│ └── db_schema_diff.py # 结构漂移巡检（测试库 vs 生产库 / vs 代码权威 DDL）
├── software/
│ ├── api-server/ # Rust API服务（产物 pms-api）
│ ├── device-server/ # Rust TCP设备服务（产物 pms-device-server）
│ ├── web/ # React管理端前端
│ └── h5-uniapp/ # 微信小程序用户端（uni-app + Vue 3，构建目标 mp-weixin）
├── hardware/ # 硬件资料（原理图/PCB等）
└── test/ # 测试/验收脚本
├── tcp_e2e_smoke.py # TCP 协议端到端（模拟柜控板打测试环境 :3001）
├── schema_alignment_e2e.py # 结构对齐端到端（造临时行并自动清理）
├── device_status_parse.test.mjs # PC 与小程序状态位解析一致性
├── rssi_signal.test.mjs # PC 与小程序 RSSI 分档一致性（0–99 逐值）
└── security-hardening/ # 安全加固探针脚本
本仓库不存放技能库（skills）。开发期技能从全局技能目录加载（
~/.dsh/skills、~/.agents/skills），请勿在仓库内重新 vendor。
部署架构
| 环境 | 域名 | API 服务 | TCP 服务 | MySQL | Redis DB | 部署路径 | 前端路径 |
|---|---|---|---|---|---|---|---|
| 正式环境 | app.anzhizhichong.com | :9000 |
:9001 |
pms |
db5 | /data/pms |
/pms/ |
| 测试环境 | test.anzhizhichong.com | :3000 |
:3001 |
pms_dev |
db6 | /data/pms_dev |
/pms/ |
⚠️ 两个环境完全隔离（独立库 + 独立 Redis DB + 独立端口 + 独立部署目录）。 ⛔ 绝不要把测试域名的 API 指向生产端口
:9000—— 历史事故：测试 nginx 曾指向当时的生产端口， 等于"测试后台在操作生产数据"。判断方法：test域名/api/pms/返回 401（有测试后端）是对的； 返回 502 说明测试后端没起。 ⚠️ 代码里的默认端口（api3000/ tcp3002）只在没设环境变量时生效，线上由.env的PORT/TCP_PORT覆盖 —— 以本表为准。
服务器：CentOS Stream 9（2核/3.5G/49G），118.31.119.206（ZeroTier 10.8.0.252）
内部服务：
- Gitea: https://app.anzhizhichong.com/doc/
- 文档Wiki: https://app.anzhizhichong.com/doc/anzhizhichong/charging-cabinet/wiki/
部署方式：本地交叉编译（cargo zigbuild --release --target x86_64-unknown-linux-gnu）后传二进制，
服务器上不装 Rust/Node（会 OOM）。一键脚本与「部署注意事项」见 AGENTS.md「部署与维护」。
服务架构
┌─────────────────────────────────────────────────────────────┐
│ API服务 (api-server / pms-api) — 主服务 │
│ - HTTP API（后台管理 + 小程序）端口: 正式 9000 / 测试 3000 │
│ - 业务逻辑处理（验签/存DB/建单结单/告警/能耗） │
│ - 节点管理（设备服务注册/心跳） │
│ - 后台 Worker：上报消费(RPOP 200ms 轮询) / 回执 / 订单超时 / │
│ 日志清理 / 占用对账 │
└─────────────────────────────────────────────────────────────┘
↑ Redis LIST device:reports ↑ Redis LIST device:commands
│ (设备上报，device-server LPUSH) │ (平台指令，api-server LPUSH)
│ │ device-server 按 HGET device:{imei} node_id
│ │ 路由到 device:commands:{node_id}
┌─────────────────────────────────────────────────────────────┐
│ 设备服务 (device-server / pms-device-server) — 轻量化 │
│ - TCP监听: 正式 9001 / 测试 3001（设备长连接） │
│ - 只处理通信和指令解析（归属/签名/业务全在 api-server） │
│ - 不存DB、不验证签名、不处理业务 │
│ - 节点注册/心跳：Redis `node:{node_id}`（含 ip/tcp_port/ │
│ status/last_heartbeat），TTL = DEVICE_REGISTER_TTL │
│ - 设备路由：`device:{imei}` 的 `node_id` 字段 │
└─────────────────────────────────────────────────────────────┘
核心设计原则：
- TCP服务轻量化 — 只处理TCP通信和指令解析，不处理业务逻辑
- Redis做缓冲 — 服务间通信用Redis LIST，不用HTTP直接调用
- 全异步处理 — 所有指令异步处理，msg_id匹配响应
- 协程处理任务 — API服务用tokio::spawn处理Redis队列消息
通信流程：
- 设备上报：设备 → TCP → 设备服务（
LPUSH device:reports，带LTRIM上限）→ API服务 worker 消费 - 平台指令：API服务（
LPUSH device:commands）→ 设备服务按node_id路由 → TCP → 设备 - 指令响应：设备 → TCP → 设备服务 → Redis LIST → API服务按
msg_id+act匹配回执 - 死信：投递失败的指令进
device:commands:dead
⚠️ 队列消费一律用
RPOP非阻塞轮询（200ms）+ 空队列sleep，禁止BRPOP—— Redis 走 nginx stream 代理 + 多路复用连接时BRPOP语义不可靠（BRPOP 0会永久卡死且无日志）； 该 stream 转发已于 2026-09-20 移除（服务侧现直连阿里云 Redis，开发机走tools/dev-tunnel.ps1隧道）， 但轮询约定不变。 依据：workers/report_worker.rs的REDIS_POLL_INTERVAL_MS注释。
节点管理：
- 设备服务启动时注册到 Redis
node:{node_id}（并调用 API 的注册接口） - 每 60 秒心跳（
HEARTBEAT_INTERVAL=60），180 秒无心跳视为离线（DEVICE_REGISTER_TTL=180， 线上.env显式设置；代码默认值是 300，仅在没有该环境变量时生效） - 支持多节点扩展（当前单节点
node-1）
TCP 设备通讯协议
TCP 设备通讯协议见 docs/protocol/柜控板固件对接文档.md（唯一权威，v1.1）。本文不再重复。 全局整数单位（voltage mV、current mA、temp K×100、soc ‰）见 docs/tech/API.md。 平台侧 Redis 实时状态的实际存储结构（key/字段/写入时机）见 AGENTS.md。
开发任务与质量约束
- 任务需求写到
tasks/目录的md文件（编号递增） - 通过 Agent 子代理包裹 opencode 执行，异步通知
- 质量约束模板固定追加到每个任务文件（模板见 AGENTS.md）
- 完成代码后执行对应栈静态校验：Rust →
cargo check，TS →npm run typecheck（即tsc -b），零报错零警告- ⛔ 不要写
tsc --noEmit：software/web/tsconfig.json是 solution 型（files: []+references）， 不带-b时它一个文件都不编译、直接 exit 0，是假绿。实测依据见 AGENTS.md 「踩过的坑」第 2 条
- ⛔ 不要写
验收与自检
# 后端：静态校验 + 单测
cd software/api-server && cargo check --all-targets && cargo test --bin pms-api
cd software/device-server && cargo check --all-targets && cargo test --bin pms-device-server
# 前端：真实类型检查
cd software/web && npm run typecheck
# 结构漂移巡检（改了表结构/迁移必跑）
python tools/db_schema_diff.py
python tools/db_schema_diff.py --vs-ddl
# 端到端
python test/tcp_e2e_smoke.py
python test/schema_alignment_e2e.py --env dev --jwt-secret <JWT_SECRET>
# 两端一致性（PC ↔ 小程序）
node test/device_status_parse.test.mjs
node test/rssi_signal.test.mjs
完整验收流程（含自证能失败的要求）见 AGENTS.md。