feat(order): 添加退货功能模块并修复订单字段类型

- 新增退货主服务接口及实现类
- 新增退货商品明细服务接口及实现类
- 添加退货主和退货商品明细的实体类、业务对象和视图对象
- 创建退货主和退货商品明细的控制器
- 添加退货相关的数据访问层和映射文件
- 修复OrderMain中spiltStatus和isSplitChild字段类型从Long改为String
- 统一OrderMainBo和OrderMainVo中拆单状态字段名为splitStatus

ruoyi-common/ruoyi-common-core/src/main/java/org/dromara/common/core/enums/OrderSplitStatus.java

@@ -0,0 +1,27 @@
+package org.dromara.common.core.enums;
+
+import lombok.AllArgsConstructor;
+import lombok.Getter;
+
+/**
+ * 用户状态
+ *
+ * @author ruoyi
+ */
+@Getter
+@AllArgsConstructor
+public enum OrderSplitStatus {
+    /**
+     * 未拆单
+     */
+    WAIT_SPLIT("0", "未拆单"),
+    /**
+     * 已拆单
+     */
+    SPLITED("1", "已拆单");
+
+
+    private final String code;
+    private final String info;
+
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/controller/OrderReturnController.java

@@ -0,0 +1,106 @@
+package org.dromara.order.controller;
+
+import java.util.List;
+
+import lombok.RequiredArgsConstructor;
+import jakarta.servlet.http.HttpServletResponse;
+import jakarta.validation.constraints.*;
+import cn.dev33.satoken.annotation.SaCheckPermission;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.validation.annotation.Validated;
+import org.dromara.common.idempotent.annotation.RepeatSubmit;
+import org.dromara.common.log.annotation.Log;
+import org.dromara.common.web.core.BaseController;
+import org.dromara.common.mybatis.core.page.PageQuery;
+import org.dromara.common.core.domain.R;
+import org.dromara.common.core.validate.AddGroup;
+import org.dromara.common.core.validate.EditGroup;
+import org.dromara.common.log.enums.BusinessType;
+import org.dromara.common.excel.utils.ExcelUtil;
+import org.dromara.order.domain.vo.OrderReturnVo;
+import org.dromara.order.domain.bo.OrderReturnBo;
+import org.dromara.order.service.IOrderReturnService;
+import org.dromara.common.mybatis.core.page.TableDataInfo;
+
+/**
+ * 退货主
+ * 前端访问路由地址为:/order/orderReturn
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+@Validated
+@RequiredArgsConstructor
+@RestController
+@RequestMapping("/orderReturn")
+public class OrderReturnController extends BaseController {
+
+    private final IOrderReturnService orderReturnService;
+
+    /**
+     * 查询退货主列表
+     */
+//    @SaCheckPermission("order:orderReturn:list")
+    @GetMapping("/list")
+    public TableDataInfo<OrderReturnVo> list(OrderReturnBo bo, PageQuery pageQuery) {
+        return orderReturnService.queryPageList(bo, pageQuery);
+    }
+
+    /**
+     * 导出退货主列表
+     */
+//    @SaCheckPermission("order:orderReturn:export")
+    @Log(title = "退货主", businessType = BusinessType.EXPORT)
+    @PostMapping("/export")
+    public void export(OrderReturnBo bo, HttpServletResponse response) {
+        List<OrderReturnVo> list = orderReturnService.queryList(bo);
+        ExcelUtil.exportExcel(list, "退货主", OrderReturnVo.class, response);
+    }
+
+    /**
+     * 获取退货主详细信息
+     *
+     * @param id 主键
+     */
+//    @SaCheckPermission("order:orderReturn:query")
+    @GetMapping("/{id}")
+    public R<OrderReturnVo> getInfo(@NotNull(message = "主键不能为空")
+                                    @PathVariable("id") Long id) {
+        return R.ok(orderReturnService.queryById(id));
+    }
+
+    /**
+     * 新增退货主
+     */
+//    @SaCheckPermission("order:orderReturn:add")
+    @Log(title = "退货主", businessType = BusinessType.INSERT)
+    @RepeatSubmit()
+    @PostMapping()
+    public R<Void> add(@Validated(AddGroup.class) @RequestBody OrderReturnBo bo) {
+        return toAjax(orderReturnService.insertByBo(bo));
+    }
+
+    /**
+     * 修改退货主
+     */
+//    @SaCheckPermission("order:orderReturn:edit")
+    @Log(title = "退货主", businessType = BusinessType.UPDATE)
+    @RepeatSubmit()
+    @PutMapping()
+    public R<Void> edit(@Validated(EditGroup.class) @RequestBody OrderReturnBo bo) {
+        return toAjax(orderReturnService.updateByBo(bo));
+    }
+
+    /**
+     * 删除退货主
+     *
+     * @param ids 主键串
+     */
+//    @SaCheckPermission("order:orderReturn:remove")
+    @Log(title = "退货主", businessType = BusinessType.DELETE)
+    @DeleteMapping("/{ids}")
+    public R<Void> remove(@NotEmpty(message = "主键不能为空")
+                          @PathVariable("ids") Long[] ids) {
+        return toAjax(orderReturnService.deleteWithValidByIds(List.of(ids), true));
+    }
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/controller/OrderReturnItemController.java

@@ -0,0 +1,106 @@
+package org.dromara.order.controller;
+
+import java.util.List;
+
+import lombok.RequiredArgsConstructor;
+import jakarta.servlet.http.HttpServletResponse;
+import jakarta.validation.constraints.*;
+import cn.dev33.satoken.annotation.SaCheckPermission;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.validation.annotation.Validated;
+import org.dromara.common.idempotent.annotation.RepeatSubmit;
+import org.dromara.common.log.annotation.Log;
+import org.dromara.common.web.core.BaseController;
+import org.dromara.common.mybatis.core.page.PageQuery;
+import org.dromara.common.core.domain.R;
+import org.dromara.common.core.validate.AddGroup;
+import org.dromara.common.core.validate.EditGroup;
+import org.dromara.common.log.enums.BusinessType;
+import org.dromara.common.excel.utils.ExcelUtil;
+import org.dromara.order.domain.vo.OrderReturnItemVo;
+import org.dromara.order.domain.bo.OrderReturnItemBo;
+import org.dromara.order.service.IOrderReturnItemService;
+import org.dromara.common.mybatis.core.page.TableDataInfo;
+
+/**
+ * 退货商品明细
+ * 前端访问路由地址为:/order/orderReturnItem
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+@Validated
+@RequiredArgsConstructor
+@RestController
+@RequestMapping("/orderReturnItem")
+public class OrderReturnItemController extends BaseController {
+
+    private final IOrderReturnItemService orderReturnItemService;
+
+    /**
+     * 查询退货商品明细列表
+     */
+//    @SaCheckPermission("order:orderReturnItem:list")
+    @GetMapping("/list")
+    public TableDataInfo<OrderReturnItemVo> list(OrderReturnItemBo bo, PageQuery pageQuery) {
+        return orderReturnItemService.queryPageList(bo, pageQuery);
+    }
+
+    /**
+     * 导出退货商品明细列表
+     */
+//    @SaCheckPermission("order:orderReturnItem:export")
+    @Log(title = "退货商品明细", businessType = BusinessType.EXPORT)
+    @PostMapping("/export")
+    public void export(OrderReturnItemBo bo, HttpServletResponse response) {
+        List<OrderReturnItemVo> list = orderReturnItemService.queryList(bo);
+        ExcelUtil.exportExcel(list, "退货商品明细", OrderReturnItemVo.class, response);
+    }
+
+    /**
+     * 获取退货商品明细详细信息
+     *
+     * @param id 主键
+     */
+//    @SaCheckPermission("order:orderReturnItem:query")
+    @GetMapping("/{id}")
+    public R<OrderReturnItemVo> getInfo(@NotNull(message = "主键不能为空")
+                                        @PathVariable("id") Long id) {
+        return R.ok(orderReturnItemService.queryById(id));
+    }
+
+    /**
+     * 新增退货商品明细
+     */
+//    @SaCheckPermission("order:orderReturnItem:add")
+    @Log(title = "退货商品明细", businessType = BusinessType.INSERT)
+    @RepeatSubmit()
+    @PostMapping()
+    public R<Void> add(@Validated(AddGroup.class) @RequestBody OrderReturnItemBo bo) {
+        return toAjax(orderReturnItemService.insertByBo(bo));
+    }
+
+    /**
+     * 修改退货商品明细
+     */
+//    @SaCheckPermission("order:orderReturnItem:edit")
+    @Log(title = "退货商品明细", businessType = BusinessType.UPDATE)
+    @RepeatSubmit()
+    @PutMapping()
+    public R<Void> edit(@Validated(EditGroup.class) @RequestBody OrderReturnItemBo bo) {
+        return toAjax(orderReturnItemService.updateByBo(bo));
+    }
+
+    /**
+     * 删除退货商品明细
+     *
+     * @param ids 主键串
+     */
+//    @SaCheckPermission("order:orderReturnItem:remove")
+    @Log(title = "退货商品明细", businessType = BusinessType.DELETE)
+    @DeleteMapping("/{ids}")
+    public R<Void> remove(@NotEmpty(message = "主键不能为空")
+                          @PathVariable("ids") Long[] ids) {
+        return toAjax(orderReturnItemService.deleteWithValidByIds(List.of(ids), true));
+    }
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/domain/OrderMain.java

@@ -188,12 +188,12 @@ public class OrderMain extends TenantEntity {
     /**
      * 拆单状态：0=未拆, 1=已拆出子单
      */
-    private Long spiltStatus;
+    private String splitStatus;
 
     /**
      * 是否为拆分子单：0=是, 1=否
      */
-    private Long isSplitChild;
+    private String isSplitChild;
 
     /**
      * 包裹数量

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/domain/OrderReturn.java

@@ -0,0 +1,220 @@
+package org.dromara.order.domain;
+
+import org.dromara.common.tenant.core.TenantEntity;
+import com.baomidou.mybatisplus.annotation.*;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import java.math.BigDecimal;
+import java.util.Date;
+import com.fasterxml.jackson.annotation.JsonFormat;
+
+import java.io.Serial;
+
+/**
+ * 退货主对象 order_return
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("order_return")
+public class OrderReturn extends TenantEntity {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 主键ID
+     */
+    @TableId(value = "id")
+    private Long id;
+
+    /**
+     * 原订单id
+     */
+    private Long orderId;
+
+    /**
+     * 原订单编号
+     */
+    private String orderNo;
+
+    /**
+     * 售后服务类型（如：退货、换货、仅退款等）
+     */
+    private String serviceType;
+
+    /**
+     * 退货申请时间
+     */
+    private Date returnTime;
+
+    /**
+     * 退货单号
+     */
+    private String returnNo;
+
+    /**
+     * 客户编号
+     */
+    private Long customerId;
+
+    /**
+     * 客户编号
+     */
+    private String customerNo;
+
+    /**
+     * 客户姓名
+     */
+    private String customerName;
+
+    /**
+     * 售后金额
+     */
+    private Long afterSaleAmount;
+
+    /**
+     * 退货订单状态
+     */
+    private String returnStatus;
+
+    /**
+     * 退货商品总数量
+     */
+    private Long returnProductNum;
+
+    /**
+     * 处理完成时间
+     */
+    private Date processingTime;
+
+    /**
+     * 退货原因id
+     */
+    private Long returnReasonId;
+
+    /**
+     * 退货原因
+     */
+    private String returnReason;
+
+    /**
+     * 问题描述
+     */
+    private String problemDescription;
+
+    /**
+     * 凭证图片URL
+     */
+    private String voucherPhoto;
+
+    /**
+     * 运费金额
+     */
+    private BigDecimal shippingFee;
+
+    /**
+     * 是否承担运费
+     */
+    private String isShippingFee;
+
+    /**
+     * 原订单总金额
+     */
+    private BigDecimal orderAmount;
+
+    /**
+     * 实际退款金额
+     */
+    private BigDecimal returnAmount;
+
+    /**
+     * 售后备注
+     */
+    private String afterSalesRemarks;
+
+    /**
+     * 退货方式（如：上门取件、自行寄回）
+     */
+    private String returnMethod;
+
+    /**
+     * 取件人姓名
+     */
+    private String chargebackName;
+
+    /**
+     * 取件联系电话
+     */
+    private String chargebackPhone;
+
+    /**
+     * 预约取件时间
+     */
+    private String chargebackPickupTime;
+
+    /**
+     * 取件省
+     */
+    private String chargebackProvincial;
+
+    /**
+     * 取件市
+     */
+    private String chargebackCity;
+
+    /**
+     * 取件区/县
+     */
+    private String chargebackCounty;
+
+    /**
+     * 取件区/县
+     */
+    private String provincialCityCounty;
+
+    /**
+     * 取件详细地址
+     */
+    private String chargebackAddress;
+
+    /**
+     * 推送状态（如：0-未推送, 1-已推送）
+     */
+    private String pushStatus;
+
+    /**
+     * 物流公司id
+     */
+    private Long logisticsId;
+
+    /**
+     * 物流公司名称
+     */
+    private String logisticsName;
+
+    /**
+     * 物流单号
+     */
+    private String logisticsNo;
+
+    /**
+     * 状态（0正常 1停用）
+     */
+    private String status;
+
+    /**
+     * 删除标志（0代表存在 2代表删除）
+     */
+    @TableLogic
+    private String delFlag;
+
+    /**
+     * 备注
+     */
+    private String remark;
+
+
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/domain/OrderReturnItem.java

@@ -0,0 +1,88 @@
+package org.dromara.order.domain;
+
+import org.dromara.common.tenant.core.TenantEntity;
+import com.baomidou.mybatisplus.annotation.*;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import java.math.BigDecimal;
+
+import java.io.Serial;
+
+/**
+ * 退货商品明细对象 order_return_item
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@TableName("order_return_item")
+public class OrderReturnItem extends TenantEntity {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 主键ID
+     */
+    @TableId(value = "id")
+    private Long id;
+
+    /**
+     * 关联的退货单ID
+     */
+    private Long returnId;
+
+    /**
+     * 原订单明细ID
+     */
+    private Long orderProductId;
+
+    /**
+     * 商品SKU编码
+     */
+    private String productSku;
+
+    /**
+     * 商品名称
+     */
+    private String productName;
+
+    /**
+     * 本次退货数量
+     */
+    private Long returnQuantity;
+
+    /**
+     * 商品单价
+     */
+    private BigDecimal unitPrice;
+
+    /**
+     * 该项退货总金额
+     */
+    private BigDecimal totalAmount;
+
+    /**
+     * 该商品的具体退货原因
+     */
+    private String reasonDetail;
+
+    /**
+     * 状态（0正常 1停用）
+     */
+    private String status;
+
+    /**
+     * 删除标志（0代表存在 2代表删除）
+     */
+    @TableLogic
+    private String delFlag;
+
+    /**
+     * 备注
+     */
+    private String remark;
+
+
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/domain/bo/OrderMainBo.java

@@ -189,7 +189,7 @@ public class OrderMainBo extends BaseEntity {
     /**
      * 拆单状态：0=未拆, 1=已拆出子单
      */
-    private Long spiltStatus;
+    private Long splitStatus;
 
     /**
      * 是否为拆分子单：0=是, 1=否

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/domain/bo/OrderReturnBo.java

@@ -0,0 +1,217 @@
+package org.dromara.order.domain.bo;
+
+import org.dromara.order.domain.OrderReturn;
+import org.dromara.common.mybatis.core.domain.BaseEntity;
+import org.dromara.common.core.validate.AddGroup;
+import org.dromara.common.core.validate.EditGroup;
+import io.github.linpeilie.annotations.AutoMapper;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import jakarta.validation.constraints.*;
+
+import java.math.BigDecimal;
+import java.util.Date;
+import java.util.List;
+
+import com.fasterxml.jackson.annotation.JsonFormat;
+
+/**
+ * 退货主业务对象 order_return
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@AutoMapper(target = OrderReturn.class, reverseConvertGenerate = false)
+public class OrderReturnBo extends BaseEntity {
+
+    /**
+     * 主键ID
+     */
+    private Long id;
+
+    /**
+     * 原订单id
+     */
+    private Long orderId;
+
+    /**
+     * 原订单编号
+     */
+    private String orderNo;
+
+    /**
+     * 售后服务类型（如：退货、换货、仅退款等）
+     */
+    private String serviceType;
+
+    /**
+     * 退货申请时间
+     */
+    private Date returnTime;
+
+    /**
+     * 退货单号
+     */
+    private String returnNo;
+
+    /**
+     * 客户编号
+     */
+    private Long customerId;
+
+    /**
+     * 客户编号
+     */
+    private String customerNo;
+
+    /**
+     * 客户姓名
+     */
+    private String customerName;
+
+    /**
+     * 售后金额
+     */
+    private Long afterSaleAmount;
+
+    /**
+     * 退货订单状态
+     */
+    private String returnStatus;
+
+    /**
+     * 退货商品总数量
+     */
+    private Long returnProductNum;
+
+    /**
+     * 处理完成时间
+     */
+    private Date processingTime;
+
+    /**
+     * 退货原因id
+     */
+    private Long returnReasonId;
+
+    /**
+     * 退货原因
+     */
+    private String returnReason;
+
+    /**
+     * 问题描述
+     */
+    private String problemDescription;
+
+    /**
+     * 凭证图片URL
+     */
+    private String voucherPhoto;
+
+    /**
+     * 运费金额
+     */
+    private BigDecimal shippingFee;
+
+    /**
+     * 是否承担运费
+     */
+    private String isShippingFee;
+
+    /**
+     * 原订单总金额
+     */
+    private BigDecimal orderAmount;
+
+    /**
+     * 实际退款金额
+     */
+    private BigDecimal returnAmount;
+
+    /**
+     * 售后备注
+     */
+    private String afterSalesRemarks;
+
+    /**
+     * 退货方式（如：上门取件、自行寄回）
+     */
+    private String returnMethod;
+
+    /**
+     * 取件人姓名
+     */
+    private String chargebackName;
+
+    /**
+     * 取件联系电话
+     */
+    private String chargebackPhone;
+
+    /**
+     * 预约取件时间
+     */
+    private String chargebackPickupTime;
+
+    /**
+     * 取件省
+     */
+    private String chargebackProvincial;
+
+    /**
+     * 取件市
+     */
+    private String chargebackCity;
+
+    /**
+     * 取件区/县
+     */
+    private String chargebackCounty;
+
+    /**
+     * 取件区/县
+     */
+    private String provincialCityCounty;
+
+    /**
+     * 取件详细地址
+     */
+    private String chargebackAddress;
+
+    /**
+     * 推送状态（如：0-未推送, 1-已推送）
+     */
+    private String pushStatus;
+
+    /**
+     * 物流公司id
+     */
+    private Long logisticsId;
+
+    /**
+     * 物流公司名称
+     */
+    private String logisticsName;
+
+    /**
+     * 物流单号
+     */
+    private String logisticsNo;
+
+    /**
+     * 状态（0正常 1停用）
+     */
+    private String status;
+
+    /**
+     * 备注
+     */
+    private String remark;
+
+    private List<OrderReturnItemBo> orderReturnItemList;
+
+
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/domain/bo/OrderReturnItemBo.java

@@ -0,0 +1,80 @@
+package org.dromara.order.domain.bo;
+
+import org.dromara.order.domain.OrderReturnItem;
+import org.dromara.common.mybatis.core.domain.BaseEntity;
+import org.dromara.common.core.validate.AddGroup;
+import org.dromara.common.core.validate.EditGroup;
+import io.github.linpeilie.annotations.AutoMapper;
+import lombok.Data;
+import lombok.EqualsAndHashCode;
+import jakarta.validation.constraints.*;
+import java.math.BigDecimal;
+
+/**
+ * 退货商品明细业务对象 order_return_item
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+@Data
+@EqualsAndHashCode(callSuper = true)
+@AutoMapper(target = OrderReturnItem.class, reverseConvertGenerate = false)
+public class OrderReturnItemBo extends BaseEntity {
+
+    /**
+     * 主键ID
+     */
+    private Long id;
+
+    /**
+     * 关联的退货单ID
+     */
+    private Long returnId;
+
+    /**
+     * 原订单明细ID
+     */
+    private Long orderProductId;
+
+    /**
+     * 商品SKU编码
+     */
+    private String productSku;
+
+    /**
+     * 商品名称
+     */
+    private String productName;
+
+    /**
+     * 本次退货数量
+     */
+    private Long returnQuantity;
+
+    /**
+     * 商品单价
+     */
+    private BigDecimal unitPrice;
+
+    /**
+     * 该项退货总金额
+     */
+    private BigDecimal totalAmount;
+
+    /**
+     * 该商品的具体退货原因
+     */
+    private String reasonDetail;
+
+    /**
+     * 状态（0正常 1停用）
+     */
+    private String status;
+
+    /**
+     * 备注
+     */
+    private String remark;
+
+
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/domain/bo/OrderSplitAssignBo.java

@@ -0,0 +1,18 @@
+package org.dromara.order.domain.bo;
+
+import lombok.Data;
+import org.dromara.order.domain.OrderProductAssignRule;
+
+import java.util.List;
+
+@Data
+public class OrderSplitAssignBo {
+
+    private Long orderId; // 父订单ID
+
+    private List<OrderProductAssignRule> itemRules; // 商品分配规则
+
+    private String remark;
+
+
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/domain/vo/OrderMainVo.java

@@ -339,7 +339,7 @@ public class OrderMainVo implements Serializable {
     /**
      * 拆单状态：0=未拆, 1=已拆出子单
      */
-    private Long spiltStatus;
+    private Long splitStatus;
 
     /**
      * 是否为拆分子单：0=是, 1=否

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/domain/vo/OrderReturnItemVo.java

@@ -0,0 +1,100 @@
+package org.dromara.order.domain.vo;
+
+import java.math.BigDecimal;
+import org.dromara.order.domain.OrderReturnItem;
+import cn.idev.excel.annotation.ExcelIgnoreUnannotated;
+import cn.idev.excel.annotation.ExcelProperty;
+import org.dromara.common.excel.annotation.ExcelDictFormat;
+import org.dromara.common.excel.convert.ExcelDictConvert;
+import io.github.linpeilie.annotations.AutoMapper;
+import lombok.Data;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.Date;
+
+
+
+/**
+ * 退货商品明细视图对象 order_return_item
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+@Data
+@ExcelIgnoreUnannotated
+@AutoMapper(target = OrderReturnItem.class)
+public class OrderReturnItemVo implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 主键ID
+     */
+    @ExcelProperty(value = "主键ID")
+    private Long id;
+
+    /**
+     * 关联的退货单ID
+     */
+    @ExcelProperty(value = "关联的退货单ID")
+    private Long returnId;
+
+    /**
+     * 原订单明细ID
+     */
+    @ExcelProperty(value = "原订单明细ID")
+    private Long orderProductId;
+
+    /**
+     * 商品SKU编码
+     */
+    @ExcelProperty(value = "商品SKU编码")
+    private String productSku;
+
+    /**
+     * 商品名称
+     */
+    @ExcelProperty(value = "商品名称")
+    private String productName;
+
+    /**
+     * 本次退货数量
+     */
+    @ExcelProperty(value = "本次退货数量")
+    private Long returnQuantity;
+
+    /**
+     * 商品单价
+     */
+    @ExcelProperty(value = "商品单价")
+    private BigDecimal unitPrice;
+
+    /**
+     * 该项退货总金额
+     */
+    @ExcelProperty(value = "该项退货总金额")
+    private BigDecimal totalAmount;
+
+    /**
+     * 该商品的具体退货原因
+     */
+    @ExcelProperty(value = "该商品的具体退货原因")
+    private String reasonDetail;
+
+    /**
+     * 状态（0正常 1停用）
+     */
+    @ExcelProperty(value = "状态", converter = ExcelDictConvert.class)
+    @ExcelDictFormat(readConverterExp = "0=正常,1=停用")
+    private String status;
+
+    /**
+     * 备注
+     */
+    @ExcelProperty(value = "备注")
+    private String remark;
+
+
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/domain/vo/OrderReturnVo.java

@@ -0,0 +1,267 @@
+package org.dromara.order.domain.vo;
+
+import java.math.BigDecimal;
+import java.util.Date;
+
+import com.fasterxml.jackson.annotation.JsonFormat;
+import org.dromara.order.domain.OrderReturn;
+import cn.idev.excel.annotation.ExcelIgnoreUnannotated;
+import cn.idev.excel.annotation.ExcelProperty;
+import org.dromara.common.excel.annotation.ExcelDictFormat;
+import org.dromara.common.excel.convert.ExcelDictConvert;
+import io.github.linpeilie.annotations.AutoMapper;
+import lombok.Data;
+import org.dromara.order.domain.bo.OrderReturnItemBo;
+
+import java.io.Serial;
+import java.io.Serializable;
+import java.util.Date;
+import java.util.List;
+
+
+/**
+ * 退货主视图对象 order_return
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+@Data
+@ExcelIgnoreUnannotated
+@AutoMapper(target = OrderReturn.class)
+public class OrderReturnVo implements Serializable {
+
+    @Serial
+    private static final long serialVersionUID = 1L;
+
+    /**
+     * 主键ID
+     */
+    @ExcelProperty(value = "主键ID")
+    private Long id;
+
+    /**
+     * 原订单id
+     */
+    @ExcelProperty(value = "原订单id")
+    private Long orderId;
+
+    /**
+     * 原订单编号
+     */
+    @ExcelProperty(value = "原订单编号")
+    private String orderNo;
+
+    /**
+     * 售后服务类型（如：退货、换货、仅退款等）
+     */
+    @ExcelProperty(value = "售后服务类型", converter = ExcelDictConvert.class)
+    @ExcelDictFormat(readConverterExp = "如=：退货、换货、仅退款等")
+    private String serviceType;
+
+    /**
+     * 退货申请时间
+     */
+    @ExcelProperty(value = "退货申请时间")
+    private Date returnTime;
+
+    /**
+     * 退货单号
+     */
+    @ExcelProperty(value = "退货单号")
+    private String returnNo;
+
+    /**
+     * 客户编号
+     */
+    @ExcelProperty(value = "客户编号")
+    private Long customerId;
+
+    /**
+     * 客户编号
+     */
+    @ExcelProperty(value = "客户编号")
+    private String customerNo;
+
+    /**
+     * 客户姓名
+     */
+    @ExcelProperty(value = "客户姓名")
+    private String customerName;
+
+    /**
+     * 售后金额
+     */
+    @ExcelProperty(value = "售后金额")
+    private Long afterSaleAmount;
+
+    /**
+     * 退货订单状态
+     */
+    @ExcelProperty(value = "退货订单状态", converter = ExcelDictConvert.class)
+    @ExcelDictFormat(dictType = "return_order_status")
+    private String returnStatus;
+
+    /**
+     * 退货商品总数量
+     */
+    @ExcelProperty(value = "退货商品总数量")
+    private Long returnProductNum;
+
+    /**
+     * 处理完成时间
+     */
+    @ExcelProperty(value = "处理完成时间")
+    private Date processingTime;
+
+    /**
+     * 退货原因id
+     */
+    @ExcelProperty(value = "退货原因id")
+    private Long returnReasonId;
+
+    /**
+     * 退货原因
+     */
+    @ExcelProperty(value = "退货原因")
+    private String returnReason;
+
+    /**
+     * 问题描述
+     */
+    @ExcelProperty(value = "问题描述")
+    private String problemDescription;
+
+    /**
+     * 凭证图片URL
+     */
+    @ExcelProperty(value = "凭证图片URL")
+    private String voucherPhoto;
+
+    /**
+     * 运费金额
+     */
+    @ExcelProperty(value = "运费金额")
+    private BigDecimal shippingFee;
+
+    /**
+     * 是否承担运费
+     */
+    @ExcelProperty(value = "是否承担运费")
+    private String isShippingFee;
+
+    /**
+     * 原订单总金额
+     */
+    @ExcelProperty(value = "原订单总金额")
+    private BigDecimal orderAmount;
+
+    /**
+     * 实际退款金额
+     */
+    @ExcelProperty(value = "实际退款金额")
+    private BigDecimal returnAmount;
+
+    /**
+     * 售后备注
+     */
+    @ExcelProperty(value = "售后备注")
+    private String afterSalesRemarks;
+
+    /**
+     * 退货方式（如：上门取件、自行寄回）
+     */
+    @ExcelProperty(value = "退货方式", converter = ExcelDictConvert.class)
+    @ExcelDictFormat(readConverterExp = "如=：上门取件、自行寄回")
+    private String returnMethod;
+
+    /**
+     * 取件人姓名
+     */
+    @ExcelProperty(value = "取件人姓名")
+    private String chargebackName;
+
+    /**
+     * 取件联系电话
+     */
+    @ExcelProperty(value = "取件联系电话")
+    private String chargebackPhone;
+
+    /**
+     * 预约取件时间
+     */
+    @ExcelProperty(value = "预约取件时间")
+    private String chargebackPickupTime;
+
+    /**
+     * 取件省
+     */
+    @ExcelProperty(value = "取件省")
+    private String chargebackProvincial;
+
+    /**
+     * 取件市
+     */
+    @ExcelProperty(value = "取件市")
+    private String chargebackCity;
+
+    /**
+     * 取件区/县
+     */
+    @ExcelProperty(value = "取件区/县")
+    private String chargebackCounty;
+
+    /**
+     * 取件区/县
+     */
+    @ExcelProperty(value = "取件区/县")
+    private String provincialCityCounty;
+
+    /**
+     * 取件详细地址
+     */
+    @ExcelProperty(value = "取件详细地址")
+    private String chargebackAddress;
+
+    /**
+     * 推送状态（如：0-未推送, 1-已推送）
+     */
+    @ExcelProperty(value = "推送状态", converter = ExcelDictConvert.class)
+    @ExcelDictFormat(readConverterExp = "如=：0-未推送,,1=-已推送")
+    private String pushStatus;
+
+    /**
+     * 物流公司id
+     */
+    @ExcelProperty(value = "物流公司id")
+    private Long logisticsId;
+
+    /**
+     * 物流公司名称
+     */
+    @ExcelProperty(value = "物流公司名称")
+    private String logisticsName;
+
+    /**
+     * 物流单号
+     */
+    @ExcelProperty(value = "物流单号")
+    private String logisticsNo;
+
+    /**
+     * 状态（0正常 1停用）
+     */
+    @ExcelProperty(value = "状态", converter = ExcelDictConvert.class)
+    @ExcelDictFormat(readConverterExp = "0=正常,1=停用")
+    private String status;
+
+    /**
+     * 备注
+     */
+    @ExcelProperty(value = "备注")
+    private String remark;
+
+    private Date createTime;
+
+    private List<OrderReturnItemVo> orderReturnItemList;
+
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/mapper/OrderReturnItemMapper.java

@@ -0,0 +1,18 @@
+package org.dromara.order.mapper;
+
+import org.apache.dubbo.remoting.http12.rest.Param;
+import org.dromara.order.domain.OrderReturnItem;
+import org.dromara.order.domain.vo.OrderReturnItemVo;
+import org.dromara.common.mybatis.core.mapper.BaseMapperPlus;
+
+/**
+ * 退货商品明细Mapper接口
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+public interface OrderReturnItemMapper extends BaseMapperPlus<OrderReturnItem, OrderReturnItemVo> {
+
+    void deleteByOrderReturnId(@Param("orderReturnId") Long orderReturnId);
+
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/mapper/OrderReturnMapper.java

@@ -0,0 +1,15 @@
+package org.dromara.order.mapper;
+
+import org.dromara.order.domain.OrderReturn;
+import org.dromara.order.domain.vo.OrderReturnVo;
+import org.dromara.common.mybatis.core.mapper.BaseMapperPlus;
+
+/**
+ * 退货主Mapper接口
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+public interface OrderReturnMapper extends BaseMapperPlus<OrderReturn, OrderReturnVo> {
+
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/service/IOrderReturnItemService.java

@@ -0,0 +1,70 @@
+package org.dromara.order.service;
+
+import com.baomidou.mybatisplus.extension.service.IService;
+import org.dromara.order.domain.OrderReturnItem;
+import org.dromara.order.domain.vo.OrderReturnItemVo;
+import org.dromara.order.domain.bo.OrderReturnItemBo;
+import org.dromara.common.mybatis.core.page.TableDataInfo;
+import org.dromara.common.mybatis.core.page.PageQuery;
+
+import java.util.Collection;
+import java.util.List;
+
+/**
+ * 退货商品明细Service接口
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+public interface IOrderReturnItemService extends IService<OrderReturnItem>{
+
+    /**
+     * 查询退货商品明细
+     *
+     * @param id 主键
+     * @return 退货商品明细
+     */
+    OrderReturnItemVo queryById(Long id);
+
+    /**
+     * 分页查询退货商品明细列表
+     *
+     * @param bo        查询条件
+     * @param pageQuery 分页参数
+     * @return 退货商品明细分页列表
+     */
+    TableDataInfo<OrderReturnItemVo> queryPageList(OrderReturnItemBo bo, PageQuery pageQuery);
+
+    /**
+     * 查询符合条件的退货商品明细列表
+     *
+     * @param bo 查询条件
+     * @return 退货商品明细列表
+     */
+    List<OrderReturnItemVo> queryList(OrderReturnItemBo bo);
+
+    /**
+     * 新增退货商品明细
+     *
+     * @param bo 退货商品明细
+     * @return 是否新增成功
+     */
+    Boolean insertByBo(OrderReturnItemBo bo);
+
+    /**
+     * 修改退货商品明细
+     *
+     * @param bo 退货商品明细
+     * @return 是否修改成功
+     */
+    Boolean updateByBo(OrderReturnItemBo bo);
+
+    /**
+     * 校验并批量删除退货商品明细信息
+     *
+     * @param ids     待删除的主键集合
+     * @param isValid 是否进行有效性校验
+     * @return 是否删除成功
+     */
+    Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/service/IOrderReturnService.java

@@ -0,0 +1,70 @@
+package org.dromara.order.service;
+
+import com.baomidou.mybatisplus.extension.service.IService;
+import org.dromara.order.domain.OrderReturn;
+import org.dromara.order.domain.vo.OrderReturnVo;
+import org.dromara.order.domain.bo.OrderReturnBo;
+import org.dromara.common.mybatis.core.page.TableDataInfo;
+import org.dromara.common.mybatis.core.page.PageQuery;
+
+import java.util.Collection;
+import java.util.List;
+
+/**
+ * 退货主Service接口
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+public interface IOrderReturnService extends IService<OrderReturn>{
+
+    /**
+     * 查询退货主
+     *
+     * @param id 主键
+     * @return 退货主
+     */
+    OrderReturnVo queryById(Long id);
+
+    /**
+     * 分页查询退货主列表
+     *
+     * @param bo        查询条件
+     * @param pageQuery 分页参数
+     * @return 退货主分页列表
+     */
+    TableDataInfo<OrderReturnVo> queryPageList(OrderReturnBo bo, PageQuery pageQuery);
+
+    /**
+     * 查询符合条件的退货主列表
+     *
+     * @param bo 查询条件
+     * @return 退货主列表
+     */
+    List<OrderReturnVo> queryList(OrderReturnBo bo);
+
+    /**
+     * 新增退货主
+     *
+     * @param bo 退货主
+     * @return 是否新增成功
+     */
+    Boolean insertByBo(OrderReturnBo bo);
+
+    /**
+     * 修改退货主
+     *
+     * @param bo 退货主
+     * @return 是否修改成功
+     */
+    Boolean updateByBo(OrderReturnBo bo);
+
+    /**
+     * 校验并批量删除退货主信息
+     *
+     * @param ids     待删除的主键集合
+     * @param isValid 是否进行有效性校验
+     * @return 是否删除成功
+     */
+    Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid);
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/service/impl/OrderReturnItemServiceImpl.java

@@ -0,0 +1,142 @@
+package org.dromara.order.service.impl;
+
+import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
+import org.dromara.common.core.utils.MapstructUtils;
+import org.dromara.common.core.utils.StringUtils;
+import org.dromara.common.mybatis.core.page.TableDataInfo;
+import org.dromara.common.mybatis.core.page.PageQuery;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.springframework.stereotype.Service;
+import org.dromara.order.domain.bo.OrderReturnItemBo;
+import org.dromara.order.domain.vo.OrderReturnItemVo;
+import org.dromara.order.domain.OrderReturnItem;
+import org.dromara.order.mapper.OrderReturnItemMapper;
+import org.dromara.order.service.IOrderReturnItemService;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Collection;
+
+/**
+ * 退货商品明细Service业务层处理
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+@Slf4j
+@RequiredArgsConstructor
+@Service
+public class OrderReturnItemServiceImpl  extends ServiceImpl<OrderReturnItemMapper, OrderReturnItem> implements IOrderReturnItemService {
+
+    private final OrderReturnItemMapper baseMapper;
+
+    /**
+     * 查询退货商品明细
+     *
+     * @param id 主键
+     * @return 退货商品明细
+     */
+    @Override
+    public OrderReturnItemVo queryById(Long id){
+        return baseMapper.selectVoById(id);
+    }
+
+    /**
+     * 分页查询退货商品明细列表
+     *
+     * @param bo        查询条件
+     * @param pageQuery 分页参数
+     * @return 退货商品明细分页列表
+     */
+    @Override
+    public TableDataInfo<OrderReturnItemVo> queryPageList(OrderReturnItemBo bo, PageQuery pageQuery) {
+        LambdaQueryWrapper<OrderReturnItem> lqw = buildQueryWrapper(bo);
+        Page<OrderReturnItemVo> result = baseMapper.selectVoPage(pageQuery.build(), lqw);
+        return TableDataInfo.build(result);
+    }
+
+    /**
+     * 查询符合条件的退货商品明细列表
+     *
+     * @param bo 查询条件
+     * @return 退货商品明细列表
+     */
+    @Override
+    public List<OrderReturnItemVo> queryList(OrderReturnItemBo bo) {
+        LambdaQueryWrapper<OrderReturnItem> lqw = buildQueryWrapper(bo);
+        return baseMapper.selectVoList(lqw);
+    }
+
+    private LambdaQueryWrapper<OrderReturnItem> buildQueryWrapper(OrderReturnItemBo bo) {
+        Map<String, Object> params = bo.getParams();
+        LambdaQueryWrapper<OrderReturnItem> lqw = Wrappers.lambdaQuery();
+        lqw.orderByAsc(OrderReturnItem::getId);
+        lqw.eq(bo.getReturnId() != null, OrderReturnItem::getReturnId, bo.getReturnId());
+        lqw.eq(bo.getOrderProductId() != null, OrderReturnItem::getOrderProductId, bo.getOrderProductId());
+        lqw.eq(StringUtils.isNotBlank(bo.getProductSku()), OrderReturnItem::getProductSku, bo.getProductSku());
+        lqw.like(StringUtils.isNotBlank(bo.getProductName()), OrderReturnItem::getProductName, bo.getProductName());
+        lqw.eq(bo.getReturnQuantity() != null, OrderReturnItem::getReturnQuantity, bo.getReturnQuantity());
+        lqw.eq(bo.getUnitPrice() != null, OrderReturnItem::getUnitPrice, bo.getUnitPrice());
+        lqw.eq(bo.getTotalAmount() != null, OrderReturnItem::getTotalAmount, bo.getTotalAmount());
+        lqw.eq(StringUtils.isNotBlank(bo.getReasonDetail()), OrderReturnItem::getReasonDetail, bo.getReasonDetail());
+        lqw.eq(StringUtils.isNotBlank(bo.getStatus()), OrderReturnItem::getStatus, bo.getStatus());
+        lqw.eq(StringUtils.isNotBlank(bo.getPlatformCode()), OrderReturnItem::getPlatformCode, bo.getPlatformCode());
+        return lqw;
+    }
+
+    /**
+     * 新增退货商品明细
+     *
+     * @param bo 退货商品明细
+     * @return 是否新增成功
+     */
+    @Override
+    public Boolean insertByBo(OrderReturnItemBo bo) {
+        OrderReturnItem add = MapstructUtils.convert(bo, OrderReturnItem.class);
+        validEntityBeforeSave(add);
+        boolean flag = baseMapper.insert(add) > 0;
+        if (flag) {
+            bo.setId(add.getId());
+        }
+        return flag;
+    }
+
+    /**
+     * 修改退货商品明细
+     *
+     * @param bo 退货商品明细
+     * @return 是否修改成功
+     */
+    @Override
+    public Boolean updateByBo(OrderReturnItemBo bo) {
+        OrderReturnItem update = MapstructUtils.convert(bo, OrderReturnItem.class);
+        validEntityBeforeSave(update);
+        return baseMapper.updateById(update) > 0;
+    }
+
+    /**
+     * 保存前的数据校验
+     */
+    private void validEntityBeforeSave(OrderReturnItem entity){
+        //TODO 做一些数据校验,如唯一约束
+    }
+
+    /**
+     * 校验并批量删除退货商品明细信息
+     *
+     * @param ids     待删除的主键集合
+     * @param isValid 是否进行有效性校验
+     * @return 是否删除成功
+     */
+    @Override
+    public Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid) {
+        if(isValid){
+            //TODO 做一些业务上的校验,判断是否需要校验
+        }
+        return baseMapper.deleteByIds(ids) > 0;
+    }
+}

ruoyi-modules/ruoyi-order/src/main/java/org/dromara/order/service/impl/OrderReturnServiceImpl.java

@@ -0,0 +1,264 @@
+package org.dromara.order.service.impl;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.toolkit.Wrappers;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.baomidou.mybatisplus.extension.service.impl.ServiceImpl;
+import lombok.RequiredArgsConstructor;
+import lombok.extern.slf4j.Slf4j;
+import org.dromara.common.core.utils.MapstructUtils;
+import org.dromara.common.core.utils.StringUtils;
+import org.dromara.common.mybatis.core.page.PageQuery;
+import org.dromara.common.mybatis.core.page.TableDataInfo;
+import org.dromara.common.redis.utils.SequenceUtils;
+import org.dromara.order.domain.OrderMain;
+import org.dromara.order.domain.OrderReturn;
+import org.dromara.order.domain.OrderReturnItem;
+import org.dromara.order.domain.OrderRevenueHeader;
+import org.dromara.order.domain.bo.OrderReturnBo;
+import org.dromara.order.domain.bo.OrderReturnItemBo;
+import org.dromara.order.domain.vo.OrderReturnVo;
+import org.dromara.order.mapper.OrderReturnItemMapper;
+import org.dromara.order.mapper.OrderReturnMapper;
+import org.dromara.order.service.IOrderReturnService;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.util.Collection;
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.stream.Collectors;
+
+/**
+ * 退货主Service业务层处理
+ *
+ * @author LionLi
+ * @date 2026-01-05
+ */
+@Slf4j
+@RequiredArgsConstructor
+@Service
+public class OrderReturnServiceImpl extends ServiceImpl<OrderReturnMapper, OrderReturn> implements IOrderReturnService {
+
+    private final OrderReturnMapper baseMapper;
+
+    private final OrderReturnItemMapper orderReturnItemMapper;
+
+    /**
+     * 查询退货主
+     *
+     * @param id 主键
+     * @return 退货主
+     */
+    @Override
+    public OrderReturnVo queryById(Long id) {
+        OrderReturnVo orderReturnVo = baseMapper.selectVoById(id);
+        orderReturnVo.setOrderReturnItemList(orderReturnItemMapper.selectVoList(new LambdaQueryWrapper<OrderReturnItem>()
+            .eq(OrderReturnItem::getReturnId, orderReturnVo.getId())));
+        return baseMapper.selectVoById(id);
+    }
+
+    /**
+     * 分页查询退货主列表
+     *
+     * @param bo        查询条件
+     * @param pageQuery 分页参数
+     * @return 退货主分页列表
+     */
+    @Override
+    public TableDataInfo<OrderReturnVo> queryPageList(OrderReturnBo bo, PageQuery pageQuery) {
+        LambdaQueryWrapper<OrderReturn> lqw = buildQueryWrapper(bo);
+        Page<OrderReturnVo> result = baseMapper.selectVoPage(pageQuery.build(), lqw);
+        return TableDataInfo.build(result);
+    }
+
+    /**
+     * 查询符合条件的退货主列表
+     *
+     * @param bo 查询条件
+     * @return 退货主列表
+     */
+    @Override
+    public List<OrderReturnVo> queryList(OrderReturnBo bo) {
+        LambdaQueryWrapper<OrderReturn> lqw = buildQueryWrapper(bo);
+        return baseMapper.selectVoList(lqw);
+    }
+
+    private LambdaQueryWrapper<OrderReturn> buildQueryWrapper(OrderReturnBo bo) {
+        Map<String, Object> params = bo.getParams();
+        LambdaQueryWrapper<OrderReturn> lqw = Wrappers.lambdaQuery();
+        lqw.orderByAsc(OrderReturn::getId);
+        lqw.eq(bo.getOrderId() != null, OrderReturn::getOrderId, bo.getOrderId());
+        lqw.eq(StringUtils.isNotBlank(bo.getOrderNo()), OrderReturn::getOrderNo, bo.getOrderNo());
+        lqw.eq(StringUtils.isNotBlank(bo.getServiceType()), OrderReturn::getServiceType, bo.getServiceType());
+        lqw.eq(bo.getReturnTime() != null, OrderReturn::getReturnTime, bo.getReturnTime());
+        lqw.eq(StringUtils.isNotBlank(bo.getReturnNo()), OrderReturn::getReturnNo, bo.getReturnNo());
+        lqw.eq(bo.getCustomerId() != null, OrderReturn::getCustomerId, bo.getCustomerId());
+        lqw.eq(StringUtils.isNotBlank(bo.getCustomerNo()), OrderReturn::getCustomerNo, bo.getCustomerNo());
+        lqw.like(StringUtils.isNotBlank(bo.getCustomerName()), OrderReturn::getCustomerName, bo.getCustomerName());
+        lqw.eq(bo.getAfterSaleAmount() != null, OrderReturn::getAfterSaleAmount, bo.getAfterSaleAmount());
+        lqw.eq(StringUtils.isNotBlank(bo.getReturnStatus()), OrderReturn::getReturnStatus, bo.getReturnStatus());
+        lqw.eq(bo.getReturnProductNum() != null, OrderReturn::getReturnProductNum, bo.getReturnProductNum());
+        lqw.eq(bo.getProcessingTime() != null, OrderReturn::getProcessingTime, bo.getProcessingTime());
+        lqw.eq(bo.getReturnReasonId() != null, OrderReturn::getReturnReasonId, bo.getReturnReasonId());
+        lqw.eq(StringUtils.isNotBlank(bo.getReturnReason()), OrderReturn::getReturnReason, bo.getReturnReason());
+        lqw.eq(StringUtils.isNotBlank(bo.getProblemDescription()), OrderReturn::getProblemDescription, bo.getProblemDescription());
+        lqw.eq(StringUtils.isNotBlank(bo.getVoucherPhoto()), OrderReturn::getVoucherPhoto, bo.getVoucherPhoto());
+        lqw.eq(bo.getShippingFee() != null, OrderReturn::getShippingFee, bo.getShippingFee());
+        lqw.eq(StringUtils.isNotBlank(bo.getIsShippingFee()), OrderReturn::getIsShippingFee, bo.getIsShippingFee());
+        lqw.eq(bo.getOrderAmount() != null, OrderReturn::getOrderAmount, bo.getOrderAmount());
+        lqw.eq(bo.getReturnAmount() != null, OrderReturn::getReturnAmount, bo.getReturnAmount());
+        lqw.eq(StringUtils.isNotBlank(bo.getAfterSalesRemarks()), OrderReturn::getAfterSalesRemarks, bo.getAfterSalesRemarks());
+        lqw.eq(StringUtils.isNotBlank(bo.getReturnMethod()), OrderReturn::getReturnMethod, bo.getReturnMethod());
+        lqw.like(StringUtils.isNotBlank(bo.getChargebackName()), OrderReturn::getChargebackName, bo.getChargebackName());
+        lqw.eq(StringUtils.isNotBlank(bo.getChargebackPhone()), OrderReturn::getChargebackPhone, bo.getChargebackPhone());
+        lqw.eq(StringUtils.isNotBlank(bo.getChargebackPickupTime()), OrderReturn::getChargebackPickupTime, bo.getChargebackPickupTime());
+        lqw.eq(StringUtils.isNotBlank(bo.getChargebackProvincial()), OrderReturn::getChargebackProvincial, bo.getChargebackProvincial());
+        lqw.eq(StringUtils.isNotBlank(bo.getChargebackCity()), OrderReturn::getChargebackCity, bo.getChargebackCity());
+        lqw.eq(StringUtils.isNotBlank(bo.getChargebackCounty()), OrderReturn::getChargebackCounty, bo.getChargebackCounty());
+        lqw.eq(StringUtils.isNotBlank(bo.getProvincialCityCounty()), OrderReturn::getProvincialCityCounty, bo.getProvincialCityCounty());
+        lqw.eq(StringUtils.isNotBlank(bo.getChargebackAddress()), OrderReturn::getChargebackAddress, bo.getChargebackAddress());
+        lqw.eq(StringUtils.isNotBlank(bo.getPushStatus()), OrderReturn::getPushStatus, bo.getPushStatus());
+        lqw.eq(bo.getLogisticsId() != null, OrderReturn::getLogisticsId, bo.getLogisticsId());
+        lqw.like(StringUtils.isNotBlank(bo.getLogisticsName()), OrderReturn::getLogisticsName, bo.getLogisticsName());
+        lqw.eq(StringUtils.isNotBlank(bo.getLogisticsNo()), OrderReturn::getLogisticsNo, bo.getLogisticsNo());
+        lqw.eq(StringUtils.isNotBlank(bo.getStatus()), OrderReturn::getStatus, bo.getStatus());
+        if (params != null) {
+            lqw.between(params.get("beginTime") != null && params.get("endTime") != null,
+                OrderReturn::getCreateTime, params.get("beginTime"), params.get("endTime"));
+        }
+        return lqw;
+    }
+
+    /**
+     * 新增退货主
+     *
+     * @param bo 退货主
+     * @return 是否新增成功
+     */
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public Boolean insertByBo(OrderReturnBo bo) {
+
+        if (bo == null) {
+            log.warn("新增退货单失败：入参为空");
+            return false;
+        }
+
+        // 生成单号
+        bo.setReturnNo(SequenceUtils.generateOrderCode("OR"));
+
+        // 转换并校验
+        OrderReturn entity = MapstructUtils.convert(bo, OrderReturn.class);
+        validEntityBeforeSave(entity);
+
+        // 插入主表
+        boolean inserted = baseMapper.insert(entity) > 0;
+        if (!inserted) {
+            log.warn("插入退货单主表失败");
+            return false;
+        }
+
+        // 保存明细
+        saveOrderReturnItems(entity.getId(), bo.getOrderReturnItemList(), false);
+
+        log.info("新增退货单成功，单号: {}", entity.getReturnNo());
+        return true;
+    }
+
+    /**
+     * 修改退货主
+     *
+     * @param bo 退货主
+     * @return 是否修改成功
+     */
+    @Override
+    @Transactional(rollbackFor = Exception.class)
+    public Boolean updateByBo(OrderReturnBo bo) {
+
+        if (bo == null || bo.getId() == null) {
+            log.warn("修改退货单失败：BO 或 ID 为空");
+            return false;
+        }
+
+        // 检查主表记录是否存在
+        if (baseMapper.selectById(bo.getId()) == null) {
+            log.warn("修改退货单失败：主表记录不存在，ID={}", bo.getId());
+            return false;
+        }
+
+        // 转换并校验
+        OrderReturn entity = MapstructUtils.convert(bo, OrderReturn.class);
+        validEntityBeforeSave(entity);
+
+        // 更新主表
+        boolean updated = baseMapper.updateById(entity) > 0;
+        if (!updated) {
+            log.warn("更新退货单主表失败，ID={}", bo.getId());
+            return false;
+        }
+
+        // 先删后插明细
+        saveOrderReturnItems(bo.getId(), bo.getOrderReturnItemList(), true);
+
+        log.info("修改退货单成功，ID: {}", bo.getId());
+        return true;
+    }
+
+    /**
+     * 保存收入单明细
+     *
+     * @param orderReturnId 主表ID
+     * @param itemList      明细列表
+     * @param deleteFirst   是否先删除已有明细（true=编辑模式）
+     */
+    private void saveOrderReturnItems(Long orderReturnId, List<OrderReturnItemBo> itemList, boolean deleteFirst) {
+        if (orderReturnId == null) {
+            return;
+        }
+
+        if (deleteFirst) {
+            orderReturnItemMapper.deleteByOrderReturnId(orderReturnId);
+        }
+
+        if (itemList == null || itemList.isEmpty()) {
+            return;
+        }
+
+        List<OrderReturnItem> items = itemList.stream()
+            .filter(Objects::nonNull) // 防止空元素
+            .map(bo -> {
+                OrderReturnItem item = MapstructUtils.convert(bo, OrderReturnItem.class);
+                item.setReturnId(orderReturnId);
+                return item;
+            })
+            .collect(Collectors.toList());
+
+        if (!items.isEmpty()) {
+            orderReturnItemMapper.insertBatch(items);
+        }
+    }
+
+    /**
+     * 保存前的数据校验
+     */
+    private void validEntityBeforeSave(OrderReturn entity) {
+        //TODO 做一些数据校验,如唯一约束
+    }
+
+    /**
+     * 校验并批量删除退货主信息
+     *
+     * @param ids     待删除的主键集合
+     * @param isValid 是否进行有效性校验
+     * @return 是否删除成功
+     */
+    @Override
+    public Boolean deleteWithValidByIds(Collection<Long> ids, Boolean isValid) {
+        if (isValid) {
+            //TODO 做一些业务上的校验,判断是否需要校验
+        }
+        return baseMapper.deleteByIds(ids) > 0;
+    }
+}

ruoyi-modules/ruoyi-order/src/main/resources/mapper/order/OrderReturnItemMapper.xml

@@ -0,0 +1,14 @@
+<?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="org.dromara.order.mapper.OrderReturnItemMapper">
+
+    <delete id="deleteByOrderReturnId" parameterType="java.lang.Long">
+        DELETE
+        FROM order_return_item
+        WHERE return_id = #{orderReturnId}
+    </delete>
+
+
+</mapper>

ruoyi-modules/ruoyi-order/src/main/resources/mapper/order/OrderReturnMapper.xml

@@ -0,0 +1,7 @@
+<?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="org.dromara.order.mapper.OrderReturnMapper">
+
+</mapper>