feat:打印机器修改

2026-09-04 16:23:49 +08:00
1 parent 9147aafec8
commit 991685ca48
@@ -7,7 +7,7 @@ import lombok.Getter;
 import java.util.Arrays;

 /**
- * 打印任务失败阶段，帮助管理端区分配置问题、服务端故障和终端故障。
+ * 打印任务失败阶段，帮助管理端区分配置问题、服务端故障和业务终端代理打印故障。
 */
@Getter
@AllArgsConstructor
@@ -19,10 +19,10 @@ public enum HardPrintFailureStageEnum {
    /** 服务端读取业务数据、绘制 PNG 或上传文件失败。 */
    IMAGE_GENERATION("IMAGE_GENERATION", "图片生成"),

-    /** 服务端向目标打印终端发布 MQTT 消息失败。 */
+    /** 服务端向绑定的来源业务终端发布 MQTT 消息失败。 */
    MQTT_DISPATCH("MQTT_DISPATCH", "MQTT下发"),

-    /** 打印终端下载图片、连接 USB 或写入 ESC/POS 数据失败。 */
+    /** 来源业务终端下载图片、连接 USB 或写入 ESC/POS 数据失败。 */
    TERMINAL_PRINT("TERMINAL_PRINT", "终端打印");

    /** 持久化阶段编码。 */
@@ -20,10 +20,10 @@ public enum HardPrintStatusEnum {
    /** 图片已生成并允许下发，历史枚举名保留为 GENERATE 以保持二进制兼容。 */
    GENERATE("1", "待打印"),

-    /** 打印终端已确认完整 USB 数据和切纸命令写入成功。 */
+    /** 来源业务终端已确认完整 USB 数据和切纸命令写入成功。 */
    PRINT("2", "已打印"),

-    /** 绑定、图片生成、MQTT 下发或终端打印阶段失败，可重试原任务。 */
+    /** 绑定、图片生成、MQTT 下发或业务终端代理打印阶段失败，可重试原任务。 */
    FAILED("3", "打印失败"),

    /** 核销回退等业务动作取消了尚未打印的任务。 */
@@ -26,7 +26,7 @@ public enum HardTypeEnum {
    YUN_XFJ("9", "云版消费机"),
    YYX_4G("10", "4G-云音响"),
    YYX_WIFI("11", "wifi-云音响"),
-    /** 运行打印专用终端模式、通过 USB 驱动尔印 ESC/POS 打印机的设备。 */
+    /** 由绑定的超市或食堂 Android 终端代理驱动的无屏尔印 USB 打印机。 */
    EY_PRINT("12", "尔印打印机器"),
    ;
    private final String type;
@@ -48,7 +48,7 @@ public enum HardTypeEnum {
    }

    /**
-     * 判断指定设备类型是否为独立打印终端。
+     * 判断指定设备类型是否为尔印逻辑打印机资产。
     *
     * @param hardTypeEnum 待判断的设备类型
     * @return 类型为 {@link #EY_PRINT} 时返回 {@code true}
@@ -6,10 +6,10 @@ import jakarta.validation.constraints.NotNull;
 import lombok.Data;

 /**
- * EY_PRINT 终端提交的打印结果回执。
+ * 食堂或超市终端代理无屏 EY_PRINT 提交的打印结果回执。
 */
@Data
-@Schema(description = "打印终端结果回执")
+@Schema(description = "业务终端代理打印结果回执")
 public class HardPrintResultDto {

    /** hard_invoice 打印任务主键。 */
@@ -22,7 +22,7 @@ public class HardPrintResultDto {
    @Schema(description = "订单ID")
    private Long orderId;

-    /** 终端实际处理的重试版本。 */
+    /** 来源业务终端实际处理的重试版本。 */
    @NotNull(message = "重试版本不能为空")
    @Min(value = 0, message = "重试版本不能小于0")
    @Schema(description = "重试版本")
@@ -33,7 +33,7 @@ public class HardPrintResultDto {
    @Schema(description = "是否成功")
    private Boolean success;

-    /** 本版本在终端执行的 USB 尝试次数。 */
+    /** 本版本在来源业务终端执行的 USB 尝试次数。 */
    @NotNull(message = "尝试次数不能为空")
    @Min(value = 1, message = "尝试次数不能小于1")
    @Schema(description = "终端尝试次数")
@@ -5,10 +5,10 @@ import jakarta.validation.constraints.NotNull;
 import lombok.Data;

 /**
- * 创建业务终端与尔印打印终端绑定关系的请求。
+ * 创建业务终端与无屏尔印 USB 打印机绑定关系的请求。
 */
@Data
-@Schema(description = "打印终端绑定请求")
+@Schema(description = "USB 打印机绑定请求")
 public class HardPrinterBindingDto {

    /** SUPERMARKET 或 CANTEEN 来源终端 ID。 */
@@ -16,8 +16,8 @@ public class HardPrinterBindingDto {
    @Schema(description = "来源业务终端ID")
    private Long sourceHardId;

-    /** EY_PRINT 目标终端 ID。 */
-    @NotNull(message = "打印终端不能为空")
-    @Schema(description = "目标打印终端ID")
+    /** EY_PRINT 逻辑打印机资产 ID。 */
+    @NotNull(message = "打印机不能为空")
+    @Schema(description = "逻辑打印机资产ID")
    private Long printerHardId;
 }
@@ -6,15 +6,15 @@ import jakarta.validation.constraints.NotNull;
 import lombok.Data;

 /**
- * 保存尔印打印终端 USB 与 ESC/POS 参数的请求。
+ * 保存无屏尔印 USB 打印机参数的请求。
 */
@Data
-@Schema(description = "打印终端配置请求")
+@Schema(description = "USB 打印机配置请求")
 public class HardPrinterConfigDto {

-    /** EY_PRINT 设备 ID。 */
-    @NotNull(message = "打印终端不能为空")
-    @Schema(description = "打印终端ID")
+    /** EY_PRINT 逻辑打印机资产 ID。 */
+    @NotNull(message = "打印机不能为空")
+    @Schema(description = "逻辑打印机资产ID")
    private Long printerHardId;

    /** 真机型号；未联调前允许为空。 */
@@ -9,10 +9,10 @@ import jakarta.validation.constraints.Size;
 import lombok.Data;

 /**
- * 尔印打印终端上报实际 USB 打印机信息的请求。
+ * 食堂或超市终端代理上报实际 USB 打印机信息的请求。
 */
@Data
-@Schema(description = "打印终端实际 USB 打印机信息")
+@Schema(description = "业务终端代理上报的 USB 打印机信息")
 public class HardPrinterInfoReportDto {

    /** USB 描述符中的厂商和产品名称组合，最长保存 128 个字符。 */
@@ -44,9 +44,9 @@ public class HardInvoiceEntity extends Model<HardInvoiceEntity> {
    private Long hardId;

    /**
-     * 实际接收任务的尔印打印终端 ID；历史记录和绑定失败任务允许为空。
+     * 任务路由关联的尔印逻辑打印机资产 ID；历史记录和绑定失败任务允许为空。
     */
-    @Schema(description="目标打印终端ID")
+    @Schema(description="逻辑打印机资产ID")
    private Long printerHardId;

 	/**
@@ -74,13 +74,13 @@ public class HardInvoiceEntity extends Model<HardInvoiceEntity> {
    private Integer printNo;

    /**
-     * 人工重试版本；终端用任务 ID 和该版本共同判断是否允许再次打印。
+     * 人工重试版本；来源业务终端用任务 ID 和该版本共同判断是否允许再次打印。
     */
    @Schema(description="重试版本")
    private Integer retryVersion;

    /**
-     * 打印终端上报的 USB 累计尝试次数。
+     * 来源业务终端代理上报的 USB 累计尝试次数。
     */
    @Schema(description="终端尝试次数")
    private Integer attemptCount;
@@ -98,7 +98,7 @@ public class HardInvoiceEntity extends Model<HardInvoiceEntity> {
    private String lastError;

    /**
-     * 打印终端确认完整 USB 数据和切纸命令写入成功的时间。
+     * 来源业务终端确认完整 USB 数据和切纸命令写入成功的时间。
     */
    @Schema(description="打印成功时间")
    private LocalDateTime printedAt;
@@ -17,7 +17,7 @@ import lombok.NoArgsConstructor;
 import java.time.LocalDateTime;

 /**
- * 业务终端与尔印打印终端的一对一绑定关系。
+ * 业务 Android 终端与无屏尔印 USB 打印机资产的一对一绑定关系。
 *
 * <p>记录使用物理删除，数据库分别对来源和目标设备设置唯一键，确保任何时刻都不能出现多重绑定。</p>
 */
@@ -28,7 +28,7 @@ import java.time.LocalDateTime;
@TenantTable
@TableName("hard_printer_binding")
@EqualsAndHashCode(callSuper = true)
-@Schema(description = "业务终端与打印终端绑定关系")
+@Schema(description = "业务终端与 USB 打印机绑定关系")
 public class HardPrinterBindingEntity extends Model<HardPrinterBindingEntity> {

    /** 绑定关系主键。 */
@@ -40,8 +40,8 @@ public class HardPrinterBindingEntity extends Model<HardPrinterBindingEntity> {
    @Schema(description = "来源业务终端ID")
    private Long sourceHardId;

-    /** 目标打印终端 ID，只允许 EY_PRINT。 */
-    @Schema(description = "目标打印终端ID")
+    /** 逻辑打印机资产 ID，只允许 EY_PRINT；设备本身不登录、不上报心跳。 */
+    @Schema(description = "逻辑打印机资产ID")
    private Long printerHardId;

    /** 双方共同所属商户 ID 快照。 */
@@ -17,7 +17,7 @@ import lombok.NoArgsConstructor;
 import java.time.LocalDateTime;

 /**
- * 尔印打印终端的 USB 和 ESC/POS 参数配置。
+ * 无屏尔印 USB 打印机资产的 USB 和 ESC/POS 参数配置。
 */
@Data
@Builder
@@ -26,7 +26,7 @@ import java.time.LocalDateTime;
@TenantTable
@TableName("hard_printer_config")
@EqualsAndHashCode(callSuper = true)
-@Schema(description = "尔印打印终端配置")
+@Schema(description = "尔印 USB 打印机配置")
 public class HardPrinterConfigEntity extends Model<HardPrinterConfigEntity> {

    /** 配置主键。 */
@@ -34,8 +34,8 @@ public class HardPrinterConfigEntity extends Model<HardPrinterConfigEntity> {
    @Schema(description = "配置主键")
    private Long id;

-    /** 配置所属 EY_PRINT 设备 ID。 */
-    @Schema(description = "打印终端ID")
+    /** 配置所属 EY_PRINT 逻辑打印机资产 ID。 */
+    @Schema(description = "逻辑打印机资产ID")
    private Long printerHardId;

    /** 真机联调后填写的打印机型号。 */
@@ -67,7 +67,7 @@ public class HardInvoiceVo extends HardInvoiceEntity implements BaseUserDeptInte

    private String hardType;

-    /** 目标尔印打印终端名称。 */
+    /** 任务绑定的尔印 USB 打印机资产名称。 */
    private String printerHardName;

    /**
@@ -7,11 +7,11 @@ import lombok.Data;
 import lombok.EqualsAndHashCode;

 /**
- * 打印终端绑定关系及两端设备展示信息。
+ * 业务终端与无屏 USB 打印机绑定关系及展示信息。
 */
@Data
@EqualsAndHashCode(callSuper = true)
-@Schema(description = "打印终端绑定详情")
+@Schema(description = "USB 打印机绑定详情")
 public class HardPrinterBindingVo extends HardPrinterBindingEntity {

    /** 来源业务终端名称。 */
@@ -22,11 +22,11 @@ public class HardPrinterBindingVo extends HardPrinterBindingEntity {
    @Schema(description = "来源业务终端类型")
    private String sourceHardType;

-    /** 目标打印终端名称。 */
-    @Schema(description = "目标打印终端名称")
+    /** 逻辑打印机资产名称。 */
+    @Schema(description = "逻辑打印机资产名称")
    private String printerHardName;

-    /** 目标打印终端当前配置；尚未保存时返回默认配置。 */
-    @Schema(description = "打印终端配置")
+    /** 目标 USB 打印机当前配置；尚未保存时返回默认配置。 */
+    @Schema(description = "USB 打印机配置")
    private HardPrinterConfigEntity printerConfig;
 }
@@ -59,16 +59,16 @@ public class HardManagerVo extends HardManagerEntity implements BaseDeptInterfac
     */
    private String disconnectReason;

-    /** 当前来源业务终端所绑定的 EY_PRINT 设备 ID；未绑定或当前行为打印机时为空。 */
+    /** 当前来源业务终端所绑定的 EY_PRINT 打印机资产 ID；未绑定或当前行为打印机时为空。 */
    private Long boundPrinterHardId;

    /** 当前来源业务终端所绑定的 EY_PRINT 设备名称。 */
    private String boundPrinterHardName;

-    /** 当前 EY_PRINT 反向绑定的来源业务终端 ID；未绑定或当前行为来源设备时为空。 */
+    /** 当前 EY_PRINT 打印机资产反向绑定的来源业务终端 ID；未绑定或当前行为来源设备时为空。 */
    private Long boundSourceHardId;

-    /** 当前 EY_PRINT 反向绑定的来源业务终端名称。 */
+    /** 当前 EY_PRINT 打印机资产反向绑定的来源业务终端名称。 */
    private String boundSourceHardName;

    /** EY_PRINT 型号；未维护配置或非打印设备时为空。 */