Просмотр исходного кода

feat(order): 退款三阶段状态机 pending_refund/refunding/refunded + 回滚记录 + 确认到账端点

Xiaogang Liao 3 дней назад
Родитель
Сommit
64115b446f

+ 23 - 0
cfc-backend/src/main/java/com/etotem/cfc/controller/admin/AdminProductOrderController.java

@@ -217,4 +217,27 @@ public class AdminProductOrderController {
         String reason = (String) params.get("reason");
         return orderService.rejectRefund(orderNo, adminId, reason);
     }
+
+    @Operation(summary = "确认退款到账(PROCESSING 状态的退款中订单)")
+    @PostMapping("/refund/confirm-arrive")
+    public Result<String> confirmRefundArrive(@RequestBody Map<String, Object> params,
+                                              @RequestAttribute("userId") Long adminId,
+                                              @RequestAttribute("role") String role) {
+        // B-142-1:角色守卫——非 admin 不得越权确认到账
+        if (!"admin".equals(role)) {
+            return Result.forbidden("无权限");
+        }
+        return doConfirmRefundArrive(params, adminId);
+    }
+
+    /** 契约直调重载(非 HTTP 路由):锁定「委托 orderService.confirmRefundArrive」契约,HTTP 请走带角色守卫的路由重载。 */
+    public Result<String> confirmRefundArrive(@RequestBody Map<String, Object> params,
+                                              @RequestAttribute("userId") Long adminId) {
+        return doConfirmRefundArrive(params, adminId);
+    }
+
+    private Result<String> doConfirmRefundArrive(Map<String, Object> params, Long adminId) {
+        String orderNo = (String) params.get("orderNo");
+        return orderService.confirmRefundArrive(orderNo, adminId);
+    }
 }

+ 9 - 2
cfc-backend/src/main/java/com/etotem/cfc/service/AfterSalesService.java

@@ -55,7 +55,11 @@ public class AfterSalesService {
         // 写快照:在把订单置为 refunding 之前保存当前状态,供后续取消时回滚。
         order.setRefundBeforeStatus(order.getStatus());
         order.setRefundBeforeRefundStatus(order.getRefundStatus());
-        order.setStatus("refunding");
+        // 记录退款前状态,供驳回/取消时回滚(不再写死 paid)
+        order.setRefundBeforeStatus(order.getStatus());
+        order.setRefundBeforeRefundStatus(order.getRefundStatus() != null ? order.getRefundStatus() : 0);
+        // 用户申请售后 = 待退款(等后台审核),不是退款中
+        order.setStatus("pending_refund");
         order.setRefundStatus(1);
         order.setRefundReason(request.getReason());
         order.setRefundAmount(refundAmount);
@@ -161,7 +165,10 @@ public class AfterSalesService {
         if (order == null) {
             return Result.error("订单不存在");
         }
-        if (!"refunding".equals(order.getStatus()) || order.getRefundStatus() == null || order.getRefundStatus() != 1) {
+        // 取消窗口:用户申请后(待退款)、或已受理在途(退款中)均允许取消
+        String st = order.getStatus();
+        boolean inRefundFlow = "pending_refund".equals(st) || "refunding".equals(st);
+        if (!inRefundFlow || order.getRefundStatus() == null || order.getRefundStatus() != 1) {
             return Result.error("当前状态不可取消");
         }
         // 售后单置 cancelled

+ 4 - 3
cfc-backend/src/main/java/com/etotem/cfc/service/PaymentService.java

@@ -441,10 +441,10 @@ public class PaymentService implements PaymentServiceInterface {
         }
     }
 
-    public void refund(String orderNo, Integer amount, String reason) {
+    public String refund(String orderNo, Integer amount, String reason) {
         if (testMode) {
             log.info("【测试模式】跳过微信退款请求: orderNo={}, amount={}, reason={}", orderNo, amount, reason);
-            return;
+            return "SUCCESS";
         }
         try {
             PackageOrder order = getOrderStatus(orderNo);
@@ -473,11 +473,12 @@ public class PaymentService implements PaymentServiceInterface {
             log.info("微信退款结果: orderNo={}, outRefundNo={}, status={}", orderNo, outRefundNo, status);
 
             if ("SUCCESS".equals(status) || "PROCESSING".equals(status)) {
-                log.info("退款请求成功: orderNo={}, outRefundNo={}", orderNo, outRefundNo);
+                log.info("退款请求成功: orderNo={}, outRefundNo={}, status={}", orderNo, outRefundNo, status);
             } else {
                 log.error("微信退款失败: orderNo={}, response={}", orderNo, respBody);
                 throw new RuntimeException("退款失败: " + resp.getString("code") + " " + resp.getString("message"));
             }
+            return status; // SUCCESS=资金已退回;PROCESSING=已受理、到账中(银行卡 1-3 天)
         } catch (Exception e) {
             log.error("微信退款异常: orderNo={}", orderNo, e);
             throw new RuntimeException("退款失败: " + e.getMessage(), e);

+ 54 - 8
cfc-backend/src/main/java/com/etotem/cfc/service/ProductOrderService.java

@@ -1800,9 +1800,13 @@ public class ProductOrderService {
         if (order.getRefundStatus() != null && order.getRefundStatus() == 1) {
             return Result.error("已有退款申请正在处理中");
         }
-        order.setRefundStatus(1); // 申请中
+        // 记录退款前状态,供管理员驳回时回滚(写死 paid 会让「待收货」单驳回后错乱)
+        order.setRefundBeforeStatus(order.getStatus());
+        order.setRefundBeforeRefundStatus(order.getRefundStatus() != null ? order.getRefundStatus() : 0);
+        order.setRefundStatus(1); // 申请中(待后台审核)
         order.setRefundReason(reason);
-        order.setStatus("refunding");
+        // 用户申请退款 = 待退款(等后台审核),不是退款中
+        order.setStatus("pending_refund");
         order.setUpdatedAt(new Date());
         orderMapper.updateById(order);
         return Result.success("退款申请已提交");
@@ -1825,9 +1829,10 @@ public class ProductOrderService {
         if (refundAmount == null || refundAmount < 0) {
             refundAmount = order.getTotalAmount();
         }
+        String wxStatus = null; // 微信退款受理状态:SUCCESS=资金已退回;PROCESSING=已受理、到账中
         if (refundAmount != null && refundAmount > 0) {
             try {
-                paymentService.refund(orderNo, refundAmount, order.getRefundReason());
+                wxStatus = paymentService.refund(orderNo, refundAmount, order.getRefundReason());
             } catch (Exception e) {
                 if (e.getMessage() != null && e.getMessage().contains("NOT_ENOUGH")) {
                     pendingRefundService.createPendingRefund(order.getBuyerId(), null, refundAmount, "product", orderNo);
@@ -1847,6 +1852,27 @@ public class ProductOrderService {
             // 优惠券/积分全额抵扣、用户未付现金:直接走完退款流程,无需调微信退款接口
             log.info("订单实付金额为0(优惠券/积分全额抵扣),跳过微信退款: orderNo={}", orderNo);
         }
+        if ("PROCESSING".equals(wxStatus)) {
+            // 微信已受理、资金到账中(银行卡退款 1-3 天):置退款中,副作用延后到「确认到账」
+            order.setRefundStatus(2);
+            order.setRefundAmount(refundAmount);
+            order.setRefundTime(new Date());
+            order.setStatus("refunding");
+            order.setUpdatedAt(new Date());
+            orderMapper.updateById(order);
+            syncAfterSalesRequestStatus(orderNo, "approved", adminId);
+            log.info("退款已受理、到账中: orderNo={}", orderNo);
+            return Result.success("退款已受理,到账后将自动完成");
+        }
+        // SUCCESS 或全额抵扣路径:资金已退回,直接完成退款(含库存/券/CF 还原)
+        finalizeRefund(order, adminId, refundAmount);
+        syncAfterSalesRequestStatus(orderNo, "approved", adminId);
+        log.info("退款完成: orderNo={}, adminId={}", orderNo, adminId);
+        return Result.success("退款已处理");
+    }
+
+    /** 退款终态收尾:置已退款 + 库存回补 + 券/CF 还原 + 特价扣量回滚。SUCCESS 即时、确认到账时复用。 */
+    public void finalizeRefund(ProductOrder order, Long adminId, Integer refundAmount) {
         order.setRefundStatus(2);
         order.setRefundAmount(refundAmount);
         order.setRefundTime(new Date());
@@ -1859,11 +1885,11 @@ public class ProductOrderService {
             productService.increaseStock(order.getProductId(), order.getQuantity());
         }
         inventoryService.recordRefundInbound(order.getProductId(), null, order.getQuantity(),
-                "order", order.getId(), adminId, "退款:" + orderNo);
+                "order", order.getId(), adminId, "退款:" + order.getOrderNo());
         // 退款成功:归还优惠券;CF 兑换来的券同时退还 CF 值
         releaseCouponForCancelledOrder(order.getCouponId());
         // F-5:退还下单时抵扣的 CF 值(原路返还到购买人 member 账本)
-        refundOrderPoints(order, "退款退还CF值:" + orderNo);
+        refundOrderPoints(order, "退款退还CF值:" + order.getOrderNo());
         // 特价订单回滚扣量(与恢复库存并列,失败仅记日志不阻断退款)
         try {
             specialPriceService.releaseQuota(order.getSpecialDealId(), order.getQuantity());
@@ -1871,9 +1897,28 @@ public class ProductOrderService {
             log.warn("特价扣量回滚失败(refund): dealId={}, orderNo={}, err={}",
                     order.getSpecialDealId(), order.getOrderNo(), ex.getMessage());
         }
+    }
+
+    public Result<String> confirmRefundArrive(String orderNo, Long adminId) {
+        ProductOrder order = orderMapper.selectOne(
+            new LambdaQueryWrapper<ProductOrder>().eq(ProductOrder::getOrderNo, orderNo));
+        if (order == null) {
+            return Result.error("订单不存在");
+        }
+        if ("refunded".equals(order.getStatus())) {
+            return Result.success("已退款"); // 幂等:重复确认不重复副作用
+        }
+        if (!"refunding".equals(order.getStatus())) {
+            return Result.error("当前状态不可确认到账");
+        }
+        Integer refundAmount = order.getRefundAmount() != null ? order.getRefundAmount() : order.getMoneyAmount();
+        if (refundAmount == null || refundAmount < 0) {
+            refundAmount = order.getTotalAmount();
+        }
+        finalizeRefund(order, adminId, refundAmount);
         syncAfterSalesRequestStatus(orderNo, "approved", adminId);
-        log.info("退款完成: orderNo={}, adminId={}", orderNo, adminId);
-        return Result.success("退款已处理");
+        log.info("确认退款到账: orderNo={}, adminId={}", orderNo, adminId);
+        return Result.success("已确认到账,退款完成");
     }
 
     public Result<String> rejectRefund(String orderNo, Long adminId, String reason) {
@@ -1886,7 +1931,8 @@ public class ProductOrderService {
             return Result.error("没有待处理的退款申请");
         }
         order.setRefundStatus(3);
-        order.setStatus("paid");
+        // 回滚到申请退款前的状态(如待收货),不再写死 paid
+        order.setStatus(order.getRefundBeforeStatus() != null ? order.getRefundBeforeStatus() : "paid");
         order.setUpdatedAt(new Date());
         orderMapper.updateById(order);
         syncAfterSalesRequestStatus(orderNo, "rejected", adminId);

+ 14 - 9
cfc-backend/src/main/java/com/etotem/cfc/task/RefundScheduledTasks.java

@@ -156,21 +156,26 @@ public class RefundScheduledTasks {
 
         pendingRefundService.markProcessing(pendingRefund.getId());
 
-        paymentService.refund(orderNo, amount, "商品退款(待退款队列)");
+        String wxStatus = paymentService.refund(orderNo, amount, "商品退款(待退款队列)");
 
         LambdaQueryWrapper<ProductOrder> wrapper = new LambdaQueryWrapper<>();
         wrapper.eq(ProductOrder::getOrderNo, orderNo);
         SortUtil.applySort(wrapper);
         ProductOrder order = productOrderMapper.selectOne(wrapper);
         if (order != null) {
-            order.setRefundStatus(2);
-            order.setRefundAmount(amount);
-            order.setRefundTime(new Date());
-            order.setStatus("refunded");
-            order.setUpdatedAt(new Date());
-            productOrderMapper.updateById(order);
-            // 实际退款到账:归还优惠券;CF 兑换来的券同时退还 CF 值(管理员审批时因余额不足挂起的那一步在此补上)
-            productOrderService.releaseCouponForCancelledOrder(order.getCouponId());
+            if ("PROCESSING".equals(wxStatus)) {
+                // 微信已受理、资金到账中(银行卡 1-3 天):置退款中,副作用延后到「确认到账」
+                order.setRefundStatus(2);
+                order.setRefundAmount(amount);
+                order.setRefundTime(new Date());
+                order.setStatus("refunding");
+                order.setUpdatedAt(new Date());
+                productOrderMapper.updateById(order);
+                log.info("商品退款已受理、到账中:orderNo={}", orderNo);
+            } else {
+                // SUCCESS:资金已退回,统一走 finalizeRefund(库存/券/CF 还原 + 特价回滚,副作用只执行一次)
+                productOrderService.finalizeRefund(order, null, amount);
+            }
         }
 
         pendingRefundService.markSuccess(pendingRefund.getId(), amount);

+ 1 - 1
cfc-backend/src/test/java/com/etotem/cfc/unit/AfterSalesScS06ContractTest.java

@@ -95,7 +95,7 @@ class AfterSalesScS06ContractTest {
         assertEquals(200, result.getCode(), "申请售后应成功");
         assertEquals("pending", result.getData().getStatus());
         assertEquals(9900, result.getData().getRefundAmount());
-        assertEquals("refunding", order.getStatus(), "订单应转 refunding");
+        assertEquals("pending_refund", order.getStatus(), "用户申请售后后订单应为待退款(等后台审核)");
         verify(requestMapper).insert(any(AfterSalesRequest.class));
         verify(orderMapper).updateById(order);
     }

+ 67 - 6
cfc-backend/src/test/java/com/etotem/cfc/unit/OrderRefundScP56ScA12ContractTest.java

@@ -127,15 +127,17 @@ class OrderRefundScP56ScA12ContractTest {
     // ==================== 正常流(SC-P-56 申请退款) ====================
 
     @Test
-    void 正常流_申请退款_进入refunding() {
+    void 正常流_申请退款_进入待退款pending_refund_并记录回滚前状态() {
         ProductOrder order = orderOf("PO3", "paid", 1L);
         when(orderMapper.selectOne(any(com.baomidou.mybatisplus.core.conditions.Wrapper.class))).thenReturn(order);
 
         Result<String> result = service.applyRefund("PO3", 1L, "不想要了");
 
         assertEquals(200, result.getCode(), "申请退款应成功");
-        assertEquals("refunding", order.getStatus());
+        assertEquals("pending_refund", order.getStatus(), "用户申请退款后应为待退款(等后台审核),不是退款中");
         assertEquals(1, order.getRefundStatus().intValue());
+        assertEquals("paid", order.getRefundBeforeStatus(), "应记录退款前的订单状态,供驳回时回滚");
+        assertEquals(0, order.getRefundBeforeRefundStatus().intValue(), "应记录退款前的退款状态");
         verify(orderMapper).updateById(order);
     }
 
@@ -191,26 +193,71 @@ class OrderRefundScP56ScA12ContractTest {
     // ==================== 正常流(SC-A-12 平台处理) ====================
 
     @Test
-    void 正常流_管理员批准退款_原路退款并回补库存() {
-        ProductOrder order = orderOf("PO7", "refunding", 1L);
+    void 正常流_管理员批准退款_微信受理成功_原路退款并回补库存() {
+        ProductOrder order = orderOf("PO7", "pending_refund", 1L);
         order.setRefundStatus(1);
         order.setRefundReason("不想要了");
         when(orderMapper.selectOne(any(com.baomidou.mybatisplus.core.conditions.Wrapper.class))).thenReturn(order);
+        when(paymentService.refund(anyString(), anyInt(), anyString())).thenReturn("SUCCESS");
 
         Result<String> result = service.approveRefund("PO7", 1L);
 
         assertEquals(200, result.getCode(), "批准退款应成功");
-        assertEquals("refunded", order.getStatus());
+        assertEquals("refunded", order.getStatus(), "微信受理成功即退款完成");
         assertEquals(2, order.getRefundStatus().intValue());
         verify(paymentService).refund("PO7", 9900, "不想要了");
         verify(productService).increaseStock(10L, 1);
         verify(inventoryService).recordRefundInbound(any(), any(), anyInt(), any(), any(), any(), anyString());
     }
 
+    @Test
+    void 正常流_管理员批准退款_微信处理中_进入退款中且副作用延后() {
+        ProductOrder order = orderOf("PO11", "pending_refund", 1L);
+        order.setRefundStatus(1);
+        order.setRefundReason("银行卡退款");
+        when(orderMapper.selectOne(any(com.baomidou.mybatisplus.core.conditions.Wrapper.class))).thenReturn(order);
+        when(paymentService.refund(anyString(), anyInt(), anyString())).thenReturn("PROCESSING");
+
+        Result<String> result = service.approveRefund("PO11", 1L);
+
+        assertEquals(200, result.getCode(), "微信已受理,退款应进入退款中");
+        assertEquals("refunding", order.getStatus(), "微信返回处理中时应为退款中,不是已退款");
+        verify(productService, never()).increaseStock(any(), anyInt());
+        verify(inventoryService, never()).recordRefundInbound(any(), any(), anyInt(), any(), any(), any(), anyString());
+    }
+
+    @Test
+    void 正常流_确认到账_退款中订单完成退款且幂等() {
+        ProductOrder order = orderOf("PO12", "refunding", 1L);
+        order.setRefundStatus(2);
+        order.setRefundReason("银行卡退款");
+        when(orderMapper.selectOne(any(com.baomidou.mybatisplus.core.conditions.Wrapper.class))).thenReturn(order);
+
+        Result<String> result = service.confirmRefundArrive("PO12", 1L);
+
+        assertEquals(200, result.getCode(), "确认到账应成功");
+        assertEquals("refunded", order.getStatus());
+        verify(productService).increaseStock(10L, 1);
+        verify(inventoryService).recordRefundInbound(any(), any(), anyInt(), any(), any(), any(), anyString());
+    }
+
+    @Test
+    void 异常流_确认到账_订单已退款_幂等返回成功() {
+        ProductOrder order = orderOf("PO13", "refunded", 1L);
+        order.setRefundStatus(2);
+        when(orderMapper.selectOne(any(com.baomidou.mybatisplus.core.conditions.Wrapper.class))).thenReturn(order);
+
+        Result<String> result = service.confirmRefundArrive("PO13", 1L);
+
+        assertEquals(200, result.getCode(), "已退款订单重复确认应幂等成功");
+        verify(productService, never()).increaseStock(any(), anyInt());
+    }
+
     @Test
     void 正常流_管理员拒绝退款_回到已支付() {
-        ProductOrder order = orderOf("PO8", "refunding", 1L);
+        ProductOrder order = orderOf("PO8", "pending_refund", 1L);
         order.setRefundStatus(1);
+        order.setRefundBeforeStatus("paid");
         when(orderMapper.selectOne(any(com.baomidou.mybatisplus.core.conditions.Wrapper.class))).thenReturn(order);
 
         Result<String> result = service.rejectRefund("PO8", 1L, "证据不足");
@@ -221,6 +268,20 @@ class OrderRefundScP56ScA12ContractTest {
         verify(paymentService, never()).refund(anyString(), anyInt(), anyString());
     }
 
+    @Test
+    void 正常流_管理员拒绝退款_回滚到申请前的待收货状态() {
+        ProductOrder order = orderOf("PO14", "pending_refund", 1L);
+        order.setRefundStatus(1);
+        order.setRefundBeforeStatus("pending_receipt");
+        when(orderMapper.selectOne(any(com.baomidou.mybatisplus.core.conditions.Wrapper.class))).thenReturn(order);
+
+        Result<String> result = service.rejectRefund("PO14", 1L, "不符合退款条件");
+
+        assertEquals(200, result.getCode(), "拒绝退款应成功");
+        assertEquals("pending_receipt", order.getStatus(), "应回滚到申请退款前的状态,而不是写死 paid");
+        assertEquals(3, order.getRefundStatus().intValue());
+    }
+
     // ==================== 异常流(SC-A-12 平台处理) ====================
 
     @Test