feat:apk自动更新

db/20260729_terminal_log_menu_permissions.sql

@@ -1,77 +0,0 @@
--- 终端日志文件管理端权限补充。
--- 当前 sys_menu.permission 长度为 32，下载权限使用 down，避免 33 位的 download 标识被数据库截断。
--- 本脚本只维护权限元数据，不写 sys_role_menu；新按钮由管理员按角色显式授权，避免扩大现有角色权限。
-
-SET @terminal_log_menu_seed := (SELECT COALESCE(MAX(menu_id), 0) FROM sys_menu);
-
-INSERT INTO sys_menu
-    (menu_id, name, permission, path, component, parent_id, icon, visible, sort_order, keep_alive, embedded,
-     menu_type, create_by, create_time, update_by, update_time, del_flag, tenant_id)
-SELECT (@terminal_log_menu_seed := @terminal_log_menu_seed + 1), '日志预览',
-       'hard_hardTerminalLogFile_preview', NULL, NULL, view_menu.parent_id, NULL, '0', 1, '0', '0', '1',
-       'admin', NOW(), 'admin', NOW(), '0', view_menu.tenant_id
-FROM sys_menu view_menu
-WHERE view_menu.permission = 'hard_hardTerminalLogFile_view'
-  AND view_menu.del_flag = '0'
-  AND NOT EXISTS (
-    SELECT 1
-    FROM sys_menu existing
-    WHERE existing.tenant_id <=> view_menu.tenant_id
-      AND existing.permission = 'hard_hardTerminalLogFile_preview'
-  );
-
-INSERT INTO sys_menu
-    (menu_id, name, permission, path, component, parent_id, icon, visible, sort_order, keep_alive, embedded,
-     menu_type, create_by, create_time, update_by, update_time, del_flag, tenant_id)
-SELECT (@terminal_log_menu_seed := @terminal_log_menu_seed + 1), '日志下载',
-       'hard_hardTerminalLogFile_down', NULL, NULL, view_menu.parent_id, NULL, '0', 2, '0', '0', '1',
-       'admin', NOW(), 'admin', NOW(), '0', view_menu.tenant_id
-FROM sys_menu view_menu
-WHERE view_menu.permission = 'hard_hardTerminalLogFile_view'
-  AND view_menu.del_flag = '0'
-  AND NOT EXISTS (
-    SELECT 1
-    FROM sys_menu existing
-    WHERE existing.tenant_id <=> view_menu.tenant_id
-      AND existing.permission = 'hard_hardTerminalLogFile_down'
-  );
-
-INSERT INTO sys_menu
-    (menu_id, name, permission, path, component, parent_id, icon, visible, sort_order, keep_alive, embedded,
-     menu_type, create_by, create_time, update_by, update_time, del_flag, tenant_id)
-SELECT (@terminal_log_menu_seed := @terminal_log_menu_seed + 1), '立即拉取日志',
-       'hard_hardTerminalLogFile_pull', NULL, NULL, view_menu.parent_id, NULL, '0', 3, '0', '0', '1',
-       'admin', NOW(), 'admin', NOW(), '0', view_menu.tenant_id
-FROM sys_menu view_menu
-WHERE view_menu.permission = 'hard_hardTerminalLogFile_view'
-  AND view_menu.del_flag = '0'
-  AND NOT EXISTS (
-    SELECT 1
-    FROM sys_menu existing
-    WHERE existing.tenant_id <=> view_menu.tenant_id
-      AND existing.permission = 'hard_hardTerminalLogFile_pull'
-  );
-
-UPDATE sys_menu
-SET del_flag = '0',
-    visible = '0',
-    update_by = 'admin',
-    update_time = NOW()
-WHERE permission IN (
-    'hard_hardTerminalLogFile_preview',
-    'hard_hardTerminalLogFile_down',
-    'hard_hardTerminalLogFile_pull'
-);
-
--- 生成器默认的写操作和导出按钮不再对管理端开放，保留记录便于审计和重复执行。
-UPDATE sys_menu
-SET del_flag = '1',
-    visible = '0',
-    update_by = 'admin',
-    update_time = NOW()
-WHERE permission IN (
-    'hard_hardTerminalLogFile_add',
-    'hard_hardTerminalLogFile_edit',
-    'hard_hardTerminalLogFile_del',
-    'hard_hardTerminalLogFile_export'
-);

db/20260730_add_hard_terminal_status.sql

@@ -0,0 +1,24 @@
+-- 食堂、超市 Android 终端心跳状态。在线状态由服务端按最后心跳时间实时计算，不冗余落库。
+CREATE TABLE `hard_terminal_status` (
+  `hard_id` bigint NOT NULL COMMENT '设备ID，对应hard_manager.id',
+  `last_online_time` datetime NOT NULL COMMENT '服务端最近收到心跳的时间',
+  `heartbeat_scene` varchar(32) NOT NULL COMMENT '最近心跳场景(ONLINE,AUTO_UPDATE)',
+  `disconnect_reason` varchar(128) DEFAULT NULL COMMENT '计划内断开原因，目前用于标记自动更新重启',
+  `apk_version_name` varchar(64) DEFAULT NULL COMMENT '终端上报的APK展示版本号',
+  `apk_version_code` bigint DEFAULT NULL COMMENT '终端上报的APK内部版本码',
+  `system_uptime_seconds` bigint DEFAULT NULL COMMENT 'Android系统本次启动后运行秒数',
+  `app_uptime_seconds` bigint DEFAULT NULL COMMENT '终端App本次进程运行秒数',
+  `network_type` varchar(32) DEFAULT NULL COMMENT '最近心跳使用的网络类型',
+  `available_storage_bytes` bigint DEFAULT NULL COMMENT '应用存储卷最近可用空间，单位字节',
+  `root_status` varchar(16) DEFAULT NULL COMMENT 'Root状态(unknown,available,unavailable)',
+  `device_owner` tinyint(1) DEFAULT NULL COMMENT '当前应用是否为Device Owner',
+  `kiosk_active` tinyint(1) DEFAULT NULL COMMENT '最近心跳时是否处于Kiosk锁定任务模式',
+  `device_status_json` json DEFAULT NULL COMMENT '打印机、电子秤、读卡器、副屏等可选硬件状态快照',
+  `create_by` varchar(64) DEFAULT NULL COMMENT '创建人',
+  `create_time` datetime NOT NULL COMMENT '创建时间',
+  `update_by` varchar(64) DEFAULT NULL COMMENT '修改人',
+  `update_time` datetime NOT NULL COMMENT '修改时间',
+  `tenant_id` bigint NOT NULL COMMENT '租户ID',
+  PRIMARY KEY (`hard_id`),
+  KEY `idx_hard_terminal_status_tenant_online` (`tenant_id`, `last_online_time`)
+) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_bin COMMENT='食堂超市终端心跳状态';

pjcloud-hardware/pjcloud-hardware-api/src/main/java/com/bsd/pjcloud/hard/api/constant/TerminalHeartbeatSceneEnum.java

@@ -0,0 +1,19 @@
+package com.bsd.pjcloud.hard.api.constant;
+
+/**
+ * 终端心跳场景。
+ *
+ * <p>枚举名称是终端与服务端之间的固定接口编码，不得随展示文案调整。</p>
+ */
+public enum TerminalHeartbeatSceneEnum {
+
+    /**
+     * 普通在线心跳；收到后清除之前的计划更新断开原因。
+     */
+    ONLINE,
+
+    /**
+     * 自动更新安装前心跳；用于在应用重启期间保留可解释的离线原因。
+     */
+    AUTO_UPDATE
+}

pjcloud-hardware/pjcloud-hardware-api/src/main/java/com/bsd/pjcloud/hard/api/dto/hard/TerminalHeartbeatDto.java

@@ -0,0 +1,85 @@
+package com.bsd.pjcloud.hard.api.dto.hard;
+
+import com.bsd.pjcloud.hard.api.constant.TerminalHeartbeatSceneEnum;
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Pattern;
+import lombok.Data;
+
+import java.util.Map;
+
+/**
+ * 食堂、超市 Android 终端心跳请求。
+ */
+@Data
+@Schema(description = "终端心跳请求")
+public class TerminalHeartbeatDto {
+
+    /**
+     * APK 展示版本号，来源于终端当前安装包；取不到时允许为空。
+     */
+    @Schema(description = "APK展示版本号")
+    private String apkVersionName;
+
+    /**
+     * APK 内部版本码，来源于终端当前安装包；取不到时允许为空。
+     */
+    @Schema(description = "APK内部版本码")
+    private Long apkVersionCode;
+
+    /**
+     * 本次上报场景，使用 {@link TerminalHeartbeatSceneEnum} 的固定接口名称。
+     */
+    @NotNull(message = "心跳场景不能为空")
+    @Schema(description = "心跳场景", requiredMode = Schema.RequiredMode.REQUIRED)
+    private TerminalHeartbeatSceneEnum scene;
+
+    /**
+     * Android 系统本次启动后的运行秒数，用于区分整机重启与应用进程重启。
+     */
+    @Schema(description = "Android系统运行秒数")
+    private Long systemUptimeSeconds;
+
+    /**
+     * 当前应用进程运行秒数，用于识别应用崩溃或被系统重新拉起。
+     */
+    @Schema(description = "应用进程运行秒数")
+    private Long appUptimeSeconds;
+
+    /**
+     * 最近上报时使用的网络类型，例如 ethernet、wifi、4g 或 offline。
+     */
+    @Schema(description = "网络类型")
+    private String networkType;
+
+    /**
+     * 应用私有目录所在存储卷的可用空间，单位为字节。
+     */
+    @Schema(description = "可用存储空间，单位字节")
+    private Long availableStorageBytes;
+
+    /**
+     * Root 最近检测状态，持久化值固定为 unknown、available 或 unavailable。
+     */
+    @Pattern(regexp = "unknown|available|unavailable", message = "Root状态不正确")
+    @Schema(description = "Root状态")
+    private String rootStatus;
+
+    /**
+     * 当前应用是否已被 Android 配置为 Device Owner；无法读取时为空。
+     */
+    @Schema(description = "是否为Device Owner")
+    private Boolean deviceOwner;
+
+    /**
+     * 最近上报时是否处于 Kiosk 锁定任务模式；无法读取时为空。
+     */
+    @Schema(description = "是否处于Kiosk模式")
+    private Boolean kioskActive;
+
+    /**
+     * 可选外围硬件状态，以稳定功能编码映射布尔值，例如 printer、steelyard、cardReader、subScreen。
+     */
+    @Schema(description = "可选外围硬件状态")
+    private Map<String, Boolean> deviceStatus;
+}

pjcloud-hardware/pjcloud-hardware-api/src/main/java/com/bsd/pjcloud/hard/api/entity/manager/HardTerminalStatusEntity.java

@@ -0,0 +1,146 @@
+package com.bsd.pjcloud.hard.api.entity.manager;
+
+import com.baomidou.mybatisplus.annotation.FieldFill;
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableField;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import com.baomidou.mybatisplus.extension.activerecord.Model;
+import com.bsd.pjcloud.common.core.util.TenantTable;
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+import java.time.LocalDateTime;
+
+/**
+ * 食堂、超市 Android 终端的最新心跳状态。
+ *
+ * <p>每台设备只保留一条最新记录，在线布尔值由服务端按时间阈值实时计算。</p>
+ */
+@Data
+@TenantTable
+@TableName("hard_terminal_status")
+@EqualsAndHashCode(callSuper = true)
+@Schema(description = "终端最新心跳状态")
+public class HardTerminalStatusEntity extends Model<HardTerminalStatusEntity> {
+
+    /**
+     * 设备 ID，同时作为主键，对应 {@code hard_manager.id}。
+     */
+    @TableId(type = IdType.INPUT)
+    @Schema(description = "设备ID")
+    private Long hardId;
+
+    /**
+     * 服务端最近收到心跳的时间，在线计算以此时间为准。
+     */
+    @Schema(description = "最后在线时间")
+    private LocalDateTime lastOnlineTime;
+
+    /**
+     * 最近一次心跳场景，保存 {@code ONLINE} 或 {@code AUTO_UPDATE} 接口编码。
+     */
+    @Schema(description = "最近心跳场景")
+    private String heartbeatScene;
+
+    /**
+     * 计划内断开原因；普通在线心跳会清空，当前仅保留“自动更新重启”。
+     */
+    @Schema(description = "计划内断开原因")
+    private String disconnectReason;
+
+    /**
+     * 终端上报的 APK 展示版本号，无法读取时为空。
+     */
+    @Schema(description = "APK展示版本号")
+    private String apkVersionName;
+
+    /**
+     * 终端上报的 APK 内部版本码，无法读取时为空。
+     */
+    @Schema(description = "APK内部版本码")
+    private Long apkVersionCode;
+
+    /**
+     * Android 系统本次启动后的运行时长，单位为秒；终端无法读取时为空。
+     */
+    @Schema(description = "Android系统运行秒数")
+    private Long systemUptimeSeconds;
+
+    /**
+     * 当前应用进程运行时长，单位为秒；终端无法读取时为空。
+     */
+    @Schema(description = "应用进程运行秒数")
+    private Long appUptimeSeconds;
+
+    /**
+     * 最近一次心跳的网络类型，例如 ethernet、wifi、4g 或 offline。
+     */
+    @Schema(description = "网络类型")
+    private String networkType;
+
+    /**
+     * 应用私有目录所在存储卷的可用空间，单位为字节。
+     */
+    @Schema(description = "可用存储空间，单位字节")
+    private Long availableStorageBytes;
+
+    /**
+     * Root 最近检测状态，固定为 unknown、available 或 unavailable。
+     */
+    @Schema(description = "Root状态")
+    private String rootStatus;
+
+    /**
+     * 最近一次心跳时当前应用是否为 Device Owner；无法读取时为空。
+     */
+    @Schema(description = "是否为Device Owner")
+    private Boolean deviceOwner;
+
+    /**
+     * 最近一次心跳时是否处于 Kiosk 锁定任务模式；无法读取时为空。
+     */
+    @Schema(description = "是否处于Kiosk模式")
+    private Boolean kioskActive;
+
+    /**
+     * 打印机、电子秤、读卡器和副屏等可选硬件状态 JSON 快照。
+     */
+    @Schema(description = "可选外围硬件状态JSON")
+    private String deviceStatusJson;
+
+    /**
+     * 创建人；设备心跳没有后台用户上下文时为空。
+     */
+    @TableField(fill = FieldFill.INSERT)
+    @Schema(description = "创建人")
+    private String createBy;
+
+    /**
+     * 首次收到该设备心跳的服务端时间。
+     */
+    @TableField(fill = FieldFill.INSERT)
+    @Schema(description = "创建时间")
+    private LocalDateTime createTime;
+
+    /**
+     * 修改人；设备心跳没有后台用户上下文时为空。
+     */
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    @Schema(description = "修改人")
+    private String updateBy;
+
+    /**
+     * 最近一次心跳写入的服务端时间。
+     */
+    @TableField(fill = FieldFill.INSERT_UPDATE)
+    @Schema(description = "修改时间")
+    private LocalDateTime updateTime;
+
+    /**
+     * 数据所属租户 ID，取自已通过当前租户校验的设备记录。
+     */
+    @Schema(description = "租户ID")
+    private Long tenantId;
+}

pjcloud-hardware/pjcloud-hardware-api/src/main/java/com/bsd/pjcloud/hard/api/vo/manager/HardManagerVo.java

@@ -6,6 +6,11 @@ import com.bsd.pjcloud.hard.api.vo.base.BaseHardGroupInterface;
 import com.bsd.pjcloud.wallet.api.vo.base.BaseMchInterface;
 import lombok.Data;
 
+import java.time.LocalDateTime;
+
+/**
+ * 设备管理视图，包含设备基础资料及仅用于接口返回的关联、运行状态信息。
+ */
 @Data
 public class HardManagerVo extends HardManagerEntity implements BaseDeptInterface, BaseMchInterface, BaseHardGroupInterface {
 
@@ -29,4 +34,29 @@ public class HardManagerVo extends HardManagerEntity implements BaseDeptInterfac
 
     private String hardGroupName;
 
+    /**
+     * 终端是否在线；超市、食堂设备返回布尔值，其他设备类型返回 {@code null} 表示暂不支持。
+     */
+    private Boolean online;
+
+    /**
+     * 服务端最近收到终端心跳的时间；尚未上报或设备类型不支持时为空。
+     */
+    private LocalDateTime lastOnlineTime;
+
+    /**
+     * 当前 APK 展示版本号，来源于终端最近一次心跳；未上报时为空。
+     */
+    private String apkVersionName;
+
+    /**
+     * 当前 APK 内部版本码，来源于终端最近一次心跳；未上报时为空。
+     */
+    private Long apkVersionCode;
+
+    /**
+     * 断开连接的可解释原因；除主动自动更新外均为基于心跳超时的推断结果。
+     */
+    private String disconnectReason;
+
 }

pjcloud-hardware/pjcloud-hardware-biz/src/main/java/com/bsd/pjcloud/hard/controller/hard/HardApiController.java

@@ -54,6 +54,10 @@ public class HardApiController {
     private final HardOrderTotalService hardOrderTotalService;
     private final ReservationMenuQueryService reservationMenuQueryService;
     private final VerificationRecordService verificationRecordService;
+    /**
+     * 食堂、超市 Android 终端心跳状态服务。
+     */
+    private final HardTerminalStatusService hardTerminalStatusService;
 
     @PostMapping("/bind")
     @Operation(summary = "绑定服务端设备")
@@ -61,6 +65,20 @@ public class HardApiController {
         return R.ok(hardManagerService.bind(dto));
     }
 
+    /**
+     * 接收食堂、超市 Android 终端的在线心跳，设备身份由请求头中的设备 ID 确认。
+     *
+     * @param hardId 当前绑定设备 ID
+     * @param dto APK 版本与心跳场景
+     * @return 无业务数据的成功响应
+     */
+    @PostMapping("/terminal-heartbeat")
+    @Operation(summary = "上报终端心跳")
+    public R<Void> terminalHeartbeat(@RequestHeader("DEVICE-ID") Long hardId, @Valid @RequestBody TerminalHeartbeatDto dto) {
+        hardTerminalStatusService.heartbeat(hardId, dto);
+        return R.ok();
+    }
+
     @GetMapping("/get")
     @Operation(summary = "获取硬件配置信息")
     public R<HardManagerVo> get(@RequestParam Long id) {

pjcloud-hardware/pjcloud-hardware-biz/src/main/java/com/bsd/pjcloud/hard/mapper/manager/HardTerminalStatusMapper.java

@@ -0,0 +1,21 @@
+package com.bsd.pjcloud.hard.mapper.manager;
+
+import com.bsd.pjcloud.common.data.datascope.PjcloudBaseMapper;
+import com.bsd.pjcloud.hard.api.entity.manager.HardTerminalStatusEntity;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+
+/**
+ * 终端最新心跳状态数据访问层。
+ */
+@Mapper
+public interface HardTerminalStatusMapper extends PjcloudBaseMapper<HardTerminalStatusEntity> {
+
+    /**
+     * 以设备 ID 为唯一键写入最新心跳；冲突时仅更新最新状态和审计修改时间。
+     *
+     * @param status 已经完成设备与租户校验的心跳状态
+     * @return MySQL 受影响行数；新增通常为 1，更新通常为 2
+     */
+    int upsert(@Param("status") HardTerminalStatusEntity status);
+}

pjcloud-hardware/pjcloud-hardware-biz/src/main/java/com/bsd/pjcloud/hard/service/HardTerminalStatusService.java

@@ -0,0 +1,29 @@
+package com.bsd.pjcloud.hard.service;
+
+import com.baomidou.mybatisplus.extension.service.IService;
+import com.bsd.pjcloud.hard.api.dto.hard.TerminalHeartbeatDto;
+import com.bsd.pjcloud.hard.api.entity.manager.HardTerminalStatusEntity;
+import com.bsd.pjcloud.hard.api.vo.manager.HardManagerVo;
+
+import java.util.List;
+
+/**
+ * 食堂、超市 Android 终端心跳状态服务。
+ */
+public interface HardTerminalStatusService extends IService<HardTerminalStatusEntity> {
+
+    /**
+     * 校验设备类型并以服务端时间写入最新心跳。
+     *
+     * @param hardId 请求头中的设备 ID
+     * @param dto APK 版本与心跳场景
+     */
+    void heartbeat(Long hardId, TerminalHeartbeatDto dto);
+
+    /**
+     * 按当前页设备 ID 批量补充在线状态与 APK 信息；不改变上游数据权限筛选结果。
+     *
+     * @param records 已完成数据权限查询的设备视图列表
+     */
+    void enrich(List<HardManagerVo> records);
+}

pjcloud-hardware/pjcloud-hardware-biz/src/main/java/com/bsd/pjcloud/hard/service/impl/manager/HardManagerServiceImpl.java

@@ -28,6 +28,7 @@ import com.bsd.pjcloud.hard.mapper.HardGroupMapper;
 import com.bsd.pjcloud.hard.mapper.manager.HardManagerMapper;
 import com.bsd.pjcloud.hard.service.HardDoorManagerService;
 import com.bsd.pjcloud.hard.service.HardManagerService;
+import com.bsd.pjcloud.hard.service.HardTerminalStatusService;
 import com.bsd.pjcloud.hard.mqtt.config.MqttConfig;
 import com.bsd.pjcloud.hard.utils.MqTopicUtil;
 import com.bsd.pjcloud.mqtt.api.feign.RemoteMqttEventService;
@@ -63,6 +64,10 @@ public class HardManagerServiceImpl extends ServiceImpl<HardManagerMapper, HardM
     private final RemoteMchService mchService;
     private final RemoteDeptService deptService;
     private final RemoteMqttEventService remoteMqttEventService;
+    /**
+     * 为已完成数据权限过滤的设备分页批量补充终端运行状态。
+     */
+    private final HardTerminalStatusService hardTerminalStatusService;
 
     @Override
     public Page<HardManagerVo> pageJoin(Page page, HardManagerDto dto) {
@@ -118,6 +123,7 @@ public class HardManagerServiceImpl extends ServiceImpl<HardManagerMapper, HardM
                     HardUtil.convertHardGroupList(list.getRecords(), CollectionUtils.convertMap(groupList, HardGroupEntity::getId));
                 }
             }
+            hardTerminalStatusService.enrich(list.getRecords());
         }
         return list;
     }
@@ -306,4 +312,4 @@ public class HardManagerServiceImpl extends ServiceImpl<HardManagerMapper, HardM
         }
         return null;
     }
-}
+}

pjcloud-hardware/pjcloud-hardware-biz/src/main/java/com/bsd/pjcloud/hard/service/impl/manager/HardTerminalStatusServiceImpl.java

@@ -0,0 +1,159 @@
+package com.bsd.pjcloud.hard.service.impl.manager;
+
+import cn.hutool.core.util.ObjectUtil;
+import cn.hutool.json.JSONUtil;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
+import com.bsd.pjcloud.hard.api.constant.HardTypeEnum;
+import com.bsd.pjcloud.hard.api.constant.TerminalHeartbeatSceneEnum;
+import com.bsd.pjcloud.hard.api.dto.hard.TerminalHeartbeatDto;
+import com.bsd.pjcloud.hard.api.entity.manager.HardManagerEntity;
+import com.bsd.pjcloud.hard.api.entity.manager.HardTerminalStatusEntity;
+import com.bsd.pjcloud.hard.api.vo.manager.HardManagerVo;
+import com.bsd.pjcloud.hard.mapper.manager.HardManagerMapper;
+import com.bsd.pjcloud.hard.mapper.manager.HardTerminalStatusMapper;
+import com.bsd.pjcloud.hard.service.HardTerminalStatusService;
+import lombok.RequiredArgsConstructor;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+import java.util.Collections;
+import java.util.List;
+import java.util.Map;
+import java.util.function.Function;
+import java.util.stream.Collectors;
+
+/**
+ * 食堂、超市 Android 终端心跳状态服务实现。
+ */
+@Service
+@RequiredArgsConstructor
+public class HardTerminalStatusServiceImpl extends ServiceImpl<HardTerminalStatusMapper, HardTerminalStatusEntity> implements HardTerminalStatusService {
+
+    /**
+     * 终端连续 180 秒未上报后判定离线；恰好位于边界时间仍视为在线。
+     */
+    private static final long ONLINE_TIMEOUT_SECONDS = 180L;
+
+    /**
+     * 从未上报心跳时返回给管理端的原因。
+     */
+    private static final String NEVER_ONLINE_REASON = "尚未收到终端心跳";
+
+    /**
+     * 非计划更新场景下超时离线的推断原因。
+     */
+    private static final String GENERIC_DISCONNECT_REASON = "可能断电、断网或应用异常退出";
+
+    /**
+     * 自动更新安装前持久化的计划内断开原因。
+     */
+    private static final String AUTO_UPDATE_REASON = "自动更新重启";
+
+    /**
+     * 用于在心跳入口校验设备归属与设备类型的设备 Mapper。
+     */
+    private final HardManagerMapper hardManagerMapper;
+
+    /**
+     * 写入终端最新心跳。服务端时间是在线判定的唯一时间源，避免终端时钟偏差影响结果。
+     *
+     * @param hardId 请求头中的设备 ID
+     * @param dto APK 版本与心跳场景
+     */
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public void heartbeat(Long hardId, TerminalHeartbeatDto dto) {
+        if (hardId == null) {
+            throw new RuntimeException("设备ID不能为空");
+        }
+        HardManagerEntity hard = hardManagerMapper.selectById(hardId);
+        if (hard == null) {
+            throw new RuntimeException("设备不存在或不属于当前租户");
+        }
+        if (!isSupported(hard.getType())) {
+            throw new RuntimeException("当前设备类型暂不支持终端心跳");
+        }
+
+        LocalDateTime now = LocalDateTime.now();
+        HardTerminalStatusEntity status = new HardTerminalStatusEntity();
+        status.setHardId(hardId);
+        status.setLastOnlineTime(now);
+        status.setHeartbeatScene(dto.getScene().name());
+        status.setDisconnectReason(dto.getScene() == TerminalHeartbeatSceneEnum.AUTO_UPDATE ? AUTO_UPDATE_REASON : null);
+        status.setApkVersionName(dto.getApkVersionName());
+        status.setApkVersionCode(dto.getApkVersionCode());
+        status.setSystemUptimeSeconds(dto.getSystemUptimeSeconds());
+        status.setAppUptimeSeconds(dto.getAppUptimeSeconds());
+        status.setNetworkType(dto.getNetworkType());
+        status.setAvailableStorageBytes(dto.getAvailableStorageBytes());
+        status.setRootStatus(dto.getRootStatus());
+        status.setDeviceOwner(dto.getDeviceOwner());
+        status.setKioskActive(dto.getKioskActive());
+        status.setDeviceStatusJson(dto.getDeviceStatus() == null ? null : JSONUtil.toJsonStr(dto.getDeviceStatus()));
+        status.setCreateTime(now);
+        status.setUpdateTime(now);
+        status.setTenantId(hard.getTenantId());
+        baseMapper.upsert(status);
+    }
+
+    /**
+     * 为已完成权限过滤的设备记录批量补充运行状态，不支持的设备在线值保持为空。
+     *
+     * @param records 当前页设备视图列表
+     */
+    @Override
+    public void enrich(List<HardManagerVo> records) {
+        if (records == null || records.isEmpty()) {
+            return;
+        }
+        List<Long> supportedIds = records.stream()
+                .filter(record -> isSupported(record.getType()))
+                .map(HardManagerVo::getId)
+                .filter(ObjectUtil::isNotEmpty)
+                .distinct()
+                .toList();
+        Map<Long, HardTerminalStatusEntity> statusMap = supportedIds.isEmpty()
+                ? Collections.emptyMap()
+                : baseMapper.selectList(new LambdaQueryWrapper<HardTerminalStatusEntity>()
+                        .in(HardTerminalStatusEntity::getHardId, supportedIds)).stream()
+                        .collect(Collectors.toMap(HardTerminalStatusEntity::getHardId, Function.identity()));
+        LocalDateTime onlineCutoff = LocalDateTime.now().minusSeconds(ONLINE_TIMEOUT_SECONDS);
+
+        for (HardManagerVo record : records) {
+            if (!isSupported(record.getType())) {
+                record.setOnline(null);
+                continue;
+            }
+            HardTerminalStatusEntity status = statusMap.get(record.getId());
+            if (status == null) {
+                record.setOnline(false);
+                record.setDisconnectReason(NEVER_ONLINE_REASON);
+                continue;
+            }
+            boolean online = status.getLastOnlineTime() != null && !status.getLastOnlineTime().isBefore(onlineCutoff);
+            record.setOnline(online);
+            record.setLastOnlineTime(status.getLastOnlineTime());
+            record.setApkVersionName(status.getApkVersionName());
+            record.setApkVersionCode(status.getApkVersionCode());
+            if (online) {
+                record.setDisconnectReason(status.getDisconnectReason());
+            } else {
+                record.setDisconnectReason(ObjectUtil.isNotEmpty(status.getDisconnectReason())
+                        ? status.getDisconnectReason() : GENERIC_DISCONNECT_REASON);
+            }
+        }
+    }
+
+    /**
+     * 判断设备是否属于支持在线监控的超市或食堂 Android 终端。
+     *
+     * @param hardType {@code hard_manager.type} 的持久化编码
+     * @return 超市或食堂设备返回 {@code true}
+     */
+    private boolean isSupported(String hardType) {
+        return ObjectUtil.equals(HardTypeEnum.SUPERMARKET.getType(), hardType)
+                || ObjectUtil.equals(HardTypeEnum.CANTEEN.getType(), hardType);
+    }
+}

pjcloud-hardware/pjcloud-hardware-biz/src/main/resources/mapper/manager/HardTerminalStatusMapper.xml

@@ -0,0 +1,60 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE mapper PUBLIC "-//mybatis.org//DTD Mapper 3.0//EN" "http://mybatis.org/dtd/mybatis-3-mapper.dtd">
+
+<mapper namespace="com.bsd.pjcloud.hard.mapper.manager.HardTerminalStatusMapper">
+    <insert id="upsert">
+        INSERT INTO hard_terminal_status (
+            hard_id,
+            last_online_time,
+            heartbeat_scene,
+            disconnect_reason,
+            apk_version_name,
+            apk_version_code,
+            system_uptime_seconds,
+            app_uptime_seconds,
+            network_type,
+            available_storage_bytes,
+            root_status,
+            device_owner,
+            kiosk_active,
+            device_status_json,
+            create_time,
+            update_time,
+            tenant_id
+        ) VALUES (
+            #{status.hardId},
+            #{status.lastOnlineTime},
+            #{status.heartbeatScene},
+            #{status.disconnectReason},
+            #{status.apkVersionName},
+            #{status.apkVersionCode},
+            #{status.systemUptimeSeconds},
+            #{status.appUptimeSeconds},
+            #{status.networkType},
+            #{status.availableStorageBytes},
+            #{status.rootStatus},
+            #{status.deviceOwner},
+            #{status.kioskActive},
+            #{status.deviceStatusJson},
+            #{status.createTime},
+            #{status.updateTime},
+            #{status.tenantId}
+        )
+        ON DUPLICATE KEY UPDATE
+            last_online_time = VALUES(last_online_time),
+            heartbeat_scene = VALUES(heartbeat_scene),
+            disconnect_reason = VALUES(disconnect_reason),
+            apk_version_name = VALUES(apk_version_name),
+            apk_version_code = VALUES(apk_version_code),
+            system_uptime_seconds = VALUES(system_uptime_seconds),
+            app_uptime_seconds = VALUES(app_uptime_seconds),
+            network_type = VALUES(network_type),
+            available_storage_bytes = VALUES(available_storage_bytes),
+            root_status = VALUES(root_status),
+            device_owner = VALUES(device_owner),
+            kiosk_active = VALUES(kiosk_active),
+            device_status_json = VALUES(device_status_json),
+            update_time = VALUES(update_time),
+            tenant_id = VALUES(tenant_id)
+    </insert>
+</mapper>

pjcloud-integrated/pjcloud-integrated-api/src/main/java/com/bsd/pjcloud/integrated/constant/app/AppPlatformEnum.java

@@ -15,6 +15,8 @@ public enum AppPlatformEnum {
 
     ANDROID("1", "android"),
     IOS("2", "ios"),
+    SUPERMARKET_ANDROID("3", "超市android机器"),
+    CANTEEN_ANDROID("4", "食堂android机器"),
     ;
     private final String code;
     private final String desc;

pjcloud-integrated/pjcloud-integrated-biz/src/main/java/com/bsd/pjcloud/integrated/controller/app/AppVersionController.java

@@ -34,7 +34,7 @@ public class AppVersionController {
     @Operation(summary = "分页查询", description = "分页查询")
     @GetMapping("/ad/page")
     public R<Page<AppVersionVo>> hardPage(@ParameterObject Page page, @ParameterObject AppVersionDto dto) {
-        return R.ok(appVersionService.pageList(page, dto));
+        return R.ok(appVersionService.terminalPageList(page, dto));
     }
     /* ************************************* end 设备端 end ************************************* */
 

pjcloud-integrated/pjcloud-integrated-biz/src/main/java/com/bsd/pjcloud/integrated/mapper/app/AppVersionMapper.java

@@ -13,4 +13,13 @@ public interface AppVersionMapper extends PjcloudBaseMapper<AppVersionEntity> {
 
     Page<AppVersionVo> pagList(Page page, @Param("dto") AppVersionDto dto);
 
-}
+    /**
+     * 精确查询指定终端和平台的已发布版本，排序由 SQL 固定为版本码倒序。
+     *
+     * @param page 分页参数
+     * @param dto 终端 App 编码与平台参数
+     * @return 终端可见的已发布版本分页
+     */
+    Page<AppVersionVo> terminalPageList(Page page, @Param("dto") AppVersionDto dto);
+
+}

pjcloud-integrated/pjcloud-integrated-biz/src/main/java/com/bsd/pjcloud/integrated/service/AppVersionService.java

@@ -17,4 +17,13 @@ public interface AppVersionService extends IService<AppVersionEntity> {
      * 获取最新版本
      */
     AppVersionEntity lastVersion(AppVersionDto dto);
-}
+
+    /**
+     * 按终端 App 编码和平台精确查询已发布版本，并按版本码从高到低分页。
+     *
+     * @param page 分页参数
+     * @param dto 终端 App 编码与平台参数
+     * @return 仅包含匹配终端的已发布版本
+     */
+    Page<AppVersionVo> terminalPageList(Page page, AppVersionDto dto);
+}

pjcloud-integrated/pjcloud-integrated-biz/src/main/java/com/bsd/pjcloud/integrated/service/impl/app/AppVersionServiceImpl.java

@@ -26,6 +26,18 @@ public class AppVersionServiceImpl extends ServiceImpl<AppVersionMapper, AppVers
         return baseMapper.pagList(page, dto);
     }
 
+    /**
+     * 按终端 App 编码和平台精确查询已发布版本。
+     *
+     * @param page 分页参数
+     * @param dto 终端 App 编码与平台参数
+     * @return 版本码倒序的终端版本分页
+     */
+    @Override
+    public Page<AppVersionVo> terminalPageList(Page page, AppVersionDto dto) {
+        return baseMapper.terminalPageList(page, dto);
+    }
+
     /**
      * 获取最新版本
      */
@@ -34,9 +46,10 @@ public class AppVersionServiceImpl extends ServiceImpl<AppVersionMapper, AppVers
         LambdaQueryWrapper<AppVersionEntity> queryWrapper = new LambdaQueryWrapper<AppVersionEntity>()
                 .gt(ObjectUtil.isNotEmpty(dto.getVersionCode()), AppVersionEntity::getVersionCode, dto.getVersionCode())
                 .eq(AppVersionEntity::getStatus, AppVersionStatusEnum.PUBLISHED.getCode())
-                .like(ObjectUtil.isNotEmpty(dto.getPlatform()), AppVersionEntity::getPlatform, dto.getPlatform())
+                .eq(ObjectUtil.isNotEmpty(dto.getPlatform()), AppVersionEntity::getPlatform, dto.getPlatform())
+                .eq(ObjectUtil.isNotEmpty(dto.getAppUniqueCode()), AppVersionEntity::getAppUniqueCode, dto.getAppUniqueCode())
                 .orderByDesc(AppVersionEntity::getVersionCode)
                 .last("limit 1");
         return baseMapper.selectOne(queryWrapper);
     }
-}
+}

pjcloud-integrated/pjcloud-integrated-biz/src/main/resources/mapper/app/AppVersionMapper.xml

@@ -42,4 +42,20 @@
         </where>
     </select>
 
-</mapper>
+    <select id="terminalPageList" resultType="com.bsd.pjcloud.integrated.vo.app.AppVersionVo">
+        <include refid="selectA"/>
+        from app_version a
+        <where>
+            a.del_flag = '0'
+            and a.status = '1'
+            <if test="dto.appUniqueCode != null and dto.appUniqueCode != ''">
+                and a.app_unique_code = #{dto.appUniqueCode}
+            </if>
+            <if test="dto.platform != null and dto.platform != ''">
+                and a.platform = #{dto.platform}
+            </if>
+        </where>
+        order by a.version_code desc, a.create_time desc
+    </select>
+
+</mapper>