feat: gate overseas receiving and harden phase4 workflows

2026-08-25 10:31:04 +08:00
parent cb78bc6b41
commit 52b9fc382f
93 changed files with 2779 additions and 201 deletions
@@ -11,6 +11,8 @@ import com.baiyue.lastleg.security.InternalServiceTokenGuard;
 import com.baiyue.lastleg.security.OverseasPermissions;
 import com.baiyue.lastleg.service.LastlegOrderService;
 import com.baiyue.lastleg.service.LoadingCompletedConsumer;
+import com.baiyue.lastleg.shipping.service.ContainerShippingNodeConsumer;
+import com.baiyue.common.event.EventTypes;
 import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.validation.Valid;
@@ -37,17 +39,20 @@ import java.nio.charset.StandardCharsets;
@Tag(name = "Tail-leg orders")
 public class LastlegOrderController {
    @Resource private LoadingCompletedConsumer consumer;
+    @Resource private ContainerShippingNodeConsumer shippingNodeConsumer;
    @Resource private LastlegOrderService orderService;
    @Resource private InternalServiceTokenGuard tokenGuard;

    @PostMapping("/internal/lastleg/events")
-    @Operation(summary = "Receive a first-leg loading-completed event",
-        description = "V2 orders[].destinationType is FBA or OVERSEAS. FBA may use package counts; OVERSEAS requires one carton mark per loaded package. Legacy events are accepted only when the destination type can be inferred safely.")
+    @Operation(summary = "Receive a first-leg loading or actual shipping-node event",
+        description = "Accepts loading-completed V1/V2 and FirstLegContainerShippingNodeRecorded V1 through the internal token boundary; only monotonic actual PICKUP_READY-or-later facts open overseas PDA receiving.")
    public ApiResponse<Integer> receive(
        @RequestHeader(value = "X-Internal-Service-Token", required = false) String token,
        @RequestBody EventEnvelope event) {
        tokenGuard.verify(token);
-        return ApiResponse.success(consumer.consume(event));
+        int consumed = EventTypes.FIRST_LEG_CONTAINER_SHIPPING_NODE_RECORDED.equals(event.eventType())
+            ? shippingNodeConsumer.consume(event) : consumer.consume(event);
+        return ApiResponse.success(consumed);
    }

    @GetMapping("/api/platform/v1/last-leg/orders")
@@ -29,7 +29,7 @@ import java.util.List;
@RestController
@RequestMapping("/api/pda/v1/last-leg/receiving-containers")
@Tag(name = "Overseas PDA container receiving")
-@PreAuthorize("hasAuthority('lastleg:pda:operate')")
+@PreAuthorize("hasAuthority('lastleg:pda:operate') and hasAuthority('ROLE_WAREHOUSE_PICKER')")
 public class ReceivingContainerController {
    public static final String OPERATE_PERMISSION = PdaWarehouseIdentity.OPERATE_PERMISSION;
    @Resource private ReceivingContainerService service;
@@ -114,6 +114,33 @@ public class HttpWarehouseResourceGateway implements WarehouseResourceGateway {
            response.data().fbaWarehouseCode(), response.data().version());
    }

+    @Override
+    public WarehouseLocationReference resolveLocation(long warehouseId, String locationCode) {
+        WarehouseLocationResponse response = client.get()
+            .uri(uri -> uri.path("/internal/v1/warehouse-resource-locks/locations/resolve/{locationCode}")
+                .queryParam("warehouseId", warehouseId).build(locationCode))
+            .header("X-Internal-Service-Token", internalToken).retrieve()
+            .body(WarehouseLocationResponse.class);
+        return location(response);
+    }
+
+    @Override
+    public WarehouseLocationReference resolveLocation(long warehouseId, long locationId) {
+        WarehouseLocationResponse response = client.get()
+            .uri(uri -> uri.path("/internal/v1/warehouse-resource-locks/locations/{locationId}")
+                .queryParam("warehouseId", warehouseId).build(locationId))
+            .header("X-Internal-Service-Token", internalToken).retrieve()
+            .body(WarehouseLocationResponse.class);
+        return location(response);
+    }
+
+    private WarehouseLocationReference location(WarehouseLocationResponse response) {
+        if (response == null || response.data() == null) {
+            throw new ResponseStatusException(HttpStatus.NOT_FOUND, "Warehouse location was not found");
+        }
+        return response.data();
+    }
+
    @Override
    public WarehouseReference requireActiveSharedWarehouse(long warehouseId) {
        WarehouseReferenceResponse response = client.get()
@@ -147,4 +174,5 @@ public class HttpWarehouseResourceGateway implements WarehouseResourceGateway {
    private record ReserveEnvelope(ReserveData data) {}
    private record ReserveData(long lockId) {}
    private record WarehouseReferenceResponse(String code, String message, WarehouseReference data) {}
+    private record WarehouseLocationResponse(String code, String message, WarehouseLocationReference data) {}
 }
@@ -8,6 +8,12 @@ public interface WarehouseResourceGateway {
    void scrap(String customerId, long resourceLockId);
    void scrapPallet(String customerId, long palletId);
    WarehousePalletReference resolvePallet(String palletCode);
+    default WarehouseLocationReference resolveLocation(long warehouseId, String locationCode) {
+        throw new UnsupportedOperationException("Warehouse location resolution is not configured");
+    }
+    default WarehouseLocationReference resolveLocation(long warehouseId, long locationId) {
+        throw new UnsupportedOperationException("Warehouse location resolution is not configured");
+    }
    default WarehouseReference requireActiveSharedWarehouse(long warehouseId) {
        throw new UnsupportedOperationException("Shared warehouse resolution is not configured");
    }
@@ -21,4 +27,6 @@ public interface WarehouseResourceGateway {

    record WarehouseReference(long warehouseId, String warehouseCode, String warehouseName,
                              String status) { }
+    record WarehouseLocationReference(long locationId, String locationCode, String locationType,
+                                      java.math.BigDecimal maxLoadKg, String status) { }
 }
@@ -27,6 +27,7 @@ import com.baiyue.lastleg.inboundplan.pda.mapper.ReceivingContainerSessionMapper
 import com.baiyue.lastleg.inboundplan.pda.mapper.ReceivingSkuReceiptMapper;
 import com.baiyue.lastleg.mapper.LastlegOrderDetailMapper;
 import com.baiyue.lastleg.mapper.LastlegOrderMapper;
+import com.baiyue.lastleg.shipping.mapper.ContainerShippingGateMapper;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.core.type.TypeReference;
 import com.fasterxml.jackson.databind.MapperFeature;
@@ -67,6 +68,7 @@ public class ReceivingContainerService {
    @Resource private ReceivingContainerSessionMapper sessions;
    @Resource private ReceivingContainerOperationMapper operations;
    @Resource private ReceivingSkuReceiptMapper skuReceipts;
+    @Resource private ContainerShippingGateMapper shippingGates;
    @Resource private WarehouseResourceGateway warehouse;
    @Resource private UnloadPhotoFileGateway unloadPhotos;
    @Resource private InboundPdaWorkflowService workflow;
@@ -104,7 +106,8 @@ public class ReceivingContainerService {
    public ReceivingContainerResponses.Session detail(String operatorKey, long overseasWarehouseId, String containerNo) {
        List<InboundPlan> containerPlans = requirePlans(containerNo);
        String customerId = requireSingleCustomer(containerPlans, containerNo);
-        if (!eligible(containerPlans, overseasWarehouseId)) throw notFound("Container is assigned to another overseas warehouse");
+        if (!warehouseEligible(containerPlans, overseasWarehouseId)) throw notFound("Container is assigned to another overseas warehouse");
+        requireReceivingAvailable(customerId, containerNo);
        ReceivingContainerSession current = sessions.findActiveByOperator(activeOperatorKey(operatorKey));
        requireSessionWarehouse(current, overseasWarehouseId);
        if (current != null && !containerNo.equals(current.getContainerNo())) {
@@ -130,7 +133,8 @@ public class ReceivingContainerService {
        }
        List<InboundPlan> containerPlans = requirePlans(containerNo);
        String customerId = requireSingleCustomer(containerPlans, containerNo);
-        if (!eligible(containerPlans, overseasWarehouseId)) throw conflict("Container is assigned to another overseas warehouse");
+        if (!warehouseEligible(containerPlans, overseasWarehouseId)) throw conflict("Container is assigned to another overseas warehouse");
+        requireReceivingAvailable(customerId, containerNo);
        String activeOperatorKey = activeOperatorKey(operatorKey);
        ReceivingContainerSession active = sessions.lockActiveByOperator(activeOperatorKey);
        requireSessionWarehouse(active, overseasWarehouseId);
@@ -641,6 +645,12 @@ public class ReceivingContainerService {
    }

    private boolean eligible(List<InboundPlan> containerPlans, long overseasWarehouseId) {
+        String customerId = requireSingleCustomer(containerPlans, containerPlans.get(0).getContainerNo());
+        return warehouseEligible(containerPlans, overseasWarehouseId)
+            && shippingGates.receivingAvailable(customerId, containerPlans.get(0).getContainerNo()) == 1;
+    }
+
+    private boolean warehouseEligible(List<InboundPlan> containerPlans, long overseasWarehouseId) {
        Set<Long> assigned = containerPlans.stream().map(InboundPlan::getOverseasWarehouseId)
            .filter(Objects::nonNull).collect(Collectors.toSet());
        if (assigned.size() > 1 || (!assigned.isEmpty() && containerPlans.stream()
@@ -650,6 +660,12 @@ public class ReceivingContainerService {
        return assigned.isEmpty() || assigned.contains(overseasWarehouseId);
    }

+    private void requireReceivingAvailable(String customerId, String containerNo) {
+        if (shippingGates.receivingAvailable(customerId, containerNo) != 1) {
+            throw conflict("Container has not reached PICKUP_READY and is not available for overseas receiving");
+        }
+    }
+
    private void claimReceivingWarehouse(String customerId, List<InboundPlan> containerPlans,
                                          WarehouseResourceGateway.WarehouseReference warehouse) {
        long overseasWarehouseId = warehouse.warehouseId();
@@ -68,5 +68,6 @@ public final class LocalLooseboardRequests {
    public record ChangeStatus(
        @NotNull @Min(0) Long version,
        @NotBlank @Size(max = 32) String status,
+        @NotBlank @Size(max = 255) String idempotencyKey,
        @Size(max = 1000) String remark) { }
 }
@@ -17,7 +17,7 @@ public final class LocalLooseboardResponses {

    public record History(
        String operationType, String fromStatus, String toStatus, String operatorId,
-        String changeDetail, String remark, LocalDateTime createdAt) { }
+        String idempotencyKey, String changeDetail, String remark, LocalDateTime createdAt) { }

    public record Detail(
        Summary summary, String originAddress, String destinationAddress, String remark,
@@ -17,6 +17,7 @@ public class LocalLooseboardHistory {
    private String fromStatus;
    private String toStatus;
    private String operatorId;
+    private String idempotencyKey;
    private String changeDetail;
    private String remark;
    private LocalDateTime createdAt;
@@ -0,0 +1,22 @@
+package com.baiyue.lastleg.looseboard.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_local_looseboard_operation")
+public class LocalLooseboardOperation {
+    @TableId(type = IdType.INPUT) private Long id;
+    private Long orderId;
+    private String customerId;
+    private String operationType;
+    private String idempotencyKey;
+    private String requestHash;
+    private Long resultVersion;
+    private String createdBy;
+    private LocalDateTime createdAt;
+}
@@ -0,0 +1,15 @@
+package com.baiyue.lastleg.looseboard.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.lastleg.looseboard.entity.LocalLooseboardOperation;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+@Mapper
+public interface LocalLooseboardOperationMapper extends BaseMapper<LocalLooseboardOperation> {
+    @Select("SELECT * FROM ll_local_looseboard_operation WHERE customer_id=#{customerId} AND order_id=#{orderId} AND idempotency_key=#{key} LIMIT 1")
+    LocalLooseboardOperation findKey(@Param("customerId") String customerId,
+                                     @Param("orderId") Long orderId,
+                                     @Param("key") String key);
+}
@@ -12,8 +12,10 @@ import com.baiyue.lastleg.looseboard.dto.LocalLooseboardRequests;
 import com.baiyue.lastleg.looseboard.dto.LocalLooseboardResponses;
 import com.baiyue.lastleg.looseboard.entity.LocalLooseboardHistory;
 import com.baiyue.lastleg.looseboard.entity.LocalLooseboardOrder;
+import com.baiyue.lastleg.looseboard.entity.LocalLooseboardOperation;
 import com.baiyue.lastleg.looseboard.mapper.LocalLooseboardHistoryMapper;
 import com.baiyue.lastleg.looseboard.mapper.LocalLooseboardOrderMapper;
+import com.baiyue.lastleg.looseboard.mapper.LocalLooseboardOperationMapper;
 import com.baiyue.lastleg.service.LastlegOrderNoGenerator;
 import com.fasterxml.jackson.core.JsonProcessingException;
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -51,6 +53,7 @@ public class LocalLooseboardService {

    @Resource private LocalLooseboardOrderMapper orders;
    @Resource private LocalLooseboardHistoryMapper histories;
+    @Resource private LocalLooseboardOperationMapper operations;
    @Resource private LastlegOrderMapper lastlegOrders;
    @Resource private LastlegOrderStatusHistoryMapper lastlegHistories;
    @Resource private LastlegOrderNoGenerator lastlegOrderNoGenerator;
@@ -88,7 +91,8 @@ public class LocalLooseboardService {
            if (concurrent != null) return replay(customerId, concurrent, requestHash);
            throw exception;
        }
-        history(order, "CREATE", null, PENDING_ACCEPTANCE, operatorId, null, request.remark(), now);
+        history(order, "CREATE", null, PENDING_ACCEPTANCE, operatorId,
+            key, null, request.remark(), now);
        lastlegHistory(customerId, lastlegOrder.getId(), null, lastlegOrder.getCurrentStatus(),
            "Local looseboard order submitted", now);
        return detail(customerId, order.getOrderNo());
@@ -139,7 +143,7 @@ public class LocalLooseboardService {
        touch(order, now);
        orders.updateById(order);
        history(order, "UPDATE", order.getStatus(), order.getStatus(), operatorId,
-            changeDetail(before, after), null, now);
+            null, changeDetail(before, after), null, now);
        return response(order);
    }

@@ -147,6 +151,15 @@ public class LocalLooseboardService {
    public LocalLooseboardResponses.Detail changeStatus(String customerId, String orderNo, String operatorId,
                                                         LocalLooseboardRequests.ChangeStatus request) {
        LocalLooseboardOrder order = lock(customerId, orderNo);
+        String key = request.idempotencyKey().trim();
+        String requestHash = hash(request);
+        LocalLooseboardOperation existing = operations.findKey(customerId, order.getId(), key);
+        if (existing != null) {
+            if (!"STATUS".equals(existing.getOperationType()) || !requestHash.equals(existing.getRequestHash())) {
+                throw conflict("Idempotency key was reused with a different looseboard status payload");
+            }
+            return response(order);
+        }
        if (!request.version().equals(value(order.getVersion()))) throw conflict("Order was changed; refresh and retry");
        String next = norm(request.status());
        if (!STATUSES.contains(next)) throw badRequest("Unsupported looseboard order status");
@@ -160,7 +173,13 @@ public class LocalLooseboardService {
        touch(order, now);
        orders.updateById(order);
        syncLastlegOrder(order, next, now);
-        history(order, "STATUS", from, next, operatorId, null, request.remark(), now);
+        LocalLooseboardOperation operation = new LocalLooseboardOperation();
+        operation.setId(IdWorker.getId()); operation.setOrderId(order.getId());
+        operation.setCustomerId(customerId); operation.setOperationType("STATUS");
+        operation.setIdempotencyKey(key); operation.setRequestHash(requestHash);
+        operation.setResultVersion(order.getVersion()); operation.setCreatedBy(operatorId);
+        operation.setCreatedAt(now); operations.insert(operation);
+        history(order, "STATUS", from, next, operatorId, key, null, request.remark(), now);
        return response(order);
    }

@@ -204,7 +223,8 @@ public class LocalLooseboardService {
            order.getDestinationAddress(), order.getRemark(), order.getCreatedBy(),
            histories.listOrder(order.getCustomerId(), order.getId()).stream()
                .map(value -> new LocalLooseboardResponses.History(value.getOperationType(), value.getFromStatus(),
-                    value.getToStatus(), value.getOperatorId(), value.getChangeDetail(), value.getRemark(),
+                    value.getToStatus(), value.getOperatorId(), value.getIdempotencyKey(),
+                    value.getChangeDetail(), value.getRemark(),
                    value.getCreatedAt())).toList());
    }

@@ -218,7 +238,7 @@ public class LocalLooseboardService {
    }

    private void history(LocalLooseboardOrder order, String type, String from, String to, String operator,
-                         String changeDetail, String remark, LocalDateTime now) {
+                         String idempotencyKey, String changeDetail, String remark, LocalDateTime now) {
        LocalLooseboardHistory history = new LocalLooseboardHistory();
        history.setId(IdWorker.getId());
        history.setOrderId(order.getId());
@@ -227,6 +247,7 @@ public class LocalLooseboardService {
        history.setFromStatus(from);
        history.setToStatus(to);
        history.setOperatorId(operator);
+        history.setIdempotencyKey(trim(idempotencyKey));
        history.setChangeDetail(changeDetail);
        history.setRemark(trim(remark));
        history.setCreatedAt(now);
@@ -0,0 +1,53 @@
+package com.baiyue.lastleg.pda.warehouse.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.pda.security.PdaWarehouseIdentity;
+import com.baiyue.lastleg.pda.warehouse.dto.PdaWarehouseRequests;
+import com.baiyue.lastleg.pda.warehouse.dto.PdaWarehouseResponses;
+import com.baiyue.lastleg.pda.warehouse.service.PdaWarehouseService;
+import jakarta.annotation.Resource;
+import jakarta.validation.Valid;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.security.core.annotation.AuthenticationPrincipal;
+import org.springframework.web.bind.annotation.GetMapping;
+import org.springframework.web.bind.annotation.PostMapping;
+import org.springframework.web.bind.annotation.RequestBody;
+import org.springframework.web.bind.annotation.RequestMapping;
+import org.springframework.web.bind.annotation.RestController;
+
+@RestController
+@RequestMapping("/api/pda/v1/last-leg")
+@PreAuthorize("hasAuthority('lastleg:pda:operate') and hasAuthority('ROLE_WAREHOUSE_PICKER')")
+public class PdaWarehouseController {
+    @Resource private PdaWarehouseService service;
+
+    @PostMapping("/inventory/resolve")
+    public ApiResponse<PdaWarehouseResponses.InventoryScan> inventory(@AuthenticationPrincipal AuthenticatedUser user,
+        @Valid @RequestBody PdaWarehouseRequests.Scan request) {
+        PdaWarehouseIdentity identity = PdaWarehouseIdentity.require(user);
+        return ApiResponse.success(service.inventory(identity.overseasWarehouseId(), request));
+    }
+
+    @PostMapping("/locations/resolve")
+    public ApiResponse<PdaWarehouseResponses.Location> location(@AuthenticationPrincipal AuthenticatedUser user,
+        @Valid @RequestBody PdaWarehouseRequests.Scan request) {
+        PdaWarehouseIdentity identity = PdaWarehouseIdentity.require(user);
+        return ApiResponse.success(service.location(identity.overseasWarehouseId(), request));
+    }
+
+    @PostMapping("/pallets/resolve")
+    public ApiResponse<PdaWarehouseResponses.Pallet> pallet(@AuthenticationPrincipal AuthenticatedUser user,
+        @Valid @RequestBody PdaWarehouseRequests.Scan request) {
+        PdaWarehouseIdentity identity = PdaWarehouseIdentity.require(user);
+        return ApiResponse.success(service.pallet(identity.overseasWarehouseId(), request));
+    }
+
+    @GetMapping("/operations")
+    public ApiResponse<PageResult<PdaWarehouseResponses.Operation>> operations(
+        @AuthenticationPrincipal AuthenticatedUser user, @Valid PdaWarehouseRequests.HistoryQuery query) {
+        PdaWarehouseIdentity identity = PdaWarehouseIdentity.require(user);
+        return ApiResponse.success(service.history(identity.overseasWarehouseId(), identity.operatorKey(), query));
+    }
+}
@@ -11,7 +11,7 @@ import java.util.List;

@Mapper
 public interface PdaWarehouseMapper extends BaseMapper<PdaOperationHistory> {
-    String INVENTORY_SELECT = "SELECT b.customer_id,b.customer_name,b.id balance_id,p.id position_id," +
+    String INVENTORY_SELECT = "SELECT DISTINCT b.customer_id,b.customer_name,b.id balance_id,p.id position_id," +
        "COALESCE(NULLIF(r.sku_code,''),b.sku_code) sku_code," +
        "COALESCE(NULLIF(r.product_name_zh,''),b.product_name_zh) product_name_zh," +
        "COALESCE(NULLIF(r.product_name_en,''),b.product_name_en) product_name_en,b.inbound_code," +
@@ -0,0 +1,101 @@
+package com.baiyue.lastleg.pda.warehouse.service;
+
+import com.baomidou.mybatisplus.core.toolkit.IdWorker;
+import com.baiyue.common.core.api.PageResult;
+import com.baiyue.lastleg.inboundplan.pda.gateway.WarehouseResourceGateway;
+import com.baiyue.lastleg.pda.warehouse.dto.PdaWarehouseRequests;
+import com.baiyue.lastleg.pda.warehouse.dto.PdaWarehouseResponses;
+import com.baiyue.lastleg.pda.warehouse.entity.PdaOperationHistory;
+import com.baiyue.lastleg.pda.warehouse.mapper.PdaWarehouseMapper;
+import com.baiyue.lastleg.pda.warehouse.model.PdaInventoryProjection;
+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;
+
+@Service
+public class PdaWarehouseService {
+    @Resource private PdaWarehouseMapper mapper;
+    @Resource private WarehouseResourceGateway warehouse;
+
+    public PdaWarehouseResponses.InventoryScan inventory(long warehouseId, PdaWarehouseRequests.Scan request) {
+        String code = code(request.code());
+        List<PdaWarehouseResponses.InventoryItem> items = items(mapper.scanInventory(String.valueOf(warehouseId), code));
+        if (items.isEmpty()) throw notFound("Inventory code was not found in the bound warehouse");
+        return new PdaWarehouseResponses.InventoryScan(code, items);
+    }
+
+    public PdaWarehouseResponses.Location location(long warehouseId, PdaWarehouseRequests.Scan request) {
+        WarehouseResourceGateway.WarehouseLocationReference location = warehouse.resolveLocation(warehouseId,
+            code(request.code()));
+        List<PdaWarehouseResponses.InventoryItem> inventory = items(mapper.inventoryByLocation(
+            String.valueOf(warehouseId), location.locationId(), location.locationCode(), "__NO_CARTON__"));
+        long packages = inventory.stream().mapToLong(this::packages).sum();
+        int positions = (int) inventory.stream().map(PdaWarehouseResponses.InventoryItem::positionId).distinct().count();
+        return new PdaWarehouseResponses.Location(location.locationId(), location.locationCode(),
+            location.locationType(), location.maxLoadKg(), location.status(), packages, positions);
+    }
+
+    public PdaWarehouseResponses.Pallet pallet(long warehouseId, PdaWarehouseRequests.Scan request) {
+        WarehouseResourceGateway.WarehousePalletReference pallet = warehouse.resolvePallet(code(request.code()));
+        if (pallet.warehouseId() != warehouseId) throw conflict("Pallet belongs to another overseas warehouse");
+        WarehouseResourceGateway.WarehouseLocationReference location = warehouse.resolveLocation(warehouseId,
+            pallet.locationId());
+        List<PdaWarehouseResponses.InventoryItem> inventory = items(mapper.inventoryByPallet(
+            String.valueOf(warehouseId), pallet.palletId(), "__NO_CARTON__"));
+        long packages = inventory.stream().mapToLong(this::packages).sum();
+        int positions = (int) inventory.stream().map(PdaWarehouseResponses.InventoryItem::positionId).distinct().count();
+        return new PdaWarehouseResponses.Pallet(pallet.palletId(), pallet.palletNo(), pallet.status(), pallet.version(),
+            location.locationId(), location.locationCode(), packages, positions, inventory);
+    }
+
+    public PageResult<PdaWarehouseResponses.Operation> history(long warehouseId, String operatorKey,
+                                                               PdaWarehouseRequests.HistoryQuery query) {
+        long offset = (query.page() - 1) * query.size();
+        List<PdaWarehouseResponses.Operation> rows = mapper.history(warehouseId, operatorKey,
+            trim(query.operationType()), offset, query.size());
+        long total = mapper.countHistory(warehouseId, operatorKey, trim(query.operationType()));
+        return new PageResult<>(rows, query.page(), query.size(), total,
+            total == 0 ? 0 : (total + query.size() - 1) / query.size());
+    }
+
+    public void record(long warehouseId, String customerId, String operatorKey, String operationType,
+                       String businessKey, String status, String idempotencyKey, String requestHash, String summary) {
+        PdaOperationHistory history = new PdaOperationHistory();
+        history.setId(IdWorker.getId()); history.setOverseasWarehouseId(warehouseId);
+        history.setCustomerId(trim(customerId)); history.setOperatorKey(operatorKey);
+        history.setOperationType(operationType); history.setBusinessKey(businessKey); history.setStatus(status);
+        history.setIdempotencyKey(trim(idempotencyKey)); history.setRequestHash(trim(requestHash));
+        history.setSummary(trim(summary)); history.setOccurredAt(LocalDateTime.now()); history.setCreatedAt(history.getOccurredAt());
+        mapper.insert(history);
+    }
+
+    private List<PdaWarehouseResponses.InventoryItem> items(List<PdaInventoryProjection> values) {
+        LinkedHashMap<String, PdaWarehouseResponses.InventoryItem> result = new LinkedHashMap<>();
+        for (PdaInventoryProjection value : values) {
+            String key = value.getPositionId() + ":" + text(value.getSkuCode()) + ":" + text(value.getCartonMark());
+            result.putIfAbsent(key, new PdaWarehouseResponses.InventoryItem(value.getCustomerId(), value.getCustomerName(),
+                number(value.getBalanceId()), number(value.getPositionId()), value.getSkuCode(),
+                first(value.getProductNameZh(), value.getProductNameEn()), value.getInboundCode(), value.getCartonMark(),
+                number(value.getPalletId()), value.getPalletCode(), value.getLocationId(), value.getLocationCode(),
+                number(value.getAvailablePackages()), number(value.getHoldPackages()), number(value.getReceivingPackages()),
+                value.getStatus(), number(value.getVersion())));
+        }
+        return List.copyOf(result.values());
+    }
+
+    private long packages(PdaWarehouseResponses.InventoryItem value) {
+        return value.availablePackages() + value.holdPackages() + value.receivingPackages();
+    }
+    private static String code(String value) { String result = trim(value); if (result == null) throw new ResponseStatusException(HttpStatus.BAD_REQUEST, "Scan code is required"); return result; }
+    private static String trim(String value) { return value == null || value.isBlank() ? null : value.trim(); }
+    private static String text(String value) { return value == null ? "" : value; }
+    private static String first(String first, String second) { String value = trim(first); return value == null ? trim(second) : value; }
+    private static long number(Long value) { return value == null ? 0 : value; }
+    private static ResponseStatusException notFound(String message) { return new ResponseStatusException(HttpStatus.NOT_FOUND, message); }
+    private static ResponseStatusException conflict(String message) { return new ResponseStatusException(HttpStatus.CONFLICT, message); }
+}
@@ -36,7 +36,11 @@ public final class OverseasProcurementRequests {
        String productName, String status, String purchaseWarehouseId,
        LocalDateTime createdFrom, LocalDateTime createdTo) {}

-    public record Review(@NotBlank String decision, @Size(max = 1000) String remark) {}
+    public record Review(
+        @NotNull @Min(0) Long version,
+        @NotBlank String decision,
+        @NotBlank @Size(max = 255) String idempotencyKey,
+        @Size(max = 1000) String remark) {}

    public record Update(
        @NotNull @Min(0) Long version,
@@ -22,7 +22,7 @@ public final class OverseasProcurementResponses {

    public record History(
        String operationType, String fromStatus, String toStatus, String operatorId,
-        String changeDetail, String remark,
+        String idempotencyKey, String changeDetail, String remark,
        LocalDateTime createdAt) {}

    public record Detail(
@@ -42,6 +42,8 @@ public class OverseasProcurementOrder {
    private String createdBy;
    private String reviewedBy;
    private String reviewRemark;
+    private String reviewIdempotencyKey;
+    private String reviewRequestHash;
    private LocalDateTime reviewedAt;
    private Long version;
    private LocalDateTime createdAt;
@@ -17,6 +17,7 @@ public class OverseasProcurementStatusHistory {
    private String fromStatus;
    private String toStatus;
    private String operatorId;
+    private String idempotencyKey;
    private String changeDetail;
    private String remark;
    private LocalDateTime createdAt;
@@ -89,7 +89,8 @@ public class OverseasProcurementService {
            if (concurrent != null) return replay(customerId, concurrent, requestHash);
            throw exception;
        }
-        history(order, "CREATE", null, PENDING_REVIEW, operatorId, null, request.remark(), now);
+        history(order, "CREATE", null, PENDING_REVIEW, operatorId,
+            key, null, request.remark(), now);
        return detail(customerId, order.getOrderNo());
    }

@@ -144,7 +145,8 @@ public class OverseasProcurementService {
            order.getCreatedBy(), order.getReviewedBy(), order.getReviewRemark(), order.getReviewedAt(),
            histories.listOrder(customerId, order.getId()).stream().map(value ->
                new OverseasProcurementResponses.History(value.getOperationType(), value.getFromStatus(),
-                    value.getToStatus(), value.getOperatorId(), value.getChangeDetail(), value.getRemark(),
+                    value.getToStatus(), value.getOperatorId(), value.getIdempotencyKey(),
+                    value.getChangeDetail(), value.getRemark(),
                    value.getCreatedAt())).toList());
    }

@@ -157,16 +159,27 @@ public class OverseasProcurementService {
            default -> throw badRequest("Review decision must be APPROVE or REJECT");
        };
        OverseasProcurementOrder order = lock(customerId, orderNo);
-        if (next.equals(order.getStatus())) return detail(customerId, orderNo);
+        String key = request.idempotencyKey().trim();
+        String requestHash = hash(request);
+        if (key.equals(order.getReviewIdempotencyKey())) {
+            if (!requestHash.equals(order.getReviewRequestHash())) {
+                throw conflict("Review idempotency key was reused with a different payload");
+            }
+            return detail(customerId, orderNo);
+        }
+        if (!request.version().equals(order.getVersion())) throw conflict("Order was changed; refresh and retry");
        if (!PENDING_REVIEW.equals(order.getStatus())) throw conflict("Overseas procurement order was already reviewed");
        LocalDateTime now = LocalDateTime.now();
        order.setStatus(next);
        order.setReviewedBy(operatorId);
        order.setReviewRemark(trim(request.remark()));
+        order.setReviewIdempotencyKey(key);
+        order.setReviewRequestHash(requestHash);
        order.setReviewedAt(now);
        touch(order, now);
        orders.updateById(order);
-        history(order, "REVIEW", PENDING_REVIEW, next, operatorId, null, request.remark(), now);
+        history(order, "REVIEW", PENDING_REVIEW, next, operatorId,
+            key, null, request.remark(), now);
        return detail(customerId, orderNo);
    }

@@ -197,7 +210,7 @@ public class OverseasProcurementService {
        touch(order, now);
        orders.updateById(order);
        history(order, "UPDATE", order.getStatus(), order.getStatus(), operatorId,
-            changeDetail(before, after), null, now);
+            null, changeDetail(before, after), null, now);
        return detail(customerId, orderNo);
    }

@@ -224,7 +237,8 @@ public class OverseasProcurementService {
    }

    private void history(OverseasProcurementOrder order, String operationType, String from, String to,
-                         String operator, String changeDetail, String remark, LocalDateTime now) {
+                         String operator, String idempotencyKey, String changeDetail,
+                         String remark, LocalDateTime now) {
        OverseasProcurementStatusHistory history = new OverseasProcurementStatusHistory();
        history.setId(IdWorker.getId());
        history.setOrderId(order.getId());
@@ -233,6 +247,7 @@ public class OverseasProcurementService {
        history.setFromStatus(from);
        history.setToStatus(to);
        history.setOperatorId(operator);
+        history.setIdempotencyKey(trim(idempotencyKey));
        history.setChangeDetail(changeDetail);
        history.setRemark(trim(remark));
        history.setCreatedAt(now);
@@ -11,6 +11,7 @@ import com.baiyue.lastleg.inboundplan.service.InboundPlanService;
 import com.baiyue.lastleg.inboundplan.dto.InboundPlanResponse;
 import com.baiyue.lastleg.inventory.command.dto.InventoryCommandRequests;
 import com.baiyue.lastleg.inventory.command.service.InventoryCommandService;
+import com.baiyue.lastleg.shipping.mapper.ContainerShippingGateMapper;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import com.fasterxml.jackson.databind.DeserializationFeature;
 import jakarta.annotation.Resource;
@@ -41,6 +42,7 @@ public class LoadingCompletedConsumer {
    @Resource private LastlegOrderNoGenerator orderNoGenerator;
    @Resource private DropshipOrderService dropshipOrders;
    @Resource private InventoryCommandService inventory;
+    @Resource private ContainerShippingGateMapper shippingGates;

    @Transactional(isolation = Isolation.READ_COMMITTED)
    public int consume(EventEnvelope envelope) {
@@ -71,6 +73,9 @@ public class LoadingCompletedConsumer {
            return countOrders(envelope,payload.containerNo());
        }

+        shippingGates.initialize(payload.containerBookingId(), envelope.tenantId(), "",
+            payload.containerNo(), envelope.aggregateVersion(), envelope.handoverVersion());
+
        String orderNo = orderNoGenerator.forContainerNo(payload.containerNo());
        JsonNode rawOrders = envelope.payload().path("orders");
        for (int index = 0; index < payload.orders().size(); index++) {
@@ -0,0 +1,36 @@
+package com.baiyue.lastleg.shipping.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_container_shipping_gate")
+public class ContainerShippingGate {
+    @TableId(type = IdType.INPUT)
+    private String containerBookingId;
+    private String customerId;
+    private String oceanBookingId;
+    private String containerNo;
+    private String status;
+    private String standardNode;
+    private Integer nodeSequence;
+    private LocalDateTime observedAt;
+    private LocalDateTime actualAt;
+    private String locationCode;
+    private String locationName;
+    private String providerCode;
+    private String providerEventId;
+    private String providerNodeCode;
+    private String sourceReference;
+    private String rawPayloadHash;
+    private Long aggregateVersion;
+    private Long handoverVersion;
+    private String lastEventId;
+    private String payloadHash;
+    private LocalDateTime createdAt;
+    private LocalDateTime updatedAt;
+}
@@ -0,0 +1,29 @@
+package com.baiyue.lastleg.shipping.mapper;
+
+import com.baomidou.mybatisplus.core.mapper.BaseMapper;
+import com.baiyue.lastleg.shipping.entity.ContainerShippingGate;
+import org.apache.ibatis.annotations.Insert;
+import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Param;
+import org.apache.ibatis.annotations.Select;
+
+@Mapper
+public interface ContainerShippingGateMapper extends BaseMapper<ContainerShippingGate> {
+    @Select("SELECT * FROM ll_container_shipping_gate WHERE container_booking_id=#{containerBookingId} FOR UPDATE")
+    ContainerShippingGate lock(@Param("containerBookingId") String containerBookingId);
+
+    @Insert("INSERT IGNORE INTO ll_container_shipping_gate(container_booking_id,customer_id,ocean_booking_id," +
+        "container_no,status,node_sequence,aggregate_version,handover_version,created_at,updated_at) VALUES(" +
+        "#{containerBookingId},#{customerId},#{oceanBookingId},#{containerNo},'AWAITING_PICKUP_READY',0," +
+        "#{aggregateVersion},#{handoverVersion},NOW(3),NOW(3))")
+    int initialize(@Param("containerBookingId") String containerBookingId, @Param("customerId") String customerId,
+                   @Param("oceanBookingId") String oceanBookingId, @Param("containerNo") String containerNo,
+                   @Param("aggregateVersion") long aggregateVersion, @Param("handoverVersion") long handoverVersion);
+
+    @Select("SELECT CASE WHEN COUNT(DISTINCT o.source_container_booking_id)=1 " +
+        "AND MIN(CASE WHEN g.status='RECEIVING_AVAILABLE' THEN 1 ELSE 0 END)=1 THEN 1 ELSE 0 END " +
+        "FROM ll_order o LEFT JOIN ll_container_shipping_gate g " +
+        "ON g.container_booking_id=o.source_container_booking_id AND g.customer_id=o.customer_id " +
+        "WHERE o.customer_id=#{customerId} AND o.container_no=#{containerNo}")
+    int receivingAvailable(@Param("customerId") String customerId, @Param("containerNo") String containerNo);
+}
@@ -0,0 +1,123 @@
+package com.baiyue.lastleg.shipping.service;
+
+import com.baiyue.common.event.EventEnvelope;
+import com.baiyue.common.event.EventTypes;
+import com.baiyue.common.event.FirstLegContainerShippingNodeRecordedV1;
+import com.baiyue.common.event.RegionCode;
+import com.baiyue.lastleg.entity.LastlegEventInbox;
+import com.baiyue.lastleg.mapper.LastlegEventInboxMapper;
+import com.baiyue.lastleg.shipping.entity.ContainerShippingGate;
+import com.baiyue.lastleg.shipping.mapper.ContainerShippingGateMapper;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import jakarta.annotation.Resource;
+import org.springframework.dao.DuplicateKeyException;
+import org.springframework.stereotype.Service;
+import org.springframework.transaction.annotation.Isolation;
+import org.springframework.transaction.annotation.Transactional;
+
+import java.time.LocalDateTime;
+import java.time.ZoneOffset;
+
+@Service
+public class ContainerShippingNodeConsumer {
+    public static final int PICKUP_READY_SEQUENCE = 80;
+    @Resource private LastlegEventInboxMapper inboxes;
+    @Resource private ContainerShippingGateMapper gates;
+    @Resource private ObjectMapper objectMapper;
+
+    @Transactional(isolation = Isolation.READ_COMMITTED)
+    public int consume(EventEnvelope envelope) {
+        validate(envelope);
+        FirstLegContainerShippingNodeRecordedV1 payload = payload(envelope);
+        validateEnvelopePayload(envelope, payload);
+        LastlegEventInbox existing = inboxes.selectById(envelope.eventId());
+        if (existing != null) {
+            if (!existing.getPayloadHash().equalsIgnoreCase(envelope.payloadHash())) {
+                throw new IllegalArgumentException("船节点事件摘要冲突");
+            }
+            return 1;
+        }
+        LastlegEventInbox inbox = inbox(envelope);
+        try { inboxes.insert(inbox); }
+        catch (DuplicateKeyException raced) {
+            LastlegEventInbox concurrent = inboxes.selectById(envelope.eventId());
+            if (concurrent == null || !concurrent.getPayloadHash().equalsIgnoreCase(envelope.payloadHash())) {
+                throw new IllegalArgumentException("船节点事件摘要冲突", raced);
+            }
+            return 1;
+        }
+
+        gates.initialize(payload.containerBookingId(), payload.customerId(), payload.oceanBookingId(),
+            payload.containerNo(), 0, 1);
+        ContainerShippingGate gate = gates.lock(payload.containerBookingId());
+        if (gate == null || !payload.customerId().equals(gate.getCustomerId())
+            || !payload.containerNo().equals(gate.getContainerNo())) {
+            throw new IllegalArgumentException("船节点柜号快照与装柜交接不一致");
+        }
+        apply(gate, envelope, payload);
+        gates.updateById(gate);
+        inbox.setStatus("PROCESSED"); inbox.setProcessedAt(LocalDateTime.now()); inboxes.updateById(inbox);
+        return 1;
+    }
+
+    private void apply(ContainerShippingGate gate, EventEnvelope envelope,
+                       FirstLegContainerShippingNodeRecordedV1 payload) {
+        long currentVersion = gate.getAggregateVersion() == null ? 0 : gate.getAggregateVersion();
+        int currentSequence = gate.getNodeSequence() == null ? 0 : gate.getNodeSequence();
+        LocalDateTime actualAt = LocalDateTime.ofInstant(payload.actualAt(), ZoneOffset.UTC);
+        boolean newerVersion = envelope.aggregateVersion() >= currentVersion;
+        boolean newerNode = payload.nodeSequence() > currentSequence;
+        boolean laterSameNode = payload.nodeSequence() == currentSequence
+            && (gate.getActualAt() == null || actualAt.isAfter(gate.getActualAt()));
+        boolean accepted = newerVersion && (newerNode || laterSameNode);
+        if (accepted) {
+            gate.setOceanBookingId(payload.oceanBookingId());
+            gate.setStandardNode(payload.standardNode()); gate.setNodeSequence(payload.nodeSequence());
+            gate.setObservedAt(LocalDateTime.ofInstant(payload.observedAt(), ZoneOffset.UTC)); gate.setActualAt(actualAt);
+            gate.setLocationCode(payload.locationCode()); gate.setLocationName(payload.locationName());
+            gate.setProviderCode(payload.providerCode()); gate.setProviderEventId(payload.providerEventId());
+            gate.setProviderNodeCode(payload.providerNodeCode()); gate.setSourceReference(payload.sourceReference());
+            gate.setRawPayloadHash(payload.rawPayloadHash()); gate.setLastEventId(envelope.eventId());
+            gate.setPayloadHash(envelope.payloadHash());
+        }
+        if (accepted && payload.nodeSequence() >= PICKUP_READY_SEQUENCE) {
+            gate.setStatus("RECEIVING_AVAILABLE");
+        }
+        gate.setAggregateVersion(Math.max(currentVersion, envelope.aggregateVersion()));
+        gate.setHandoverVersion(Math.max(gate.getHandoverVersion() == null ? 0 : gate.getHandoverVersion(),
+            envelope.handoverVersion()));
+        gate.setUpdatedAt(LocalDateTime.now());
+    }
+
+    private void validate(EventEnvelope envelope) {
+        envelope.requireValid();
+        if (!EventTypes.FIRST_LEG_CONTAINER_SHIPPING_NODE_RECORDED.equals(envelope.eventType())
+            || envelope.eventVersion() != 1 || envelope.sourceRegion() != RegionCode.CN
+            || envelope.targetRegion() != RegionCode.OVERSEAS
+            || !"CONTAINER_BOOKING".equals(envelope.aggregateType())
+            || envelope.handoverVersion() == null
+            || envelope.handoverVersion() != envelope.aggregateVersion() + 1) {
+            throw new IllegalArgumentException("船节点交接信封无效");
+        }
+    }
+
+    private void validateEnvelopePayload(EventEnvelope envelope, FirstLegContainerShippingNodeRecordedV1 payload) {
+        if (!envelope.tenantId().equals(payload.customerId())
+            || !envelope.aggregateId().equals(payload.containerBookingId())) {
+            throw new IllegalArgumentException("船节点交接客户或聚合标识不一致");
+        }
+    }
+
+    private FirstLegContainerShippingNodeRecordedV1 payload(EventEnvelope envelope) {
+        try { return objectMapper.treeToValue(envelope.payload(), FirstLegContainerShippingNodeRecordedV1.class); }
+        catch (Exception exception) { throw new IllegalArgumentException("船节点交接负载无效", exception); }
+    }
+
+    private LastlegEventInbox inbox(EventEnvelope envelope) {
+        LastlegEventInbox value = new LastlegEventInbox(); value.setEventId(envelope.eventId());
+        value.setCustomerId(envelope.tenantId()); value.setEventType(envelope.eventType());
+        value.setEventVersion(envelope.eventVersion()); value.setPayloadHash(envelope.payloadHash());
+        value.setPayloadJson(envelope.payload().toString()); value.setStatus("RECEIVED");
+        value.setReceivedAt(LocalDateTime.now()); return value;
+    }
+}
@@ -289,8 +289,7 @@ public class UsTruckOrderService {
            pallet.setUpdatedAt(now);
            pallets.updateById(pallet);
        }
-        int allocated = (int) rows.stream().filter(row -> "ALLOCATED".equals(row.getStatus())).count()
-            + selected.size();
+        int allocated = (int) rows.stream().filter(row -> "ALLOCATED".equals(row.getStatus())).count();
        int accepted = value(order.getReceivedPalletCount());
        if (accepted < 1 || allocated > accepted) throw conflict("Allocated pallet count exceeds accepted pallets");
        String from = order.getStatus();
@@ -330,6 +329,69 @@ public class UsTruckOrderService {
        return command(customerId, orderNo, operatorId, "COMPLETE", IN_TRANSIT, COMPLETED, request);
    }

+    private UsTruckOrderResponses.Detail command(String customerId, String orderNo, String operatorId,
+                                                  String operationType, String expectedStatus, String nextStatus,
+                                                  UsTruckOrderRequests.Command request) {
+        UsTruckOrder order = lock(customerId, orderNo);
+        UsTruckOrderResponses.Detail replay = replayOperation(order, operationType,
+            request.idempotencyKey(), request);
+        if (replay != null) return replay;
+        requireVersion(order, request.version());
+        if (!expectedStatus.equals(order.getStatus())) {
+            throw conflict("Truck order must be " + expectedStatus + " before " + operationType);
+        }
+        if (ALLOCATED.equals(expectedStatus)
+            && value(order.getAllocatedPalletCount()) != value(order.getReceivedPalletCount())) {
+            throw conflict("All accepted pallets must be allocated before dispatch preparation");
+        }
+        return transition(order, operatorId, operationType, request.idempotencyKey(), request,
+            expectedStatus, nextStatus, request.remark());
+    }
+
+    private UsTruckOrderResponses.Detail transition(UsTruckOrder order, String operatorId,
+                                                     String operationType, String idempotencyKey, Object request,
+                                                     String from, String to, String remark) {
+        LocalDateTime now = LocalDateTime.now();
+        order.setStatus(to);
+        touch(order);
+        orders.updateById(order);
+        recordOperation(order, operationType, idempotencyKey, request, operatorId, now);
+        history(order, operationType, from, to, operatorId, idempotencyKey, remark, now);
+        return detail(order.getCustomerId(), order.getOrderNo());
+    }
+
+    private UsTruckOrderResponses.Detail replayOperation(UsTruckOrder order, String operationType,
+                                                          String idempotencyKey, Object request) {
+        String key = idempotencyKey.trim();
+        UsTruckOrderOperation existing = operations.findKey(order.getCustomerId(), order.getId(), key);
+        if (existing == null) return null;
+        if (!operationType.equals(existing.getOperationType()) || !hash(request).equals(existing.getRequestHash())) {
+            throw conflict("Idempotency key was reused with a different truck operation payload");
+        }
+        return detail(order.getCustomerId(), order.getOrderNo());
+    }
+
+    private void recordOperation(UsTruckOrder order, String operationType, String idempotencyKey,
+                                 Object request, String operatorId, LocalDateTime now) {
+        UsTruckOrderOperation operation = new UsTruckOrderOperation();
+        operation.setId(IdWorker.getId());
+        operation.setOrderId(order.getId());
+        operation.setCustomerId(order.getCustomerId());
+        operation.setOperationType(operationType);
+        operation.setIdempotencyKey(idempotencyKey.trim());
+        operation.setRequestHash(hash(request));
+        operation.setResultVersion(order.getVersion());
+        operation.setCreatedBy(operatorId);
+        operation.setCreatedAt(now);
+        operations.insert(operation);
+    }
+
+    private void requireVersion(UsTruckOrder order, Long requestedVersion) {
+        if (!requestedVersion.equals(value(order.getVersion()))) {
+            throw conflict("Order was changed; refresh and retry");
+        }
+    }
+
    private UsTruckOrder lock(String customerId, String orderNo) { UsTruckOrder o = orders.lockNo(customerId, orderNo); if (o == null) throw notFound(); return o; }
    private UsTruckOrderResponses.Detail replay(String customerId, UsTruckOrder order, String hash) { if (!hash.equals(order.getRequestHash())) throw conflict("Idempotency key was reused with different truck data"); return detail(customerId, order.getOrderNo()); }
    private UsTruckOrderResponses.Detail detail(UsTruckOrder o, List<UsTruckOrderStatusHistory> hs) {
@@ -338,15 +400,23 @@ public class UsTruckOrderService {
            .toList();
        return new UsTruckOrderResponses.Detail(summary(o), o.getOriginAddress(), o.getDestinationAddress(),
            o.getRemark(), o.getCreatedBy(), palletDetails,
-            hs.stream().map(h -> new UsTruckOrderResponses.History(h.getFromStatus(), h.getToStatus(),
-                h.getOperatorId(), h.getRemark(), h.getCreatedAt())).toList());
+            hs.stream().map(h -> new UsTruckOrderResponses.History(h.getOperationType(),
+                h.getFromStatus(), h.getToStatus(), h.getOperatorId(), h.getIdempotencyKey(),
+                h.getRemark(), h.getCreatedAt())).toList());
    }
    private UsTruckOrderResponses.Pallet pallet(UsTruckOrderPallet p) {
        return new UsTruckOrderResponses.Pallet(p.getId(), p.getPalletNo(), value(p.getSequenceNo()),
            p.getSource(), p.getStatus(), p.getWarehousePalletId(), p.getPackageCount(), p.getReceivedAt());
    }
-    private UsTruckOrderResponses.Summary summary(UsTruckOrder o) { return new UsTruckOrderResponses.Summary(o.getId(), o.getCustomerId(), o.getOrderNo(), o.getTransportType(), o.getOrigin(), o.getDestination(), o.getContainerType(), value(o.getPalletCount()), value(o.getPackageCount()), value(o.getReceivedPalletCount()), value(o.getAllocatedPalletCount()), value(o.getShippedPalletCount()), o.getTotalWeightKg(), o.getTotalVolumeCbm(), o.getBudgetAmount(), o.getCurrency(), o.getContactName(), o.getContactInfo(), o.getRequestedDate(), o.getStatus(), value(o.getVersion()), o.getCreatedAt(), o.getUpdatedAt()); }
-    private void history(UsTruckOrder o, String from, String to, String operator, String remark, LocalDateTime at) { UsTruckOrderStatusHistory h = new UsTruckOrderStatusHistory(); h.setId(IdWorker.getId()); h.setOrderId(o.getId()); h.setCustomerId(o.getCustomerId()); h.setFromStatus(from); h.setToStatus(to); h.setOperatorId(operator); h.setRemark(trim(remark)); h.setCreatedAt(at); histories.insert(h); }
+    private UsTruckOrderResponses.Summary summary(UsTruckOrder o) { return new UsTruckOrderResponses.Summary(o.getId(), o.getCustomerId(), o.getOrderNo(), o.getTransportType(), o.getOrigin(), o.getDestination(), o.getContainerType(), value(o.getPalletCount()), value(o.getPackageCount()), value(o.getReceivedPalletCount()), value(o.getAllocatedPalletCount()), o.getTotalWeightKg(), o.getTotalVolumeCbm(), o.getBudgetAmount(), o.getCurrency(), o.getContactName(), o.getContactInfo(), o.getRequestedDate(), o.getStatus(), value(o.getVersion()), o.getCreatedAt(), o.getUpdatedAt()); }
+    private void history(UsTruckOrder o, String operationType, String from, String to, String operator,
+                         String idempotencyKey, String remark, LocalDateTime at) {
+        UsTruckOrderStatusHistory h = new UsTruckOrderStatusHistory();
+        h.setId(IdWorker.getId()); h.setOrderId(o.getId()); h.setCustomerId(o.getCustomerId());
+        h.setOperationType(operationType); h.setFromStatus(from); h.setToStatus(to);
+        h.setOperatorId(operator); h.setIdempotencyKey(trim(idempotencyKey)); h.setRemark(trim(remark));
+        h.setCreatedAt(at); histories.insert(h);
+    }
    private void createPlannedPallets(UsTruckOrder order) {
        int existing = pallets.listOrder(order.getCustomerId(), order.getId()).size();
        LocalDateTime now = LocalDateTime.now();
@@ -18,6 +18,23 @@ CREATE TABLE IF NOT EXISTS ll_loading_event_inbox (
  UNIQUE KEY uk_ll_loading_inbox_tenant_key (customer_id,event_type,event_id)
 ) ENGINE=InnoDB COMMENT='头程装柜完成事件接收幂等箱';

+CREATE TABLE IF NOT EXISTS ll_container_shipping_gate (
+  container_booking_id VARCHAR(128) NOT NULL COMMENT '来源头程柜预订ID', customer_id VARCHAR(128) NOT NULL COMMENT '客户标识',
+  ocean_booking_id VARCHAR(128) NOT NULL COMMENT '来源海运订舱ID', container_no VARCHAR(64) NOT NULL COMMENT '实际集装箱号',
+  status VARCHAR(32) NOT NULL DEFAULT 'AWAITING_PICKUP_READY' COMMENT '海外收货门禁状态：AWAITING_PICKUP_READY、RECEIVING_AVAILABLE',
+  standard_node VARCHAR(64) NULL COMMENT '最新有效标准船节点', node_sequence INT NOT NULL DEFAULT 0 COMMENT '最新有效节点单调序号',
+  observed_at DATETIME(3) NULL COMMENT '供应商节点观测时间', actual_at DATETIME(3) NULL COMMENT '节点实际发生时间',
+  location_code VARCHAR(128) NULL COMMENT '节点地点编码', location_name VARCHAR(255) NULL COMMENT '节点地点名称',
+  provider_code VARCHAR(64) NULL COMMENT '船节点供应商编码', provider_event_id VARCHAR(128) NULL COMMENT '供应商事件ID',
+  provider_node_code VARCHAR(128) NULL COMMENT '供应商原始节点编码', source_reference VARCHAR(255) NULL COMMENT '供应商来源引用',
+  raw_payload_hash VARCHAR(64) NULL COMMENT '供应商原始负载SHA-256', aggregate_version BIGINT NOT NULL DEFAULT 0 COMMENT '来源查询聚合版本',
+  handover_version BIGINT NOT NULL DEFAULT 1 COMMENT '跨区交接版本', last_event_id VARCHAR(128) NULL COMMENT '最近采纳的跨区事件ID',
+  payload_hash VARCHAR(71) NULL COMMENT '最近采纳事件规范化负载摘要', created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
+  PRIMARY KEY(container_booking_id), KEY idx_ll_shipping_gate_candidate(customer_id,container_no,status),
+  KEY idx_ll_shipping_gate_version(container_booking_id,aggregate_version,node_sequence)
+) ENGINE=InnoDB COMMENT='海外PDA柜号船节点收货资格快照';
+
 CREATE TABLE IF NOT EXISTS ll_order (
  id BIGINT NOT NULL COMMENT '雪花 ID',
  order_no VARCHAR(32) NOT NULL COMMENT '尾程单号',
@@ -715,6 +732,18 @@ CREATE TABLE IF NOT EXISTS ll_receiving_container_operation (
  UNIQUE KEY uk_ll_receiving_operation(operator_key,idempotency_key), KEY idx_ll_receiving_operation_session(session_id,created_at)
 ) ENGINE=InnoDB COMMENT='海外PDA柜号收货幂等审计记录';

+CREATE TABLE IF NOT EXISTS ll_pda_operation_history (
+  id BIGINT NOT NULL COMMENT 'PDA作业历史ID', overseas_warehouse_id BIGINT NOT NULL COMMENT 'Token冻结的海外实际仓ID',
+  customer_id VARCHAR(128) NULL COMMENT '作业涉及的客户标识', operator_key VARCHAR(128) NOT NULL COMMENT 'PDA操作账号标识',
+  operation_type VARCHAR(64) NOT NULL COMMENT '作业类型', business_key VARCHAR(255) NOT NULL COMMENT '作业业务键',
+  status VARCHAR(32) NOT NULL COMMENT '作业结果状态', idempotency_key VARCHAR(255) NULL COMMENT '写操作幂等键',
+  request_hash VARCHAR(128) NULL COMMENT '写请求内容哈希', summary VARCHAR(1000) NULL COMMENT '作业结果摘要',
+  occurred_at DATETIME(3) NOT NULL COMMENT '作业发生时间', created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
+  PRIMARY KEY(id), UNIQUE KEY uk_ll_pda_history_idempotency(operator_key,idempotency_key),
+  KEY idx_ll_pda_history_operator(overseas_warehouse_id,operator_key,occurred_at),
+  KEY idx_ll_pda_history_business(overseas_warehouse_id,operation_type,business_key)
+) ENGINE=InnoDB COMMENT='海外PDA真实作业历史';
+
 CREATE TABLE IF NOT EXISTS ll_inbound_fba_appointment (
  id BIGINT NOT NULL COMMENT '主键ID',
  customer_id VARCHAR(128) NOT NULL COMMENT '客户租户ID',
@@ -1253,6 +1282,7 @@ CREATE TABLE IF NOT EXISTS ll_cargo_discard_application (
  status VARCHAR(32) NOT NULL DEFAULT 'PENDING_REVIEW' COMMENT '业务状态', remark VARCHAR(1000) NULL COMMENT '备注',
  idempotency_key VARCHAR(255) NOT NULL COMMENT '业务幂等键', request_hash CHAR(64) NOT NULL COMMENT '请求内容哈希',
  created_by VARCHAR(128) NULL COMMENT '创建人ID', reviewed_by VARCHAR(128) NULL COMMENT '审核人ID', review_remark VARCHAR(1000) NULL COMMENT '审核备注',
+  review_idempotency_key VARCHAR(255) NULL COMMENT '审核幂等键', review_request_hash CHAR(64) NULL COMMENT '审核请求内容哈希',
  reviewed_at DATETIME(3) NULL COMMENT '审核时间', created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
  PRIMARY KEY(id), UNIQUE KEY uk_ll_cargo_discard_no(customer_id,discard_no),
@@ -1303,6 +1333,7 @@ CREATE TABLE IF NOT EXISTS ll_overseas_procurement_order (
  estimated_arrival_at DATETIME(3) NULL COMMENT '预计到达时间', status VARCHAR(32) NOT NULL DEFAULT 'PENDING_REVIEW' COMMENT '业务状态',
  remark VARCHAR(1000) NULL COMMENT '备注', idempotency_key VARCHAR(255) NOT NULL COMMENT '业务幂等键', request_hash CHAR(64) NOT NULL COMMENT '请求内容哈希',
  created_by VARCHAR(128) NULL COMMENT '创建人ID', reviewed_by VARCHAR(128) NULL COMMENT '审核人ID', review_remark VARCHAR(1000) NULL COMMENT '审核备注',
+  review_idempotency_key VARCHAR(255) NULL COMMENT '审核幂等键', review_request_hash CHAR(64) NULL COMMENT '审核请求内容哈希',
  reviewed_at DATETIME(3) NULL COMMENT '审核时间', version BIGINT NOT NULL DEFAULT 0 COMMENT '乐观锁版本',
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
  updated_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) ON UPDATE CURRENT_TIMESTAMP(3) COMMENT '更新时间',
@@ -1316,7 +1347,7 @@ CREATE TABLE IF NOT EXISTS ll_overseas_procurement_status_history (
  id BIGINT NOT NULL COMMENT '主键ID', order_id BIGINT NOT NULL COMMENT '订单ID', customer_id VARCHAR(128) NOT NULL COMMENT '客户租户ID',
  operation_type VARCHAR(32) NOT NULL COMMENT '操作类型：CREATE、REVIEW或UPDATE',
  from_status VARCHAR(32) NULL COMMENT '变更前状态', to_status VARCHAR(32) NOT NULL COMMENT '变更后状态', operator_id VARCHAR(128) NULL COMMENT '操作人ID',
-  change_detail JSON NULL COMMENT '字段变更前后值JSON', remark VARCHAR(1000) NULL COMMENT '备注',
+  idempotency_key VARCHAR(255) NULL COMMENT '操作幂等键', change_detail JSON NULL COMMENT '字段变更前后值JSON', remark VARCHAR(1000) NULL COMMENT '备注',
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
  PRIMARY KEY(id), KEY idx_ll_overseas_procurement_history(customer_id,order_id,created_at)
 ) ENGINE=InnoDB COMMENT='海外采购操作流水';
@@ -1335,7 +1366,6 @@ CREATE TABLE IF NOT EXISTS ll_us_truck_order (
  package_count INT NULL COMMENT '可选箱数，零或空值均有效',
  received_pallet_count INT NOT NULL DEFAULT 0 COMMENT 'PDA实收托盘数',
  allocated_pallet_count INT NOT NULL DEFAULT 0 COMMENT '已分配到合车行程的托盘数',
-  shipped_pallet_count INT NOT NULL DEFAULT 0 COMMENT '已出库托盘数',
  total_weight_kg DECIMAL(18,3) NOT NULL DEFAULT 0 COMMENT '总重量（千克）',
  total_volume_cbm DECIMAL(18,6) NOT NULL DEFAULT 0 COMMENT '总体积（立方米）',
  budget_amount DECIMAL(18,2) NULL COMMENT '预算金额',
@@ -1345,8 +1375,6 @@ CREATE TABLE IF NOT EXISTS ll_us_truck_order (
  requested_date DATE NOT NULL COMMENT '要求服务日期',
  status VARCHAR(32) NOT NULL COMMENT '美国卡车订单状态',
  remark VARCHAR(1000) NULL COMMENT '备注',
-  receipt_idempotency_key VARCHAR(255) NULL COMMENT '实物收货幂等键',
-  receipt_request_hash CHAR(64) NULL COMMENT '实物收货请求哈希',
  idempotency_key VARCHAR(255) NOT NULL COMMENT '业务幂等键',
  request_hash CHAR(64) NOT NULL COMMENT '请求内容哈希',
  created_by VARCHAR(128) NULL COMMENT '创建人ID',
@@ -1356,7 +1384,6 @@ CREATE TABLE IF NOT EXISTS ll_us_truck_order (
  PRIMARY KEY(id),
  UNIQUE KEY uk_ll_us_truck_order_no(customer_id,order_no),
  UNIQUE KEY uk_ll_us_truck_order_key(customer_id,idempotency_key),
-  UNIQUE KEY uk_ll_us_truck_receipt_key(customer_id,receipt_idempotency_key),
  KEY idx_ll_us_truck_order_list(customer_id,status,created_at),
  KEY idx_ll_us_truck_order_date(customer_id,requested_date,created_at)
 ) ENGINE=InnoDB COMMENT='美国卡车运输订单';
@@ -1380,13 +1407,25 @@ CREATE TABLE IF NOT EXISTS ll_us_truck_order_pallet (
  KEY idx_ll_us_truck_order_pallet_list(customer_id,order_id,status)
 ) ENGINE=InnoDB COMMENT='美国卡车订单托盘实收记录';

+CREATE TABLE IF NOT EXISTS ll_us_truck_order_operation (
+  id BIGINT NOT NULL COMMENT '操作记录ID', order_id BIGINT NOT NULL COMMENT '美国卡车订单ID',
+  customer_id VARCHAR(128) NOT NULL COMMENT '客户租户ID', operation_type VARCHAR(64) NOT NULL COMMENT '具名操作类型',
+  idempotency_key VARCHAR(255) NOT NULL COMMENT '操作幂等键', request_hash CHAR(64) NOT NULL COMMENT '操作请求内容哈希',
+  result_version BIGINT NOT NULL COMMENT '操作完成后的订单版本', created_by VARCHAR(128) NULL COMMENT '操作人ID',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', PRIMARY KEY(id),
+  UNIQUE KEY uk_ll_us_truck_operation_key(customer_id,order_id,idempotency_key),
+  KEY idx_ll_us_truck_operation_order(customer_id,order_id,created_at)
+) ENGINE=InnoDB COMMENT='美国卡车订单幂等操作账';
+
 CREATE TABLE IF NOT EXISTS ll_us_truck_order_status_history (
  id BIGINT NOT NULL COMMENT '主键ID',
  order_id BIGINT NOT NULL COMMENT '订单ID',
  customer_id VARCHAR(128) NOT NULL COMMENT '客户租户ID',
+  operation_type VARCHAR(64) NOT NULL COMMENT '具名操作类型',
  from_status VARCHAR(32) NULL COMMENT '变更前状态',
  to_status VARCHAR(32) NOT NULL COMMENT '变更后状态',
  operator_id VARCHAR(128) NULL COMMENT '操作人ID',
+  idempotency_key VARCHAR(255) NULL COMMENT '操作幂等键',
  remark VARCHAR(1000) NULL COMMENT '备注',
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间',
  PRIMARY KEY(id),
@@ -1421,7 +1460,17 @@ CREATE TABLE IF NOT EXISTS ll_local_looseboard_history (
  id BIGINT NOT NULL COMMENT '主键ID', order_id BIGINT NOT NULL COMMENT '本土散板订单ID', customer_id VARCHAR(128) NOT NULL COMMENT '客户租户ID',
  operation_type VARCHAR(32) NOT NULL COMMENT '操作类型：CREATE、UPDATE或STATUS', from_status VARCHAR(32) NULL COMMENT '变更前状态',
  to_status VARCHAR(32) NOT NULL COMMENT '变更后状态', operator_id VARCHAR(128) NULL COMMENT '操作人ID',
-  change_detail JSON NULL COMMENT '字段变更前后值JSON', remark VARCHAR(1000) NULL COMMENT '操作备注',
+  idempotency_key VARCHAR(255) NULL COMMENT '操作幂等键', change_detail JSON NULL COMMENT '字段变更前后值JSON', remark VARCHAR(1000) NULL COMMENT '操作备注',
  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', PRIMARY KEY(id),
  KEY idx_ll_local_looseboard_history(customer_id,order_id,created_at)
 ) ENGINE=InnoDB COMMENT='本土散板操作流水';
+
+CREATE TABLE IF NOT EXISTS ll_local_looseboard_operation (
+  id BIGINT NOT NULL COMMENT '操作记录ID', order_id BIGINT NOT NULL COMMENT '本土散板订单ID',
+  customer_id VARCHAR(128) NOT NULL COMMENT '客户租户ID', operation_type VARCHAR(32) NOT NULL COMMENT '操作类型',
+  idempotency_key VARCHAR(255) NOT NULL COMMENT '操作幂等键', request_hash CHAR(64) NOT NULL COMMENT '操作请求内容哈希',
+  result_version BIGINT NOT NULL COMMENT '操作完成后的订单版本', created_by VARCHAR(128) NULL COMMENT '操作人ID',
+  created_at DATETIME(3) NOT NULL DEFAULT CURRENT_TIMESTAMP(3) COMMENT '创建时间', PRIMARY KEY(id),
+  UNIQUE KEY uk_ll_local_looseboard_operation_key(customer_id,order_id,idempotency_key),
+  KEY idx_ll_local_looseboard_operation_order(customer_id,order_id,created_at)
+) ENGINE=InnoDB COMMENT='本土散板订单幂等操作账';
@@ -6,7 +6,7 @@ paths:
  /api/pda/v1/last-leg/receiving-containers/candidates:
    get:
      summary: 查询当前客户待签收柜号
-      description: 权限 lastleg:pda:operate；仅 PLATFORM WAREHOUSE_PICKER 可用，操作账号从 Token 获取，客户由所选柜业务事实唯一解析，不接收 customerId。
+      description: 权限 lastleg:pda:operate；仅 PLATFORM WAREHOUSE_PICKER 可用；仅返回已单调消费 PICKUP_READY(80) 或更高实际船节点、状态为 RECEIVING_AVAILABLE 的柜，不接收 customerId。
      security: [{ bearerAuth: [] }]
      responses: { '200': { description: 柜号候选及箱数进度, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingCandidateListApiResponse' } } } }, '403': { description: 缺少 PDA 操作权限 } }
  /api/pda/v1/last-leg/receiving-containers/{containerNo}:
@@ -19,7 +19,7 @@ paths:
  /api/pda/v1/last-leg/receiving-containers/{containerNo}/prepare:
    post:
      summary: 选择当前待签收柜号
-      description: 权限 lastleg:pda:operate；建立 WAIT_SIGN 会话并以平台操作账号、柜号全局双唯一键防止切柜或多人同时处理。
+      description: 权限 lastleg:pda:operate；仅 RECEIVING_AVAILABLE 柜可建立 WAIT_SIGN 会话，并以平台操作账号、柜号全局双唯一键防止切柜或多人同时处理。
      security: [{ bearerAuth: [] }]
      parameters: [{ name: containerNo, in: path, required: true, schema: { type: string } }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingAction' } } } }
@@ -86,6 +86,37 @@ paths:
      security: [{ bearerAuth: [] }]
      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingAction' } } } }
      responses: { '200': { description: COMPLETED 柜号会话, content: { application/json: { schema: { $ref: '#/components/schemas/ReceivingSessionApiResponse' } } } }, '409': { description: 数量未核平或状态冲突 } }
+  /api/pda/v1/last-leg/inventory/resolve:
+    post:
+      summary: PDA按SKU、箱唛或入仓码扫码查询库存
+      description: 仅 WAREHOUSE_PICKER + lastleg:pda:operate；海外实际仓只取Token overseasWarehouseId，不接收客户或仓库参数。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PdaWarehouseScan' } } } }
+      responses: { '200': { description: 同仓跨客户库存与物理仓位事实, content: { application/json: { schema: { $ref: '#/components/schemas/PdaInventoryScanApiResponse' } } } }, '404': { description: A0404：当前绑定仓无匹配库存 } }
+  /api/pda/v1/last-leg/locations/resolve:
+    post:
+      summary: PDA查询库位容量、状态与库存占用
+      description: 库位从Warehouse Overseas公共资源解析，并强制匹配Token绑定仓。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PdaWarehouseScan' } } } }
+      responses: { '200': { description: 库位物理事实及Lastleg库存占用汇总, content: { application/json: { schema: { $ref: '#/components/schemas/PdaLocationApiResponse' } } } }, '404': { description: A0404：库位不存在或跨仓 } }
+  /api/pda/v1/last-leg/pallets/resolve:
+    post:
+      summary: PDA查询托盘、库位与绑定库存
+      description: 托盘从Warehouse Overseas公共资源解析；跨Token绑定仓返回A0409。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/PdaWarehouseScan' } } } }
+      responses: { '200': { description: 托盘物理事实及Lastleg绑定库存, content: { application/json: { schema: { $ref: '#/components/schemas/PdaPalletApiResponse' } } } }, '409': { description: A0409：托盘属于其他仓 } }
+  /api/pda/v1/last-leg/operations:
+    get:
+      summary: 查询当前PDA账号真实作业历史
+      description: 返回Token绑定仓内当前操作账号的柜号作业及盘点、移库、托盘、换标历史；不含出库或派送。
+      security: [{ bearerAuth: [] }]
+      parameters:
+        - { name: page, in: query, schema: { type: integer, minimum: 1, default: 1 } }
+        - { name: size, in: query, schema: { type: integer, minimum: 1, maximum: 200, default: 20 } }
+        - { name: operationType, in: query, schema: { type: string } }
+      responses: { '200': { description: 真实作业历史分页, content: { application/json: { schema: { $ref: '#/components/schemas/PdaOperationPageApiResponse' } } } } }
  /api/platform/v1/last-leg/orders:
    get:
      summary: 分页查询尾程订单
@@ -269,14 +300,14 @@ paths:
  /api/platform/v1/last-leg/overseas-procurements/{orderNo}/review:
    post:
      summary: 审核海外采购订单
-      description: 权限 platform:overseas-business:purchase:review。
+      description: 权限 platform:overseas-business:purchase:review；同幂等键同请求重放成功，异请求、旧 version 或终态反向审核返回 A0409。
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: orderNo, in: path, required: true, schema: { type: string } }
        - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
      requestBody:
        required: true
-        content: { application/json: { schema: { type: object, required: [decision], properties: { decision: { type: string, enum: [APPROVE, REJECT] }, remark: { type: string, nullable: true, maxLength: 1000 } } } } }
+        content: { application/json: { schema: { $ref: '#/components/schemas/ProcurementReview' } } }
      responses: { '200': { description: 统一 ApiResponse 包装的采购订单详情 } }
  /api/merchant/v1/last-leg/overseas-procurements:
    post:
@@ -325,14 +356,24 @@ paths:
      responses: { '200': { description: 统一 ApiResponse 包装的卡车订单详情 } }
  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/status:
    patch:
-      summary: 推进本土卡车订单状态
-      description: 权限 platform:overseas-business:truck:status；普通编辑接口不能修改状态。
+      summary: 取消未发车的本土卡车订单
+      description: 权限 platform:overseas-business:truck:status；该通用入口只接受 CANCELLED，正向状态必须使用具名命令，不能绕过实收、超托与分配事实。
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: orderNo, in: path, required: true, schema: { type: string } }
        - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
-      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version, status], properties: { version: { type: integer, format: int64, minimum: 0 }, status: { $ref: '#/components/schemas/TruckStatus' }, remark: { type: string, nullable: true, maxLength: 1000 } } } } } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCancel' } } } }
      responses: { '200': { description: 统一 ApiResponse 包装的卡车订单详情 }, '409': { description: 非法状态迁移 } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/review:
+    parameters: &truckOrderTarget
+      - { name: orderNo, in: path, required: true, schema: { type: string } }
+      - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+    post:
+      summary: 审核本土卡车订单
+      description: 权限 platform:overseas-business:truck:status；PENDING_REVIEW 审核通过进入 WAITING_INBOUND 并生成预期托盘；拒绝进入 REJECTED。幂等键异请求、旧 version 或非法跳转返回 A0409。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckReview' } } } }
+      responses: { '200': { description: 卡车订单详情 }, '409': { description: 版本、状态或幂等冲突 } }
  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/receive-pallets:
    post:
      summary: 记录本土卡车订单实收托盘
@@ -341,7 +382,56 @@ paths:
      parameters:
        - { name: orderNo, in: path, required: true, schema: { type: string } }
        - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckReceivePallets' } } } }
      responses: { '200': { description: 统一 ApiResponse 包装的卡车订单详情 } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/review-pallet-overage:
+    parameters: *truckOrderTarget
+    post:
+      summary: 审核实收超出申报数的托盘
+      description: 权限 platform:overseas-business:truck:status；APPROVE 将超收托盘纳入本单并进入 WAITING_CONSOLIDATION；REJECT 标记超收托盘拒收并按原申报数继续。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckReviewPalletOverage' } } } }
+      responses: { '200': { description: 卡车订单详情 }, '409': { description: 版本、状态或幂等冲突 } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/allocate-pallets:
+    parameters: *truckOrderTarget
+    post:
+      summary: 分配已实收托盘到本土卡车行程
+      description: 权限 platform:overseas-business:truck:status；仅接收本单 RECEIVED 托盘 ID；部分分配进入 PARTIALLY_ALLOCATED，全部分配进入 ALLOCATED。不创建海外仓出库单或扣减库存。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckAllocatePallets' } } } }
+      responses: { '200': { description: 卡车订单详情 }, '409': { description: 托盘归属、状态、版本或幂等冲突 } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/prepare-dispatch:
+    parameters: *truckOrderTarget
+    post:
+      summary: 全部托盘分配后准备派车
+      description: 权限 platform:overseas-business:truck:status；旧 version、幂等键异请求或非 ALLOCATED 状态返回 A0409。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCommand' } } } }
+      responses: { '200': { description: 状态 PENDING_DISPATCH } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/dispatch:
+    parameters: *truckOrderTarget
+    post:
+      summary: 确认本土卡车已派车
+      description: 权限 platform:overseas-business:truck:status；本土卡车单自身履约，不创建海外仓排车单、出库单或派送单。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCommand' } } } }
+      responses: { '200': { description: 状态 DISPATCHED } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/start-transit:
+    parameters: *truckOrderTarget
+    post:
+      summary: 确认本土卡车开始运输
+      description: 权限 platform:overseas-business:truck:status；仅 DISPATCHED 可进入 IN_TRANSIT。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCommand' } } } }
+      responses: { '200': { description: 状态 IN_TRANSIT } }
+  /api/platform/v1/last-leg/us-truck-orders/{orderNo}/complete:
+    parameters: *truckOrderTarget
+    post:
+      summary: 完成本土卡车订单
+      description: 权限 platform:overseas-business:truck:status；仅 IN_TRANSIT 可进入不可逆 COMPLETED。
+      security: [{ bearerAuth: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/TruckCommand' } } } }
+      responses: { '200': { description: 状态 COMPLETED } }
  /api/platform/v1/last-leg/local-looseboard-orders:
    get:
      summary: 分页查询本土散板订单
@@ -373,12 +463,12 @@ paths:
  /api/platform/v1/last-leg/local-looseboard-orders/{orderNo}/status:
    patch:
      summary: 推进或取消本土散板订单
-      description: 权限 platform:overseas-business:looseboard:status；只允许 PENDING_ACCEPTANCE→DISPATCHED→IN_TRANSIT→COMPLETED，未完成节点按规则取消。
+      description: 权限 platform:overseas-business:looseboard:status；只允许 PENDING_ACCEPTANCE→DISPATCHED→IN_TRANSIT→COMPLETED，另建订单可进入 CANCELLED；幂等键异请求、旧 version、非法跳转或终态反向返回 A0409。
      security: [{ bearerAuth: [] }]
      parameters:
        - { name: orderNo, in: path, required: true, schema: { type: string } }
        - { name: customerId, in: query, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
-      requestBody: { required: true, content: { application/json: { schema: { type: object, required: [version, status], properties: { version: { type: integer, format: int64, minimum: 0 }, status: { $ref: '#/components/schemas/LooseboardStatus' }, remark: { type: string, nullable: true, maxLength: 1000 } } } } } }
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/LooseboardStatusChange' } } } }
      responses: { '200': { description: 统一 ApiResponse 包装的散板订单详情 }, '409': { description: 非法状态迁移 } }
  /api/platform/v1/last-leg/relabel-applications:
    get:
@@ -423,6 +513,101 @@ paths:
      responses: { '200': { description: 统一 ApiResponse 包装的换标单详情 }, '409': { description: 非法状态迁移或关联尾程单缺失 } }
 components:
  schemas:
+    PdaWarehouseScan:
+      type: object
+      required: [code]
+      properties: { code: { type: string, minLength: 1, maxLength: 128 } }
+    PdaInventoryItem:
+      type: object
+      required: [customerId, balanceId, positionId, inboundCode, palletId, palletCode, availablePackages, holdPackages, receivingPackages, status, version]
+      properties:
+        customerId: { type: string }
+        customerName: { type: string, nullable: true }
+        balanceId: { type: integer, format: int64 }
+        positionId: { type: integer, format: int64 }
+        skuCode: { type: string, nullable: true }
+        productName: { type: string, nullable: true }
+        inboundCode: { type: string }
+        cartonMark: { type: string, nullable: true }
+        palletId: { type: integer, format: int64 }
+        palletCode: { type: string }
+        locationId: { type: integer, format: int64, nullable: true }
+        locationCode: { type: string, nullable: true }
+        availablePackages: { type: integer, format: int64, minimum: 0 }
+        holdPackages: { type: integer, format: int64, minimum: 0 }
+        receivingPackages: { type: integer, format: int64, minimum: 0 }
+        status: { type: string }
+        version: { type: integer, format: int64, minimum: 0 }
+    PdaInventoryScan:
+      type: object
+      required: [queryCode, items]
+      properties:
+        queryCode: { type: string }
+        items: { type: array, items: { $ref: '#/components/schemas/PdaInventoryItem' } }
+    PdaLocation:
+      type: object
+      required: [locationId, locationCode, locationType, status, occupiedPackages, inventoryPositionCount]
+      properties:
+        locationId: { type: integer, format: int64 }
+        locationCode: { type: string }
+        locationType: { type: string }
+        maxLoadKg: { type: number, nullable: true }
+        status: { type: string }
+        occupiedPackages: { type: integer, format: int64, minimum: 0 }
+        inventoryPositionCount: { type: integer, minimum: 0 }
+    PdaPallet:
+      type: object
+      required: [palletId, palletCode, status, version, locationId, locationCode, occupiedPackages, inventoryPositionCount, inventory]
+      properties:
+        palletId: { type: integer, format: int64 }
+        palletCode: { type: string }
+        status: { type: string }
+        version: { type: integer, minimum: 0 }
+        locationId: { type: integer, format: int64 }
+        locationCode: { type: string }
+        occupiedPackages: { type: integer, format: int64, minimum: 0 }
+        inventoryPositionCount: { type: integer, minimum: 0 }
+        inventory: { type: array, items: { $ref: '#/components/schemas/PdaInventoryItem' } }
+    PdaOperation:
+      type: object
+      required: [operationId, operationType, businessKey, status, occurredAt]
+      properties:
+        operationId: { type: integer, format: int64 }
+        operationType: { type: string }
+        businessKey: { type: string }
+        status: { type: string }
+        summary: { type: string, nullable: true }
+        customerId: { type: string, nullable: true }
+        occurredAt: { type: string, format: date-time }
+    PdaInventoryScanApiResponse:
+      allOf:
+        - { $ref: '#/components/schemas/ReceivingApiResponseBase' }
+        - type: object
+          properties: { data: { $ref: '#/components/schemas/PdaInventoryScan' } }
+    PdaLocationApiResponse:
+      allOf:
+        - { $ref: '#/components/schemas/ReceivingApiResponseBase' }
+        - type: object
+          properties: { data: { $ref: '#/components/schemas/PdaLocation' } }
+    PdaPalletApiResponse:
+      allOf:
+        - { $ref: '#/components/schemas/ReceivingApiResponseBase' }
+        - type: object
+          properties: { data: { $ref: '#/components/schemas/PdaPallet' } }
+    PdaOperationPageApiResponse:
+      allOf:
+        - { $ref: '#/components/schemas/ReceivingApiResponseBase' }
+        - type: object
+          properties:
+            data:
+              type: object
+              required: [records, page, size, total, pages]
+              properties:
+                records: { type: array, items: { $ref: '#/components/schemas/PdaOperation' } }
+                page: { type: integer }
+                size: { type: integer }
+                total: { type: integer, format: int64 }
+                pages: { type: integer, format: int64 }
    ReceivingAction:
      type: object
      required: [idempotencyKey]
@@ -765,6 +950,14 @@ components:
        status: { $ref: '#/components/schemas/RelabelStatus' }
        remark: { type: string, nullable: true, maxLength: 1000 }
    ProcurementStatus: { type: string, enum: [PENDING_REVIEW, APPROVED, REJECTED] }
+    ProcurementReview:
+      type: object
+      required: [version, decision, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        decision: { type: string, enum: [APPROVE, REJECT] }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
    ProcurementCreate:
      type: object
      required: [purchaseCategory, productName, purchaseQuantity, contactName, contactPhone, idempotencyKey]
@@ -812,6 +1005,49 @@ components:
        code: { type: string, enum: ['200'] }
        data: { type: array, items: { type: object, properties: { warehouseId: { type: string }, warehouseCode: { type: string }, warehouseName: { type: string }, countryCode: { type: string } } } }
    TruckStatus: { type: string, enum: [PENDING_REVIEW, WAITING_INBOUND, RECEIVING, WAITING_CONSOLIDATION, PALLET_OVERAGE_REVIEW, PARTIALLY_ALLOCATED, ALLOCATED, PENDING_DISPATCH, DISPATCHED, IN_TRANSIT, COMPLETED, REJECTED, CANCELLED] }
+    TruckReview:
+      type: object
+      required: [version, decision, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        decision: { type: string, enum: [APPROVE, REJECT] }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
+    TruckCancel:
+      type: object
+      required: [version, status, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        status: { type: string, enum: [CANCELLED] }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
+    TruckReceivePallets:
+      type: object
+      required: [version, actualPalletCount, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        actualPalletCount: { type: integer, minimum: 1 }
+        packageCount: { type: integer, nullable: true, minimum: 0 }
+        palletPackageCounts: { type: array, maxItems: 500, items: { type: integer, minimum: 0 } }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
+    TruckReviewPalletOverage:
+      allOf: [{ $ref: '#/components/schemas/TruckReview' }]
+    TruckAllocatePallets:
+      type: object
+      required: [version, palletIds, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        palletIds: { type: array, minItems: 1, maxItems: 500, uniqueItems: true, items: { type: integer, format: int64, minimum: 1 } }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
+    TruckCommand:
+      type: object
+      required: [version, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
    TruckCreate:
      type: object
      required: [origin, destination, palletCount, totalWeightKg, totalVolumeCbm, contactName, contactInfo, requestedDate, idempotencyKey]
@@ -855,6 +1091,14 @@ components:
        requestedDate: { type: string, format: date }
        remark: { type: string, nullable: true, maxLength: 1000 }
    LooseboardStatus: { type: string, enum: [PENDING_ACCEPTANCE, DISPATCHED, IN_TRANSIT, COMPLETED, CANCELLED] }
+    LooseboardStatusChange:
+      type: object
+      required: [version, status, idempotencyKey]
+      properties:
+        version: { type: integer, format: int64, minimum: 0 }
+        status: { $ref: '#/components/schemas/LooseboardStatus' }
+        idempotencyKey: { type: string, minLength: 1, maxLength: 255 }
+        remark: { type: string, nullable: true, maxLength: 1000 }
    LooseboardCreate:
      type: object
      required: [transportMode, palletRequired, transportType, origin, destination, packageCount, totalWeightKg, totalVolumeCbm, idempotencyKey]
@@ -8,6 +8,7 @@ import com.baiyue.lastleg.dto.LastlegOrderSummary;
 import com.baiyue.lastleg.security.InternalServiceTokenGuard;
 import com.baiyue.lastleg.service.LastlegOrderService;
 import com.baiyue.lastleg.service.LoadingCompletedConsumer;
+import com.baiyue.lastleg.shipping.service.ContainerShippingNodeConsumer;
 import org.junit.jupiter.api.Test;
 import org.springframework.test.util.ReflectionTestUtils;
 import org.springframework.web.server.ResponseStatusException;
@@ -52,6 +53,7 @@ class LastlegOrderControllerTest {
    private LastlegOrderController controller() {
        LastlegOrderController controller = new LastlegOrderController();
        ReflectionTestUtils.setField(controller, "consumer", mock(LoadingCompletedConsumer.class));
+        ReflectionTestUtils.setField(controller, "shippingNodeConsumer", mock(ContainerShippingNodeConsumer.class));
        ReflectionTestUtils.setField(controller, "orderService", service);
        ReflectionTestUtils.setField(controller, "tokenGuard", mock(InternalServiceTokenGuard.class));
        return controller;
@@ -51,7 +51,8 @@ class ReceivingContainerContractTest {
    void everyBrowserReachableReceivingMethodUsesOnlyPdaOperatePermission() {
        PreAuthorize permission = ReceivingContainerController.class.getAnnotation(PreAuthorize.class);
        assertTrue(permission != null);
-        assertTrue("hasAuthority('lastleg:pda:operate')".equals(permission.value()));
+        assertTrue("hasAuthority('lastleg:pda:operate') and hasAuthority('ROLE_WAREHOUSE_PICKER')"
+            .equals(permission.value()));
    }

    @Test
@@ -131,9 +132,9 @@ class ReceivingContainerContractTest {
        String receivingPaths = yaml.substring(yaml.indexOf(prefix), yaml.indexOf("/api/platform/v1/last-leg/orders:"));
        List<String> successResponses = receivingPaths.lines().map(String::trim)
            .filter(line -> line.startsWith("responses: { '200':")).toList();
-        assertEquals(12, successResponses.size());
-        assertTrue(successResponses.stream().allMatch(line ->
-            line.contains("content: { application/json: { schema: { $ref: '#/components/schemas/Receiving")));
+        assertEquals(16, successResponses.size());
+        assertEquals(12, successResponses.stream().filter(line -> line.contains("/schemas/Receiving")).count());
+        assertEquals(4, successResponses.stream().filter(line -> line.contains("/schemas/Pda")).count());
        assertTrue(receivingPaths.contains("返回 WAIT_SIGN、SIGNED 或 RECEIVING 当前柜"));
        assertTrue(receivingPaths.contains("仅 PLATFORM WAREHOUSE_PICKER 可用"));
        assertFalse(receivingPaths.contains("客户与操作账号均从 PDA Token 获取"));
@@ -3,6 +3,7 @@ package com.baiyue.lastleg.inboundplan.pda.controller;
 import com.baiyue.common.security.AuthenticatedUser;
 import com.baiyue.lastleg.inboundplan.pda.dto.ReceivingContainerResponses;
 import com.baiyue.lastleg.inboundplan.pda.service.ReceivingContainerService;
+import com.baiyue.lastleg.pda.security.PdaWarehouseIdentity;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
 import org.junit.jupiter.api.extension.ExtendWith;
@@ -57,13 +58,14 @@ class ReceivingContainerControllerTest {
    @Test
    void pickerAuthorityWithoutWarehouseBindingIsForbidden() {
        AuthenticatedUser unbound = new AuthenticatedUser(42L, 0L, 0L, 8L, "receiver", "PLATFORM", "PDA",
-            Set.of(ReceivingContainerController.OPERATE_PERMISSION));
+            Set.of(PdaWarehouseIdentity.PICKER_ROLE, ReceivingContainerController.OPERATE_PERMISSION));
        assertThatThrownBy(() -> controller.candidates(unbound)).isInstanceOf(ResponseStatusException.class)
            .hasMessageContaining("403");
    }

    private static AuthenticatedUser picker() {
        return new AuthenticatedUser(42L, 0L, 0L, 8L, "receiver", "PLATFORM", "PDA",
-            Set.of(ReceivingContainerController.OPERATE_PERMISSION), false, null, null, false, 900L);
+            Set.of(PdaWarehouseIdentity.PICKER_ROLE, ReceivingContainerController.OPERATE_PERMISSION),
+            false, null, null, false, 900L);
    }
 }
@@ -23,6 +23,7 @@ import com.baiyue.lastleg.inboundplan.pda.mapper.ReceivingContainerSessionMapper
 import com.baiyue.lastleg.inboundplan.pda.mapper.ReceivingSkuReceiptMapper;
 import com.baiyue.lastleg.mapper.LastlegOrderDetailMapper;
 import com.baiyue.lastleg.mapper.LastlegOrderMapper;
+import com.baiyue.lastleg.shipping.mapper.ContainerShippingGateMapper;
 import com.fasterxml.jackson.databind.ObjectMapper;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
@@ -57,6 +58,7 @@ class ReceivingContainerServiceBehaviorTest {
    @Mock ReceivingContainerSessionMapper sessions;
    @Mock ReceivingContainerOperationMapper operations;
    @Mock ReceivingSkuReceiptMapper skuReceipts;
+    @Mock ContainerShippingGateMapper shippingGates;
    @Mock WarehouseResourceGateway warehouse;
    @Mock UnloadPhotoFileGateway unloadPhotos;
    @Mock InboundPdaWorkflowService workflow;
@@ -75,11 +77,25 @@ class ReceivingContainerServiceBehaviorTest {
        ReflectionTestUtils.setField(service, "sessions", sessions);
        ReflectionTestUtils.setField(service, "operations", operations);
        ReflectionTestUtils.setField(service, "skuReceipts", skuReceipts);
+        ReflectionTestUtils.setField(service, "shippingGates", shippingGates);
        ReflectionTestUtils.setField(service, "warehouse", warehouse);
        ReflectionTestUtils.setField(service, "unloadPhotos", unloadPhotos);
        ReflectionTestUtils.setField(service, "workflow", workflow);
        ReflectionTestUtils.setField(service, "sourceObjectMapper", new ObjectMapper().findAndRegisterModules());
        service.initializeObjectMapper();
+        org.mockito.Mockito.lenient().when(shippingGates.receivingAvailable(any(), any())).thenReturn(1);
+    }
+
+    @Test
+    void containerIsHiddenAndPrepareRejectedBeforePickupReady() {
+        when(plans.selectList(any())).thenReturn(List.of(plan("CONT-A")));
+        when(shippingGates.receivingAvailable("100", "CONT-A")).thenReturn(0);
+
+        assertThat(service.candidates("7", 100L)).isEmpty();
+        assertThatThrownBy(() -> service.prepare("7", "receiver", 100L, "CONT-A",
+            new ReceivingContainerRequests.Action("not-ready")))
+            .isInstanceOf(ResponseStatusException.class).hasMessageContaining("409");
+        verifyNoInteractions(warehouse);
    }

    @Test
@@ -315,6 +331,16 @@ class ReceivingContainerServiceBehaviorTest {
        verifyNoInteractions(unloadPhotos);
    }

+    @Test
+    void signRejectsMissingPhotosBeforeFileValidation() {
+        when(sessions.lockActiveByOperator("OPERATOR:7")).thenReturn(session("CONT-A", "WAIT_SIGN"));
+        ReceivingContainerRequests.Sign request = new ReceivingContainerRequests.Sign(List.of(), "missing-photos");
+
+        assertThatThrownBy(() -> service.sign("7", "receiver", request))
+            .isInstanceOf(ResponseStatusException.class).hasMessageContaining("409");
+        verifyNoInteractions(unloadPhotos);
+    }
+
    @Test
    void signRejectsDuplicateFileIdsBeforeFileValidation() {
        when(sessions.lockActiveByOperator("OPERATOR:7")).thenReturn(session("CONT-A", "WAIT_SIGN"));
@@ -15,6 +15,8 @@ class LocalLooseboardSchemaContractTest {
        }
        assertTrue(sql.contains("CREATE TABLE IF NOT EXISTS ll_local_looseboard_order"));
        assertTrue(sql.contains("CREATE TABLE IF NOT EXISTS ll_local_looseboard_history"));
+        assertTrue(sql.contains("CREATE TABLE IF NOT EXISTS ll_local_looseboard_operation"));
+        assertTrue(sql.contains("uk_ll_local_looseboard_operation_key(customer_id,order_id,idempotency_key)"));
        assertTrue(sql.contains("operation_type VARCHAR(32) NOT NULL"));
        assertTrue(sql.contains("uk_ll_local_looseboard_no(customer_id,order_no)"));
        assertTrue(sql.contains("lastleg_order_id BIGINT NULL"));
@@ -3,8 +3,10 @@ package com.baiyue.lastleg.looseboard.service;
 import com.baiyue.lastleg.looseboard.dto.LocalLooseboardRequests;
 import com.baiyue.lastleg.looseboard.entity.LocalLooseboardHistory;
 import com.baiyue.lastleg.looseboard.entity.LocalLooseboardOrder;
+import com.baiyue.lastleg.looseboard.entity.LocalLooseboardOperation;
 import com.baiyue.lastleg.looseboard.mapper.LocalLooseboardHistoryMapper;
 import com.baiyue.lastleg.looseboard.mapper.LocalLooseboardOrderMapper;
+import com.baiyue.lastleg.looseboard.mapper.LocalLooseboardOperationMapper;
 import com.baiyue.lastleg.entity.LastlegOrder;
 import com.baiyue.lastleg.mapper.LastlegOrderMapper;
 import com.baiyue.lastleg.mapper.LastlegOrderStatusHistoryMapper;
@@ -22,6 +24,8 @@ import java.math.BigDecimal;
 import java.time.LocalDate;
 import java.time.LocalDateTime;
 import java.util.List;
+import java.util.HashMap;
+import java.util.Map;
 import java.util.concurrent.atomic.AtomicReference;

 import static org.junit.jupiter.api.Assertions.assertEquals;
@@ -29,27 +33,38 @@ import static org.junit.jupiter.api.Assertions.assertThrows;
 import static org.mockito.ArgumentMatchers.any;
 import static org.mockito.ArgumentMatchers.anyString;
 import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.times;
 import static org.mockito.Mockito.when;

@ExtendWith(MockitoExtension.class)
 class LocalLooseboardServiceTest {
    @Mock LocalLooseboardOrderMapper orders;
    @Mock LocalLooseboardHistoryMapper histories;
+    @Mock LocalLooseboardOperationMapper operations;
    @Mock LastlegOrderMapper lastlegOrders;
    @Mock LastlegOrderStatusHistoryMapper lastlegHistories;
    @Mock LastlegOrderNoGenerator lastlegOrderNoGenerator;
    private LocalLooseboardService service;
+    private final Map<String, LocalLooseboardOperation> operationRows = new HashMap<>();

    @BeforeEach
    void setUp() {
        service = new LocalLooseboardService();
        ReflectionTestUtils.setField(service, "orders", orders);
        ReflectionTestUtils.setField(service, "histories", histories);
+        ReflectionTestUtils.setField(service, "operations", operations);
        ReflectionTestUtils.setField(service, "lastlegOrders", lastlegOrders);
        ReflectionTestUtils.setField(service, "lastlegHistories", lastlegHistories);
        ReflectionTestUtils.setField(service, "lastlegOrderNoGenerator", lastlegOrderNoGenerator);
        ReflectionTestUtils.setField(service, "objectMapper", new ObjectMapper().findAndRegisterModules());
        org.mockito.Mockito.lenient().when(lastlegOrderNoGenerator.next()).thenReturn("LMO-LOOSE-1");
+        org.mockito.Mockito.lenient().when(operations.findKey(anyString(), any(), anyString()))
+            .thenAnswer(call -> operationRows.get(call.getArgument(2)));
+        org.mockito.Mockito.lenient().when(operations.insert(any(LocalLooseboardOperation.class))).thenAnswer(call -> {
+            LocalLooseboardOperation value = call.getArgument(0);
+            operationRows.put(value.getIdempotencyKey(), value);
+            return 1;
+        });
    }

    @Test
@@ -103,12 +118,54 @@ class LocalLooseboardServiceTest {
        when(histories.listOrder("100", 1L)).thenReturn(List.of());

        var detail = service.changeStatus("100", "LB1", "7",
-            new LocalLooseboardRequests.ChangeStatus(0L, "DISPATCHED", "accepted"));
+            new LocalLooseboardRequests.ChangeStatus(0L, "DISPATCHED", "status-1", "accepted"));

        assertEquals(LocalLooseboardService.DISPATCHED, detail.summary().status());
        assertEquals(1L, detail.summary().version());
        verify(histories).insert(org.mockito.ArgumentMatchers.<LocalLooseboardHistory>argThat(value ->
-            "STATUS".equals(value.getOperationType()) && "DISPATCHED".equals(value.getToStatus())));
+            "STATUS".equals(value.getOperationType()) && "DISPATCHED".equals(value.getToStatus())
+                && "7".equals(value.getOperatorId()) && "status-1".equals(value.getIdempotencyKey())));
+    }
+
+    @Test
+    void fullStatusLifecycleIsIdempotentAndCompletedCannotReverse() {
+        LocalLooseboardOrder order = order(LocalLooseboardService.PENDING_ACCEPTANCE, 0L);
+        when(orders.lockNo("100", "LB1")).thenReturn(order);
+        when(histories.listOrder("100", 1L)).thenReturn(List.of());
+        var dispatch = new LocalLooseboardRequests.ChangeStatus(0L, "DISPATCHED", "dispatch-1", "dispatch");
+        assertEquals(LocalLooseboardService.DISPATCHED,
+            service.changeStatus("100", "LB1", "operator-7", dispatch).summary().status());
+        assertEquals(1L, service.changeStatus("100", "LB1", "operator-7", dispatch).summary().version());
+        assertThrows(ResponseStatusException.class, () -> service.changeStatus("100", "LB1", "operator-7",
+            new LocalLooseboardRequests.ChangeStatus(1L, "IN_TRANSIT", "dispatch-1", "different")));
+        assertThrows(ResponseStatusException.class, () -> service.changeStatus("100", "LB1", "operator-7",
+            new LocalLooseboardRequests.ChangeStatus(0L, "IN_TRANSIT", "stale-1", "stale")));
+        assertEquals(LocalLooseboardService.IN_TRANSIT, service.changeStatus("100", "LB1", "operator-8",
+            new LocalLooseboardRequests.ChangeStatus(1L, "IN_TRANSIT", "transit-1", "transit"))
+            .summary().status());
+        assertEquals(LocalLooseboardService.COMPLETED, service.changeStatus("100", "LB1", "operator-9",
+            new LocalLooseboardRequests.ChangeStatus(2L, "COMPLETED", "complete-1", "complete"))
+            .summary().status());
+        assertThrows(ResponseStatusException.class, () -> service.changeStatus("100", "LB1", "operator-9",
+            new LocalLooseboardRequests.ChangeStatus(3L, "IN_TRANSIT", "reverse-1", "reverse")));
+        verify(histories, times(3)).insert(org.mockito.ArgumentMatchers.<LocalLooseboardHistory>argThat(value ->
+            "STATUS".equals(value.getOperationType()) && value.getOperatorId() != null
+                && value.getIdempotencyKey() != null));
+    }
+
+    @Test
+    void separateDispatchedFixtureCanCancelButCannotProgressAfterCancellation() {
+        LocalLooseboardOrder order = order(LocalLooseboardService.PENDING_ACCEPTANCE, 0L);
+        when(orders.lockNo("100", "LB1")).thenReturn(order);
+        when(histories.listOrder("100", 1L)).thenReturn(List.of());
+        assertEquals(LocalLooseboardService.DISPATCHED, service.changeStatus("100", "LB1", "operator-7",
+            new LocalLooseboardRequests.ChangeStatus(0L, "DISPATCHED", "cancel-fixture-dispatch", "dispatch"))
+            .summary().status());
+        assertEquals(LocalLooseboardService.CANCELLED, service.changeStatus("100", "LB1", "operator-7",
+            new LocalLooseboardRequests.ChangeStatus(1L, "CANCELLED", "cancel-1", "cancel"))
+            .summary().status());
+        assertThrows(ResponseStatusException.class, () -> service.changeStatus("100", "LB1", "operator-7",
+            new LocalLooseboardRequests.ChangeStatus(2L, "IN_TRANSIT", "after-cancel", "invalid")));
    }

    private LocalLooseboardRequests.Create create(String key) {
@@ -0,0 +1,78 @@
+package com.baiyue.lastleg.pda.warehouse;
+
+import com.baiyue.common.security.AuthenticatedUser;
+import com.baiyue.lastleg.pda.security.PdaWarehouseIdentity;
+import com.baiyue.lastleg.pda.warehouse.controller.PdaWarehouseController;
+import com.baiyue.lastleg.pda.warehouse.dto.PdaWarehouseRequests;
+import org.junit.jupiter.api.Test;
+import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.lang.reflect.RecordComponent;
+import java.nio.file.Files;
+import java.nio.file.Path;
+import java.util.Arrays;
+import java.util.Set;
+import java.util.stream.Collectors;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+
+class PdaWarehouseContractTest {
+    @Test
+    void requestsNeverAcceptServerOwnedIdentityOrResourceIds() {
+        Set<String> forbidden = Set.of("customerId", "warehouseId", "planNo", "allocationId", "operatorId");
+        for (Class<?> type : PdaWarehouseRequests.class.getDeclaredClasses()) {
+            if (!type.isRecord()) continue;
+            Set<String> fields = Arrays.stream(type.getRecordComponents()).map(RecordComponent::getName)
+                .collect(Collectors.toSet());
+            assertThat(fields).doesNotContainAnyElementsOf(forbidden);
+        }
+    }
+
+    @Test
+    void controllerRequiresPickerRoleAndPdaAuthority() {
+        PreAuthorize permission = PdaWarehouseController.class.getAnnotation(PreAuthorize.class);
+        assertThat(permission.value()).isEqualTo(
+            "hasAuthority('lastleg:pda:operate') and hasAuthority('ROLE_WAREHOUSE_PICKER')");
+    }
+
+    @Test
+    void identityRejectsUnboundOrNonPickerPlatformAccounts() {
+        AuthenticatedUser unbound = user(Set.of(PdaWarehouseIdentity.PICKER_ROLE,
+            PdaWarehouseIdentity.OPERATE_PERMISSION), null);
+        assertThatThrownBy(() -> PdaWarehouseIdentity.require(unbound))
+            .isInstanceOf(ResponseStatusException.class).hasMessageContaining("403");
+        AuthenticatedUser admin = user(Set.of(PdaWarehouseIdentity.OPERATE_PERMISSION), 900L);
+        assertThatThrownBy(() -> PdaWarehouseIdentity.require(admin))
+            .isInstanceOf(ResponseStatusException.class).hasMessageContaining("403");
+        assertThat(PdaWarehouseIdentity.require(user(Set.of(PdaWarehouseIdentity.PICKER_ROLE,
+            PdaWarehouseIdentity.OPERATE_PERMISSION), 900L)).overseasWarehouseId()).isEqualTo(900L);
+    }
+
+    @Test
+    void baselineContainsShippingGateAndRealOperationHistory() throws Exception {
+        String sql = Files.readString(Path.of("src/main/resources/db/lastleg.sql")).toLowerCase();
+        assertThat(sql).contains("create table if not exists ll_container_shipping_gate")
+            .contains("awaiting_pickup_ready")
+            .contains("receiving_available")
+            .contains("create table if not exists ll_pda_operation_history")
+            .contains("unique key uk_ll_pda_history_idempotency(operator_key,idempotency_key)");
+    }
+
+    @Test
+    void openApiAndGatewayPublishOnlyStablePdaPaths() throws Exception {
+        String openapi = Files.readString(Path.of("src/main/resources/openapi/overseas-business-v1.yaml"));
+        for (String path : Set.of("/api/pda/v1/last-leg/inventory/resolve:",
+            "/api/pda/v1/last-leg/locations/resolve:", "/api/pda/v1/last-leg/pallets/resolve:",
+            "/api/pda/v1/last-leg/operations:")) assertThat(openapi).contains(path);
+        assertThat(openapi).doesNotContain("/api/pda/v1/last-leg/inbound-plans/{planNo}");
+        String gateway = Files.readString(Path.of("../gateway-overseas/src/main/resources/application-overseas.yml"));
+        assertThat(gateway).contains("/api/pda/v1/last-leg/**").contains("lb://lastleg-service");
+    }
+
+    private static AuthenticatedUser user(Set<String> authorities, Long warehouseId) {
+        return new AuthenticatedUser(42L, 0L, 0L, 8L, "picker", "PLATFORM", "PDA",
+            authorities, false, null, null, false, warehouseId);
+    }
+}
@@ -0,0 +1,71 @@
+package com.baiyue.lastleg.pda.warehouse.service;
+
+import com.baiyue.lastleg.inboundplan.pda.gateway.WarehouseResourceGateway;
+import com.baiyue.lastleg.pda.warehouse.dto.PdaWarehouseRequests;
+import com.baiyue.lastleg.pda.warehouse.mapper.PdaWarehouseMapper;
+import com.baiyue.lastleg.pda.warehouse.model.PdaInventoryProjection;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.test.util.ReflectionTestUtils;
+import org.springframework.web.server.ResponseStatusException;
+
+import java.math.BigDecimal;
+import java.util.List;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class PdaWarehouseServiceTest {
+    @Mock PdaWarehouseMapper mapper;
+    @Mock WarehouseResourceGateway warehouse;
+    private PdaWarehouseService service;
+
+    @BeforeEach
+    void setUp() {
+        service = new PdaWarehouseService();
+        ReflectionTestUtils.setField(service, "mapper", mapper);
+        ReflectionTestUtils.setField(service, "warehouse", warehouse);
+    }
+
+    @Test
+    void inventoryScanIsBoundToTokenWarehouse() {
+        when(mapper.scanInventory("900", "SKU-1")).thenReturn(List.of(inventory()));
+        var result = service.inventory(900L, new PdaWarehouseRequests.Scan("SKU-1"));
+        assertThat(result.items()).hasSize(1);
+        assertThat(result.items().get(0).customerId()).isEqualTo("100");
+    }
+
+    @Test
+    void palletFromAnotherWarehouseIsRejected() {
+        when(warehouse.resolvePallet("PAL-1")).thenReturn(new WarehouseResourceGateway.WarehousePalletReference(
+            1L, "PAL-1", 901L, 2L, "OCCUPIED", null, 1));
+        assertThatThrownBy(() -> service.pallet(900L, new PdaWarehouseRequests.Scan("PAL-1")))
+            .isInstanceOf(ResponseStatusException.class).hasMessageContaining("409");
+    }
+
+    @Test
+    void locationCombinesPhysicalCapacityAndInventoryOccupation() {
+        when(warehouse.resolveLocation(900L, "A-01")).thenReturn(
+            new WarehouseResourceGateway.WarehouseLocationReference(2L, "A-01", "STORAGE",
+                new BigDecimal("1000"), "OCCUPIED"));
+        when(mapper.inventoryByLocation("900", 2L, "A-01", "__NO_CARTON__"))
+            .thenReturn(List.of(inventory()));
+        var result = service.location(900L, new PdaWarehouseRequests.Scan("A-01"));
+        assertThat(result.occupiedPackages()).isEqualTo(5);
+        assertThat(result.inventoryPositionCount()).isEqualTo(1);
+    }
+
+    private static PdaInventoryProjection inventory() {
+        PdaInventoryProjection value = new PdaInventoryProjection(); value.setCustomerId("100");
+        value.setBalanceId(10L); value.setPositionId(11L); value.setSkuCode("SKU-1");
+        value.setInboundCode("IN-1"); value.setPalletId(12L); value.setPalletCode("PAL-1");
+        value.setLocationId(2L); value.setLocationCode("A-01"); value.setAvailablePackages(5L);
+        value.setHoldPackages(0L); value.setReceivingPackages(0L); value.setVersion(1L); value.setStatus("OCCUPIED");
+        return value;
+    }
+}
@@ -31,6 +31,16 @@ class OverseasProcurementOpenApiContractTest {
        }
        assertTrue(yaml.contains("platform:overseas-business:truck:create"));
        assertTrue(yaml.contains("platform:overseas-business:truck:edit"));
+        assertTrue(yaml.contains("/{orderNo}/review:"));
+        assertTrue(yaml.contains("/{orderNo}/receive-pallets:"));
+        assertTrue(yaml.contains("/{orderNo}/review-pallet-overage:"));
+        assertTrue(yaml.contains("/{orderNo}/allocate-pallets:"));
+        assertTrue(yaml.contains("/{orderNo}/prepare-dispatch:"));
+        assertTrue(yaml.contains("/{orderNo}/dispatch:"));
+        assertTrue(yaml.contains("/{orderNo}/start-transit:"));
+        assertTrue(yaml.contains("/{orderNo}/complete:"));
+        assertTrue(yaml.contains("enum: [PENDING_REVIEW, WAITING_INBOUND, RECEIVING, WAITING_CONSOLIDATION, PALLET_OVERAGE_REVIEW, PARTIALLY_ALLOCATED, ALLOCATED, PENDING_DISPATCH, DISPATCHED, IN_TRANSIT, COMPLETED, REJECTED, CANCELLED]"));
+        assertTrue(yaml.contains("required: [version, status, idempotencyKey]"));
        assertTrue(yaml.contains("/api/platform/v1/last-leg/local-looseboard-orders:"));
        assertTrue(yaml.contains("platform:overseas-business:looseboard:list"));
        assertTrue(yaml.contains("platform:overseas-business:looseboard:create"));
@@ -16,6 +16,9 @@ class OverseasProcurementSchemaContractTest {
        assertTrue(sql.contains("CREATE TABLE IF NOT EXISTS ll_overseas_procurement_order"));
        assertTrue(sql.contains("CREATE TABLE IF NOT EXISTS ll_overseas_procurement_status_history"));
        assertTrue(sql.contains("operation_type VARCHAR(32) NOT NULL"));
+        assertTrue(sql.contains("review_idempotency_key VARCHAR(255) NULL"));
+        assertTrue(sql.contains("review_request_hash CHAR(64) NULL"));
+        assertTrue(sql.contains("idempotency_key VARCHAR(255) NULL COMMENT '操作幂等键'"));
        assertTrue(sql.contains("change_detail JSON NULL"));
        org.junit.jupiter.api.Assertions.assertFalse(sql.contains("CREATE TABLE IF NOT EXISTS ll_overseas_procurement_outbound"));
        org.junit.jupiter.api.Assertions.assertFalse(sql.contains("outbound_quantity BIGINT"));
@@ -40,7 +40,7 @@ class OverseasProcurementControllerTest {

    @Test
    void reviewRequiresExplicitPermission() {
-        var request = new OverseasProcurementRequests.Review("APPROVE", null);
+        var request = new OverseasProcurementRequests.Review(0L, "APPROVE", "review-1", null);
        ResponseStatusException error = assertThrows(ResponseStatusException.class,
            () -> platform.review(user(0L, "PLATFORM", Set.of()), "100", "HC1", request));
        assertEquals(403, error.getStatusCode().value());
@@ -56,7 +56,7 @@ class OverseasProcurementControllerTest {

    @Test
    void platformReviewUsesExplicitTargetTenant() {
-        var request = new OverseasProcurementRequests.Review("APPROVE", "ok");
+        var request = new OverseasProcurementRequests.Review(0L, "APPROVE", "review-1", "ok");
        platform.review(user(0L, "PLATFORM", Set.of(OverseasProcurementService.REVIEW_PERMISSION)),
            "100", "HC1", request);
        verify(service).review("100", "HC1", "7", request);
@@ -145,6 +145,33 @@ class OverseasProcurementServiceTest {
        assertEquals("Acme", values.get(0).customerName());
    }

+    @Test
+    void approveReviewIsIdempotentAuditedAndTerminalCannotReverse() {
+        OverseasProcurementOrder order = order(OverseasProcurementService.PENDING_REVIEW, 0, 0);
+        when(orders.lockNo("100", "HC1")).thenReturn(order);
+        when(orders.findNo("100", "HC1")).thenReturn(order);
+        when(histories.listOrder("100", 1L)).thenReturn(List.of());
+        var request = new OverseasProcurementRequests.Review(0L, "APPROVE", "approve-1", "approved");
+
+        var approved = service.review("100", "HC1", "operator-7", request);
+        assertEquals(OverseasProcurementService.APPROVED, approved.summary().status());
+        assertEquals(1L, approved.summary().version());
+        assertEquals(1L, service.review("100", "HC1", "operator-7", request).summary().version());
+        verify(histories).insert(org.mockito.ArgumentMatchers
+            .<com.baiyue.lastleg.procurement.entity.OverseasProcurementStatusHistory>argThat(value ->
+                "REVIEW".equals(value.getOperationType()) && "operator-7".equals(value.getOperatorId())
+                    && "approve-1".equals(value.getIdempotencyKey())
+                    && OverseasProcurementService.APPROVED.equals(value.getToStatus())));
+
+        assertThrows(ResponseStatusException.class, () -> service.review("100", "HC1", "operator-7",
+            new OverseasProcurementRequests.Review(1L, "REJECT", "approve-1", "different payload")));
+        assertThrows(ResponseStatusException.class, () -> service.review("100", "HC1", "operator-7",
+            new OverseasProcurementRequests.Review(0L, "REJECT", "stale-review", "old version")));
+        assertThrows(ResponseStatusException.class, () -> service.review("100", "HC1", "operator-7",
+            new OverseasProcurementRequests.Review(1L, "REJECT", "reject-after-approved", "reverse")));
+        assertEquals(OverseasProcurementService.APPROVED, order.getStatus());
+    }
+
    private OverseasProcurementOrder order(String status, long inbound, long outbound) {
        OverseasProcurementOrder order = new OverseasProcurementOrder();
        order.setId(1L);
@@ -7,6 +7,7 @@ import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
 import java.util.List;
+import java.util.Set;
 import java.util.regex.Matcher;
 import java.util.regex.Pattern;

@@ -15,6 +16,9 @@ import static org.junit.jupiter.api.Assertions.assertTrue;

 class SchemaChineseCommentContractTest {

+    private static final Set<String> MODULE_BASELINE_ONLY_TABLES = Set.of(
+        "ll_us_truck_order_operation", "ll_local_looseboard_operation");
+
    private static final Pattern CHINESE = Pattern.compile("[\\u4e00-\\u9fff]");
    private static final Pattern TABLE = Pattern.compile(
        "(?is)CREATE\\s+TABLE\\s+IF\\s+NOT\\s+EXISTS\\s+(ll_[a-z0-9_]+)"
@@ -45,14 +49,16 @@ class SchemaChineseCommentContractTest {
        List<String> columns = List.of(
            "allocation_idempotency_key", "allocation_request_hash", "outbound_idempotency_key",
            "outbound_request_hash", "outbound_at", "pallet_count", "received_pallet_count",
-            "allocated_pallet_count", "shipped_pallet_count", "receipt_idempotency_key",
-            "receipt_request_hash"
+            "allocated_pallet_count"
        );
        for (String column : columns) {
            assertColumnHasChineseComment(baseline, column, "基线 SQL");
            assertColumnHasChineseComment(incremental, column, "增量 SQL");
            assertIncrementalAddColumnHasChineseComment(incremental, column);
        }
+        for (String column : List.of("review_idempotency_key", "review_request_hash", "result_version")) {
+            assertColumnHasChineseComment(baseline, column, "基线 SQL");
+        }
    }

    private static List<TableDefinition> assertAllChineseComments(String sql, String source, int expectedCount) {
@@ -90,6 +96,9 @@ class SchemaChineseCommentContractTest {
        assertTrue(marker >= 0, "增量 SQL 缺少 025 中文备注迁移");
        String migration = incremental.substring(marker);
        for (TableDefinition table : tables) {
+            if (MODULE_BASELINE_ONLY_TABLES.contains(table.name())) {
+                continue;
+            }
            boolean createdInLegacy = hasCommentedCreate(migration, table.name());
            boolean createdInUnified = hasCommentedCreate(overseasUnified, table.name());
            assertTrue(createdInLegacy || createdInUnified
@@ -2,9 +2,10 @@ package com.baiyue.lastleg.service;
 import com.baiyue.common.event.*; import com.baiyue.lastleg.entity.*; import com.baiyue.lastleg.mapper.*; import com.baiyue.lastleg.dropship.dto.DropshipRequests; import com.baiyue.lastleg.dropship.service.DropshipOrderService; import com.baiyue.lastleg.inboundplan.dto.InboundPlanResponse; import com.baiyue.lastleg.inboundplan.entity.InboundPlanCarton; import com.baiyue.lastleg.inboundplan.mapper.InboundPlanCartonMapper; import com.baiyue.lastleg.inboundplan.service.InboundPlanService; import com.baiyue.lastleg.inventory.command.dto.InventoryCommandRequests; import com.baiyue.lastleg.inventory.command.service.InventoryCommandService; import com.fasterxml.jackson.databind.*; import org.junit.jupiter.api.*; import org.junit.jupiter.api.extension.ExtendWith; import org.mockito.*; import org.springframework.test.util.ReflectionTestUtils; import java.math.BigDecimal; import java.time.Instant; import java.util.*; import static org.junit.jupiter.api.Assertions.*; import static org.mockito.ArgumentMatchers.*; import static org.mockito.Mockito.*;
@ExtendWith(org.mockito.junit.jupiter.MockitoExtension.class)
 class LoadingCompletedConsumerTest {
- @Mock LastlegEventInboxMapper inbox; @Mock LastlegOrderMapper orders; @Mock LastlegInboundOrderMapper inboundOrders; @Mock LastlegOrderDetailMapper details; @Mock LastlegOrderStatusHistoryMapper histories; @Mock InboundPlanCartonMapper cartons; @Mock DropshipOrderService dropshipOrders; @Mock InboundPlanService inboundPlans; @Mock InventoryCommandService inventory; ObjectMapper json=new ObjectMapper().findAndRegisterModules(); LoadingCompletedConsumer service;
- @BeforeEach void setup(){ service=new LoadingCompletedConsumer(); ReflectionTestUtils.setField(service,"inboxMapper",inbox); ReflectionTestUtils.setField(service,"orderMapper",orders); ReflectionTestUtils.setField(service,"inboundOrderMapper",inboundOrders); ReflectionTestUtils.setField(service,"detailMapper",details); ReflectionTestUtils.setField(service,"historyMapper",histories); ReflectionTestUtils.setField(service,"cartonMapper",cartons); ReflectionTestUtils.setField(service,"dropshipOrders",dropshipOrders); ReflectionTestUtils.setField(service,"inboundPlans",inboundPlans); ReflectionTestUtils.setField(service,"inventory",inventory); ReflectionTestUtils.setField(service,"objectMapper",json); ReflectionTestUtils.setField(service,"orderNoGenerator",new LastlegOrderNoGenerator()); lenient().doAnswer(i->{ LastlegOrder o=i.getArgument(0); o.setId(Math.abs(o.getSourceInboundId().hashCode())+1L); return 1; }).when(orders).insert(any(LastlegOrder.class)); lenient().when(inboundPlans.convert(anyString(),anyLong())).thenReturn(new InboundPlanResponse(1L,"LIP-1","100",1L,"MSCU1","PENDING_ASSIGNMENT",1,1,BigDecimal.ONE,List.of(),List.of(),List.of())); }
+ @Mock LastlegEventInboxMapper inbox; @Mock LastlegOrderMapper orders; @Mock LastlegInboundOrderMapper inboundOrders; @Mock LastlegOrderDetailMapper details; @Mock LastlegOrderStatusHistoryMapper histories; @Mock InboundPlanCartonMapper cartons; @Mock DropshipOrderService dropshipOrders; @Mock InboundPlanService inboundPlans; @Mock InventoryCommandService inventory; @Mock com.baiyue.lastleg.shipping.mapper.ContainerShippingGateMapper shippingGates; ObjectMapper json=new ObjectMapper().findAndRegisterModules(); LoadingCompletedConsumer service;
+ @BeforeEach void setup(){ service=new LoadingCompletedConsumer(); ReflectionTestUtils.setField(service,"inboxMapper",inbox); ReflectionTestUtils.setField(service,"orderMapper",orders); ReflectionTestUtils.setField(service,"inboundOrderMapper",inboundOrders); ReflectionTestUtils.setField(service,"detailMapper",details); ReflectionTestUtils.setField(service,"historyMapper",histories); ReflectionTestUtils.setField(service,"cartonMapper",cartons); ReflectionTestUtils.setField(service,"dropshipOrders",dropshipOrders); ReflectionTestUtils.setField(service,"inboundPlans",inboundPlans); ReflectionTestUtils.setField(service,"inventory",inventory); ReflectionTestUtils.setField(service,"shippingGates",shippingGates); ReflectionTestUtils.setField(service,"objectMapper",json); ReflectionTestUtils.setField(service,"orderNoGenerator",new LastlegOrderNoGenerator()); lenient().doAnswer(i->{ LastlegOrder o=i.getArgument(0); o.setId(Math.abs(o.getSourceInboundId().hashCode())+1L); return 1; }).when(orders).insert(any(LastlegOrder.class)); lenient().when(inboundPlans.convert(anyString(),anyLong())).thenReturn(new InboundPlanResponse(1L,"LIP-1","100",1L,"MSCU1","PENDING_ASSIGNMENT",1,1,BigDecimal.ONE,List.of(),List.of(),List.of())); }
 @Test void createsOneOrderAndOneInboundPlanPerInbound(){ EventEnvelope event=event(); assertEquals(2,service.consume(event)); verify(orders,times(2)).insert(any(LastlegOrder.class)); verify(inboundPlans,times(2)).convert(eq("100"),anyLong()); verify(inventory,times(2)).registerInTransit(eq("100"),eq("SYSTEM"),any(InventoryCommandRequests.InTransit.class)); verify(details,times(2)).insert(any(LastlegOrderDetail.class)); verify(histories,times(2)).insert(any(LastlegOrderStatusHistory.class)); ArgumentCaptor<LastlegOrder> c=ArgumentCaptor.forClass(LastlegOrder.class); verify(orders,times(2)).insert(c.capture()); assertEquals(Set.of("in-1","in-2"),c.getAllValues().stream().map(LastlegOrder::getSourceInboundId).collect(java.util.stream.Collectors.toSet())); assertTrue(c.getAllValues().stream().allMatch(o->"PENDING_ASSIGNMENT".equals(o.getCurrentStatus()))); assertTrue(c.getAllValues().stream().allMatch(o->o.getId()!=null)); assertTrue(c.getAllValues().stream().allMatch(o->"MSCU1".equals(o.getContainerNo()))); assertTrue(c.getAllValues().stream().allMatch(o->"FBA".equals(o.getDestinationType()))); assertTrue(c.getAllValues().stream().allMatch(o->"ow-1".equals(o.getSourceWarehouseId())&&o.getOverseasWarehouseId()==null)); ArgumentCaptor<LastlegInboundOrder> snapshots=ArgumentCaptor.forClass(LastlegInboundOrder.class); verify(inboundOrders,times(2)).insert(snapshots.capture()); assertTrue(snapshots.getAllValues().stream().allMatch(o->"100".equals(o.getCustomerId())&&"FBA".equals(o.getDestinationType()))); assertEquals(1,c.getAllValues().stream().map(LastlegOrder::getOrderNo).distinct().count()); assertEquals(new LastlegOrderNoGenerator().forContainerNo("MSCU1"),c.getAllValues().get(0).getOrderNo()); }
+ @Test void loadingCreatesAwaitingPickupReadyGate(){ service.consume(event()); verify(shippingGates).initialize("book-1","100","","MSCU1",2L,1L); }
 @Test void repeatedEventReturnsExistingEffect(){ EventEnvelope event=event(); LastlegEventInbox row=new LastlegEventInbox(); row.setPayloadHash(event.payloadHash()); when(inbox.selectById(event.eventId())).thenReturn(row); when(orders.countContainer("100","MSCU1")).thenReturn(2L); assertEquals(2,service.consume(event)); verify(orders).countContainer("100","MSCU1"); verify(orders,never()).insert(any(LastlegOrder.class)); verify(details,never()).insert(any(LastlegOrderDetail.class)); }
 @Test void sameEventWithDifferentHashIsRejected(){ EventEnvelope event=event(); LastlegEventInbox row=new LastlegEventInbox(); row.setPayloadHash("sha256:"+"0".repeat(64)); when(inbox.selectById(event.eventId())).thenReturn(row); assertThrows(IllegalArgumentException.class,()->service.consume(event)); }
 @Test void inboundSnapshotUsesCustomerIdAndHasNoPhantomTenantColumn() throws Exception {
@@ -0,0 +1,118 @@
+package com.baiyue.lastleg.shipping.service;
+
+import com.baiyue.common.event.EventEnvelope;
+import com.baiyue.common.event.EventPayloadCanonicalizer;
+import com.baiyue.common.event.EventPayloadHash;
+import com.baiyue.common.event.EventTypes;
+import com.baiyue.common.event.FirstLegContainerShippingNodeRecordedV1;
+import com.baiyue.common.event.RegionCode;
+import com.baiyue.lastleg.entity.LastlegEventInbox;
+import com.baiyue.lastleg.mapper.LastlegEventInboxMapper;
+import com.baiyue.lastleg.shipping.entity.ContainerShippingGate;
+import com.baiyue.lastleg.shipping.mapper.ContainerShippingGateMapper;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.extension.ExtendWith;
+import org.mockito.Mock;
+import org.mockito.junit.jupiter.MockitoExtension;
+import org.springframework.test.util.ReflectionTestUtils;
+
+import java.time.Instant;
+
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.assertj.core.api.Assertions.assertThatThrownBy;
+import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.Mockito.never;
+import static org.mockito.Mockito.verify;
+import static org.mockito.Mockito.when;
+
+@ExtendWith(MockitoExtension.class)
+class ContainerShippingNodeConsumerTest {
+    @Mock LastlegEventInboxMapper inboxes;
+    @Mock ContainerShippingGateMapper gates;
+    private final ObjectMapper json = new ObjectMapper().findAndRegisterModules();
+    private ContainerShippingNodeConsumer consumer;
+
+    @BeforeEach
+    void setUp() {
+        consumer = new ContainerShippingNodeConsumer();
+        ReflectionTestUtils.setField(consumer, "inboxes", inboxes);
+        ReflectionTestUtils.setField(consumer, "gates", gates);
+        ReflectionTestUtils.setField(consumer, "objectMapper", json);
+    }
+
+    @Test
+    void pickupReadyMonotonicallyOpensReceivingGate() {
+        ContainerShippingGate gate = gate("AWAITING_PICKUP_READY", 70, 4, Instant.parse("2026-08-20T10:00:00Z"));
+        when(gates.lock("CB-1")).thenReturn(gate);
+        EventEnvelope event = event("123e4567-e89b-12d3-a456-426614174101", "PICKUP_READY", 80, 5,
+            Instant.parse("2026-08-21T10:00:00Z"));
+
+        assertThat(consumer.consume(event)).isEqualTo(1);
+
+        assertThat(gate.getStatus()).isEqualTo("RECEIVING_AVAILABLE");
+        assertThat(gate.getNodeSequence()).isEqualTo(80);
+        assertThat(gate.getAggregateVersion()).isEqualTo(5);
+        verify(gates).updateById(gate);
+    }
+
+    @Test
+    void lowerNodeAndOlderAggregateAreAuditedWithoutRegression() {
+        ContainerShippingGate gate = gate("RECEIVING_AVAILABLE", 90, 8, Instant.parse("2026-08-22T10:00:00Z"));
+        when(gates.lock("CB-1")).thenReturn(gate);
+
+        consumer.consume(event("123e4567-e89b-12d3-a456-426614174102", "PICKUP_READY", 80, 7,
+            Instant.parse("2026-08-23T10:00:00Z")));
+
+        assertThat(gate.getStatus()).isEqualTo("RECEIVING_AVAILABLE");
+        assertThat(gate.getNodeSequence()).isEqualTo(90);
+        assertThat(gate.getAggregateVersion()).isEqualTo(8);
+    }
+
+    @Test
+    void sameNodeOnlyAcceptsLaterActualTimeAndEmptyReturnedNeverClosesGate() {
+        ContainerShippingGate gate = gate("RECEIVING_AVAILABLE", 100, 9, Instant.parse("2026-08-22T10:00:00Z"));
+        when(gates.lock("CB-1")).thenReturn(gate);
+        consumer.consume(event("123e4567-e89b-12d3-a456-426614174103", "EMPTY_RETURNED", 100, 10,
+            Instant.parse("2026-08-22T12:00:00Z")));
+
+        assertThat(gate.getStatus()).isEqualTo("RECEIVING_AVAILABLE");
+        assertThat(gate.getActualAt()).isEqualTo(java.time.LocalDateTime.parse("2026-08-22T12:00:00"));
+    }
+
+    @Test
+    void eventIdIsIdempotentByHashAndRejectsDifferentHash() {
+        EventEnvelope event = event("123e4567-e89b-12d3-a456-426614174104", "PICKUP_READY", 80, 5,
+            Instant.parse("2026-08-21T10:00:00Z"));
+        LastlegEventInbox existing = new LastlegEventInbox(); existing.setPayloadHash(event.payloadHash());
+        when(inboxes.selectById(event.eventId())).thenReturn(existing);
+        assertThat(consumer.consume(event)).isEqualTo(1);
+        verify(gates, never()).updateById(any(ContainerShippingGate.class));
+
+        existing.setPayloadHash("sha256:" + "0".repeat(64));
+        assertThatThrownBy(() -> consumer.consume(event)).isInstanceOf(IllegalArgumentException.class)
+            .hasMessageContaining("摘要冲突");
+    }
+
+    private ContainerShippingGate gate(String status, int sequence, long version, Instant actualAt) {
+        ContainerShippingGate gate = new ContainerShippingGate(); gate.setContainerBookingId("CB-1");
+        gate.setCustomerId("100"); gate.setOceanBookingId("OB-1"); gate.setContainerNo("CONT-1");
+        gate.setStatus(status); gate.setNodeSequence(sequence); gate.setAggregateVersion(version);
+        gate.setHandoverVersion(version + 1); gate.setActualAt(java.time.LocalDateTime.ofInstant(actualAt,
+            java.time.ZoneOffset.UTC)); return gate;
+    }
+
+    private EventEnvelope event(String eventId, String node, int sequence, long version, Instant actualAt) {
+        FirstLegContainerShippingNodeRecordedV1 payload = new FirstLegContainerShippingNodeRecordedV1(
+            "Q-1", "100", "OB-1", "CB-1", "CONT-1", node, sequence, actualAt,
+            actualAt, "LAX", "Los Angeles", "CARRIER", "PE-1", node, "REF-1", "a".repeat(64));
+        JsonNode payloadNode = json.valueToTree(payload);
+        String hash = EventPayloadHash.sha256(EventPayloadCanonicalizer.canonicalize(payloadNode));
+        return new EventEnvelope(eventId, EventTypes.FIRST_LEG_CONTAINER_SHIPPING_NODE_RECORDED, 1,
+            actualAt, RegionCode.CN, RegionCode.OVERSEAS, "100", "CONTAINER_BOOKING", "CB-1",
+            version, version + 1, "123e4567-e89b-12d3-a456-426614174199", "shipping:CB-1", null,
+            payloadNode, hash);
+    }
+}
@@ -18,7 +18,11 @@ class UsTruckOrderSchemaContractTest {
        assertTrue(sql.contains("CREATE TABLE IF NOT EXISTS ll_us_truck_order_pallet"));
        assertTrue(sql.contains("pallet_count INT NOT NULL DEFAULT 1"));
        assertTrue(sql.contains("received_pallet_count INT NOT NULL DEFAULT 0"));
-        assertTrue(sql.contains("receipt_idempotency_key VARCHAR(255) NULL"));
+        assertTrue(sql.contains("allocated_pallet_count INT NOT NULL DEFAULT 0"));
+        assertTrue(sql.contains("CREATE TABLE IF NOT EXISTS ll_us_truck_order_operation"));
+        assertTrue(sql.contains("UNIQUE KEY uk_ll_us_truck_operation_key(customer_id,order_id,idempotency_key)"));
+        assertTrue(sql.contains("operation_type VARCHAR(64) NOT NULL"));
+        assertTrue(sql.contains("idempotency_key VARCHAR(255) NULL COMMENT '操作幂等键'"));
        assertTrue(sql.contains("UNIQUE KEY uk_ll_us_truck_order_key(customer_id,idempotency_key)"));
        assertTrue(sql.contains("KEY idx_ll_us_truck_history(customer_id,order_id,created_at)"));
    }
@@ -37,7 +37,7 @@ class UsTruckOrderControllerTest {

    @Test
    void platformStatusChangeRequiresManagePermission() {
-        var request = new UsTruckOrderRequests.ChangeStatus(0L, "DISPATCHED", null);
+        var request = new UsTruckOrderRequests.ChangeStatus(0L, "CANCELLED", "cancel-1", null);
        ResponseStatusException error = assertThrows(ResponseStatusException.class,
            () -> platform.changeStatus(user(0L, "PLATFORM", Set.of()), "100", "TK1", request));
        assertEquals(403, error.getStatusCode().value());
@@ -45,11 +45,34 @@ class UsTruckOrderControllerTest {

    @Test
    void platformStatusChangeUsesExplicitTargetTenant() {
-        var request = new UsTruckOrderRequests.ChangeStatus(0L, "DISPATCHED", "truck assigned");
+        var request = new UsTruckOrderRequests.ChangeStatus(0L, "CANCELLED", "cancel-1", "cancelled");
        platform.changeStatus(user(0L, "PLATFORM", Set.of(UsTruckOrderService.MANAGE_PERMISSION)), "100", "TK1", request);
        verify(service).changeStatus("100", "TK1", "7", request);
    }

+    @Test
+    void platformLifecycleCommandsUseExplicitTargetAndStatusPermission() {
+        var user = user(0L, "PLATFORM", Set.of(UsTruckOrderService.MANAGE_PERMISSION));
+        var review = new UsTruckOrderRequests.Review(0L, "APPROVE", "review-1", null);
+        var overage = new UsTruckOrderRequests.ReviewPalletOverage(2L, "APPROVE", "overage-1", null);
+        var allocation = new UsTruckOrderRequests.AllocatePallets(3L, java.util.List.of(1L), "allocate-1", null);
+        var command = new UsTruckOrderRequests.Command(4L, "command-1", null);
+        platform.review(user, "100", "TK1", review);
+        platform.reviewPalletOverage(user, "100", "TK1", overage);
+        platform.allocatePallets(user, "100", "TK1", allocation);
+        platform.prepareDispatch(user, "100", "TK1", command);
+        platform.dispatch(user, "100", "TK1", command);
+        platform.startTransit(user, "100", "TK1", command);
+        platform.complete(user, "100", "TK1", command);
+        verify(service).review("100", "TK1", "7", review);
+        verify(service).reviewPalletOverage("100", "TK1", "7", overage);
+        verify(service).allocatePallets("100", "TK1", "7", allocation);
+        verify(service).prepareDispatch("100", "TK1", "7", command);
+        verify(service).dispatch("100", "TK1", "7", command);
+        verify(service).startTransit("100", "TK1", "7", command);
+        verify(service).complete("100", "TK1", "7", command);
+    }
+
    @Test
    void platformCreateUsesExplicitCustomerAndCreatePermission() {
        var request = new UsTruckOrderRequests.Create("PORT_PICKUP", "Los Angeles", null,
@@ -2,9 +2,11 @@ package com.baiyue.lastleg.trucking.service;

 import com.baiyue.lastleg.trucking.dto.UsTruckOrderRequests;
 import com.baiyue.lastleg.trucking.entity.UsTruckOrder;
+import com.baiyue.lastleg.trucking.entity.UsTruckOrderOperation;
 import com.baiyue.lastleg.trucking.entity.UsTruckOrderPallet;
 import com.baiyue.lastleg.trucking.entity.UsTruckOrderStatusHistory;
 import com.baiyue.lastleg.trucking.mapper.UsTruckOrderMapper;
+import com.baiyue.lastleg.trucking.mapper.UsTruckOrderOperationMapper;
 import com.baiyue.lastleg.trucking.mapper.UsTruckOrderPalletMapper;
 import com.baiyue.lastleg.trucking.mapper.UsTruckOrderStatusHistoryMapper;
 import com.fasterxml.jackson.databind.ObjectMapper;
@@ -16,18 +18,18 @@ import org.mockito.junit.jupiter.MockitoExtension;
 import org.springframework.test.util.ReflectionTestUtils;
 import org.springframework.web.server.ResponseStatusException;

-import java.math.BigDecimal;
-import java.time.LocalDate;
 import java.time.LocalDateTime;
 import java.util.ArrayList;
+import java.util.HashMap;
 import java.util.List;
-import java.util.concurrent.atomic.AtomicReference;
+import java.util.Map;

 import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertThrows;
+import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.ArgumentMatchers.any;
+import static org.mockito.ArgumentMatchers.anyLong;
 import static org.mockito.ArgumentMatchers.anyString;
-import static org.mockito.Mockito.verify;
 import static org.mockito.Mockito.when;

@ExtendWith(MockitoExtension.class)
@@ -35,7 +37,12 @@ class UsTruckOrderServiceTest {
    @Mock UsTruckOrderMapper orders;
    @Mock UsTruckOrderPalletMapper pallets;
    @Mock UsTruckOrderStatusHistoryMapper histories;
+    @Mock UsTruckOrderOperationMapper operations;
+    private final List<UsTruckOrderPallet> palletRows = new ArrayList<>();
+    private final List<UsTruckOrderStatusHistory> historyRows = new ArrayList<>();
+    private final Map<String, UsTruckOrderOperation> operationRows = new HashMap<>();
    private UsTruckOrderService service;
+    private UsTruckOrder order;

    @BeforeEach
    void setUp() {
@@ -43,113 +50,128 @@ class UsTruckOrderServiceTest {
        ReflectionTestUtils.setField(service, "orders", orders);
        ReflectionTestUtils.setField(service, "pallets", pallets);
        ReflectionTestUtils.setField(service, "histories", histories);
+        ReflectionTestUtils.setField(service, "operations", operations);
        ReflectionTestUtils.setField(service, "objectMapper", new ObjectMapper().findAndRegisterModules());
-        org.mockito.Mockito.lenient().when(pallets.listOrder(anyString(), any())).thenReturn(List.of());
-    }
-
-    @Test
-    void customerOrderStartsPendingConfirmationAndUsesUsdByDefault() {
-        AtomicReference<UsTruckOrder> saved = new AtomicReference<>();
-        when(orders.insert(any(UsTruckOrder.class))).thenAnswer(call -> { saved.set(call.getArgument(0)); return 1; });
-        when(orders.findNo(anyString(), anyString())).thenAnswer(call -> saved.get());
-        when(histories.listOrder(anyString(), any())).thenReturn(List.of());
-
-        var detail = service.create("100", "7", create("key-1"));
-
-        assertEquals(UsTruckOrderService.PENDING_CONFIRMATION, detail.summary().status());
-        assertEquals("USD", detail.summary().currency());
-        assertEquals("100", detail.summary().customerId());
-    }
-
-    @Test
-    void statusChangePersistsHistoryAndIncrementsVersion() {
-        UsTruckOrder order = order(UsTruckOrderService.PENDING_CONFIRMATION, 0L);
-        when(orders.lockNo("100", "TK1")).thenReturn(order);
-        when(orders.findNo("100", "TK1")).thenReturn(order);
-        when(histories.listOrder("100", 1L)).thenReturn(List.of());
-
-        var result = service.changeStatus("100", "TK1", "7",
-            new UsTruckOrderRequests.ChangeStatus(0L, "WAITING_INBOUND", "accepted"));
-
-        assertEquals(UsTruckOrderService.WAITING_INBOUND, result.summary().status());
-        assertEquals(1, result.summary().version());
-        verify(histories).insert(any(UsTruckOrderStatusHistory.class));
-    }
-
-    @Test
-    void staleStatusChangeIsRejected() {
-        when(orders.lockNo("100", "TK1")).thenReturn(order(UsTruckOrderService.DISPATCHED, 2L));
-        ResponseStatusException error = assertThrows(ResponseStatusException.class, () ->
-            service.changeStatus("100", "TK1", "7", new UsTruckOrderRequests.ChangeStatus(1L, "IN_TRANSIT", null)));
-        assertEquals(409, error.getStatusCode().value());
-    }
-
-    @Test
-    void staleOrdinaryUpdateIsRejectedAsConflict() {
-        when(orders.lockNo("100", "TK1")).thenReturn(order(UsTruckOrderService.PENDING_REVIEW, 2L));
-        UsTruckOrderRequests.Update request = new UsTruckOrderRequests.Update(1L,
-            null, null, null, null, null, null, null, null, null, null, null,
-            null, null, null, null, null);
-
-        ResponseStatusException error = assertThrows(ResponseStatusException.class,
-            () -> service.update("100", "TK1", "7", request));
-
-        assertEquals(409, error.getStatusCode().value());
-    }
-
-    @Test
-    void detailIncludesBoundPallets() {
-        UsTruckOrder order = order(UsTruckOrderService.WAITING_INBOUND, 1L);
-        UsTruckOrderPallet pallet = new UsTruckOrderPallet();
-        pallet.setId(10L); pallet.setPalletNo("PLT-001"); pallet.setSequenceNo(1);
-        pallet.setSource("SYSTEM"); pallet.setStatus("OCCUPIED");
-        pallet.setWarehousePalletId(20L); pallet.setPackageCount(12);
-        when(orders.findNo("100", "TK1")).thenReturn(order);
-        when(histories.listOrder("100", 1L)).thenReturn(List.of());
-        when(pallets.listOrder("100", 1L)).thenReturn(List.of(pallet));
-
-        var detail = service.detail("100", "TK1");
-
-        assertEquals(1, detail.pallets().size());
-        assertEquals("PLT-001", detail.pallets().get(0).palletNo());
-        assertEquals(12, detail.pallets().get(0).packageCount());
-    }
-
-    @Test
-    void receivingMorePalletsCreatesOverageAndKeepsDeclaredCount() {
-        UsTruckOrder order = order(UsTruckOrderService.WAITING_INBOUND, 0L);
-        order.setPalletCount(1);
-        when(orders.lockNo("100", "TK1")).thenReturn(order);
-        when(orders.findNo("100", "TK1")).thenReturn(order);
-        when(histories.listOrder("100", 1L)).thenReturn(List.of());
-        List<UsTruckOrderPallet> savedPallets = new ArrayList<>();
-        when(pallets.listOrder("100", 1L)).thenAnswer(call -> List.copyOf(savedPallets));
-        when(pallets.insert(any(UsTruckOrderPallet.class))).thenAnswer(call -> {
-            savedPallets.add(call.getArgument(0));
-            return 1;
+        order = order(UsTruckOrderService.PENDING_REVIEW, 0L, 2);
+        when(orders.lockNo("100", "TK1")).thenAnswer(call -> order);
+        when(orders.findNo("100", "TK1")).thenAnswer(call -> order);
+        when(pallets.listOrder("100", 1L)).thenAnswer(call -> palletRows);
+        when(histories.listOrder("100", 1L)).thenAnswer(call -> historyRows);
+        when(histories.insert(any(UsTruckOrderStatusHistory.class))).thenAnswer(call -> {
+            historyRows.add(call.getArgument(0)); return 1;
        });
-
-        var result = service.receivePallets("100", "TK1", "7",
-            new UsTruckOrderRequests.ReceivePallets(0L, 3, 0, "receive-1", "actual three pallets"));
-
-        assertEquals(1, result.summary().palletCount());
-        assertEquals(3, result.summary().receivedPalletCount());
-        assertEquals(UsTruckOrderService.PALLET_OVERAGE_REVIEW, result.summary().status());
-        verify(pallets, org.mockito.Mockito.times(3)).insert(any(UsTruckOrderPallet.class));
+        when(pallets.insert(any(UsTruckOrderPallet.class))).thenAnswer(call -> {
+            UsTruckOrderPallet row = call.getArgument(0); palletRows.add(row); return 1;
+        });
+        when(operations.findKey(anyString(), anyLong(), anyString()))
+            .thenAnswer(call -> operationRows.get(call.getArgument(2)));
+        when(operations.insert(any(UsTruckOrderOperation.class))).thenAnswer(call -> {
+            UsTruckOrderOperation row = call.getArgument(0); operationRows.put(row.getIdempotencyKey(), row); return 1;
+        });
+        UsTruckOrderStatusHistory created = new UsTruckOrderStatusHistory();
+        created.setOperationType("CREATE"); created.setOperatorId("creator"); created.setIdempotencyKey("create-1");
+        created.setToStatus(UsTruckOrderService.PENDING_REVIEW); historyRows.add(created);
    }

-    private UsTruckOrderRequests.Create create(String key) {
-        return new UsTruckOrderRequests.Create("PORT_PICKUP", "Los Angeles Port", "Pier 1", "Ontario, CA",
-            "Warehouse A", "40HQ", 100, new BigDecimal("12600"), new BigDecimal("55.2"),
-            new BigDecimal("3800"), null, "Alice", "+1-555-0100", LocalDate.now().plusDays(2), null, key);
+    @Test
+    void completeLifecycleUsesFactsIdempotencyOperatorsAndCannotReverseTerminal() {
+        var review = new UsTruckOrderRequests.Review(0L, "APPROVE", "review-1", "approve");
+        var reviewed = service.review("100", "TK1", "operator-7", review);
+        assertEquals(UsTruckOrderService.WAITING_INBOUND, reviewed.summary().status());
+        assertEquals(2, palletRows.size());
+        assertEquals(1L, reviewed.summary().version());
+        assertEquals(1L, service.review("100", "TK1", "operator-7", review).summary().version());
+        assertThrows(ResponseStatusException.class, () -> service.review("100", "TK1", "operator-7",
+            new UsTruckOrderRequests.Review(1L, "REJECT", "review-1", "different")));
+
+        var receive = new UsTruckOrderRequests.ReceivePallets(1L, 3, 6, List.of(2, 2, 2),
+            "receive-1", "receive overage");
+        var received = service.receivePallets("100", "TK1", "receiver-8", receive);
+        assertEquals(UsTruckOrderService.PALLET_OVERAGE_REVIEW, received.summary().status());
+        assertEquals(3, received.summary().receivedPalletCount());
+        assertEquals(3, palletRows.size());
+        assertEquals(2L, service.receivePallets("100", "TK1", "receiver-8", receive).summary().version());
+
+        var overage = new UsTruckOrderRequests.ReviewPalletOverage(2L, "APPROVE",
+            "overage-1", "approve overage");
+        var overageReviewed = service.reviewPalletOverage("100", "TK1", "reviewer-9", overage);
+        assertEquals(UsTruckOrderService.WAITING_CONSOLIDATION, overageReviewed.summary().status());
+        assertEquals(3, overageReviewed.summary().palletCount());
+        assertTrue(palletRows.stream().allMatch(row -> "RECEIVED".equals(row.getStatus())));
+
+        Long first = palletRows.get(0).getId();
+        List<Long> remaining = palletRows.subList(1, 3).stream().map(UsTruckOrderPallet::getId).toList();
+        var partial = service.allocatePallets("100", "TK1", "allocator-10",
+            new UsTruckOrderRequests.AllocatePallets(3L, List.of(first), "allocate-1", "partial"));
+        assertEquals(UsTruckOrderService.PARTIALLY_ALLOCATED, partial.summary().status());
+        assertEquals(1, partial.summary().allocatedPalletCount());
+        var allocated = service.allocatePallets("100", "TK1", "allocator-10",
+            new UsTruckOrderRequests.AllocatePallets(4L, remaining, "allocate-2", "all"));
+        assertEquals(UsTruckOrderService.ALLOCATED, allocated.summary().status());
+        assertEquals(3, allocated.summary().allocatedPalletCount());
+
+        assertEquals(UsTruckOrderService.PENDING_DISPATCH, service.prepareDispatch("100", "TK1", "dispatcher-11",
+            command(5L, "prepare-1")).summary().status());
+        assertEquals(UsTruckOrderService.DISPATCHED, service.dispatch("100", "TK1", "dispatcher-11",
+            command(6L, "dispatch-1")).summary().status());
+        assertEquals(UsTruckOrderService.IN_TRANSIT, service.startTransit("100", "TK1", "driver-12",
+            command(7L, "transit-1")).summary().status());
+        var completed = service.complete("100", "TK1", "driver-12", command(8L, "complete-1"));
+        assertEquals(UsTruckOrderService.COMPLETED, completed.summary().status());
+        assertEquals(9L, completed.summary().version());
+        assertEquals(9L, service.complete("100", "TK1", "driver-12", command(8L, "complete-1"))
+            .summary().version());
+
+        assertThrows(ResponseStatusException.class, () -> service.changeStatus("100", "TK1", "operator-7",
+            new UsTruckOrderRequests.ChangeStatus(9L, "CANCELLED", "cancel-terminal", "forbidden")));
+        assertThrows(ResponseStatusException.class, () -> service.startTransit("100", "TK1", "driver-12",
+            command(8L, "reverse-state")));
+        assertThrows(ResponseStatusException.class, () -> service.dispatch("100", "TK1", "dispatcher-11",
+            command(1L, "stale-version")));
+
+        assertEquals(List.of("CREATE", "REVIEW", "RECEIVE_PALLETS", "REVIEW_PALLET_OVERAGE",
+                "ALLOCATE_PALLETS", "ALLOCATE_PALLETS", "PREPARE_DISPATCH", "DISPATCH",
+                "START_TRANSIT", "COMPLETE"),
+            historyRows.stream().map(UsTruckOrderStatusHistory::getOperationType).toList());
+        assertTrue(historyRows.stream().skip(1).allMatch(row -> row.getOperatorId() != null
+            && row.getIdempotencyKey() != null));
    }

-    private UsTruckOrder order(String status, long version) {
-        UsTruckOrder order = new UsTruckOrder(); order.setId(1L); order.setCustomerId("100"); order.setOrderNo("TK1");
-        order.setTransportType("PORT_PICKUP"); order.setOrigin("Los Angeles"); order.setDestination("Ontario");
-        order.setContainerType("40HQ"); order.setPalletCount(1); order.setPackageCount(0);
-        order.setReceivedPalletCount(0); order.setAllocatedPalletCount(0); order.setShippedPalletCount(0);
-        order.setStatus(status); order.setVersion(version);
-        order.setCreatedAt(LocalDateTime.now()); order.setUpdatedAt(order.getCreatedAt()); return order;
+    @Test
+    void partialReceiptUsesReceivingThenExactReceiptMovesToConsolidation() {
+        service.review("100", "TK1", "operator", new UsTruckOrderRequests.Review(
+            0L, "APPROVE", "review-partial", null));
+        var partial = service.receivePallets("100", "TK1", "receiver",
+            new UsTruckOrderRequests.ReceivePallets(1L, 1, 2, List.of(2), "receive-partial", null));
+        assertEquals(UsTruckOrderService.RECEIVING, partial.summary().status());
+        var exact = service.receivePallets("100", "TK1", "receiver",
+            new UsTruckOrderRequests.ReceivePallets(2L, 2, 4, List.of(2, 2), "receive-exact", null));
+        assertEquals(UsTruckOrderService.WAITING_CONSOLIDATION, exact.summary().status());
+    }
+
+    @Test
+    void rejectedOverageExcludesExtraPalletFromAcceptedCount() {
+        service.review("100", "TK1", "operator", new UsTruckOrderRequests.Review(
+            0L, "APPROVE", "review-reject-overage", null));
+        service.receivePallets("100", "TK1", "receiver", new UsTruckOrderRequests.ReceivePallets(
+            1L, 3, 6, List.of(2, 2, 2), "receive-reject-overage", null));
+        var reviewed = service.reviewPalletOverage("100", "TK1", "reviewer",
+            new UsTruckOrderRequests.ReviewPalletOverage(2L, "REJECT", "reject-overage", null));
+        assertEquals(2, reviewed.summary().receivedPalletCount());
+        assertEquals("OVERAGE_REJECTED", palletRows.get(2).getStatus());
+    }
+
+    private UsTruckOrderRequests.Command command(long version, String key) {
+        return new UsTruckOrderRequests.Command(version, key, key);
+    }
+
+    private UsTruckOrder order(String status, long version, int pallets) {
+        UsTruckOrder value = new UsTruckOrder();
+        value.setId(1L); value.setCustomerId("100"); value.setOrderNo("TK1");
+        value.setTransportType("PORT_PICKUP"); value.setOrigin("Los Angeles"); value.setDestination("Ontario");
+        value.setPalletCount(pallets); value.setPackageCount(0); value.setReceivedPalletCount(0);
+        value.setAllocatedPalletCount(0); value.setStatus(status); value.setVersion(version);
+        value.setCreatedAt(LocalDateTime.now()); value.setUpdatedAt(value.getCreatedAt());
+        return value;
    }
 }