foodie-server/ruoyi-system/src/main/java/com/ruoyi/system/mapper/flash/FlashDeliveryOrderMapper.java

package com.ruoyi.system.mapper.flash;

import com.baomidou.mybatisplus.core.mapper.BaseMapper;
import com.ruoyi.system.domain.flash.FlashDeliveryOrder;
import org.apache.ibatis.annotations.Param;

import java.util.Date;
import java.util.List;

/** 闪送订单持久化接口，关键状态操作均使用带前置条件的原子 SQL。 */
public interface FlashDeliveryOrderMapper extends BaseMapper<FlashDeliveryOrder> {
    /** 按用户幂等键查询已经创建的订单。 */
    FlashDeliveryOrder selectByUserRequestId(@Param("userId") Long userId,
                                             @Param("clientRequestId") String clientRequestId);

    /**
     * 原子抢单，仅当订单仍为待接单且未绑定骑手时更新成功。
     *
     * @return 1 表示抢单成功，0 表示订单已被抢走或状态已变化
     */
    int accept(@Param("id") Long id, @Param("riderId") Long riderId, @Param("now") Date now);

    /** 待接单编辑：同时校验创建人、无骑手和版本，原子更新地址、收件人绑定及路线费用。 */
    int updateWaitingAddress(@Param("order") FlashDeliveryOrder order,
                             @Param("expectedVersion") Integer expectedVersion);

    /** 待接单追加小费：版本保护避免并发覆盖与重复加款。 */
    int updateWaitingTip(@Param("order") FlashDeliveryOrder order,
                         @Param("expectedVersion") Integer expectedVersion);

    /** 按骑手归属和预期状态推进取件或送达，防止越权及并发重复操作。 */
    int transitionByRider(@Param("id") Long id, @Param("riderId") Long riderId,
                          @Param("expectedStatus") String expectedStatus,
                          @Param("nextStatus") String nextStatus,
                          @Param("timeColumn") String timeColumn, @Param("now") Date now);

    /** 按订单所有人和预期状态完成用户确认收货。 */
    int transitionByParticipant(@Param("id") Long id, @Param("userId") Long userId,
                                @Param("expectedStatus") String expectedStatus,
                                @Param("nextStatus") String nextStatus, @Param("now") Date now);

    /** 供平台和系统任务按预期状态执行条件更新。 */
    int transitionByStatus(@Param("id") Long id, @Param("expectedStatus") String expectedStatus,
                           @Param("nextStatus") String nextStatus,
                           @Param("timeColumn") String timeColumn, @Param("now") Date now);

    /** 记录取消操作人和原因，并仅从调用方已校验的当前状态转为已取消。 */
    int cancel(@Param("id") Long id, @Param("expectedStatus") String expectedStatus,
               @Param("operatorType") String operatorType, @Param("operatorId") Long operatorId,
               @Param("reason") String reason, @Param("now") Date now);

    /** 分批查询送达时间早于截止点且仍未完成的订单。 */
    List<FlashDeliveryOrder> selectAutoCompletable(@Param("deadline") Date deadline,
                                                   @Param("limit") int limit);
}