暂存提交

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/DispatchMapperConfiguration.java

@@ -0,0 +1,9 @@
+package com.baiyue.lastleg.dispatch;
+
+import org.mybatis.spring.annotation.MapperScan;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+@MapperScan("com.baiyue.lastleg.dispatch.mapper")
+public class DispatchMapperConfiguration {
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/controller/DispatchController.java

@@ -0,0 +1,134 @@
+package com.baiyue.lastleg.dispatch.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.lastleg.dispatch.dto.DispatchRequests;
+import com.baiyue.lastleg.dispatch.dto.DispatchResponse;
+import com.baiyue.lastleg.dispatch.model.DispatchPalletCandidate;
+import com.baiyue.lastleg.dispatch.pda.dto.DispatchPdaRequests;
+import com.baiyue.lastleg.dispatch.pda.dto.DispatchPdaResponses;
+import com.baiyue.lastleg.dispatch.pda.service.DispatchPdaWorkflowService;
+import com.baiyue.lastleg.dispatch.pda.controller.DispatchPdaController;
+import com.baiyue.lastleg.dispatch.service.DispatchService;
+import io.swagger.v3.oas.annotations.Operation;
+import io.swagger.v3.oas.annotations.tags.Tag;
+import jakarta.annotation.Resource;
+import jakarta.validation.Valid;
+import org.springframework.http.HttpStatus;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.DeleteMapping;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.PutMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RequestParam;
+import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.util.List;
+
+@RestController
+@RequestMapping("/api/platform/v1/last-leg/dispatches")
+@Tag(name = "Tail-leg vehicle dispatch")
+public class DispatchController {
+    @Resource private DispatchService service;
+    @Resource private DispatchPdaWorkflowService pdaWorkflow;
+
+    @GetMapping("/candidates")
+    @Operation(summary = "List unlocked planned or received pallets for intelligent pre-dispatch")
+    public ApiResponse<List<DispatchPalletCandidate>> candidates(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam(required = false) String customerId,
+        @RequestParam(required = false) String orderNo,
+        @RequestParam(required = false) String fbaWarehouseCode,
+        @RequestParam(required = false) String sourceStage) {
+        return ApiResponse.success(service.candidates(scope(user, customerId), orderNo, fbaWarehouseCode, sourceStage));
+    }
+
+    @PostMapping("/pre-arrange")
+    @Operation(summary = "Create a pending-departure dispatch and lock all selected pallets")
+    public ApiResponse<DispatchResponse> preArrange(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam(required = false) String customerId,
+        @Valid @RequestBody DispatchRequests.PreArrange request) {
+        String scopedTenant = scope(user, customerId);
+        String operatorId = user.userId() == null ? user.username() : String.valueOf(user.userId());
+        return ApiResponse.success(service.preArrange(scopedTenant, operatorId, request));
+    }
+
+    @GetMapping
+    @Operation(summary = "Page dispatch orders")
+    public ApiResponse<PageResult<DispatchResponse>> page(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam(required = false) String customerId,
+        @Valid DispatchRequests.Query query) {
+        return ApiResponse.success(service.page(scope(user, customerId), query));
+    }
+
+    @GetMapping("/{dispatchNo}")
+    @Operation(summary = "Get dispatch details and all pallet destinations")
+    public ApiResponse<DispatchResponse> detail(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam(required = false) String customerId,
+        @PathVariable String dispatchNo) {
+        return ApiResponse.success(service.detail(scope(user, customerId), dispatchNo));
+    }
+
+    @PutMapping("/{dispatchNo}")
+    @Operation(summary = "Edit vehicle, driver, appointment, route and departure data")
+    public ApiResponse<DispatchResponse> update(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam(required = false) String customerId,
+        @PathVariable String dispatchNo,
+        @Valid @RequestBody DispatchRequests.Update request) {
+        return ApiResponse.success(service.update(scope(user, customerId), dispatchNo, request));
+    }
+
+    @DeleteMapping("/{dispatchNo}")
+    @Operation(summary = "Cancel a pending dispatch and release its pallet locks")
+    public ApiResponse<Void> cancel(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam(required = false) String customerId,
+        @PathVariable String dispatchNo) {
+        service.cancel(scope(user, customerId), dispatchNo);
+        return ApiResponse.success(null);
+    }
+
+    @PostMapping("/{dispatchNo}/depart")
+    @Operation(summary = "Ship all PDA-picked pallets and mark the dispatch departed")
+    public ApiResponse<DispatchPdaResponses.Departed> depart(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @RequestParam(required = false) String customerId,
+        @PathVariable String dispatchNo,
+        @Valid @RequestBody DispatchPdaRequests.Depart request) {
+        requirePdaOperate(user);
+        String scopedTenant = scope(user, customerId);
+        String operatorId = user.userId() == null ? user.username() : String.valueOf(user.userId());
+        return ApiResponse.success(pdaWorkflow.depart(scopedTenant, dispatchNo, operatorId, request));
+    }
+
+    private String scope(AuthenticatedUser user, String requestedCustomer) {
+        if (user == null || user.tenantId() == null) {
+            throw new ResponseStatusException(HttpStatus.UNAUTHORIZED);
+        }
+        if ("PLATFORM".equals(user.appCode()) && user.tenantId() == 0L) {
+            if (requestedCustomer == null || requestedCustomer.isBlank() || "0".equals(requestedCustomer)) {
+                throw new ResponseStatusException(HttpStatus.BAD_REQUEST,
+                    "Platform request must specify target tenant");
+            }
+            return requestedCustomer;
+        }
+        return String.valueOf(user.tenantId());
+    }
+
+    private void requirePdaOperate(AuthenticatedUser user) {
+        if (user == null || user.tenantId() == null) throw new ResponseStatusException(HttpStatus.UNAUTHORIZED);
+        if (user.permissions() == null || !user.permissions().contains(DispatchPdaController.OPERATE_PERMISSION)) {
+            throw new ResponseStatusException(HttpStatus.FORBIDDEN,
+                DispatchPdaController.OPERATE_PERMISSION + " permission is required");
+        }
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/dto/DispatchRequests.java

@@ -0,0 +1,35 @@
+package com.baiyue.lastleg.dispatch.dto;
+
+import jakarta.validation.constraints.Max;
+import jakarta.validation.constraints.Min;
+import jakarta.validation.constraints.NotEmpty;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Size;
+
+import java.time.LocalDateTime;
+import java.util.List;
+
+public final class DispatchRequests {
+    private DispatchRequests() {
+    }
+
+    public record Query(@Min(1) long page, @Min(1) @Max(200) long size, String dispatchNo,
+                        String vehiclePlate, String status, String fbaAppointmentNo) {
+        public Query { if (page == 0) page = 1; if (size == 0) size = 20; }
+    }
+
+    public record PreArrange(@NotEmpty @Size(max = 500) List<@NotNull Long> planPalletIds,
+                             @Size(max = 255) String route, @Size(max = 64) String fbaAppointmentNo,
+                             @Size(max = 32) String fbaAppointmentStatus,
+                             @Size(max = 32) String vehicleAppointmentStatus) {
+    }
+
+    public record Update(@Size(max = 64) String vehiclePlate, @Size(max = 128) String driverName,
+                         @Size(max = 64) String driverPhone, @Size(max = 255) String carrierName,
+                         @Size(max = 255) String route, LocalDateTime departAt,
+                         @Size(max = 64) String fbaAppointmentNo,
+                         @Size(max = 32) String fbaAppointmentStatus,
+                         @Size(max = 32) String vehicleAppointmentStatus,
+                         LocalDateTime estimatedArrivalAt, @Size(max = 32) String status) {
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/dto/DispatchResponse.java

@@ -0,0 +1,22 @@
+package com.baiyue.lastleg.dispatch.dto;
+
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.util.List;
+
+public record DispatchResponse(Long id, String dispatchNo, String vehiclePlate, String driverName,
+                               String driverPhone, String carrierName, String orderNos, String route,
+                               String overseasWarehouseId, String overseasWarehouseName, LocalDateTime departAt,
+                               String fbaAppointmentNo, String fbaAppointmentStatus,
+                               String vehicleAppointmentStatus, LocalDateTime estimatedArrivalAt, String status,
+                               int itemCount, int palletCount, int packageCount, int pickedPackageCount,
+                               int shippedPackageCount, int remainingPackageCount, String partialCompletionReason,
+                               LocalDateTime createdAt,
+                               List<Item> items) {
+    public record Item(Long id, Long planPalletId, Long warehousePalletId, String palletNo,
+                       String overseasWarehouseId, String overseasWarehouseName,
+                       String orderNo, String orderRefs, String inboundCode, String destinationWarehouseCode,
+                       String destinationWarehouseName, String fbaWarehouseCode, int packageCount,
+                       BigDecimal volumeCbm, String sourceStage) {
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/entity/DispatchItem.java

@@ -0,0 +1,38 @@
+package com.baiyue.lastleg.dispatch.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+
+/** Immutable pallet/cargo snapshot selected into a dispatch order. */
+@Data
+@TableName("ll_dispatch_item")
+public class DispatchItem {
+    @TableId(type = IdType.INPUT)
+    private Long id;
+    private Long dispatchOrderId;
+    private String customerId;
+    private Long planId;
+    private Long planPalletId;
+    private Long warehousePalletId;
+    private Long orderId;
+    private String overseasWarehouseId;
+    private String overseasWarehouseName;
+    private String orderNo;
+    private String orderRefs;
+    private String inboundCode;
+    private String palletNo;
+    private String destinationWarehouseId;
+    private String destinationWarehouseCode;
+    private String destinationWarehouseName;
+    private String fbaWarehouseCode;
+    private Integer packageCount;
+    private BigDecimal volumeCbm;
+    /** PLAN for planned pallets; RECEIVED for warehouse/entity pallets. */
+    private String sourceStage;
+    private LocalDateTime createdAt;
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/entity/DispatchOrder.java

@@ -0,0 +1,40 @@
+package com.baiyue.lastleg.dispatch.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/** Header for a pre-dispatched vehicle load. Vehicle information remains editable before departure. */
+@Data
+@TableName("ll_dispatch_order")
+public class DispatchOrder {
+    @TableId(type = IdType.INPUT)
+    private Long id;
+    private String customerId;
+    private String dispatchNo;
+    private String overseasWarehouseId;
+    private String overseasWarehouseName;
+    private String vehiclePlate;
+    private String driverName;
+    private String driverPhone;
+    private String carrierName;
+    private String route;
+    private LocalDateTime departAt;
+    private String fbaAppointmentNo;
+    private String fbaAppointmentStatus;
+    private String vehicleAppointmentStatus;
+    private LocalDateTime estimatedArrivalAt;
+    private String status;
+    private Integer itemCount;
+    private Integer palletCount;
+    private Integer packageCount;
+    private Integer pickedPackageCount;
+    private Integer shippedPackageCount;
+    private String partialCompletionReason;
+    private String createdBy;
+    private LocalDateTime createdAt;
+    private LocalDateTime updatedAt;
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/entity/DispatchPalletLock.java

@@ -0,0 +1,29 @@
+package com.baiyue.lastleg.dispatch.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/** Prevents a source pallet from being added to more than one active dispatch order. */
+@Data
+@TableName("ll_dispatch_pallet_lock")
+public class DispatchPalletLock {
+    @TableId(type = IdType.INPUT)
+    private Long id;
+    private String customerId;
+    private String sourcePalletKey;
+    /** Equals sourcePalletKey while ACTIVE and is null after release; unique index enforces exclusivity. */
+    private String activeKey;
+    private Long planId;
+    private Long planPalletId;
+    private Long warehousePalletId;
+    private Long dispatchOrderId;
+    private String status;
+    private LocalDateTime lockedAt;
+    private LocalDateTime releasedAt;
+    private LocalDateTime createdAt;
+    private LocalDateTime updatedAt;
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/mapper/DispatchCandidateMapper.java

@@ -0,0 +1,78 @@
+package com.baiyue.lastleg.dispatch.mapper;
+
+import com.baiyue.lastleg.dispatch.model.DispatchPalletCandidate;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+import java.util.List;
+
+@Mapper
+public interface DispatchCandidateMapper {
+    @Select("<script>" +
+        "SELECT p.plan_id AS planId,p.id AS planPalletId,p.warehouse_pallet_id AS warehousePalletId," +
+        "MIN(l.order_id) AS orderId,MIN(o.overseas_warehouse_id) AS overseasWarehouseId,MIN(o.overseas_warehouse_name) AS overseasWarehouseName,MIN(o.order_no) AS orderNo," +
+        "GROUP_CONCAT(DISTINCT o.order_no ORDER BY o.order_no SEPARATOR ',') AS orderRefs,MIN(l.inbound_code) AS inboundCode," +
+        "p.pallet_no AS palletNo,p.destination_warehouse_id AS destinationWarehouseId," +
+        "p.destination_warehouse_code AS destinationWarehouseCode,p.destination_warehouse_name AS destinationWarehouseName," +
+        "MIN(l.fba_warehouse_code) AS fbaWarehouseCode," +
+        "CASE WHEN p.warehouse_pallet_id IS NOT NULL THEN COALESCE((SELECT SUM(pos.available_packages) " +
+        "FROM ll_inventory_position pos WHERE pos.customer_id=#{customerId} AND pos.pallet_id=p.warehouse_pallet_id),0) " +
+        "ELSE COALESCE(SUM(CASE WHEN a.picked_package_count &gt; 0 THEN a.picked_package_count " +
+        "ELSE a.planned_package_count END),0) END AS packageCount,p.allocated_volume_cbm AS volumeCbm," +
+        "CASE WHEN p.warehouse_pallet_id IS NULL THEN 'PLAN' ELSE 'RECEIVED' END AS sourceStage " +
+        "FROM ll_inbound_plan_pallet p JOIN ll_inbound_plan ip ON ip.id=p.plan_id " +
+        "LEFT JOIN ll_inbound_plan_pallet_allocation a ON a.pallet_id=p.id " +
+        "LEFT JOIN ll_inbound_plan_line l ON l.id=a.line_id " +
+        "LEFT JOIN ll_order o ON o.id=l.order_id " +
+        "WHERE ip.customer_id=#{customerId} " +
+        "<if test='orderNo != null and orderNo != \"\"'> AND o.order_no LIKE CONCAT('%',#{orderNo},'%')</if> " +
+        "<if test='fbaWarehouseCode != null and fbaWarehouseCode != \"\"'> AND l.fba_warehouse_code=#{fbaWarehouseCode}</if> " +
+        "<if test='sourceStage != null and sourceStage != \"\"'> AND " +
+        "CASE WHEN p.warehouse_pallet_id IS NULL THEN 'PLAN' ELSE 'RECEIVED' END=#{sourceStage}</if> " +
+        "AND (p.warehouse_pallet_id IS NULL OR EXISTS (SELECT 1 FROM ll_inventory_position pos " +
+        "WHERE pos.customer_id=#{customerId} AND pos.pallet_id=p.warehouse_pallet_id AND pos.available_packages &gt; 0)) " +
+        "AND NOT EXISTS (SELECT 1 FROM ll_dispatch_pallet_lock d " +
+        "WHERE d.customer_id=ip.customer_id AND d.status='ACTIVE' AND (" +
+        "d.source_pallet_key=CONCAT('PLAN:',p.id) OR (p.warehouse_pallet_id IS NOT NULL AND " +
+        "d.source_pallet_key=CONCAT('RECEIVED:',p.warehouse_pallet_id)))) " +
+        "AND NOT EXISTS (SELECT 1 FROM ll_warehouse_transfer_inventory_allocation ta " +
+        "JOIN ll_inventory_position tp ON tp.id=ta.inventory_position_id " +
+        "WHERE ta.customer_id=#{customerId} AND ta.status='RESERVED' AND tp.pallet_id=p.warehouse_pallet_id) " +
+        "GROUP BY p.plan_id,p.id,p.warehouse_pallet_id,p.pallet_no,p.destination_warehouse_id," +
+        "p.destination_warehouse_code,p.destination_warehouse_name,p.allocated_volume_cbm " +
+        "ORDER BY p.plan_id,p.sequence_no" +
+        "</script>")
+    List<DispatchPalletCandidate> available(@Param("customerId") String customerId,
+                                            @Param("orderNo") String orderNo,
+                                            @Param("fbaWarehouseCode") String fbaWarehouseCode,
+                                            @Param("sourceStage") String sourceStage);
+
+    @Select("<script>" +
+        "SELECT p.plan_id AS planId,p.id AS planPalletId,p.warehouse_pallet_id AS warehousePalletId," +
+        "MIN(l.order_id) AS orderId,MIN(o.overseas_warehouse_id) AS overseasWarehouseId,MIN(o.overseas_warehouse_name) AS overseasWarehouseName,MIN(o.order_no) AS orderNo," +
+        "GROUP_CONCAT(DISTINCT o.order_no ORDER BY o.order_no SEPARATOR ',') AS orderRefs,MIN(l.inbound_code) AS inboundCode," +
+        "p.pallet_no AS palletNo,p.destination_warehouse_id AS destinationWarehouseId," +
+        "p.destination_warehouse_code AS destinationWarehouseCode,p.destination_warehouse_name AS destinationWarehouseName," +
+        "MIN(l.fba_warehouse_code) AS fbaWarehouseCode," +
+        "CASE WHEN p.warehouse_pallet_id IS NOT NULL THEN COALESCE((SELECT SUM(pos.available_packages) " +
+        "FROM ll_inventory_position pos WHERE pos.customer_id=#{customerId} AND pos.pallet_id=p.warehouse_pallet_id),0) " +
+        "ELSE COALESCE(SUM(CASE WHEN a.picked_package_count &gt; 0 THEN a.picked_package_count " +
+        "ELSE a.planned_package_count END),0) END AS packageCount,p.allocated_volume_cbm AS volumeCbm," +
+        "CASE WHEN p.warehouse_pallet_id IS NULL THEN 'PLAN' ELSE 'RECEIVED' END AS sourceStage " +
+        "FROM ll_inbound_plan_pallet p JOIN ll_inbound_plan ip ON ip.id=p.plan_id " +
+        "LEFT JOIN ll_inbound_plan_pallet_allocation a ON a.pallet_id=p.id " +
+        "LEFT JOIN ll_inbound_plan_line l ON l.id=a.line_id " +
+        "LEFT JOIN ll_order o ON o.id=l.order_id " +
+        "WHERE ip.customer_id=#{customerId} AND p.id IN " +
+        "<foreach collection='planPalletIds' item='id' open='(' separator=',' close=')'>#{id}</foreach> " +
+        "AND NOT EXISTS (SELECT 1 FROM ll_warehouse_transfer_inventory_allocation ta " +
+        "JOIN ll_inventory_position tp ON tp.id=ta.inventory_position_id " +
+        "WHERE ta.customer_id=#{customerId} AND ta.status='RESERVED' AND tp.pallet_id=p.warehouse_pallet_id) " +
+        "GROUP BY p.plan_id,p.id,p.warehouse_pallet_id,p.pallet_no,p.destination_warehouse_id," +
+        "p.destination_warehouse_code,p.destination_warehouse_name,p.allocated_volume_cbm " +
+        "ORDER BY p.id FOR UPDATE" +
+        "</script>")
+    List<DispatchPalletCandidate> lockSelected(@Param("customerId") String customerId,
+                                                @Param("planPalletIds") List<Long> planPalletIds);
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/mapper/DispatchItemMapper.java

@@ -0,0 +1,25 @@
+package com.baiyue.lastleg.dispatch.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.lastleg.dispatch.entity.DispatchItem;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+import org.apache.ibatis.annotations.Update;
+
+import java.util.List;
+
+@Mapper
+public interface DispatchItemMapper extends BaseMapper<DispatchItem> {
+    @Select("SELECT * FROM ll_dispatch_item WHERE customer_id=#{customerId} AND dispatch_order_id=#{dispatchOrderId} ORDER BY id")
+    List<DispatchItem> findByDispatchOrder(@Param("customerId") String customerId,
+                                           @Param("dispatchOrderId") Long dispatchOrderId);
+
+    @Update("UPDATE ll_dispatch_item i JOIN ll_inbound_plan_pallet p ON p.id=i.plan_pallet_id " +
+        "JOIN ll_inbound_plan ip ON ip.id=p.plan_id AND ip.customer_id=i.customer_id " +
+        "SET i.warehouse_pallet_id=p.warehouse_pallet_id,i.source_stage='RECEIVED' " +
+        "WHERE i.customer_id=#{customerId} AND i.dispatch_order_id=#{dispatchOrderId} " +
+        "AND i.warehouse_pallet_id IS NULL AND p.warehouse_pallet_id IS NOT NULL")
+    int bindReceivedPallets(@Param("customerId") String customerId,
+                            @Param("dispatchOrderId") Long dispatchOrderId);
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/mapper/DispatchOrderMapper.java

@@ -0,0 +1,16 @@
+package com.baiyue.lastleg.dispatch.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.lastleg.dispatch.entity.DispatchOrder;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+@Mapper
+public interface DispatchOrderMapper extends BaseMapper<DispatchOrder> {
+    @Select("SELECT * FROM ll_dispatch_order WHERE customer_id=#{customerId} AND dispatch_no=#{dispatchNo} LIMIT 1")
+    DispatchOrder findByDispatchNo(@Param("customerId") String customerId, @Param("dispatchNo") String dispatchNo);
+
+    @Select("SELECT * FROM ll_dispatch_order WHERE customer_id=#{customerId} AND id=#{id} LIMIT 1 FOR UPDATE")
+    DispatchOrder lockById(@Param("customerId") String customerId, @Param("id") Long id);
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/mapper/DispatchPalletLockMapper.java

@@ -0,0 +1,15 @@
+package com.baiyue.lastleg.dispatch.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.lastleg.dispatch.entity.DispatchPalletLock;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+@Mapper
+public interface DispatchPalletLockMapper extends BaseMapper<DispatchPalletLock> {
+    @Select("SELECT * FROM ll_dispatch_pallet_lock WHERE customer_id=#{customerId} AND source_pallet_key=#{sourcePalletKey} " +
+        "AND status='ACTIVE' LIMIT 1 FOR UPDATE")
+    DispatchPalletLock lockActive(@Param("customerId") String customerId,
+                                  @Param("sourcePalletKey") String sourcePalletKey);
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/model/DispatchPalletCandidate.java

@@ -0,0 +1,37 @@
+package com.baiyue.lastleg.dispatch.model;
+
+import java.math.BigDecimal;
+
+public record DispatchPalletCandidate(
+    Long planId,
+    Long planPalletId,
+    Long warehousePalletId,
+    Long orderId,
+    String overseasWarehouseId,
+    String overseasWarehouseName,
+    String orderNo,
+    String orderRefs,
+    String inboundCode,
+    String palletNo,
+    String destinationWarehouseId,
+    String destinationWarehouseCode,
+    String destinationWarehouseName,
+    String fbaWarehouseCode,
+    Integer packageCount,
+    BigDecimal volumeCbm,
+    String sourceStage
+) {
+    public DispatchPalletCandidate(Long planId, Long planPalletId, Long warehousePalletId, Long orderId,
+                                   String orderNo, String orderRefs, String inboundCode, String palletNo,
+                                   String destinationWarehouseId, String destinationWarehouseCode,
+                                   String destinationWarehouseName, String fbaWarehouseCode, Integer packageCount,
+                                   BigDecimal volumeCbm, String sourceStage) {
+        this(planId, planPalletId, warehousePalletId, orderId, null, null, orderNo, orderRefs, inboundCode,
+            palletNo, destinationWarehouseId, destinationWarehouseCode, destinationWarehouseName,
+            fbaWarehouseCode, packageCount, volumeCbm, sourceStage);
+    }
+    public String sourcePalletKey() {
+        // A plan pallet keeps the same lock identity before and after the physical pallet is received.
+        return planPalletId != null ? "PLAN:" + planPalletId : "RECEIVED:" + warehousePalletId;
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/DispatchPdaMapperConfiguration.java

@@ -0,0 +1,8 @@
+package com.baiyue.lastleg.dispatch.pda;
+
+import org.mybatis.spring.annotation.MapperScan;
+import org.springframework.context.annotation.Configuration;
+
+@Configuration
+@MapperScan("com.baiyue.lastleg.dispatch.pda.mapper")
+public class DispatchPdaMapperConfiguration {}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/controller/DispatchPdaController.java

@@ -0,0 +1,69 @@
+package com.baiyue.lastleg.dispatch.pda.controller;
+
+import com.baiyue.common.core.api.ApiResponse;
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.lastleg.dispatch.pda.dto.DispatchPdaRequests;
+import com.baiyue.lastleg.dispatch.pda.dto.DispatchPdaResponses;
+import com.baiyue.lastleg.dispatch.pda.service.DispatchPdaWorkflowService;
+import jakarta.annotation.Resource;
+import jakarta.validation.Valid;
+import org.springframework.http.HttpStatus;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.*;
+import org.springframework.web.server.ResponseStatusException;
+
+@RestController
+@RequestMapping("/api/platform/v1/last-leg/dispatches/{dispatchNo}/pda")
+public class DispatchPdaController {
+    public static final String OPERATE_PERMISSION = "lastleg:pda:operate";
+    @Resource private DispatchPdaWorkflowService service;
+
+    @PostMapping("/push")
+    public ApiResponse<DispatchPdaResponses.Task> push(@AuthenticationPrincipal AuthenticatedUser user,
+                                                       @PathVariable String dispatchNo,
+                                                       @RequestParam(required = false) String customerId,
+                                                       @Valid @RequestBody DispatchPdaRequests.Push request) {
+        requireOperate(user);
+        return ApiResponse.success(service.push(scope(user, customerId), dispatchNo, request));
+    }
+    @GetMapping
+    public ApiResponse<DispatchPdaResponses.Task> task(@AuthenticationPrincipal AuthenticatedUser user,
+                                                       @PathVariable String dispatchNo,
+                                                       @RequestParam(required = false) String customerId) {
+        return ApiResponse.success(service.task(scope(user, customerId), dispatchNo));
+    }
+    @PostMapping("/items/{itemId}/pick")
+    public ApiResponse<DispatchPdaResponses.Picked> pick(@AuthenticationPrincipal AuthenticatedUser user,
+                                                          @PathVariable String dispatchNo, @PathVariable long itemId,
+                                                          @RequestParam(required = false) String customerId,
+                                                          @Valid @RequestBody DispatchPdaRequests.Pick request) {
+        requireOperate(user);
+        return ApiResponse.success(service.pick(scope(user, customerId), dispatchNo, itemId, operator(user), request));
+    }
+    @PostMapping("/complete")
+    public ApiResponse<DispatchPdaResponses.PickingCompleted> completePicking(
+        @AuthenticationPrincipal AuthenticatedUser user,
+        @PathVariable String dispatchNo,
+        @RequestParam(required = false) String customerId,
+        @Valid @RequestBody DispatchPdaRequests.CompletePicking request) {
+        requireOperate(user);
+        return ApiResponse.success(service.completePicking(scope(user, customerId), dispatchNo, request));
+    }
+    private String scope(AuthenticatedUser user, String requestedCustomer) {
+        if (user == null || user.tenantId() == null) throw new ResponseStatusException(HttpStatus.UNAUTHORIZED);
+        if ("PLATFORM".equals(user.appCode()) && user.tenantId() == 0L) {
+            if (requestedCustomer == null || requestedCustomer.isBlank() || "0".equals(requestedCustomer)) {
+                throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Platform request must specify target tenant");
+            }
+            return requestedCustomer.trim();
+        }
+        return String.valueOf(user.tenantId());
+    }
+    private String operator(AuthenticatedUser user) { return user.userId() == null ? user.username() : String.valueOf(user.userId()); }
+    private void requireOperate(AuthenticatedUser user) {
+        if (user == null || user.tenantId() == null) throw new ResponseStatusException(HttpStatus.UNAUTHORIZED);
+        if (user.permissions() == null || !user.permissions().contains(OPERATE_PERMISSION)) {
+            throw new ResponseStatusException(HttpStatus.FORBIDDEN, OPERATE_PERMISSION + " permission is required");
+        }
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/dto/DispatchPdaRequests.java

@@ -0,0 +1,26 @@
+package com.baiyue.lastleg.dispatch.pda.dto;
+
+import jakarta.validation.constraints.NotBlank;
+import jakarta.validation.constraints.NotNull;
+import jakarta.validation.constraints.Positive;
+import jakarta.validation.constraints.PositiveOrZero;
+import jakarta.validation.constraints.Size;
+
+public final class DispatchPdaRequests {
+    private DispatchPdaRequests() {}
+    public record Push(@NotBlank String idempotencyKey, String operatorId, String operatorName,
+                       String warehouseId) {
+        public Push(String idempotencyKey, String operatorId, String operatorName) {
+            this(idempotencyKey, operatorId, operatorName, null);
+        }
+    }
+    public record Pick(@NotNull Long positionId, @Positive long packages, @PositiveOrZero long productQuantity,
+                       @NotBlank String idempotencyKey, String remark, String warehouseId) {
+        public Pick(Long positionId, long packages, long productQuantity, String idempotencyKey, String remark) {
+            this(positionId, packages, productQuantity, idempotencyKey, remark, null);
+        }
+    }
+    public record Depart(@NotBlank String idempotencyKey, String remark) {}
+    public record CompletePicking(@NotBlank String idempotencyKey,
+                                  @NotBlank @Size(max = 1000) String reason) {}
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/dto/DispatchPdaResponses.java

@@ -0,0 +1,27 @@
+package com.baiyue.lastleg.dispatch.pda.dto;
+
+import java.util.List;
+
+public final class DispatchPdaResponses {
+    private DispatchPdaResponses() {}
+    public record Task(Long id, String taskNo, String dispatchNo, String vehiclePlate, String warehouseId, String status,
+                       List<Item> items) {}
+    public record Item(Long dispatchItemId, String palletNo, String destinationWarehouseCode,
+                       String destinationWarehouseName, String fbaWarehouseCode, int scheduledPackages,
+                       long pickedPackages, List<Position> positions) {}
+    public record Position(Long id, Long balanceId, long availablePackages, long allocatedPackages,
+                           long pickedPackages) {}
+    public record Picked(Long dispatchItemId, Long positionId, long packages, long pickedPackages,
+                         boolean palletScrapped, boolean replayed) {}
+    public record Departed(String dispatchNo, String status, long shippedPackages, boolean replayed) {
+        public Departed withReplay() { return new Departed(dispatchNo, status, shippedPackages, true); }
+    }
+    public record PickingCompleted(String dispatchNo, String status, long plannedPackages,
+                                   long pickedPackages, long remainingPackages, boolean partial,
+                                   boolean replayed) {
+        public PickingCompleted withReplay() {
+            return new PickingCompleted(dispatchNo, status, plannedPackages, pickedPackages,
+                remainingPackages, partial, true);
+        }
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/entity/DispatchPdaOperation.java

@@ -0,0 +1,23 @@
+package com.baiyue.lastleg.dispatch.pda.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+@Data
+@TableName("ll_dispatch_pda_operation")
+public class DispatchPdaOperation {
+    @TableId(type = IdType.INPUT) private Long id;
+    private String customerId;
+    private Long taskId;
+    private String operationType;
+    private String idempotencyKey;
+    private String requestHash;
+    private String resultJson;
+    private String status;
+    private LocalDateTime createdAt;
+    private LocalDateTime updatedAt;
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/entity/DispatchPdaPick.java

@@ -0,0 +1,23 @@
+package com.baiyue.lastleg.dispatch.pda.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+@Data
+@TableName("ll_dispatch_pda_pick")
+public class DispatchPdaPick {
+    @TableId(type = IdType.INPUT) private Long id;
+    private String customerId;
+    private Long taskId;
+    private Long dispatchItemId;
+    private Long inventoryPositionId;
+    private Long packages;
+    private Long productQuantity;
+    private String idempotencyKey;
+    private LocalDateTime pickedAt;
+    private LocalDateTime createdAt;
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/entity/DispatchPdaPickOrder.java

@@ -0,0 +1,22 @@
+package com.baiyue.lastleg.dispatch.pda.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+/** Immutable FIFO attribution of a PDA pick to its inbound receipt and tail-leg order. */
+@Data
+@TableName("ll_dispatch_pda_pick_order")
+public class DispatchPdaPickOrder {
+    @TableId(type = IdType.INPUT) private Long id;
+    private String customerId;
+    private Long pickId;
+    private Long receiptId;
+    private Long orderId;
+    private Long packages;
+    private Long productQuantity;
+    private LocalDateTime createdAt;
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/entity/DispatchPdaTask.java

@@ -0,0 +1,25 @@
+package com.baiyue.lastleg.dispatch.pda.entity;
+
+import com.baomidou.mybatisplus.annotation.IdType;
+import com.baomidou.mybatisplus.annotation.TableId;
+import com.baomidou.mybatisplus.annotation.TableName;
+import lombok.Data;
+
+import java.time.LocalDateTime;
+
+@Data
+@TableName("ll_dispatch_pda_task")
+public class DispatchPdaTask {
+    @TableId(type = IdType.INPUT) private Long id;
+    private String customerId;
+    private Long dispatchOrderId;
+    private String taskNo;
+    private String status;
+    private String operatorId;
+    private String operatorName;
+    private String warehouseId;
+    private LocalDateTime pushedAt;
+    private LocalDateTime completedAt;
+    private LocalDateTime createdAt;
+    private LocalDateTime updatedAt;
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/mapper/DispatchPdaOperationMapper.java

@@ -0,0 +1,11 @@
+package com.baiyue.lastleg.dispatch.pda.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.lastleg.dispatch.pda.entity.DispatchPdaOperation;
+import org.apache.ibatis.annotations.*;
+
+@Mapper
+public interface DispatchPdaOperationMapper extends BaseMapper<DispatchPdaOperation> {
+    @Select("SELECT * FROM ll_dispatch_pda_operation WHERE customer_id=#{customerId} AND idempotency_key=#{key} LIMIT 1")
+    DispatchPdaOperation findKey(@Param("customerId") String customerId, @Param("key") String key);
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/mapper/DispatchPdaPickMapper.java

@@ -0,0 +1,14 @@
+package com.baiyue.lastleg.dispatch.pda.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.lastleg.dispatch.pda.entity.DispatchPdaPick;
+import org.apache.ibatis.annotations.*;
+import java.util.List;
+
+@Mapper
+public interface DispatchPdaPickMapper extends BaseMapper<DispatchPdaPick> {
+    @Select("SELECT * FROM ll_dispatch_pda_pick WHERE customer_id=#{customerId} AND task_id=#{taskId} ORDER BY id")
+    List<DispatchPdaPick> listTask(@Param("customerId") String customerId, @Param("taskId") Long taskId);
+    @Select("SELECT COALESCE(SUM(packages),0) FROM ll_dispatch_pda_pick WHERE customer_id=#{customerId} AND task_id=#{taskId} AND dispatch_item_id=#{itemId}")
+    long totalItem(@Param("customerId") String customerId, @Param("taskId") Long taskId, @Param("itemId") Long itemId);
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/mapper/DispatchPdaPickOrderMapper.java

@@ -0,0 +1,31 @@
+package com.baiyue.lastleg.dispatch.pda.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.lastleg.dispatch.pda.entity.DispatchPdaPickOrder;
+import com.baiyue.lastleg.inboundplan.pda.entity.InboundStockReceipt;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+import java.util.List;
+
+@Mapper
+public interface DispatchPdaPickOrderMapper extends BaseMapper<DispatchPdaPickOrder> {
+    @Select("SELECT r.* FROM ll_inbound_stock_receipt r " +
+        "WHERE r.customer_id=#{customerId} AND r.inventory_position_id=#{positionId} " +
+        "AND r.received_packages > (SELECT COALESCE(SUM(a.packages),0) FROM ll_dispatch_pda_pick_order a " +
+        "WHERE a.customer_id=r.customer_id AND a.receipt_id=r.id) ORDER BY r.received_at,r.id")
+    List<InboundStockReceipt> availableReceipts(@Param("customerId") String customerId,
+                                                @Param("positionId") Long positionId);
+
+    @Select("SELECT COALESCE(SUM(packages),0) FROM ll_dispatch_pda_pick_order " +
+        "WHERE customer_id=#{customerId} AND receipt_id=#{receiptId}")
+    long attributedPackages(@Param("customerId") String customerId, @Param("receiptId") Long receiptId);
+
+    @Select("SELECT COALESCE(SUM(product_quantity),0) FROM ll_dispatch_pda_pick_order " +
+        "WHERE customer_id=#{customerId} AND receipt_id=#{receiptId}")
+    long attributedQuantity(@Param("customerId") String customerId, @Param("receiptId") Long receiptId);
+
+    @Select("SELECT * FROM ll_dispatch_pda_pick_order WHERE customer_id=#{customerId} AND pick_id=#{pickId} ORDER BY id")
+    List<DispatchPdaPickOrder> listPick(@Param("customerId") String customerId, @Param("pickId") Long pickId);
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/mapper/DispatchPdaTaskMapper.java

@@ -0,0 +1,14 @@
+package com.baiyue.lastleg.dispatch.pda.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.lastleg.dispatch.pda.entity.DispatchPdaTask;
+import org.apache.ibatis.annotations.*;
+
+@Mapper
+public interface DispatchPdaTaskMapper extends BaseMapper<DispatchPdaTask> {
+    @Select("SELECT * FROM ll_dispatch_pda_task WHERE customer_id=#{customerId} AND dispatch_order_id=#{dispatchOrderId} LIMIT 1 FOR UPDATE")
+    DispatchPdaTask lockByDispatch(@Param("customerId") String customerId, @Param("dispatchOrderId") Long dispatchOrderId);
+
+    @Select("SELECT * FROM ll_dispatch_pda_task WHERE customer_id=#{customerId} AND dispatch_order_id=#{dispatchOrderId} LIMIT 1")
+    DispatchPdaTask findByDispatch(@Param("customerId") String customerId, @Param("dispatchOrderId") Long dispatchOrderId);
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/service/DispatchPdaWorkflowService.java

@@ -0,0 +1,277 @@
+package com.baiyue.lastleg.dispatch.pda.service;
+
+import com.baomidou.mybatisplus.core.toolkit.IdWorker;
+import com.baiyue.lastleg.delivery.entity.OutboundOrder;
+import com.baiyue.lastleg.delivery.mapper.OutboundOrderMapper;
+import com.baiyue.lastleg.dispatch.entity.DispatchItem;
+import com.baiyue.lastleg.dispatch.entity.DispatchOrder;
+import com.baiyue.lastleg.dispatch.entity.DispatchPalletLock;
+import com.baiyue.lastleg.dispatch.mapper.DispatchItemMapper;
+import com.baiyue.lastleg.dispatch.mapper.DispatchOrderMapper;
+import com.baiyue.lastleg.dispatch.mapper.DispatchPalletLockMapper;
+import com.baiyue.lastleg.dispatch.pda.dto.DispatchPdaRequests;
+import com.baiyue.lastleg.dispatch.pda.dto.DispatchPdaResponses;
+import com.baiyue.lastleg.dispatch.pda.entity.*;
+import com.baiyue.lastleg.dispatch.pda.mapper.*;
+import com.baiyue.lastleg.inventory.command.dto.InventoryCommandRequests;
+import com.baiyue.lastleg.inventory.command.service.InventoryCommandService;
+import com.baiyue.lastleg.inventory.entity.InventoryPosition;
+import com.baiyue.lastleg.inventory.mapper.InventoryPositionMapper;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.annotation.Resource;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.nio.charset.StandardCharsets;
+import java.security.MessageDigest;
+import java.time.LocalDateTime;
+import java.util.*;
+import java.util.stream.Collectors;
+
+@Service
+public class DispatchPdaWorkflowService {
+    @Resource private DispatchOrderMapper orders;
+    @Resource private OutboundOrderMapper outboundOrders;
+    @Resource private DispatchItemMapper items;
+    @Resource private DispatchPdaTaskMapper tasks;
+    @Resource private DispatchPdaPickMapper picks;
+    @Resource private DispatchPdaOperationMapper operations;
+    @Resource private DispatchPalletLockMapper palletLocks;
+    @Resource private InventoryPositionMapper positions;
+    @Resource private InventoryCommandService inventory;
+    @Resource private DispatchPickOrderAttributionService pickAttribution;
+    @Resource private ObjectMapper objectMapper;
+
+    @Transactional
+    public DispatchPdaResponses.Task push(String customerId, String dispatchNo, DispatchPdaRequests.Push request) {
+        DispatchOrder order = requireOrder(customerId, dispatchNo);
+        requirePdaStatus(order);
+        requireVehicle(order);
+        String warehouseId = warehouse(request.warehouseId());
+        requireDispatchWarehouse(order, warehouseId);
+        DispatchPdaOperation replay = replay(customerId, "PUSH", request.idempotencyKey(), request);
+        if (replay != null) return read(replay, DispatchPdaResponses.Task.class);
+        items.bindReceivedPallets(customerId, order.getId());
+        List<DispatchItem> dispatchItems = items.findByDispatchOrder(customerId, order.getId());
+        if (dispatchItems.isEmpty()) throw conflict("Dispatch has no pallets to push");
+        if (dispatchItems.stream().anyMatch(item -> item.getWarehousePalletId() == null)) {
+            throw conflict("All pre-arranged pallets must be received before PDA push");
+        }
+        DispatchPdaTask task = tasks.lockByDispatch(customerId, order.getId());
+        LocalDateTime now = LocalDateTime.now();
+        if (task == null) {
+            task = new DispatchPdaTask();
+            task.setId(IdWorker.getId()); task.setCustomerId(customerId); task.setDispatchOrderId(order.getId());
+            task.setTaskNo("DPDA" + task.getId()); task.setStatus("PDA_PENDING");
+            task.setWarehouseId(warehouseId);
+            task.setOperatorId(trim(request.operatorId())); task.setOperatorName(trim(request.operatorName()));
+            task.setPushedAt(now); task.setCreatedAt(now); task.setUpdatedAt(now); tasks.insert(task);
+        }
+        if ("PENDING_DEPARTURE".equals(order.getStatus())) { order.setStatus("PICKING"); order.setUpdatedAt(now); orders.updateById(order); }
+        if (!warehouseId.equals(task.getWarehouseId())) throw conflict("PDA task warehouse does not match selected warehouse");
+        DispatchPdaResponses.Task result = task(customerId, order, task, dispatchItems);
+        save(customerId, task.getId(), "PUSH", request.idempotencyKey(), request, result);
+        return result;
+    }
+
+    @Transactional(readOnly = true)
+    public DispatchPdaResponses.Task task(String customerId, String dispatchNo) {
+        DispatchOrder order = requireOrder(customerId, dispatchNo);
+        DispatchPdaTask task = tasks.findByDispatch(customerId, order.getId());
+        if (task == null) throw notFound("Dispatch PDA task not found");
+        return task(customerId, order, task, items.findByDispatchOrder(customerId, order.getId()));
+    }
+
+    @Transactional
+    public DispatchPdaResponses.Picked pick(String customerId, String dispatchNo, long itemId,
+                                             String operatorId, DispatchPdaRequests.Pick request) {
+        DispatchOrder order = requireOrder(customerId, dispatchNo);
+        requirePdaStatus(order);
+        requireVehicle(order);
+        String warehouseId = warehouse(request.warehouseId());
+        requireDispatchWarehouse(order, warehouseId);
+        DispatchPdaTask task = tasks.lockByDispatch(customerId, order.getId());
+        if (task == null || !("PDA_PENDING".equals(task.getStatus()) || "PICKING".equals(task.getStatus()))) {
+            throw conflict("Dispatch PDA task is not available for picking");
+        }
+        if (!warehouseId.equals(task.getWarehouseId())) throw conflict("PDA pick warehouse does not match task warehouse");
+        DispatchItem item = items.selectById(itemId);
+        if (item == null || !customerId.equals(item.getCustomerId()) || !order.getId().equals(item.getDispatchOrderId())) {
+            throw notFound("Dispatch pallet item not found");
+        }
+        if (!warehouseId.equals(item.getOverseasWarehouseId())) throw conflict("Pallet does not belong to selected warehouse");
+        DispatchPdaOperation replay = replay(customerId, "PICK", request.idempotencyKey(), request);
+        if (replay != null) return read(replay, DispatchPdaResponses.Picked.class);
+        InventoryPosition position = positions.selectById(request.positionId());
+        if (position == null || !customerId.equals(position.getCustomerId())
+            || item.getWarehousePalletId() == null || !item.getWarehousePalletId().equals(position.getPalletId())) {
+            throw conflict("Inventory position does not belong to this dispatch pallet");
+        }
+        long picked = picks.totalItem(customerId, task.getId(), itemId);
+        if (picked + request.packages() > item.getPackageCount()) throw conflict("Picked packages exceed dispatch pallet packages");
+        String keyBase = "DISPATCH:" + order.getDispatchNo() + ":" + itemId + ":" + request.idempotencyKey();
+        InventoryCommandRequests.Move move = new InventoryCommandRequests.Move(customerId, request.positionId(),
+            request.packages(), order.getDispatchNo(), order.getDispatchNo(), null,
+            keyBase + ":ALLOCATE", request.remark());
+        inventory.allocate(customerId, operatorId, move);
+        inventory.pick(customerId, operatorId, new InventoryCommandRequests.Move(customerId, request.positionId(),
+            request.packages(), order.getDispatchNo(), order.getDispatchNo(), null,
+            keyBase + ":PICK", request.remark()));
+        DispatchPdaPick pick = new DispatchPdaPick();
+        pick.setId(IdWorker.getId()); pick.setCustomerId(customerId); pick.setTaskId(task.getId());
+        pick.setDispatchItemId(itemId); pick.setInventoryPositionId(request.positionId()); pick.setPackages(request.packages());
+        pick.setProductQuantity(request.productQuantity()); pick.setIdempotencyKey(request.idempotencyKey());
+        pick.setPickedAt(LocalDateTime.now()); pick.setCreatedAt(pick.getPickedAt()); picks.insert(pick);
+        pickAttribution.attribute(customerId, pick);
+        long total = picked + request.packages();
+        order.setPickedPackageCount((int) (n(order.getPickedPackageCount()) + request.packages()));
+        task.setStatus("PICKING"); task.setUpdatedAt(LocalDateTime.now());
+        if (allPicked(customerId, task.getId(), items.findByDispatchOrder(customerId, order.getId()))) {
+            task.setStatus("COMPLETED"); task.setCompletedAt(LocalDateTime.now()); order.setStatus("READY_TO_DEPART");
+        }
+        order.setUpdatedAt(LocalDateTime.now());
+        orders.updateById(order);
+        tasks.updateById(task);
+        DispatchPdaResponses.Picked result = new DispatchPdaResponses.Picked(itemId, request.positionId(), request.packages(), total, false, false);
+        save(customerId, task.getId(), "PICK", request.idempotencyKey(), request, result);
+        return result;
+    }
+
+    @Transactional
+    public DispatchPdaResponses.PickingCompleted completePicking(String customerId, String dispatchNo,
+                                                                   DispatchPdaRequests.CompletePicking request) {
+        DispatchOrder found = requireOrder(customerId, dispatchNo);
+        DispatchOrder order = orders.lockById(customerId, found.getId());
+        if (order == null) throw notFound("Dispatch order not found");
+        DispatchPdaOperation replay = replay(customerId, "COMPLETE_PICKING", request.idempotencyKey(), request);
+        if (replay != null) return read(replay, DispatchPdaResponses.PickingCompleted.class).withReplay();
+        requireVehicle(order);
+        DispatchPdaTask task = tasks.lockByDispatch(customerId, order.getId());
+        if (task == null || !("PDA_PENDING".equals(task.getStatus()) || "PICKING".equals(task.getStatus()))) {
+            throw conflict("Dispatch PDA task is not available for completion");
+        }
+        List<DispatchItem> source = items.findByDispatchOrder(customerId, order.getId());
+        long planned = source.stream().map(DispatchItem::getPackageCount).filter(Objects::nonNull)
+            .mapToLong(Integer::longValue).sum();
+        long picked = picks.listTask(customerId, task.getId()).stream().mapToLong(p -> n(p.getPackages())).sum();
+        if (picked <= 0 || picked > planned) throw conflict("PDA completion requires a valid picked package count");
+        boolean partial = picked < planned;
+        LocalDateTime now = LocalDateTime.now();
+        task.setStatus("COMPLETED"); task.setCompletedAt(now); task.setUpdatedAt(now); tasks.updateById(task);
+        order.setStatus(partial ? "PARTIAL_READY_TO_DEPART" : "READY_TO_DEPART");
+        order.setPartialCompletionReason(partial ? request.reason().trim() : null);
+        order.setPickedPackageCount((int) picked);
+        order.setUpdatedAt(now); orders.updateById(order);
+        DispatchPdaResponses.PickingCompleted result = new DispatchPdaResponses.PickingCompleted(order.getDispatchNo(),
+            order.getStatus(), planned, picked, planned - picked, partial, false);
+        save(customerId, task.getId(), "COMPLETE_PICKING", request.idempotencyKey(), request, result);
+        return result;
+    }
+
+    /** Final warehouse exit: only fully PDA-picked dispatches can consume picked inventory. */
+    @Transactional
+    public DispatchPdaResponses.Departed depart(String customerId, String dispatchNo, String operatorId,
+                                                 DispatchPdaRequests.Depart request) {
+        DispatchOrder found = requireOrder(customerId, dispatchNo);
+        DispatchOrder order = orders.lockById(customerId, found.getId());
+        if (order == null) throw notFound("Dispatch order not found");
+        DispatchPdaOperation replay = replay(customerId, "DEPART", request.idempotencyKey(), request);
+        if (replay != null) return read(replay, DispatchPdaResponses.Departed.class).withReplay();
+        requireVehicle(order);
+        OutboundOrder outbound = outboundOrders.lockByDispatch(customerId, order.getId());
+        if (outbound == null || !"WAIT_OUTBOUND".equals(outbound.getStatus())) {
+            throw conflict("Dispatch must be transferred to a pending outbound order before departure");
+        }
+        DispatchPdaTask task = tasks.lockByDispatch(customerId, order.getId());
+        if (task == null || !"COMPLETED".equals(task.getStatus())
+            || !("READY_TO_DEPART".equals(order.getStatus()) || "PARTIAL_READY_TO_DEPART".equals(order.getStatus()))) {
+            throw conflict("Dispatch must complete PDA picking before departure");
+        }
+
+        List<DispatchItem> dispatchItems = items.findByDispatchOrder(customerId, order.getId());
+        boolean partial = "PARTIAL_READY_TO_DEPART".equals(order.getStatus());
+        if (!partial && !allPicked(customerId, task.getId(), dispatchItems)) {
+            throw conflict("Every dispatch pallet must be fully picked before departure");
+        }
+        List<DispatchPdaPick> dispatchPicks = picks.listTask(customerId, task.getId());
+        if (dispatchPicks.isEmpty()) throw conflict("Dispatch has no PDA picks to ship");
+        long shipped = 0;
+        for (DispatchPdaPick pick : dispatchPicks) {
+            String key = "DISPATCH:" + order.getDispatchNo() + ":PICK:" + pick.getId() + ":SHIP";
+            inventory.ship(customerId, operatorId, new InventoryCommandRequests.Move(customerId,
+                pick.getInventoryPositionId(), n(pick.getPackages()),
+                outbound.getOutboundNo(), outbound.getOutboundNo(), null, key, request.remark()));
+            shipped += n(pick.getPackages());
+        }
+        LocalDateTime now = LocalDateTime.now();
+        pickAttribution.depart(customerId, outbound.getOutboundNo(), order.getDispatchNo(), dispatchPicks, now);
+        outbound.setStatus("OUTBOUNDED");
+        outbound.setUpdatedAt(now);
+        outboundOrders.updateById(outbound);
+        order.setShippedPackageCount((int) shipped);
+        order.setStatus(partial ? "PARTIAL_DEPARTED" : "DEPARTED");
+        order.setUpdatedAt(now);
+        orders.updateById(order);
+        releasePalletLocks(customerId, order.getId(), now);
+        DispatchPdaResponses.Departed result = new DispatchPdaResponses.Departed(order.getDispatchNo(),
+            order.getStatus(), shipped, false);
+        save(customerId, task.getId(), "DEPART", request.idempotencyKey(), request, result);
+        return result;
+    }
+
+    private DispatchPdaResponses.Task task(String customerId, DispatchOrder order, DispatchPdaTask task, List<DispatchItem> source) {
+        List<DispatchPdaResponses.Item> values = new ArrayList<>();
+        for (DispatchItem item : source) {
+            List<InventoryPosition> palletPositions = item.getWarehousePalletId() == null ? List.of()
+                : positions.listPallet(customerId, item.getWarehousePalletId());
+            values.add(new DispatchPdaResponses.Item(item.getId(), item.getPalletNo(), item.getDestinationWarehouseCode(),
+                item.getDestinationWarehouseName(), item.getFbaWarehouseCode(), item.getPackageCount(),
+                picks.totalItem(customerId, task.getId(), item.getId()), palletPositions.stream().map(p ->
+                new DispatchPdaResponses.Position(p.getId(), p.getBalanceId(), n(p.getAvailablePackages()),
+                    n(p.getAllocatedPackages()), n(p.getPickedPackages()))).toList()));
+        }
+        return new DispatchPdaResponses.Task(task.getId(), task.getTaskNo(), order.getDispatchNo(), order.getVehiclePlate(), task.getWarehouseId(), task.getStatus(), values);
+    }
+
+    private boolean allPicked(String customerId, Long taskId, List<DispatchItem> source) {
+        return source.stream().allMatch(item -> picks.totalItem(customerId, taskId, item.getId()) == item.getPackageCount());
+    }
+    private void releasePalletLocks(String customerId, Long dispatchOrderId, LocalDateTime now) {
+        List<DispatchPalletLock> activeLocks = palletLocks.selectList(new com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper<DispatchPalletLock>()
+            .eq(DispatchPalletLock::getCustomerId, customerId)
+            .eq(DispatchPalletLock::getDispatchOrderId, dispatchOrderId)
+            .eq(DispatchPalletLock::getStatus, "ACTIVE"));
+        for (DispatchPalletLock lock : activeLocks) {
+            lock.setStatus("RELEASED");
+            lock.setActiveKey(null);
+            lock.setReleasedAt(now);
+            lock.setUpdatedAt(now);
+            palletLocks.updateById(lock);
+        }
+    }
+    private DispatchOrder requireOrder(String customerId, String dispatchNo) { DispatchOrder order = orders.findByDispatchNo(customerId, dispatchNo); if (order == null) throw notFound("Dispatch order not found"); return order; }
+    private void requirePdaStatus(DispatchOrder order) {
+        if (!("PENDING_DEPARTURE".equals(order.getStatus()) || "PICKING".equals(order.getStatus())
+            || "READY_TO_DEPART".equals(order.getStatus()))) throw conflict("Dispatch has already departed and cannot be changed by PDA");
+    }
+    private void requireVehicle(DispatchOrder order) { if (trim(order.getVehiclePlate()) == null) throw conflict("Vehicle plate is required before PDA push or picking"); }
+    private static String warehouse(String value) { return required(value, "Warehouse selection is required for PDA work"); }
+    private static void requireDispatchWarehouse(DispatchOrder order, String warehouseId) {
+        if (trim(order.getOverseasWarehouseId()) == null || !warehouseId.equals(order.getOverseasWarehouseId().trim())) {
+            throw conflict("Selected warehouse does not match dispatch warehouse");
+        }
+    }
+    private DispatchPdaOperation replay(String customerId, String type, String key, Object request) { DispatchPdaOperation op = operations.findKey(customerId, required(key, "Idempotency key is required")); if (op == null) return null; if (!type.equals(op.getOperationType()) || !hash(request).equals(op.getRequestHash())) throw conflict("Idempotency key was reused with a different request"); if (!"COMPLETED".equals(op.getStatus())) throw conflict("PDA operation is still processing"); return op; }
+    private void save(String customerId, Long taskId, String type, String key, Object request, Object result) { DispatchPdaOperation op = new DispatchPdaOperation(); op.setId(IdWorker.getId()); op.setCustomerId(customerId); op.setTaskId(taskId); op.setOperationType(type); op.setIdempotencyKey(required(key,"Idempotency key is required")); op.setRequestHash(hash(request)); op.setResultJson(json(result)); op.setStatus("COMPLETED"); op.setCreatedAt(LocalDateTime.now()); op.setUpdatedAt(op.getCreatedAt()); operations.insert(op); }
+    private <T> T read(DispatchPdaOperation op, Class<T> type) { try { return objectMapper.readValue(op.getResultJson(), type); } catch (Exception e) { throw new IllegalStateException("Cannot read PDA replay", e); } }
+    private String hash(Object value) { try { return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(json(value).getBytes(StandardCharsets.UTF_8))); } catch (Exception e) { throw new IllegalStateException(e); } }
+    private String json(Object value) { try { return objectMapper.writeValueAsString(value); } catch (Exception e) { throw new IllegalStateException(e); } }
+    private static long n(Long value) { return value == null ? 0 : value; }
+    private static long n(Integer value) { return value == null ? 0 : value; }
+    private static String trim(String value) { return value == null || value.trim().isEmpty() ? null : value.trim(); }
+    private static String required(String value, String message) { String result = trim(value); if (result == null) throw new ResponseStatusException(HttpStatus.BAD_REQUEST, message); return result; }
+    private static ResponseStatusException conflict(String message) { return new ResponseStatusException(HttpStatus.CONFLICT, message); }
+    private static ResponseStatusException notFound(String message) { return new ResponseStatusException(HttpStatus.NOT_FOUND, message); }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/pda/service/DispatchPickOrderAttributionService.java

@@ -0,0 +1,105 @@
+package com.baiyue.lastleg.dispatch.pda.service;
+
+import com.baomidou.mybatisplus.core.toolkit.IdWorker;
+import com.baiyue.lastleg.dispatch.pda.entity.DispatchPdaPick;
+import com.baiyue.lastleg.dispatch.pda.entity.DispatchPdaPickOrder;
+import com.baiyue.lastleg.dispatch.pda.mapper.DispatchPdaPickOrderMapper;
+import com.baiyue.lastleg.entity.LastlegOrder;
+import com.baiyue.lastleg.entity.LastlegOrderStatusHistory;
+import com.baiyue.lastleg.inboundplan.pda.entity.InboundStockReceipt;
+import com.baiyue.lastleg.mapper.LastlegOrderMapper;
+import com.baiyue.lastleg.mapper.LastlegOrderStatusHistoryMapper;
+import jakarta.annotation.Resource;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.time.LocalDateTime;
+import java.util.LinkedHashMap;
+import java.util.List;
+import java.util.Map;
+
+@Service
+public class DispatchPickOrderAttributionService {
+    @Resource private DispatchPdaPickOrderMapper attributions;
+    @Resource private LastlegOrderMapper orders;
+    @Resource private LastlegOrderStatusHistoryMapper history;
+
+    /** Call after the inventory position has been locked/moved and the PDA pick row has been inserted. */
+    public List<OrderPackages> attribute(String customerId, DispatchPdaPick pick) {
+        long remainingPackages = value(pick.getPackages());
+        long totalPackages = remainingPackages;
+        long totalQuantity = value(pick.getProductQuantity());
+        long allocatedPackages = 0;
+        long allocatedQuantity = 0;
+        Map<Long, Long> pickedByOrder = new LinkedHashMap<>();
+        for (InboundStockReceipt receipt : attributions.availableReceipts(customerId,
+            pick.getInventoryPositionId())) {
+            if (remainingPackages == 0) break;
+            long receiptPackages = value(receipt.getReceivedPackages())
+                - attributions.attributedPackages(customerId, receipt.getId());
+            if (receiptPackages <= 0) continue;
+            long packages = Math.min(remainingPackages, receiptPackages);
+            long nextPackages = allocatedPackages + packages;
+            long nextQuantity = totalPackages == 0 ? 0 : Math.floorDiv(totalQuantity * nextPackages, totalPackages);
+            long quantity = nextQuantity - allocatedQuantity;
+            DispatchPdaPickOrder row = new DispatchPdaPickOrder();
+            row.setId(IdWorker.getId());
+            row.setCustomerId(customerId);
+            row.setPickId(pick.getId());
+            row.setReceiptId(receipt.getId());
+            row.setOrderId(receipt.getOrderId());
+            row.setPackages(packages);
+            row.setProductQuantity(quantity);
+            row.setCreatedAt(pick.getPickedAt() == null ? LocalDateTime.now() : pick.getPickedAt());
+            attributions.insert(row);
+            pickedByOrder.merge(receipt.getOrderId(), packages, Long::sum);
+            remainingPackages -= packages;
+            allocatedPackages = nextPackages;
+            allocatedQuantity = nextQuantity;
+        }
+        if (remainingPackages != 0) throw conflict("PDA pick cannot be attributed to inbound receipt orders");
+        for (Map.Entry<Long, Long> entry : pickedByOrder.entrySet()) {
+            if (orders.increasePicked(customerId, entry.getKey(), entry.getValue()) != 1) {
+                throw conflict("Picked packages exceed tail-leg order remaining packages");
+            }
+        }
+        return pickedByOrder.entrySet().stream().map(e -> new OrderPackages(e.getKey(), e.getValue())).toList();
+    }
+
+    /** Call once for each departing PDA pick; repeated dispatch departure is protected by its outer idempotency key. */
+    public List<OrderPackages> depart(String customerId, String outboundNo, String dispatchNo, List<DispatchPdaPick> picks,
+                                      LocalDateTime departedAt) {
+        Map<Long, Long> shippedByOrder = new LinkedHashMap<>();
+        for (DispatchPdaPick pick : picks) {
+            for (DispatchPdaPickOrder row : attributions.listPick(customerId, pick.getId())) {
+                shippedByOrder.merge(row.getOrderId(), value(row.getPackages()), Long::sum);
+            }
+        }
+        for (Map.Entry<Long, Long> entry : shippedByOrder.entrySet()) {
+            LastlegOrder before = orders.lockById(customerId, entry.getKey());
+            if (before == null || orders.transferPickedToShipped(customerId, entry.getKey(), entry.getValue(), outboundNo) != 1) {
+                throw conflict("Tail-leg order picked packages are inconsistent");
+            }
+            long shipped = value(before.getShippedPackageCount()) + entry.getValue();
+            String to = shipped == value(before.getPackageCount()) ? "COMPLETED" : "PARTIALLY_SHIPPED";
+            LastlegOrderStatusHistory row = new LastlegOrderStatusHistory();
+            row.setOrderId(entry.getKey());
+            row.setFromStatus(before.getCurrentStatus());
+            row.setToStatus(to);
+            row.setEventId("DISPATCH_DEPART:" + dispatchNo);
+            row.setRemark("Dispatch departed " + entry.getValue() + " packages; cumulative shipped "
+                + shipped + "/" + value(before.getPackageCount()));
+            row.setCreatedAt(departedAt);
+            history.insert(row);
+        }
+        return shippedByOrder.entrySet().stream().map(e -> new OrderPackages(e.getKey(), e.getValue())).toList();
+    }
+
+    public record OrderPackages(Long orderId, long packages) {}
+    private static long value(Long value) { return value == null ? 0 : value; }
+    private static long value(Integer value) { return value == null ? 0 : value; }
+    private static ResponseStatusException conflict(String message) {
+        return new ResponseStatusException(HttpStatus.CONFLICT, message);
+    }
+}

lastleg-service/src/main/java/com/baiyue/lastleg/dispatch/service/DispatchService.java

@@ -0,0 +1,261 @@
+package com.baiyue.lastleg.dispatch.service;
+
+import com.baomidou.mybatisplus.core.conditions.query.LambdaQueryWrapper;
+import com.baomidou.mybatisplus.core.toolkit.IdWorker;
+import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.lastleg.dispatch.dto.DispatchRequests;
+import com.baiyue.lastleg.dispatch.dto.DispatchResponse;
+import com.baiyue.lastleg.dispatch.entity.DispatchItem;
+import com.baiyue.lastleg.dispatch.entity.DispatchOrder;
+import com.baiyue.lastleg.dispatch.entity.DispatchPalletLock;
+import com.baiyue.lastleg.dispatch.mapper.DispatchCandidateMapper;
+import com.baiyue.lastleg.dispatch.mapper.DispatchItemMapper;
+import com.baiyue.lastleg.dispatch.mapper.DispatchOrderMapper;
+import com.baiyue.lastleg.dispatch.mapper.DispatchPalletLockMapper;
+import com.baiyue.lastleg.dispatch.model.DispatchPalletCandidate;
+import jakarta.annotation.Resource;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.http.HttpStatus;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Transactional;
+import org.springframework.util.StringUtils;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.math.BigDecimal;
+import java.time.LocalDateTime;
+import java.time.format.DateTimeFormatter;
+import java.util.HashSet;
+import java.util.List;
+import java.util.Objects;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+@Service
+public class DispatchService {
+    public static final String PENDING_DEPARTURE = "PENDING_DEPARTURE";
+    public static final String CANCELLED = "CANCELLED";
+
+    @Resource private DispatchOrderMapper orders;
+    @Resource private DispatchItemMapper items;
+    @Resource private DispatchPalletLockMapper locks;
+    @Resource private DispatchCandidateMapper candidates;
+
+    public List<DispatchPalletCandidate> candidates(String customerId, String orderNo,
+                                                     String fbaWarehouseCode, String sourceStage) {
+        if (StringUtils.hasText(sourceStage) && !Set.of("PLAN", "RECEIVED").contains(sourceStage)) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "sourceStage must be PLAN or RECEIVED");
+        }
+        return candidates.available(customerId, trimToNull(orderNo), trimToNull(fbaWarehouseCode), trimToNull(sourceStage));
+    }
+
+    @Transactional
+    public DispatchResponse preArrange(String customerId, String operatorId, DispatchRequests.PreArrange request) {
+        List<Long> palletIds = request.planPalletIds().stream().filter(Objects::nonNull).distinct().sorted().toList();
+        if (palletIds.isEmpty() || palletIds.size() != request.planPalletIds().size()) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Plan pallet IDs must be unique and non-empty");
+        }
+        List<DispatchPalletCandidate> selected = candidates.lockSelected(customerId, palletIds);
+        if (selected.size() != palletIds.size()) {
+            throw new ResponseStatusException(HttpStatus.NOT_FOUND, "One or more selected pallets are not in this tenant");
+        }
+        if (selected.stream().anyMatch(candidate -> candidate.packageCount() == null || candidate.packageCount() <= 0)) {
+            throw new ResponseStatusException(HttpStatus.CONFLICT, "Selected pallet has no remaining packages to dispatch");
+        }
+        Set<String> warehouseIds = selected.stream().map(DispatchPalletCandidate::overseasWarehouseId)
+            .filter(Objects::nonNull).map(String::trim).filter(value -> !value.isEmpty()).collect(Collectors.toSet());
+        if (warehouseIds.size() != 1 || selected.stream().anyMatch(candidate -> candidate.overseasWarehouseId() == null)) {
+            throw new ResponseStatusException(HttpStatus.CONFLICT, "A dispatch must belong to exactly one overseas warehouse");
+        }
+        for (DispatchPalletCandidate candidate : selected) {
+            boolean planLocked = candidate.planPalletId() != null
+                && locks.lockActive(customerId, "PLAN:" + candidate.planPalletId()) != null;
+            boolean receivedLocked = candidate.warehousePalletId() != null
+                && locks.lockActive(customerId, "RECEIVED:" + candidate.warehousePalletId()) != null;
+            if (planLocked || receivedLocked) {
+                throw new ResponseStatusException(HttpStatus.CONFLICT,
+                    "Pallet is already locked by another active dispatch: " + candidate.palletNo());
+            }
+        }
+
+        LocalDateTime now = LocalDateTime.now();
+        DispatchOrder dispatch = new DispatchOrder();
+        dispatch.setId(IdWorker.getId());
+        dispatch.setCustomerId(customerId);
+        dispatch.setDispatchNo("PC" + now.format(DateTimeFormatter.BASIC_ISO_DATE) + dispatch.getId());
+        dispatch.setOverseasWarehouseId(selected.get(0).overseasWarehouseId());
+        dispatch.setOverseasWarehouseName(selected.get(0).overseasWarehouseName());
+        dispatch.setRoute(StringUtils.hasText(request.route()) ? request.route().trim() : route(selected));
+        dispatch.setFbaAppointmentNo(trimToNull(request.fbaAppointmentNo()));
+        dispatch.setFbaAppointmentStatus(defaultStatus(request.fbaAppointmentStatus()));
+        dispatch.setVehicleAppointmentStatus(defaultStatus(request.vehicleAppointmentStatus()));
+        dispatch.setStatus(PENDING_DEPARTURE);
+        dispatch.setItemCount(selected.size());
+        dispatch.setPalletCount(selected.size());
+        dispatch.setPackageCount(selected.stream().map(DispatchPalletCandidate::packageCount)
+            .filter(Objects::nonNull).mapToInt(Integer::intValue).sum());
+        dispatch.setPickedPackageCount(0);
+        dispatch.setShippedPackageCount(0);
+        dispatch.setCreatedBy(trimToNull(operatorId));
+        dispatch.setCreatedAt(now);
+        dispatch.setUpdatedAt(now);
+        orders.insert(dispatch);
+
+        for (DispatchPalletCandidate candidate : selected) {
+            DispatchPalletLock lock = new DispatchPalletLock();
+            lock.setId(IdWorker.getId());
+            lock.setCustomerId(customerId);
+            lock.setSourcePalletKey(candidate.sourcePalletKey());
+            lock.setActiveKey(candidate.sourcePalletKey());
+            lock.setPlanId(candidate.planId());
+            lock.setPlanPalletId(candidate.planPalletId());
+            lock.setWarehousePalletId(candidate.warehousePalletId());
+            lock.setDispatchOrderId(dispatch.getId());
+            lock.setStatus("ACTIVE");
+            lock.setLockedAt(now);
+            lock.setCreatedAt(now);
+            lock.setUpdatedAt(now);
+            try {
+                locks.insert(lock);
+            } catch (DuplicateKeyException exception) {
+                throw new ResponseStatusException(HttpStatus.CONFLICT,
+                    "Pallet is already locked by another active dispatch: " + candidate.palletNo(), exception);
+            }
+            DispatchItem item = new DispatchItem();
+            item.setId(IdWorker.getId());
+            item.setDispatchOrderId(dispatch.getId());
+            item.setCustomerId(customerId);
+            item.setPlanId(candidate.planId());
+            item.setPlanPalletId(candidate.planPalletId());
+            item.setWarehousePalletId(candidate.warehousePalletId());
+            item.setOrderId(candidate.orderId());
+            item.setOverseasWarehouseId(candidate.overseasWarehouseId());
+            item.setOverseasWarehouseName(candidate.overseasWarehouseName());
+            item.setOrderNo(candidate.orderNo());
+            item.setOrderRefs(candidate.orderRefs());
+            item.setInboundCode(candidate.inboundCode());
+            item.setPalletNo(candidate.palletNo());
+            item.setDestinationWarehouseId(candidate.destinationWarehouseId());
+            item.setDestinationWarehouseCode(candidate.destinationWarehouseCode());
+            item.setDestinationWarehouseName(candidate.destinationWarehouseName());
+            item.setFbaWarehouseCode(candidate.fbaWarehouseCode());
+            item.setPackageCount(Objects.requireNonNullElse(candidate.packageCount(), 0));
+            item.setVolumeCbm(Objects.requireNonNullElse(candidate.volumeCbm(), BigDecimal.ZERO));
+            item.setSourceStage(candidate.sourceStage());
+            item.setCreatedAt(now);
+            items.insert(item);
+        }
+        return response(dispatch, items.findByDispatchOrder(customerId, dispatch.getId()));
+    }
+
+    public PageResult<DispatchResponse> page(String customerId, DispatchRequests.Query query) {
+        Page<DispatchOrder> page = orders.selectPage(new Page<>(query.page(), query.size()),
+            new LambdaQueryWrapper<DispatchOrder>().eq(DispatchOrder::getCustomerId, customerId)
+                .like(StringUtils.hasText(query.dispatchNo()), DispatchOrder::getDispatchNo, query.dispatchNo())
+                .like(StringUtils.hasText(query.vehiclePlate()), DispatchOrder::getVehiclePlate, query.vehiclePlate())
+                .eq(StringUtils.hasText(query.status()), DispatchOrder::getStatus, query.status())
+                .like(StringUtils.hasText(query.fbaAppointmentNo()), DispatchOrder::getFbaAppointmentNo,
+                    query.fbaAppointmentNo())
+                .orderByDesc(DispatchOrder::getCreatedAt));
+        List<DispatchResponse> records = page.getRecords().stream()
+            .map(order -> response(order, items.findByDispatchOrder(customerId, order.getId()))).toList();
+        return new PageResult<>(records, page.getCurrent(), page.getSize(), page.getTotal(), page.getPages());
+    }
+
+    public DispatchResponse detail(String customerId, String dispatchNo) {
+        DispatchOrder dispatch = find(customerId, dispatchNo);
+        return response(dispatch, items.findByDispatchOrder(customerId, dispatch.getId()));
+    }
+
+    @Transactional
+    public DispatchResponse update(String customerId, String dispatchNo, DispatchRequests.Update request) {
+        DispatchOrder dispatch = orders.lockById(customerId, find(customerId, dispatchNo).getId());
+        if (dispatch == null) throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Dispatch order not found");
+        // Vehicle plate is intentionally editable through all dispatch states.
+        dispatch.setVehiclePlate(trimToNull(request.vehiclePlate()));
+        dispatch.setDriverName(trimToNull(request.driverName()));
+        dispatch.setDriverPhone(trimToNull(request.driverPhone()));
+        dispatch.setCarrierName(trimToNull(request.carrierName()));
+        dispatch.setRoute(trimToNull(request.route()));
+        dispatch.setDepartAt(request.departAt());
+        dispatch.setFbaAppointmentNo(trimToNull(request.fbaAppointmentNo()));
+        dispatch.setFbaAppointmentStatus(defaultStatus(request.fbaAppointmentStatus()));
+        dispatch.setVehicleAppointmentStatus(defaultStatus(request.vehicleAppointmentStatus()));
+        dispatch.setEstimatedArrivalAt(request.estimatedArrivalAt());
+        if (StringUtils.hasText(request.status())) {
+            throw new ResponseStatusException(HttpStatus.BAD_REQUEST,
+                "Dispatch status is PDA-managed and cannot be changed by the edit endpoint");
+        }
+        dispatch.setUpdatedAt(LocalDateTime.now());
+        orders.updateById(dispatch);
+        return response(dispatch, items.findByDispatchOrder(customerId, dispatch.getId()));
+    }
+
+    @Transactional
+    public void cancel(String customerId, String dispatchNo) {
+        DispatchOrder dispatch = orders.lockById(customerId, find(customerId, dispatchNo).getId());
+        if (dispatch == null) throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Dispatch order not found");
+        if (!(PENDING_DEPARTURE.equals(dispatch.getStatus()))) {
+            throw new ResponseStatusException(HttpStatus.CONFLICT, "Dispatched order cannot be cancelled");
+        }
+        LocalDateTime now = LocalDateTime.now();
+        dispatch.setStatus(CANCELLED);
+        dispatch.setUpdatedAt(now);
+        orders.updateById(dispatch);
+        List<DispatchPalletLock> activeLocks = locks.selectList(new LambdaQueryWrapper<DispatchPalletLock>()
+            .eq(DispatchPalletLock::getCustomerId, customerId)
+            .eq(DispatchPalletLock::getDispatchOrderId, dispatch.getId())
+            .eq(DispatchPalletLock::getStatus, "ACTIVE"));
+        for (DispatchPalletLock lock : activeLocks) {
+            lock.setStatus("RELEASED");
+            lock.setActiveKey(null);
+            lock.setReleasedAt(now);
+            lock.setUpdatedAt(now);
+            locks.updateById(lock);
+        }
+    }
+
+    private DispatchOrder find(String customerId, String dispatchNo) {
+        DispatchOrder dispatch = orders.findByDispatchNo(customerId, dispatchNo);
+        if (dispatch == null) throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Dispatch order not found");
+        return dispatch;
+    }
+
+    private DispatchResponse response(DispatchOrder order, List<DispatchItem> itemList) {
+        String orderNos = itemList.stream().flatMap(item -> splitOrderRefs(item.getOrderRefs(), item.getOrderNo()).stream())
+            .distinct().collect(Collectors.joining(","));
+        return new DispatchResponse(order.getId(), order.getDispatchNo(), order.getVehiclePlate(), order.getDriverName(),
+            order.getDriverPhone(), order.getCarrierName(), orderNos, order.getRoute(),
+            order.getOverseasWarehouseId(), order.getOverseasWarehouseName(), order.getDepartAt(),
+            order.getFbaAppointmentNo(), order.getFbaAppointmentStatus(), order.getVehicleAppointmentStatus(),
+            order.getEstimatedArrivalAt(), order.getStatus(), Objects.requireNonNullElse(order.getItemCount(), 0),
+            Objects.requireNonNullElse(order.getPalletCount(), 0), Objects.requireNonNullElse(order.getPackageCount(), 0),
+            Objects.requireNonNullElse(order.getPickedPackageCount(), 0),
+            Objects.requireNonNullElse(order.getShippedPackageCount(), 0),
+            Math.max(0, Objects.requireNonNullElse(order.getPackageCount(), 0)
+                - Objects.requireNonNullElse(order.getShippedPackageCount(), 0)), order.getPartialCompletionReason(),
+            order.getCreatedAt(), itemList.stream().map(item -> new DispatchResponse.Item(item.getId(), item.getPlanPalletId(),
+                item.getWarehousePalletId(), item.getPalletNo(), item.getOverseasWarehouseId(), item.getOverseasWarehouseName(),
+                item.getOrderNo(), item.getOrderRefs(), item.getInboundCode(),
+                item.getDestinationWarehouseCode(), item.getDestinationWarehouseName(), item.getFbaWarehouseCode(),
+                Objects.requireNonNullElse(item.getPackageCount(), 0), item.getVolumeCbm(), item.getSourceStage())).toList());
+    }
+
+    private static String route(List<DispatchPalletCandidate> selected) {
+        return selected.stream().map(DispatchPalletCandidate::destinationWarehouseCode).filter(StringUtils::hasText)
+            .distinct().collect(Collectors.joining(" -> "));
+    }
+
+    private static List<String> splitOrderRefs(String refs, String fallback) {
+        String value = StringUtils.hasText(refs) ? refs : fallback;
+        return StringUtils.hasText(value) ? List.of(value.split(",")) : List.of();
+    }
+
+    private static String defaultStatus(String status) {
+        return StringUtils.hasText(status) ? status.trim().toUpperCase() : "PENDING";
+    }
+
+    private static String trimToNull(String value) {
+        return StringUtils.hasText(value) ? value.trim() : null;
+    }
+}