# AGENTS.md - 充电柜项目工作手册

## 项目简介

充电柜矩阵系统（Power Matrix System / PMS）
产品名：安知充（anzhizhichong），已有充电站平台在运行，充电柜是新增产品线。
仓数不固定：1柜控板+N仓控板，每仓控板管6仓，最小6仓。

## 设备标识

- **平台抽象ID**：`10-00000000`（绑定柜控板，二维码对应此ID）
- **设备ID**：4G SIM卡15位IMEI（10进制）
- **仓体全局ID**：`平台层ID-仓板ID-仓体ID`
- **扫码链接**：`https://app.anzhizhichong.com/h5/{抽象ID}`

## 技术栈

- 后端：Rust + Axum
- 前端：React + Arco Design Pro（React版）
- H5用户端：uni-app + Vue 3 + Pinia（跨平台，支持 H5 / 微信小程序）
- 数据库：MySQL（阿里云RDS），开发/生产共用
- 缓存：Redis（阿里云Redis），开发/生产共用
- 设备通讯：TCP长连接（柜控板4G模块，Air780E Cat.1）
- 权限：RBAC，精确到按钮级别（权限码如 device:door:unlock）

## 项目结构

```
D:\charging-cabinet\
├── tasks/              # 任务文件（opencode执行）
├── docs/               # 开发文档、协议文档
├── deploy/             # 部署配置文件
│   ├── nginx/          # Nginx配置
│   ├── *.service       # systemd服务单元
│   └── deploy-*.sh     # 部署脚本
├── tools/              # 开发工具
│   └── db.py           # 数据库工具
├── software/
│   ├── api-server/     # Rust API服务
│   ├── device-server/  # Rust TCP设备服务
│   ├── h5-uniapp/      # H5用户端（uni-app + Vue 3）
│   └── web/            # React前端（WEB管理端）
├── hardware/           # 硬件资料（原理图/PCB等）
└── test/               # 测试用例/报告
```

## 部署架构

### 环境规划

| 环境 | 域名 | API服务 | TCP服务 | Redis DB | 部署路径 | URL路径 |
|------|------|---------|---------|----------|----------|---------|
| 正式环境 | app.anzhizhichong.com | :9000 | :9001 | db5 | /data/pms | /pms/ |
| 测试环境 | test.anzhizhichong.com | :3000 | :3001 | db6 | /data/pms_dev | /pms/ |

**服务端口分配：**
- 测试环境：API 3000，TCP 3001
- 正式环境：API 9000，TCP 9001

**部署路径：**
- 产品介绍页：/data/landing
- 正式环境：/data/pms（api-server、device-server、web、h5）
- 测试环境：/data/pms_dev（api-server、device-server、web、h5）

**Nginx配置：**
- 正式: /etc/nginx/conf.d/app.anzhizhichong.com.conf
- 测试: /etc/nginx/conf.d/test.anzhizhichong.com.conf

### 服务器信息

- **外网IP**: 118.31.119.206
- **内网IP**: 172.25.42.239
- **系统**: CentOS Stream 9（2核/3.5G/49G）
- **ZeroTier**: 网络ID `63e843dd42f54b9c`，服务器节点 `12a91dd47d`，IP `10.8.0.252`
- **本地电脑ZeroTier IP**: `10.8.0.248`
- **已装软件**: Nginx 1.20.1、ZeroTier 1.16.2、socat（开机自启）
- **服务**: mysql-proxy(3306→RDS)、redis-proxy(6379→Redis)、Gitea(3080)、acme.sh
- **不装**: Docker/Node/Rust（本地编译传二进制）
- **SSH**: plink连接，首次需 `echo y` 接受host key

### 正式环境数据库

- MySQL: `rm-bp1bb7yiv5n8z4uvp.mysql.rds.aliyuncs.com`，user: root，password: Hbhyg731024，database: `pms`
- Redis: `r-bp1lsezvgzmgtwhbtg.redis.rds.aliyuncs.com`，password: Hbhyg731024，db: 5

### 本地开发环境

**数据库连接（通过ZeroTier）：**
```
MySQL: 10.8.0.252:3306
  user: root
  password: Hbhyg731024@
  database: pms_dev (新建，不动AZZCWeChat*)

Redis: 10.8.0.252:6379
  password: Hbhyg731024@
  db: 6 (测试环境用db6，不动db1-5)
```

**代理说明：**
- 服务器nginx stream转发MySQL(3306)和Redis(6379)到阿里云RDS
- systemd自启，`Restart=always` 自动恢复
- 本地直连 `10.8.0.252`，无需SSH隧道

### 数据库工具

本地可直接访问数据库（通过ZeroTier），使用 `tools/db.py`：

```bash
# 列出所有表
python tools/db.py tables

# 统计各表数据量
python tools/db.py count

# 执行查询
python tools/db.py query "SELECT * FROM users"

# 执行写入
python tools/db.py exec "UPDATE users SET status=1 WHERE id=1"

# 导入SQL文件
python tools/db.py import data.sql
```

### 证书

- 阿里云免费SSL证书（acme.sh自动续期）
- 存放路径: `/etc/nginx/ssl/{域名}.pem` + `/etc/nginx/ssl/{域名}.key`
- 已配置: app.anzhizhichong.com、test.anzhizhichong.com

### 内部服务

- **Gitea**: `https://app.anzhizhichong.com/doc/` (端口3080)
  - 组织: anzhizhichong
  - 仓库: charging-cabinet
  - 用户: admin / skyp76

## 开发约束

### 禁止操作

- **禁止在服务器上编译Rust** — 2核/3.5G会OOM，本地编译传二进制
- **禁止使用socat fork模式** — 进程泄漏会耗尽内存，用nginx stream代理

### 编码规范

- 任务需求写到 `tasks/` 目录的md文件
- 通过Agent子代理包裹opencode执行，异步通知
- 任务要拆的尽量细
- 质量约束模板固定追加到每个任务文件
- opencode超时必须报告用户，不能fallback手动执行
- 审查用不同模型（不用开发同款）

### 编码任务下发

- 任务需求写到 `tasks/` 目录的md文件
- 通过Agent子代理包裹opencode执行，异步通知
- 质量约束模板固定追加到每个任务文件

### 质量约束模板

所有编码任务必须追加以下约束：

1. 完成代码后执行对应栈静态校验（Rust→cargo check，TS→tsc --noEmit），零报错零警告
2. 分层拆分，单函数≤80行，命名语义化，完整注释
3. 所有外部IO/网络请求异常捕获，禁止裸panic
4. 分支逻辑全覆盖，不遗漏兜底分支
5. 常量抽离，不使用废弃API
6. Rust：内存安全，合理管理所有权，禁用unsafe无合理理由
7. React：函数式组件+Hooks，不写Class组件

### 验收流程

1. 静态校验命令通过
2. 跑起来看效果
3. 抽查关键逻辑（异常处理、权限校验、协议解析）

## 部署与维护

### SSH连接

```bash
# 外网IP（推荐）
echo y | plink -ssh root@118.31.119.206 -pw "Hbhyg731024@"

# ZeroTier内网IP
echo y | plink -ssh root@10.8.0.252 -pw "Hbhyg731024@"
```

### 数据库连接

```bash
# MySQL（通过ZeroTier代理）
mysql -h 10.8.0.252 -u root -p
# 密码：Hbhyg731024@
# 测试环境库：pms_dev
# 正式环境库：pms

# Redis（通过ZeroTier代理）
redis-cli -h 10.8.0.252 -a "Hbhyg731024@"
# 测试环境：db6
# 正式环境：db5
```

### Nginx配置

**正式环境** (`/etc/nginx/conf.d/app.anzhizhichong.com.conf`):
```nginx
server {
    listen 80;
    server_name app.anzhizhichong.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name app.anzhizhichong.com;

    ssl_certificate /etc/nginx/ssl/app.anzhizhichong.com.pem;
    ssl_certificate_key /etc/nginx/ssl/app.anzhizhichong.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    # 产品介绍页
    root /data/landing;
    index index.html;

    location /doc/ {
        proxy_pass http://127.0.0.1:3080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        client_max_body_size 500m;
    }

    location /pms/api/ {
        proxy_pass http://127.0.0.1:9000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # PMS管理前端 - 不带斜杠时重定向
    location = /pms {
        return 301 /pms/;
    }

    # PMS管理前端
    location /pms/ {
        alias /data/pms/web/;
        try_files $uri $uri/ /pms/index.html;
    }

    # H5用户端 - 不带斜杠时重定向
    location = /h5 {
        return 301 /h5/;
    }

    # H5用户端
    location /h5/ {
        alias /data/pms/h5/;
        try_files $uri $uri/ /h5/index.html;
    }
}
```

**测试环境** (`/etc/nginx/conf.d/test.anzhizhichong.com.conf`):
```nginx
server {
    listen 80;
    server_name test.anzhizhichong.com;
    return 301 https://$server_name$request_uri;
}

server {
    listen 443 ssl http2;
    server_name test.anzhizhichong.com;

    ssl_certificate /etc/nginx/ssl/test.anzhizhichong.com.pem;
    ssl_certificate_key /etc/nginx/ssl/test.anzhizhichong.com.key;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    root /data/pms_dev;
    index index.html;

    location /pms/api/ {
        proxy_pass http://127.0.0.1:3000/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /pms/ {
        try_files $uri $uri/ /pms/index.html;
    }

    # H5用户端
    location /h5/ {
        alias /data/pms_dev/h5/;
        try_files $uri $uri/ /h5/index.html;
    }
}
```

> 测试环境SSL证书与正式环境共用（test是app证书的SAN域名），部署时复制pem+key即可。

### 部署步骤

**1. 本地编译**
```bash
# 后端（Rust）
cd software/api-server
cargo build --release

cd software/device-server
cargo build --release

# 前端（React）
cd software/web
npm run build
```

**2. 传输到服务器**
```bash
# 传输后端二进制（测试环境）
scp software/api-server/target/release/api-server root@118.31.119.206:/data/pms_dev/api-server/
scp software/device-server/target/release/device-server root@118.31.119.206:/data/pms_dev/device-server/

# 传输后端二进制（正式环境）
scp software/api-server/target/release/api-server root@118.31.119.206:/data/pms/api-server/
scp software/device-server/target/release/device-server root@118.31.119.206:/data/pms/device-server/

# 传输前端静态文件
scp -r software/web/dist/* root@118.31.119.206:/data/pms_dev/web/  # 测试环境
scp -r software/web/dist/* root@118.31.119.206:/data/pms/web/  # 正式环境

# 传输H5用户端（tar.gz打包方式，保留UTF-8编码）
cd software/h5-uniapp/dist/build/h5
tar -czf /tmp/h5-build.tar.gz .
pscp -pw "Hbhyg731024@" /tmp/h5-build.tar.gz root@118.31.119.206:/tmp/
plink -ssh -pw "Hbhyg731024@" root@118.31.119.206 "rm -rf /data/pms/h5/* && cd /data/pms/h5 && tar -xzf /tmp/h5-build.tar.gz"
```

> ⚠️ H5部署必须用tar.gz打包方式，不要用plink/pscp管道传单文件（会丢失UTF-8编码导致中文变问号）。

**3. 服务器重启服务**
```bash
# SSH到服务器
echo y | plink -ssh root@118.31.119.206 -pw "Hbhyg731024@"

# 重启测试环境
systemctl restart pms-api-test
systemctl restart pms-device-test

# 重启正式环境
systemctl restart pms-api-prod
systemctl restart pms-device-prod

# 重启Nginx
systemctl restart nginx
```

### 服务管理

```bash
# 查看服务状态
systemctl status pms-api-test   # 测试环境API
systemctl status pms-api-prod   # 正式环境API
systemctl status nginx

# 查看日志
journalctl -u pms-api-test -f
journalctl -u pms-api-prod -f
tail -f /var/log/nginx/error.log
```

## 硬件架构

- 柜控板(ID128)×1 + 仓控板(ID1-N)×N，每仓控板管6个仓体
- 仓控板与电源：1TN RS485协议（翌工）
- 仓控板与BMS：星恒Modbus / 天能485 / 无协议（平台可配置）
- 仓控板与柜控板：自定义485协议（14+功能码）
- 柜控板与后台：4G TCP长连接（Air780E模块）

## 开发范围（当前阶段）

### 做

- 后台管理系统（Web端）
- 用户端H5页面（`/pms/{id}`，微信扫码可访问）
- 设备TCP通讯服务（协议文档已就绪）

### 不做

- 微信小程序（名额暂不可用，先用H5，uni-app可后续转换）
- 支付/计费（本系统不涉及）

## 组织架构

```
组织(企业) → 项目(放置地点) → 设备(充电柜)
```

设备卖给哪个企业就划拨给该组织，设备放置的具体地点称为项目，设备必须划拨到项目下。

## 数据模型

### 核心关系

```
organization(组织/企业)
├── project(项目/放置地点)
│   └── cabinet(充电柜)
│       ├── cabin_board(仓控板×N)
│       │   └── compartment(仓体×6)
│       ├── charge_record(充电记录)
│       └── energy_stat(能耗统计)
├── user(用户)
└── device_log(设备日志)

operation_log(操作日志)
```

### 数据库表

| 表名 | 说明 |
|------|------|
| organizations | 组织表 |
| projects | 项目表 |
| cabinets | 充电柜表（IMEI、abstract_id、auth_str） |
| cabin_boards | 仓控板表 |
| compartments | 仓体表 |
| users | 用户表（手机号登录） |
| charge_records | 充电记录表 |
| device_logs | 设备日志表 |
| energy_stats | 能耗统计表 |
| operation_logs | 操作日志表 |

### Redis 实时状态存储

设备实时状态通过 Redis Hash 层级存储，按 `status_post` 上报内容解析写入。

**层级结构：**

```
device:{imei}                              # 设备级 Hash
├─ online = "1"                            # 在线标记（TTL 300秒）
├─ rssi = "85"                             # 信号强度
├─ pow_fail_dc = "0/1"                     # 直流停电（12V掉电）
├─ pow_fail_ac = "0/1"                     # 交流停电（380V掉电）
└─ device:{imei}:board:{board_idx}         # 板级 Hash（仓控板1~N）
   ├─ status_hex = "000100020003000400050006"  # 原始hex状态
   └─ device:{imei}:board:{board_idx}:ch:{0-5}  # 通道级 Hash（6仓）
      ├─ on = "0/1"                        # 充电中
      ├─ full = "0/1"                      # 充满
      ├─ fault = "0/1"                     # 故障
      └─ hex = "00010002"                  # 原始hex
```

**写入时机：**
| 事件 | 写入位置 | 说明 |
|------|----------|------|
| `login` | `device:{imei}.online` | 标记在线，设置TTL 300秒 |
| `status_post` | `device:{imei}` + board + ch | 解析status字典，按层级写入 |
| `pow_fail` | `device:{imei}.pow_fail_dc/ac` | 更新停电状态 |

**通道状态映射（hex → 语义）：**
- 空闲（idle）
- 插入（inserted）
- 充电中（charging）
- 充满（full）
- 故障（fault）

> ⚠️ hex编码格式待硬件团队最终确认，当前实现预留状态字段，按 bit 位解析。

**API 接口：**
| 接口 | 说明 | 查询方式 |
|------|------|----------|
| `GET /api/cabinets/filter` | 设备列表（设备级状态） | Pipeline 批量 HGET，1次往返 |
| `GET /api/cabinets/realtime-status?imei=xxx` | 单设备详情（板级+通道级） | KEYS 扫描 + HMGET |

## TCP通讯协议

- 长连接，无需PING包
- 空闲1分钟上报，充电15秒上报
- 超时5000ms
- JSON去空格回车省流量，LF处理粘包
- `dev_id`：IMEI（10进制），`sub_device_id`：485 ID
- `msg_id`：自增会话ID
- 全局通道号：`dev_id-sub_device_id-通道号`（如`123456789012345-01-6`）

### 签名机制

- 设备首次连接调 `auth_str` 接口获取8位安全码（仅一次）
- `sign = SHA256(dev_id + auth_str + timestamp).substring(56, 63)`
- 时间戳秒级，平台校验±60秒

### 指令清单

| 动作 | 方向 | id格式 | 说明 |
|------|------|--------|------|
| `login` | 设备→平台 | 无 | 登录（含sign+timestamp） |
| `auth_str` | 设备→平台 | 无 | 获取安全码（仅首次） |
| `status_post` | 设备→平台 | 无 | 定时上报（rssi+status字典） |
| `pow_fail` | 设备→平台 | 无 | 12V电源掉电上报 |
| `bat_in` | 设备→平台 | `IMEI-仓控板-通道` | 电池插入（含BMS数据，字段待定） |
| `bat_out` | 设备→平台 | `IMEI-仓控板-通道` | 电池拔出 |
| `on` | **双向** | `IMEI-仓控板-通道` | 开始充电（平台下发/设备上报） |
| `off` | **双向** | `IMEI-仓控板-通道` | 停止供电（平台手动/设备自动） |
| `open` | 平台→设备 | `IMEI` | 开门 |
| `pow_on` | 平台→设备 | `IMEI` | 接触器合闸（恢复380V供电） |
| `pow_off` | 平台→设备 | `IMEI` | 接触器分闸（切断380V供电） |
| `reset` | 平台→设备 | `IMEI` 或 `IMEI-仓控板` | 重启整柜或仓控板 |

### 指令详情

#### login（设备→平台）

设备登录，验证签名。

```json
// 请求
{"act":"login","msg_id":1,"dev_id":"123456789012345","sign":"abc12345","timestamp":1719800000,"h_ver":"1.0.0","s_ver":"1.0.0"}

// 响应
{"suc":1,"msg_id":1,"cell":6}
```

**字段说明：**
- `sign` — 签名（SHA256(dev_id+auth_str+timestamp)后8位）
- `timestamp` — 秒级时间戳（平台校验±60秒）
- `h_ver` — 硬件版本
- `s_ver` — 软件版本
- `cell` — 仓控板数量（响应）

---

#### auth_str（设备→平台）

获取8位安全码，仅首次连接调用。

```json
// 请求
{"act":"auth_str","msg_id":2,"dev_id":"123456789012345","ccid":"89860000000000000000"}

// 响应
{"suc":1,"msg_id":2,"data":{"auth_str":"abcd1234"}}
```

**字段说明：**
- `ccid` — SIM卡ICCID号
- `auth_str` — 8位随机安全码（响应，仅返回一次）

---

#### status_post（设备→平台）

定时上报，空闲60秒/充电15秒。

```json
// 请求
{"act":"status_post","msg_id":10,"dev_id":"123456789012345","rssi":85,"status":{"123456789012345-01":"000100020003000400050006"}}

// 响应
{"suc":1,"msg_id":10}
```

**status字段说明：**
- key: `IMEI-仓控板ID`
- value: 6个通道状态拼接（每通道2字节=4个HEX字符）

---

#### pow_fail（设备→平台）

电源掉电上报。

```json
// 请求
{"act":"pow_fail","msg_id":15,"dev_id":"123456789012345","info":"0"}

// 响应
{"suc":1,"msg_id":15}
```

**字段说明：**
- `info` — 停电类型：`0`=直流停电(12V掉电)，`1`=交流停电(380V掉电)

---

#### pow_on（平台→设备）

接触器合闸，恢复380V充电电源供电。

```json
// 请求
{"act":"pow_on","msg_id":16,"dev_id":"123456789012345"}

// 响应
{"suc":1,"msg_id":16}
```

---

#### pow_off（平台→设备）

接触器分闸，切断380V充电电源供电。

```json
// 请求
{"act":"pow_off","msg_id":16,"dev_id":"123456789012345"}

// 响应
{"suc":1,"msg_id":16}
```

---

#### bat_in（设备→平台）

电池插入事件，立即上报。

```json
// 请求
{"act":"bat_in","msg_id":20,"id":"123456789012345-01-6","bms":{"soc":45,"voltage":52.3}}

// 响应
{"suc":1,"msg_id":20}
```

**平台处理：**
1. 记录电池信息
2. 验证电池合规性
3. 自动下发 `on` 指令

---

#### bat_out（设备→平台）

电池拔出事件，立即上报。

```json
// 请求
{"act":"bat_out","msg_id":21,"id":"123456789012345-01-6"}

// 响应
{"suc":1,"msg_id":21}
```

---

#### on（双向）

**平台→设备：** 开始充电

```json
// 请求
{"act":"on","msg_id":30,"id":"123456789012345-01-6"}

// 响应
{"suc":1,"msg_id":30}
```

**设备→平台：** 充电开始确认（自动充电模式）

```json
// 上报
{"act":"on","msg_id":30,"id":"123456789012345-01-6"}
```

---

#### off（双向）

**平台→设备：** 手动停止充电

```json
// 请求
{"act":"off","msg_id":31,"id":"123456789012345-01-6"}

// 响应
{"suc":1,"msg_id":31}
```

**设备→平台：** 充满自动停止

```json
// 上报
{"act":"off","msg_id":31,"id":"123456789012345-01-6"}
```

---

#### open（平台→设备）

开门，只需IMEI。

```json
// 请求
{"act":"open","msg_id":40,"id":"123456789012345"}

// 响应
{"suc":1,"msg_id":40}
```

**错误码63 = 门锁故障。**

---

#### reset（平台→设备）

重启整柜或仓控板。

```json
// 重启整柜
{"act":"reset","msg_id":60,"id":"123456789012345"}

// 重启仓控板
{"act":"reset","msg_id":61,"id":"123456789012345-01"}

// 响应
{"suc":1,"msg_id":60}
```

### 充电结束原因（平台判断）

| 平台收到 | 判断原因 |
|---------|---------|
| `off` (设备→平台) | `normal` — 正常充满 |
| `off` (平台→设备) | `user_stop` — 用户手动停止 |
| `bat_out` | `normal` — 电池拔出 |
| `bat_in` (通道已有电池) | `forced` — 新电池插入，旧电池强制结束 |
| 超时未响应 | `timeout` — 通信超时 |

## H5用户端

- 路径：`/pms/{抽象ID}`
- 功能：显示柜子每个通道状态，可开始/停止充电
- 无支付/计费功能