9.7 KiB

Raw Permalink Blame History

智能柜系统指南

概述

智能柜系统是本项目的重要功能模块，用于管理智能储物柜设备，支持企业微信集成、格口操作、状态监控等功能。

功能特性

✅ 智能柜设备管理
✅ 格口状态监控
✅ 企业微信集成（支持corpid）
✅ 格口操作（开锁、关锁、锁定）
✅ 使用记录管理
✅ 设备状态监控

数据库设计

智能柜表结构

smart_cabinet (智能柜表)

CREATE TABLE `smart_cabinet` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `cabinet_no` varchar(50) NOT NULL COMMENT '柜体编号',
  `name` varchar(100) NOT NULL COMMENT '柜体名称',
  `location` varchar(200) DEFAULT NULL COMMENT '安装位置',
  `status` tinyint DEFAULT '1' COMMENT '状态：1-正常 0-停用',
  `corpid` varchar(50) DEFAULT NULL COMMENT '企业微信id',
  `ip_address` varchar(50) DEFAULT NULL COMMENT 'IP地址',
  `port` int DEFAULT NULL COMMENT '端口',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  UNIQUE KEY `uk_cabinet_no` (`cabinet_no`)
);

cabinet_cell (柜体格口表)

CREATE TABLE `cabinet_cell` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `cabinet_id` bigint NOT NULL COMMENT '柜体ID',
  `cell_no` varchar(20) NOT NULL COMMENT '格口编号',
  `cell_type` varchar(20) DEFAULT 'SMALL' COMMENT '格口类型：SMALL-小格 LARGE-大格',
  `status` tinyint DEFAULT '1' COMMENT '状态：1-空闲 2-占用 3-故障',
  `current_order_id` bigint DEFAULT NULL COMMENT '当前订单ID',
  `lock_status` tinyint DEFAULT '0' COMMENT '锁状态：0-关闭 1-开启',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
  `update_time` datetime DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_cabinet_id` (`cabinet_id`),
  KEY `idx_cell_no` (`cell_no`)
);

cabinet_cell_operation (格口操作记录表)

CREATE TABLE `cabinet_cell_operation` (
  `id` bigint NOT NULL AUTO_INCREMENT,
  `cabinet_id` bigint NOT NULL COMMENT '柜体ID',
  `cell_id` bigint NOT NULL COMMENT '格口ID',
  `operation_type` varchar(20) NOT NULL COMMENT '操作类型：OPEN-开锁 CLOSE-关锁 LOCK-锁定',
  `operator_id` bigint DEFAULT NULL COMMENT '操作员ID',
  `operator_type` varchar(20) DEFAULT NULL COMMENT '操作员类型：USER-用户 ADMIN-管理员',
  `result` tinyint DEFAULT '1' COMMENT '操作结果：1-成功 0-失败',
  `error_msg` varchar(500) DEFAULT NULL COMMENT '错误信息',
  `create_time` datetime DEFAULT CURRENT_TIMESTAMP,
  PRIMARY KEY (`id`),
  KEY `idx_cabinet_cell` (`cabinet_id`, `cell_id`),
  KEY `idx_create_time` (`create_time`)
);

API接口

1. 柜体管理

1.1 获取柜体列表

GET /cabinet/list?pageNum=1&pageSize=10

响应:

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 5,
    "rows": [
      {
        "id": 1,
        "cabinetNo": "CAB001",
        "name": "一号智能柜",
        "location": "一楼大厅",
        "status": 1,
        "corpid": "ww1234567890abcdef",
        "ipAddress": "192.168.1.100",
        "port": 8080,
        "totalCells": 24,
        "freeCells": 18,
        "createTime": "2025-03-08 10:00:00"
      }
    ]
  }
}

1.2 新增柜体

POST /cabinet
Content-Type: application/json

{
  "cabinetNo": "CAB002",
  "name": "二号智能柜",
  "location": "二楼走廊",
  "corpid": "ww1234567890abcdef",
  "ipAddress": "192.168.1.101",
  "port": 8080
}

1.3 修改柜体

PUT /cabinet/{cabinetId}
Content-Type: application/json

{
  "name": "二号智能柜（更新）",
  "location": "二楼东侧走廊",
  "status": 1
}

2. 格口管理

2.1 获取格口列表

GET /cabinet/{cabinetId}/cells?pageNum=1&pageSize=20

响应:

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 24,
    "rows": [
      {
        "id": 1,
        "cellNo": "A01",
        "cellType": "SMALL",
        "status": 1,
        "lockStatus": 0,
        "currentOrderId": null,
        "createTime": "2025-03-08 10:00:00"
      }
    ]
  }
}

2.2 格口操作

POST /cabinet/cell/operate
Content-Type: application/json

{
  "cabinetId": 1,
  "cellId": 1,
  "operation": "open",
  "operatorId": 1001,
  "operatorType": "USER"
}

操作类型:

open: 开锁
close: 关锁
lock: 锁定

3. 操作记录

3.1 获取操作记录

GET /cabinet/operation/logs?cabinetId=1&cellId=1&pageNum=1&pageSize=10

企业微信集成

1. corpid字段说明

corpid字段用于关联企业微信应用，支持以下功能：

企业微信用户身份验证
企业微信消息推送
企业微信扫码开柜
企业微信审批流程

2. 企业微信扫码开柜

2.1 生成开柜二维码

GET /cabinet/{cabinetId}/qrcode

响应:

{
  "code": 200,
  "msg": "success",
  "data": {
    "qrcodeUrl": "https://qyapi.weixin.qq.com/cgi-bin/qrcode?ticket=xxx",
    "expireTime": "2025-03-08 11:00:00"
  }
}

2.2 企业微信回调处理

当用户扫描二维码后，企业微信会回调到配置的URL：

POST /qywx/cabinet/callback
Content-Type: application/xml

回调数据:

<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>1348831860</CreateTime>
  <MsgType><![CDATA[event]]></MsgType>
  <Event><![CDATA[SCAN]]></Event>
  <EventKey><![CDATA[CAB001_A01]]></EventKey>
  <Ticket><![CDATA[gQH47joAAAAAAAAAASxodHRwOi8vd2VpeGluLnFxLmNvbS9xL2taZ2Z3TVRtNzJXV1Brb3ZhYmJJAAIEZ23sUwMEmm3sUw==]]></Ticket>
</xml>

设备通信协议

1. TCP通信协议

智能柜设备通过TCP协议与系统通信：

1.1 开锁指令

指令格式: OPEN|{cabinetNo}|{cellNo}|{timestamp}|{sign}
示例: OPEN|CAB001|A01|1657794651|BDF0099C9FF443C4DC5C5D68C4B97C3F

1.2 关锁指令

指令格式: CLOSE|{cabinetNo}|{cellNo}|{timestamp}|{sign}

1.3 状态查询

指令格式: STATUS|{cabinetNo}|{timestamp}|{sign}

2. 签名算法

public class CabinetSignUtils {

    public static String generateSign(String cabinetNo, String cellNo, long timestamp, String secret) {
        String content = cabinetNo + "|" + cellNo + "|" + timestamp + "|" + secret;
        return DigestUtils.md5Hex(content).toUpperCase();
    }

    public static boolean verifySign(String cabinetNo, String cellNo, long timestamp, String sign, String secret) {
        String expectedSign = generateSign(cabinetNo, cellNo, timestamp, secret);
        return expectedSign.equals(sign);
    }
}

业务逻辑

1. 开柜流程

@Service
@RequiredArgsConstructor
public class CabinetService {

    private final CabinetDeviceClient deviceClient;
    private final CabinetCellOperationService operationService;

    @Transactional
    public void openCell(Long cabinetId, Long cellId, Long operatorId, String operatorType) {
        // 1. 验证柜体和格口状态
        CabinetCell cell = validateCellStatus(cabinetId, cellId);

        // 2. 发送开锁指令
        boolean success = deviceClient.sendOpenCommand(cell.getCabinetNo(), cell.getCellNo());

        // 3. 记录操作日志
        CabinetCellOperation operation = createOperationLog(
            cabinetId, cellId, "OPEN", operatorId, operatorType, success
        );

        // 4. 更新格口状态
        if (success) {
            updateCellLockStatus(cellId, 1); // 锁开启
        } else {
            throw new ApiException("开锁失败，请重试");
        }
    }
}

2. 状态监控

@Service
@RequiredArgsConstructor
public class CabinetMonitorService {

    @Scheduled(fixedRate = 30000) // 每30秒执行一次
    public void monitorCabinetStatus() {
        List<SmartCabinet> cabinets = cabinetService.getAllActiveCabinets();

        for (SmartCabinet cabinet : cabinets) {
            try {
                // 查询设备状态
                CabinetStatus status = deviceClient.queryStatus(cabinet.getCabinetNo());

                // 更新数据库状态
                updateCabinetStatus(cabinet.getId(), status);

                // 记录监控日志
                logMonitorResult(cabinet.getId(), status, true);

            } catch (Exception e) {
                // 设备连接失败
                logMonitorResult(cabinet.getId(), null, false);
                log.error("监控柜体{}状态失败: {}", cabinet.getCabinetNo(), e.getMessage());
            }
        }
    }
}

配置管理

1. 设备配置

cabinet:
  device:
    timeout: 5000
    retry-count: 3
    heartbeat-interval: 30000
    reconnect-interval: 10000

2. 企业微信配置

qywx:
  cabinet:
    enabled: true
    callback-url: https://your-domain.com/qywx/cabinet/callback
    qrcode-expire: 300

安全考虑

1. 通信安全

TCP通信使用TLS加密
指令签名验证
防止重放攻击
IP白名单控制

2. 业务安全

操作权限验证
操作频率限制
异常操作告警
操作日志审计

3. 数据安全

敏感数据加密存储
数据库访问权限控制
定期数据备份
操作日志保留

故障处理

1. 设备离线

自动重连机制
状态告警通知
手动干预流程

2. 通信异常

超时重试机制
异常日志记录
人工排查流程

3. 数据不一致

状态同步机制
数据修复工具
手动核对流程

监控告警

1. 监控指标

设备在线率
操作成功率
响应时间
错误率

2. 告警规则

设备离线超过5分钟
操作失败率超过10%
响应时间超过3秒
连续错误次数超过3次

3. 告警方式

企业微信消息
短信通知
邮件通知
系统日志

9.7 KiB Raw Permalink Blame History Unescape Escape

智能柜系统指南

概述

功能特性

数据库设计

智能柜表结构

smart_cabinet (智能柜表)

cabinet_cell (柜体格口表)

cabinet_cell_operation (格口操作记录表)

API接口

1. 柜体管理

1.1 获取柜体列表

1.2 新增柜体

1.3 修改柜体

2. 格口管理

2.1 获取格口列表

2.2 格口操作

3. 操作记录

3.1 获取操作记录

企业微信集成

1. corpid字段说明

2. 企业微信扫码开柜

2.1 生成开柜二维码

2.2 企业微信回调处理

设备通信协议

1. TCP通信协议

1.1 开锁指令

1.2 关锁指令

1.3 状态查询

2. 签名算法

业务逻辑

1. 开柜流程

2. 状态监控

配置管理

1. 设备配置

2. 企业微信配置

安全考虑

1. 通信安全

2. 业务安全

3. 数据安全

故障处理

1. 设备离线

2. 通信异常

3. 数据不一致

监控告警

1. 监控指标

2. 告警规则

3. 告警方式

9.7 KiB

Raw Permalink Blame History