Bladeren bron

Merge task/S-cfc-402 into cfclub (shop.order.receiptTimeout 待收货超时自动完成 S-cfc-402)

Agnes Agent 3 dagen geleden
bovenliggende
commit
10628c9e70

+ 2 - 0
cfc-backend/src/main/java/com/etotem/cfc/service/ProductOrderService.java

@@ -1474,6 +1474,8 @@ public class ProductOrderService {
             order.setShippingCost(shippingCost);
         }
         order.setStatus("pending_receipt");
+        // P0-B 待收货超时兜底:发货成功即写 shipped_at=now,作为超时自动完成/收货提醒的基准时间
+        order.setShippedAt(new Date());
         if (st == ShipType.SELF_PICKUP) {
             // 履约扩展:自取/线上订单必须供应商先确认(confirmReceive 有校验),此处统一置为已确认
             order.setFulfillStatus("confirmed_by_vendor");

+ 224 - 0
cfc-backend/src/main/java/com/etotem/cfc/task/OrderReceiptTimeoutTask.java

@@ -0,0 +1,224 @@
+package com.etotem.cfc.task;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.etotem.cfc.config.DatabaseInitializer;
+import com.etotem.cfc.entity.ProductOrder;
+import com.etotem.cfc.entity.User;
+import com.etotem.cfc.mapper.ProductOrderMapper;
+import com.etotem.cfc.mapper.UserMapper;
+import com.etotem.cfc.service.UserOperationLogService;
+import com.etotem.cfc.service.WechatService;
+import org.apache.commons.lang3.StringUtils;
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+import org.springframework.beans.factory.annotation.Value;
+import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.stereotype.Component;
+import org.springframework.transaction.annotation.Transactional;
+
+import javax.annotation.Resource;
+import java.util.Calendar;
+import java.util.Date;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+
+/**
+ * 待收货超时自动完成 / 第N天收货提醒定时任务(能力键 {@code shop.order.receiptTimeout})。
+ *
+ * <p>契约来源:{@code docs/superpowers/specs/2026-11-14-product-order-gap-prd.md} §3 P0-B +
+ * {@code docs/superpowers/specs/2026-11-14-product-order-gap-arch-design.md} §3.3 / §6 T03,
+ * 仿 {@code OrderTimeoutCancelTask} 模式({@code @Scheduled} + {@code isMigrationsComplete} 守卫 + {@code @Transactional})。</p>
+ *
+ * <p>行为:
+ * <ol>
+ *   <li><b>自动完成</b>:{@code status=pending_receipt AND COALESCE(shipped_at, updated_at) &lt; now - receipt-timeout-days}
+ *       → {@code status=completed}、{@code confirmTime=now}、{@code updatedAt=now}、写 {@code user_operation_logs}
+ *       (type=product_order_auto_complete,备注含 orderNo/原因)留痕;completed 不再被扫中,重复执行幂等;</li>
+ *   <li><b>第N天提醒</b>:{@code status=pending_receipt AND shipped_at IS NOT NULL AND shipped_at &lt; now - receipt-remind-days
+ *       AND receipt_remind_at IS NULL} → 经 {@code WechatService.sendTemplateMessage} 推送,推送后写
+ *       {@code receipt_remind_at=now}(幂等防重复;模板ID空=跳过,fail-open);</li>
+ *   <li><b>总开关</b>:{@code receipt-auto-complete-enabled=false} 时仅提醒不自动完成(灰度开关)。</li>
+ * </ol>
+ * 阈值 / 提醒天数 / 开关 / 模板ID 全部走 {@code application.yml}({@code shop.order.*})配置,不硬编码。</p>
+ */
+@Component
+public class OrderReceiptTimeoutTask {
+
+    private static final Logger log = LoggerFactory.getLogger(OrderReceiptTimeoutTask.class);
+
+    /** 待收货状态:自动完成/提醒仅作用于该状态,completed 不再被扫中(幂等) */
+    static final String STATUS_PENDING_RECEIPT = "pending_receipt";
+
+    /** 自动完成可追溯日志类型(user_operation_logs.operation_type) */
+    static final String AUTO_COMPLETE_LOG_TYPE = "product_order_auto_complete";
+
+    @Resource
+    private ProductOrderMapper orderMapper;
+
+    @Resource
+    private UserMapper userMapper;
+
+    @Resource
+    private WechatService wechatService;
+
+    @Resource
+    private UserOperationLogService operationLogService;
+
+    /** 发货后未确认收货自动完成天数(默认10,配置键 shop.order.receipt-timeout-days) */
+    @Value("${shop.order.receipt-timeout-days:10}")
+    private int receiptTimeoutDays;
+
+    /** 发货后第N天推送收货提醒(默认9,配置键 shop.order.receipt-remind-days) */
+    @Value("${shop.order.receipt-remind-days:9}")
+    private int receiptRemindDays;
+
+    /** 自动完成总开关(灰度/回滚用,false 时仅提醒不自动完成) */
+    @Value("${shop.order.receipt-auto-complete-enabled:true}")
+    private boolean receiptAutoCompleteEnabled;
+
+    /** 收货提醒订阅消息模板ID(空=跳过推送,fail-open,运营配置) */
+    @Value("${shop.order.receipt-remind-template-id:}")
+    private String receiptRemindTemplateId;
+
+    /**
+     * 定时入口:每分钟扫描待收货超时订单。先提醒(第N天)后自动完成(超时),
+     * 避免同一轮先完成再提醒的错序;自动完成受总开关控制。
+     */
+    @Scheduled(fixedRate = 60000)
+    @Transactional(rollbackFor = Exception.class)
+    public void processTimeoutOrders() {
+        if (!DatabaseInitializer.isMigrationsComplete()) {
+            log.info("数据库迁移尚未完成,跳过本轮待收货超时检查");
+            return;
+        }
+        sendRemind();
+        if (receiptAutoCompleteEnabled) {
+            autoComplete();
+        } else {
+            log.info("自动完成总开关关闭(receipt-auto-complete-enabled=false),本轮仅提醒不自动完成");
+        }
+    }
+
+    /**
+     * 自动完成:扫描 pending_receipt 且 COALESCE(shipped_at, updated_at) 早于超时阈值的订单,
+     * 置 completed + confirmTime=now + updatedAt=now,写 user_operation_logs 可追溯留痕 + SLF4J 日志。
+     * 幂等:completed 订单不在扫描范围内,重复执行不重复完成。
+     */
+    void autoComplete() {
+        Calendar cal = Calendar.getInstance();
+        cal.add(Calendar.DAY_OF_MONTH, -receiptTimeoutDays);
+        Date deadline = cal.getTime();
+
+        // COALESCE(shipped_at, updated_at) < deadline ⇔ (shipped_at 非空且 < deadline) OR (shipped_at 空且 updated_at < deadline)
+        List<ProductOrder> timeoutOrders = orderMapper.selectList(
+                new LambdaQueryWrapper<ProductOrder>()
+                        .eq(ProductOrder::getStatus, STATUS_PENDING_RECEIPT)
+                        .and(w -> w.isNotNull(ProductOrder::getShippedAt)
+                                        .lt(ProductOrder::getShippedAt, deadline)
+                                .or()
+                                .isNull(ProductOrder::getShippedAt)
+                                        .lt(ProductOrder::getUpdatedAt, deadline)));
+
+        if (timeoutOrders.isEmpty()) {
+            return;
+        }
+
+        Date now = new Date();
+        for (ProductOrder order : timeoutOrders) {
+            try {
+                order.setStatus("completed");
+                order.setConfirmTime(now);
+                order.setUpdatedAt(now);
+                orderMapper.updateById(order);
+                writeAutoCompleteLog(order);
+                log.info("订单 {} 发货后 {} 天未确认收货,系统自动完成", order.getOrderNo(), receiptTimeoutDays);
+            } catch (Exception e) {
+                // 单条失败不阻塞批次;状态幂等,下一轮可自动补齐
+                log.error("订单 {} 自动完成失败: {}", order.getOrderNo(), e.getMessage());
+            }
+        }
+        log.info("本次自动完成 {} 个超时待收货订单", timeoutOrders.size());
+    }
+
+    /**
+     * 第N天提醒:扫描 pending_receipt 且 shipped_at 存在、早于提醒阈值且未推送过(receipt_remind_at IS NULL)的订单,
+     * 经 WechatService.sendTemplateMessage 向买家推送收货提醒,推送后写 receipt_remind_at=now(幂等防重复);
+     * 模板ID未配置时跳过(fail-open)。
+     */
+    void sendRemind() {
+        if (StringUtils.isBlank(receiptRemindTemplateId)) {
+            log.info("收货提醒模板ID未配置(receipt-remind-template-id 为空),跳过第{}天收货提醒", receiptRemindDays);
+            return;
+        }
+        Calendar cal = Calendar.getInstance();
+        cal.add(Calendar.DAY_OF_MONTH, -receiptRemindDays);
+        Date remindTime = cal.getTime();
+
+        List<ProductOrder> remindOrders = orderMapper.selectList(
+                new LambdaQueryWrapper<ProductOrder>()
+                        .eq(ProductOrder::getStatus, STATUS_PENDING_RECEIPT)
+                        .isNotNull(ProductOrder::getShippedAt)
+                        .lt(ProductOrder::getShippedAt, remindTime)
+                        .isNull(ProductOrder::getReceiptRemindAt));
+
+        if (remindOrders.isEmpty()) {
+            return;
+        }
+
+        for (ProductOrder order : remindOrders) {
+            try {
+                if (order.getBuyerId() == null) {
+                    continue;
+                }
+                User buyer = userMapper.selectById(order.getBuyerId());
+                if (buyer == null || StringUtils.isBlank(buyer.getOpenid())) {
+                    log.info("订单 {} 买家无 openid,跳过收货提醒", order.getOrderNo());
+                    continue;
+                }
+                Map<String, Object> keywordMap = new HashMap<>();
+                keywordMap.put("keyword1", order.getProductName() != null ? order.getProductName() : "商品订单");
+                keywordMap.put("keyword2", order.getOrderNo());
+                keywordMap.put("keyword3", "您的订单已发货 " + receiptRemindDays + " 天,请及时确认收货");
+                wechatService.sendTemplateMessage(buyer.getOpenid(), receiptRemindTemplateId, keywordMap);
+                order.setReceiptRemindAt(new Date());
+                order.setUpdatedAt(new Date());
+                orderMapper.updateById(order);
+                log.info("订单 {} 第{}天收货提醒已推送", order.getOrderNo(), receiptRemindDays);
+            } catch (Exception e) {
+                // 失败仅日志,不重试风暴:receipt_remind_at 未写则下一轮自然再试
+                log.error("订单 {} 第{}天收货提醒推送失败: {}", order.getOrderNo(), receiptRemindDays, e.getMessage());
+            }
+        }
+        log.info("本次共推送 {} 个收货提醒", remindOrders.size());
+    }
+
+    /**
+     * 发货时间基准:COALESCE(shipped_at, updated_at)。
+     * 存量订单 shipped_at 为空时以 updated_at 兜底,避免历史待收货订单永久卡单(架构设计 §2.2)。
+     */
+    Date resolveShipTimeBase(ProductOrder order) {
+        if (order == null) {
+            return null;
+        }
+        return order.getShippedAt() != null ? order.getShippedAt() : order.getUpdatedAt();
+    }
+
+    /**
+     * 自动完成可追溯留痕:写 user_operation_logs(type=product_order_auto_complete,备注含 orderNo/原因)。
+     */
+    private void writeAutoCompleteLog(ProductOrder order) {
+        if (order.getBuyerId() == null) {
+            return;
+        }
+        try {
+            operationLogService.logOperation(order.getBuyerId(), AUTO_COMPLETE_LOG_TYPE,
+                    "订单 " + order.getOrderNo() + " 发货后超过 " + receiptTimeoutDays
+                            + " 天未确认收货,系统自动完成",
+                    null, null, null, null, null, null);
+        } catch (Exception e) {
+            // 留痕失败不阻塞自动完成主流程(日志服务内部已兜底)
+            log.warn("订单 {} 自动完成操作日志写入失败: {}", order.getOrderNo(), e.getMessage());
+        }
+    }
+}