feat:后台批量退款

2026-08-27 17:49:40 +08:00
1 parent f4ff6bd3a3
commit be749076bf
@@ -0,0 +1,25 @@
+package com.bsd.pjcloud.hard.api.dto.order;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+import lombok.Data;
+
+import java.util.List;
+
+/**
+ * 后台批量退款预览请求，只接收列表页已经勾选的订单主键。
+ */
+@Data
+@Schema(description = "后台批量退款预览请求")
+public class HardBatchRefundPreviewDto {
+
+    /**
+     * 待预览的订单主键，服务端会去重并重新校验数据权限和退款资格，单次最多 1000 笔。
+     */
+    @NotEmpty(message = "请选择需要退款的订单")
+    @Size(max = 1000, message = "单次最多选择1000个订单")
+    @Schema(description = "待退款订单主键，单次最多1000笔")
+    private List<@NotNull(message = "订单id不能为空") Long> orderIds;
+}
@@ -0,0 +1,24 @@
+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;
+
+/**
+ * 后台批量退款提交请求，在预览订单集合之外补充本批次统一备注。
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@Schema(description = "后台批量退款提交请求")
+public class HardBatchRefundSubmitDto extends HardBatchRefundPreviewDto {
+
+    /**
+     * 本批次退款备注，同时写入每笔售后单的申请原因和补充描述，去除首尾空白后不能为空。
+     */
+    @NotBlank(message = "请输入退款备注")
+    @Size(max = 200, message = "退款备注不能超过200个字符")
+    @Schema(description = "本批次统一退款备注，最多200个字符")
+    private String remark;
+}
@@ -1,8 +1,21 @@
 package com.bsd.pjcloud.hard.api.vo.order;

 import com.bsd.pjcloud.hard.api.entity.order.HardAfterSaleLogEntity;
+import io.swagger.v3.oas.annotations.media.Schema;
 import lombok.Data;
+import lombok.EqualsAndHashCode;

+/**
+ * App 售后进度记录，在持久化日志之外补充当前节点对应的退款原因。
+ */
@Data
+@EqualsAndHashCode(callSuper = true)
+@Schema(description = "App 售后进度记录")
 public class HardAfterSaleLogVo extends HardAfterSaleLogEntity {
+
+    /**
+     * 当前进度节点对应的退款或拒绝原因；无可展示原因时为空，不写入售后日志表。
+     */
+    @Schema(description = "当前进度节点对应的退款原因")
+    private String reason;
 }
@@ -0,0 +1,156 @@
+package com.bsd.pjcloud.hard.api.vo.order;
+
+import io.swagger.v3.oas.annotations.media.Schema;
+import lombok.Data;
+
+import java.math.BigDecimal;
+import java.time.LocalDate;
+import java.util.List;
+
+/**
+ * 后台批量退款预览结果，按订单展示服务端实时核定的剩余可退商品和金额。
+ */
+@Data
+@Schema(description = "后台批量退款预览结果")
+public class HardBatchRefundPreviewVo {
+
+    /**
+     * 当前预览范围的订单、人员、商品和金额汇总，不包含无权限或不存在的订单。
+     */
+    @Schema(description = "批量退款汇总")
+    private Summary summary;
+
+    /**
+     * 按服务端订单排序返回的预览明细；不可退款订单保留原因但不会进入实际退款任务。
+     */
+    @Schema(description = "批量退款订单明细")
+    private List<OrderItem> orders;
+
+    /**
+     * 批量退款预览汇总，数量和金额仅累计当前仍可退款的订单。
+     */
+    @Data
+    @Schema(description = "批量退款预览汇总")
+    public static class Summary {
+
+        /** 当前请求中通过数据权限校验的订单数量。 */
+        @Schema(description = "预览订单数")
+        private Integer selectedOrderCount;
+
+        /** 当前校验通过并会进入退款任务的订单数量。 */
+        @Schema(description = "可退款订单数")
+        private Integer refundableOrderCount;
+
+        /** 因状态、渠道或剩余金额不满足要求而跳过的订单数量。 */
+        @Schema(description = "不可退款订单数")
+        private Integer unavailableOrderCount;
+
+        /** 可退款订单中的去重订餐人数，未知用户不计入。 */
+        @Schema(description = "订餐人数")
+        private Integer userCount;
+
+        /** 可退款订单中按商品主键去重后的菜品种类数。 */
+        @Schema(description = "菜品种类数")
+        private Integer productKindCount;
+
+        /** 可退款数量商品的剩余总份数，不包含称重商品。 */
+        @Schema(description = "剩余可退商品总份数")
+        private Long productCount;
+
+        /** 可退款称重商品的剩余总重量，单位沿用购物车重量协议。 */
+        @Schema(description = "剩余可退商品总重量")
+        private BigDecimal productWeight;
+
+        /** 可退款订单的剩余可退总金额，单位为分。 */
+        @Schema(description = "剩余可退总金额，单位分")
+        private Long refundPrice;
+    }
+
+    /**
+     * 单笔订单的批量退款预览信息。
+     */
+    @Data
+    @Schema(description = "批量退款订单预览明细")
+    public static class OrderItem {
+
+        /** Hardware 订单主键，也是异步任务逐笔退款的稳定业务标识。 */
+        @Schema(description = "订单主键")
+        private Long orderId;
+
+        /** 订单业务编号；历史数据可能为空。 */
+        @Schema(description = "订单业务编号")
+        private String orderNo;
+
+        /** 优先取预约用餐日期，其次取支付日期，最后取订单创建日期。 */
+        @Schema(description = "退款预览业务日期")
+        private LocalDate businessDate;
+
+        /** 用餐餐段字典编码；非餐饮或历史订单可能为空。 */
+        @Schema(description = "用餐餐段字典编码")
+        private String hourType;
+
+        /** 实际订餐用户主键；匿名或历史订单可能为空。 */
+        @Schema(description = "订餐用户主键")
+        private Long userId;
+
+        /** 实际订餐人姓名；无法关联用户资料时为空。 */
+        @Schema(description = "订餐人姓名")
+        private String username;
+
+        /** 订餐人下单时关联部门名称；历史数据可能为空。 */
+        @Schema(description = "订餐人部门名称")
+        private String userDeptName;
+
+        /** 订单所属商户名称；无法关联商户资料时为空。 */
+        @Schema(description = "商户名称")
+        private String merchantName;
+
+        /** 当前已完成退款后剩余可退金额，单位为分。 */
+        @Schema(description = "剩余可退金额，单位分")
+        private Integer refundPrice;
+
+        /** 是否通过当前批量退款资格校验。 */
+        @Schema(description = "是否可以退款")
+        private Boolean refundable;
+
+        /** 不可退款原因；可退款时为空。 */
+        @Schema(description = "不可退款原因")
+        private String unavailableReason;
+
+        /** 当前订单扣除待审核和已完成售后占用后的剩余商品。 */
+        @Schema(description = "剩余可退商品")
+        private List<ProductItem> products;
+    }
+
+    /**
+     * 单个商品的剩余可退数量、重量和商品金额。
+     */
+    @Data
+    @Schema(description = "批量退款商品预览明细")
+    public static class ProductItem {
+
+        /** 原订单购物车快照中的商品主键。 */
+        @Schema(description = "商品主键")
+        private Long productId;
+
+        /** 原订单购物车快照中的商品名称，不回查可能已改名的商品主数据。 */
+        @Schema(description = "商品名称")
+        private String productName;
+
+        /** 商品性质字典编码，用于区分数量商品和称重商品。 */
+        @Schema(description = "商品性质字典编码")
+        private String productNature;
+
+        /** 数量商品的剩余可退份数；称重商品固定为零。 */
+        @Schema(description = "剩余可退份数")
+        private Integer productCount;
+
+        /** 称重商品的剩余可退重量；数量商品固定为零。 */
+        @Schema(description = "剩余可退重量")
+        private BigDecimal productWeight;
+
+        /** 原购物车商品总价扣除有效售后占用后的剩余可退金额，单位为分。 */
+        @Schema(description = "剩余可退商品金额，单位分")
+        private Long refundPrice;
+    }
+}