charging-cabinet/deploy/pms-api-prod.service

[Unit]
Description=PMS API Server - Production
After=network.target

[Service]
Type=simple
# 降权运行（2026-09 安全加固）：仅需读 .env（systemd 以 root 读取 EnvironmentFile）、
# 可写 ./uploads 与 ./exports（两者已 chown pms:pms），9000 端口 >1024 无需特权
User=pms
Group=pms
WorkingDirectory=/data/pms/api-server
ExecStart=/data/pms/api-server/pms-api
EnvironmentFile=/data/pms/api-server/.env
Restart=always
RestartSec=5
# 提高文件描述符上限：默认软限制 1024 在大规模设备接入时会先耗尽
LimitNOFILE=65535

[Install]
WantedBy=multi-user.target
-												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
+								[Unit]
 								Description=PMS API Server - Production
 								After=network.target
 								[Service]
 								Type=simple
-												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
+								# 降权运行（2026-09 安全加固）：仅需读 .env（systemd 以 root 读取 EnvironmentFile）、
 								# 可写 ./uploads 与 ./exports（两者已 chown pms:pms），9000 端口 >1024 无需特权
 								User=pms
 								Group=pms
-												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
+								WorkingDirectory=/data/pms/api-server
-												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:40:46 +08:00
+								ExecStart=/data/pms/api-server/pms-api
-												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
+								EnvironmentFile=/data/pms/api-server/.env
 								Restart=always
 								RestartSec=5
-												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
+								# 提高文件描述符上限：默认软限制 1024 在大规模设备接入时会先耗尽
 								LimitNOFILE=65535
-												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
 								[Install]
 								WantedBy=multi-user.target