11

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

@@ -38,9 +38,12 @@ public class HardOrderDto extends HardOrderEntity implements BaseIsIncludeTreeIn
 
     private LocalDateTime[] createTimeList;
 
-    /** 更新时间范围采用左闭右开区间，供按订单实际状态变更时间查询。 */
+    /** 更新时间范围采用左闭右开区间，供兼容旧调用方按订单状态变更时间查询。 */
     private LocalDateTime[] updateTimeList;
 
+    /** 订单核销时间闭区间，仅按订单实际核销完成时间查询。 */
+    private LocalDateTime[] verificationTimeList;
+
     private LocalDateTime[] payTimeList;
 
     private LocalDateTime[] refundTimeList;

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

@@ -0,0 +1,45 @@
+package com.bsd.pjcloud.hard.api.dto.order;
+
+import cn.hutool.core.util.StrUtil;
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.AssertTrue;
+import jakarta.validation.constraints.Positive;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+
+/**
+ * 终端订单识别证据的订单定位参数。
+ *
+ * <p>消费机现场下单继续使用终端订单号对账；预约核销订单不是当前终端创建的，核销成功后改用
+ * 服务端订单 ID 定位。两种方式都必须结合请求头中的设备 ID 校验订单归属。</p>
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@Schema(description = "订单识别证据的订单定位参数")
+public abstract class HardOrderEvidenceOrderRefDto extends HardOrderEvidenceMetadataDto {
+
+    /**
+     * 终端本地稳定订单号，用于消费机现场下单后对账；预约核销证据允许为空。
+     */
+    @Size(max = 128, message = "终端订单号不能超过128个字符")
+    @Schema(description = "终端订单号，与服务端订单ID二选一")
+    private String androidOrderCode;
+
+    /**
+     * 已存在的服务端订单主键，仅用于当前设备已经成功核销的预约订单；现场下单证据允许为空。
+     */
+    @Positive(message = "服务端订单ID必须大于0")
+    @Schema(description = "服务端订单ID，与终端订单号二选一")
+    private Long orderId;
+
+    /**
+     * 校验至少提供一种订单定位信息，防止无条件查询或写入订单证据。
+     *
+     * @return 提供终端订单号或服务端订单 ID 时返回 {@code true}
+     */
+    @AssertTrue(message = "终端订单号和服务端订单ID不能同时为空")
+    public boolean isOrderReferencePresent() {
+        return StrUtil.isNotBlank(androidOrderCode) || orderId != null;
+    }
+}

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

@@ -12,15 +12,7 @@ import lombok.EqualsAndHashCode;
 @Data
 @EqualsAndHashCode(callSuper = true)
 @Schema(description = "订单证据元数据提交请求")
-public class HardOrderEvidenceSubmitDto extends HardOrderEvidenceMetadataDto {
-
-    /**
-     * 终端本地稳定订单号，用于接口响应丢失后的服务端订单对账。
-     */
-    @NotBlank(message = "终端订单号不能为空")
-    @Size(max = 128, message = "终端订单号不能超过128个字符")
-    @Schema(description = "终端订单号")
-    private String androidOrderCode;
+public class HardOrderEvidenceSubmitDto extends HardOrderEvidenceOrderRefDto {
 
     /**
      * 终端请求写入的目标状态，仅允许 PENDING 或 UNAVAILABLE；现场图片上传成功由服务端改为 AVAILABLE。

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

@@ -1,7 +1,6 @@
 package com.bsd.pjcloud.hard.api.dto.order;
 
 import io.swagger.v3.oas.annotations.media.Schema;
-import jakarta.validation.constraints.NotBlank;
 import jakarta.validation.constraints.Size;
 import lombok.Data;
 import lombok.EqualsAndHashCode;
@@ -12,15 +11,7 @@ import lombok.EqualsAndHashCode;
 @Data
 @EqualsAndHashCode(callSuper = true)
 @Schema(description = "订单现场证据上传请求")
-public class HardOrderEvidenceUploadDto extends HardOrderEvidenceMetadataDto {
-
-    /**
-     * 终端本地稳定订单号，服务端通过该编号解析真实订单主键。
-     */
-    @NotBlank(message = "终端订单号不能为空")
-    @Size(max = 128, message = "终端订单号不能超过128个字符")
-    @Schema(description = "终端订单号")
-    private String androidOrderCode;
+public class HardOrderEvidenceUploadDto extends HardOrderEvidenceOrderRefDto {
 
     /**
      * 产生识别证据的终端应用版本，用于问题追溯。

pjcloud-hardware/pjcloud-hardware-api/src/main/java/com/bsd/pjcloud/hard/api/entity/order/HardOrderEntity.java

@@ -235,6 +235,12 @@ public class HardOrderEntity extends Model<HardOrderEntity> {
     @Schema(description = "退款状态")
     private String refundStatus;
 
+    /**
+     * 订单核销完成时间；仅在订单实际完成核销时写入，避免被后续退款等订单更新覆盖。
+     */
+    @Schema(description = "订单核销时间")
+    private LocalDateTime verificationTime;
+
     /**
      * 订单取消时间(退款订单)
      */

pjcloud-hardware/pjcloud-hardware-api/src/main/java/com/bsd/pjcloud/hard/api/entity/order/HardOrderEvidenceImageEntity.java

@@ -39,9 +39,9 @@ public class HardOrderEvidenceImageEntity extends Model<HardOrderEvidenceImageEn
     private Long orderId;
 
     /**
-     * 终端本地稳定订单号快照，来源于 hard_order.android_order_code。
+     * 证据订单引用快照；现场订单取终端订单号，预约等服务端订单取订单号或服务端主键内部引用。
      */
-    @Schema(description = "终端订单号")
+    @Schema(description = "证据订单引用快照")
     private String androidOrderCode;
 
     /**

pjcloud-hardware/pjcloud-hardware-api/src/main/java/com/bsd/pjcloud/hard/api/vo/order/HardCanteenUserApptOrderVo.java

@@ -36,7 +36,7 @@ public class HardCanteenUserApptOrderVo {
     @Schema(description = "订单状态协议编码")
     private String orderStatus;
 
-    /** 订单最近更新时间；已核销订单中作为核销时间展示。 */
+    /** 核销时间兼容字段；优先来源于订单独立核销时间，历史空值回退到订单最近更新时间。 */
     @Schema(description = "核销时间")
     private LocalDateTime updateTime;