feat(ops): add confirm event DTO and update audit DTO

viewsh-module-ops/viewsh-module-ops-biz/src/main/java/com/viewsh/module/ops/core/badge/BadgeDeviceStatusService.java

@@ -0,0 +1,229 @@
+package com.viewsh.module.ops.core.badge;
+
+import com.viewsh.module.ops.api.badge.BadgeDeviceStatusDTO;
+import com.viewsh.module.ops.enums.BadgeDeviceStatusEnum;
+
+import java.util.List;
+
+/**
+ * 工牌设备状态服务接口
+ * <p>
+ * 职责：
+ * 1. 管理工牌设备状态（Redis 存储和查询）
+ * 2. 处理设备心跳更新
+ * 3. 状态转换（IDLE ↔ BUSY ↔ PAUSED ↔ OFFLINE）
+ * 4. 区域设备查询
+ * 5. 当前任务关联
+ * <p>
+ * 设计原则：
+ * - 状态存储在 Redis 中，不依赖数据库表
+ * - 与保洁员状态解耦，只关注设备本身
+ * - 为调度引擎提供设备状态查询能力
+ *
+ * @author lzh
+ */
+public interface BadgeDeviceStatusService {
+
+    // ==================== 状态管理 ====================
+
+    /**
+     * 更新工牌设备状态
+     * <p>
+     * 状态转换会记录状态变更时间和操作原因
+     *
+     * @param deviceId  设备ID
+     * @param status    目标状态
+     * @param operatorId 操作人ID（可为null，表示系统操作）
+     * @param reason    状态变更原因
+     */
+    void updateBadgeStatus(Long deviceId, BadgeDeviceStatusEnum status, Long operatorId, String reason);
+
+    /**
+     * 批量更新工牌设备状态
+     *
+     * @param deviceIds 设备ID列表
+     * @param status     目标状态
+     * @param operatorId 操作人ID
+     * @param reason     状态变更原因
+     */
+    void batchUpdateBadgeStatus(List<Long> deviceIds, BadgeDeviceStatusEnum status, Long operatorId, String reason);
+
+    // ==================== 状态查询 ====================
+
+    /**
+     * 获取工牌设备状态
+     *
+     * @param deviceId 设备ID
+     * @return 设备状态DTO，不存在返回null
+     */
+    BadgeDeviceStatusDTO getBadgeStatus(Long deviceId);
+
+    /**
+     * 批量获取工牌设备状态
+     *
+     * @param deviceIds 设备ID列表
+     * @return 设备状态DTO列表
+     */
+    List<BadgeDeviceStatusDTO> batchGetBadgeStatus(List<Long> deviceIds);
+
+    /**
+     * 获取指定区域的工牌设备列表
+     * <p>
+     * 只返回非 OFFLINE 状态的设备
+     *
+     * @param areaId 区域ID
+     * @return 设备状态DTO列表
+     */
+    List<BadgeDeviceStatusDTO> listBadgesByArea(Long areaId);
+
+    /**
+     * 获取可接单的工牌设备（IDLE 状态）
+     *
+     * @param areaId 区域ID
+     * @return 可接单设备列表
+     */
+    List<BadgeDeviceStatusDTO> listAvailableBadges(Long areaId);
+
+    /**
+     * 获取所有活跃的工牌设备（非OFFLINE状态）
+     *
+     * @return 活跃设备列表
+     */
+    List<BadgeDeviceStatusDTO> listActiveBadges();
+
+    // ==================== 心跳处理 ====================
+
+    /**
+     * 处理工牌设备心跳
+     * <p>
+     * 更新最后心跳时间和电量：
+     * <ul>
+     *   <li>如果设备之前为 OFFLINE，转为 IDLE</li>
+     *   <li>如果设备已存在，更新心跳时间和电量</li>
+     *   <li>如果设备不存在，创建新记录（状态为 IDLE）</li>
+     * </ul>
+     *
+     * @param deviceId     设备ID
+     * @param deviceCode   设备编码
+     * @param batteryLevel 电量（0-100）
+     */
+    void handleHeartbeat(Long deviceId, String deviceCode, Integer batteryLevel);
+
+    /**
+     * 处理工牌设备心跳（带区域信息）
+     *
+     * @param deviceId     设备ID
+     * @param deviceCode   设备编码
+     * @param batteryLevel 电量（0-100）
+     * @param areaId       当前所在区域ID
+     * @param areaName     当前所在区域名称
+     */
+    void handleHeartbeatWithArea(Long deviceId, String deviceCode, Integer batteryLevel,
+                                  Long areaId, String areaName);
+
+    // ==================== 在线状态检查 ====================
+
+    /**
+     * 检查工牌设备是否在线（非OFFLINE状态）
+     *
+     * @param deviceId 设备ID
+     * @return 是否在线
+     */
+    boolean isBadgeOnline(Long deviceId);
+
+    /**
+     * 检查工牌设备心跳是否超时
+     *
+     * @param deviceId         设备ID
+     * @param thresholdMinutes 超时阈值（分钟）
+     * @return 是否超时
+     */
+    boolean isHeartbeatTimeout(Long deviceId, int thresholdMinutes);
+
+    /**
+     * 检查心跳超时并将超时设备设为OFFLINE
+     * <p>
+     * 定时任务调用，默认超时时间为30分钟
+     */
+    void checkAndMarkOfflineDevices();
+
+    // ==================== 工单关联 ====================
+
+    /**
+     * 设置当前工单
+     *
+     * @param deviceId 设备ID
+     * @param orderId  工单ID
+     */
+    void setCurrentOrder(Long deviceId, Long orderId);
+
+    /**
+     * 清除当前工单
+     *
+     * @param deviceId 设备ID
+     */
+    void clearCurrentOrder(Long deviceId);
+
+    /**
+     * 获取当前有工单的设备列表
+     *
+     * @return 有工单的设备列表
+     */
+    List<BadgeDeviceStatusDTO> listBadgesWithCurrentOrder();
+
+    // ==================== 区域管理 ====================
+
+    /**
+     * 更新工牌设备所在区域
+     *
+     * @param deviceId 设备ID
+     * @param areaId   区域ID
+     * @param areaName 区域名称
+     */
+    void updateBadgeArea(Long deviceId, Long areaId, String areaName);
+
+    /**
+     * 初始化区域设备索引
+     * <p>
+     * 从 ops_area_device_relation 表加载 BADGE 类型的设备，
+     * 建立区域到设备的索引关系
+     */
+    void initAreaDeviceIndex();
+
+    /**
+     * 刷新区域设备索引
+     * <p>
+     * 重新从数据库加载区域设备关系
+     */
+    void refreshAreaDeviceIndex();
+
+    /**
+     * 将设备添加到区域索引
+     *
+     * @param deviceId 设备ID
+     * @param areaId   区域ID
+     */
+    void addToAreaIndex(Long deviceId, Long areaId);
+
+    /**
+     * 从区域索引移除设备
+     *
+     * @param deviceId 设备ID
+     * @param areaId   区域ID
+     */
+    void removeFromAreaIndex(Long deviceId, Long areaId);
+
+    // ==================== 设备管理 ====================
+
+    /**
+     * 删除工牌设备状态
+     *
+     * @param deviceId 设备ID
+     */
+    void deleteBadgeStatus(Long deviceId);
+
+    /**
+     * 清理所有离线设备的状态
+     */
+    void clearOfflineBadges();
+}