修复费用记录、装柜完成及海外履约资料

2026-10-21 23:20:09 +08:00
parent 5356a8c898
commit 2c3435adaf
62 changed files with 1622 additions and 298 deletions
@@ -4,6 +4,7 @@ import com.baomidou.mybatisplus.core.mapper.BaseMapper;
 import com.baiyue.firstleg.entity.LoadingCompletionCommandEntity;
 import org.apache.ibatis.annotations.Insert;
 import org.apache.ibatis.annotations.Mapper;
+import org.apache.ibatis.annotations.Options;
 import org.apache.ibatis.annotations.Param;
 import org.apache.ibatis.annotations.Select;
 import org.apache.ibatis.annotations.Update;
@@ -55,28 +56,34 @@ public interface LoadingCompletionCommandMapper extends BaseMapper<LoadingComple
    int claim(@Param("id") long id, @Param("worker") String worker,
              @Param("leaseUntil") LocalDateTime leaseUntil);

+    /** 只有尚未过期的当前所有者可以续租，过期执行者必须重新领取。 */
    @Update("""
        UPDATE fl_loading_completion_command SET lease_until=#{leaseUntil},updated_at=CURRENT_TIMESTAMP(3)
         WHERE id=#{id} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
        """)
    int renew(@Param("id") long id, @Param("worker") String worker,
              @Param("leaseUntil") LocalDateTime leaseUntil);

+    /** 完成落库必须仍持有有效租约，拒绝过期或已易主的旧执行者。 */
    @Update("""
        UPDATE fl_loading_completion_command
           SET command_status='COMPLETED',completed_at=CURRENT_TIMESTAMP(3),updated_at=CURRENT_TIMESTAMP(3),
               lease_owner=NULL,lease_until=NULL,failure_stage=NULL,failure_code=NULL,
               failure_request_id=NULL,failure_trace_id=NULL
         WHERE id=#{id} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
        """)
    int complete(@Param("id") long id, @Param("worker") String worker);

+    /** 失败回执也受当前有效租约保护，不能覆盖新执行者的状态。 */
    @Update("""
        UPDATE fl_loading_completion_command
           SET command_status=#{status},next_retry_at=#{nextRetryAt},updated_at=CURRENT_TIMESTAMP(3),
               lease_owner=NULL,lease_until=NULL,failure_stage=#{stage},failure_code=#{code},
               failure_request_id=#{requestId},failure_trace_id=#{traceId}
         WHERE id=#{id} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
        """)
    int fail(@Param("id") long id, @Param("worker") String worker, @Param("status") String status,
             @Param("nextRetryAt") LocalDateTime nextRetryAt, @Param("stage") String stage,
@@ -97,13 +104,32 @@ public interface LoadingCompletionCommandMapper extends BaseMapper<LoadingComple
    String checkpoint(@Param("commandId") long commandId, @Param("tenantId") long tenantId,
                      @Param("inboundId") long inboundId);

+    /** 检查点事务锁住当前有效租约，与并发重新领取互斥。 */
+    @Options(useCache = false, flushCache = Options.FlushCachePolicy.TRUE)
+    @Select("""
+        SELECT id FROM fl_loading_completion_command
+         WHERE id=#{commandId} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
+         FOR UPDATE
+        """)
+    Long lockCheckpointLease(@Param("commandId") long commandId, @Param("worker") String worker);
+
+    /** 在已锁定的命令行上重验有效租约；检查点只能前进，不能被迟到写入降级。 */
    @Insert("""
        INSERT INTO fl_loading_completion_checkpoint
          (command_id,tenant_id,inbound_id,owner_sequence,checkpoint_stage)
-        VALUES (#{commandId},#{tenantId},#{inboundId},#{sequence},#{stage})
-        ON DUPLICATE KEY UPDATE checkpoint_stage=VALUES(checkpoint_stage),updated_at=CURRENT_TIMESTAMP(3)
+        SELECT id,#{tenantId},#{inboundId},#{sequence},#{stage}
+          FROM fl_loading_completion_command
+         WHERE id=#{commandId} AND command_status='PROCESSING' AND lease_owner=#{worker}
+           AND lease_until>CURRENT_TIMESTAMP(3)
+        ON DUPLICATE KEY UPDATE checkpoint_stage=CASE
+          WHEN checkpoint_stage='INBOUND_COMPLETED' OR #{stage}='INBOUND_COMPLETED'
+            THEN 'INBOUND_COMPLETED'
+          WHEN checkpoint_stage='SETTLED' OR #{stage}='SETTLED' THEN 'SETTLED'
+          ELSE 'READY' END,updated_at=CURRENT_TIMESTAMP(3)
        """)
-    int checkpointCompleted(@Param("commandId") long commandId, @Param("tenantId") long tenantId,
+    int checkpointCompleted(@Param("commandId") long commandId, @Param("worker") String worker,
+                            @Param("tenantId") long tenantId,
                            @Param("inboundId") long inboundId, @Param("sequence") int sequence,
                            @Param("stage") String stage);
 }
@@ -11,16 +11,27 @@ import java.util.stream.Collectors;
@Service
 public class AppointmentForecastService {
    public record Forecast(Long containerBookingId,AppointmentForecastMapper.Fact latest,
-                           AppointmentForecastMapper.Fact previous,String timeBasis) { }
+                           AppointmentForecastMapper.Fact previous,String timeBasis,
+                           java.time.LocalDateTime portArrivalAt) { }
    private final AppointmentForecastMapper mapper;
-    public AppointmentForecastService(AppointmentForecastMapper mapper){this.mapper=mapper;}
+    private final com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository sources;
+    /** 读取船节点及日历权威到港来源，不从调用端接收推算日期。 */
+    public AppointmentForecastService(AppointmentForecastMapper mapper,
+        com.baiyue.firstleg.terminaldrayage.repository.ContainerCalendarSourceRepository sources) {
+        this.mapper=mapper; this.sources=sources;
+    }
+    /** 返回明确来源柜的到港事实，保留未知日期。 */
    public List<Forecast> batch(List<Long> ids) {
        if(ids==null || ids.isEmpty() || ids.size()>200 || ids.stream().anyMatch(id->id==null || id<=0)
            || new HashSet<>(ids).size()!=ids.size()) throw new ResponseStatusException(HttpStatus.BAD_REQUEST,"每批须提供1至200个不重复的柜次");
        var facts=mapper.latest(ids).stream().collect(Collectors.groupingBy(AppointmentForecastMapper.Fact::containerBookingId));
+        var arrivals=sources.byIds(ids).stream().collect(Collectors.toMap(
+            com.baiyue.firstleg.terminaldrayage.dto.ContainerCalendarSource::containerBookingId,
+            java.util.function.Function.identity()));
        return ids.stream().map(id->{
            var rows=facts.getOrDefault(id,List.of());
-            return new Forecast(id,rows.isEmpty()?null:rows.get(0),rows.size()<2?null:rows.get(1),"SOURCE_LOCAL_UNSPECIFIED");
+            return new Forecast(id,rows.isEmpty()?null:rows.get(0),rows.size()<2?null:rows.get(1),"SOURCE_LOCAL_UNSPECIFIED",
+                arrivals.containsKey(id)?arrivals.get(id).arrivalAt():null);
        }).toList();
    }
 }
@@ -4,6 +4,7 @@ import com.baiyue.firstleg.entity.LoadingCompletionCommandEntity;
 import com.baiyue.firstleg.mapper.LoadingCompletionCommandMapper;
 import jakarta.annotation.Resource;
 import org.springframework.stereotype.Repository;
+import org.springframework.transaction.annotation.Transactional;

 import java.time.LocalDateTime;
 import java.util.List;
@@ -12,6 +13,9 @@ import java.util.List;
 public class LoadingCompletionCommandRepository {
    @Resource private LoadingCompletionCommandMapper mapper;

+    /** 按事务提交后的命令标识读取唯一完成请求。 */
+    public LoadingCompletionCommandEntity command(long id) { return mapper.selectById(id); }
+
    public int insert(LoadingCompletionCommandEntity command) { return mapper.insertCommand(command); }
    public LoadingCompletionCommandEntity operation(String operationId) { return mapper.findByOperation(operationId); }
    public LoadingCompletionCommandEntity active(long taskId) { return mapper.findActiveByTask(taskId); }
@@ -28,7 +32,13 @@ public class LoadingCompletionCommandRepository {
    public String checkpoint(long commandId, long tenantId, long inboundId) {
        return mapper.checkpoint(commandId, tenantId, inboundId);
    }
-    public void checkpoint(long commandId, long tenantId, long inboundId, int sequence, String stage) {
-        mapper.checkpointCompleted(commandId, tenantId, inboundId, sequence, stage);
+    /** 命令行锁覆盖租约检查与检查点写入，旧执行者不能在租约易主后覆盖新结果。 */
+    @Transactional
+    public boolean checkpoint(long commandId, String worker, long tenantId, long inboundId,
+                              int sequence, String stage) {
+        if (mapper.lockCheckpointLease(commandId, worker) == null) return false;
+        int written = mapper.checkpointCompleted(commandId, worker, tenantId, inboundId, sequence, stage);
+        // 同阶段重放可能被驱动计为零行；命令行仍被本事务锁住，重验租约区分幂等与过期拒绝。
+        return written > 0 || mapper.lockCheckpointLease(commandId, worker) != null;
    }
 }
@@ -9,37 +9,77 @@ import jakarta.annotation.Resource;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 import org.springframework.scheduling.annotation.Scheduled;
+import org.springframework.core.task.TaskExecutor;
 import org.springframework.stereotype.Service;
+import org.springframework.transaction.event.TransactionalEventListener;

 import java.time.LocalDateTime;
 import java.util.UUID;
+import java.util.concurrent.RejectedExecutionException;

-/** Lease-based recovery worker for PDA completion commands. */
+/** 事务提交后立即处理 PDA 完成命令，并按持久化租约定时恢复。 */
@Service
 public class LoadingCompletionWorker {
    private static final Logger log = LoggerFactory.getLogger(LoadingCompletionWorker.class);
    private static final int MAX_ATTEMPTS = 5;
-    private final String workerId = "pda-completion-" + UUID.randomUUID();

    @Resource private LoadingCompletionCommandRepository commands;
    @Resource private LoadingPickRepository picks;
    @Resource private LoadingPickService loadingPicks;
+    @Resource(name = "applicationTaskExecutor") private TaskExecutor completionExecutor;

-    @Scheduled(fixedDelayString = "${baiyue.firstleg.pda-completion.fixed-delay-ms:2000}")
-    public void dispatch() {
-        for (LoadingCompletionCommandEntity candidate : commands.due(10)) {
-            if (!commands.claim(candidate.getId(), workerId, LocalDateTime.now().plusMinutes(10))) {
-                continue;
-            }
-            try {
-                loadingPicks.processCompletion(candidate, workerId);
-            } catch (RuntimeException exception) {
-                handleFailure(candidate, exception);
-            }
+    /** 唤醒只发生在受理事务提交后，异步执行不延长 HTTP 受理请求。 */
+    @TransactionalEventListener
+    public void accepted(LoadingPickService.CompletionAccepted accepted) {
+        try {
+            completionExecutor.execute(() -> dispatchAccepted(accepted));
+        } catch (RejectedExecutionException exception) {
+            // 执行器繁忙或关闭时保留持久化命令，仍由定时扫描领取，不能影响已提交回执。
+            log.warn("pda_completion_wakeup_deferred commandId={}", accepted.commandId(), exception);
        }
    }

-    private void handleFailure(LoadingCompletionCommandEntity command, RuntimeException exception) {
+    /** 唤醒与恢复共用原子领取；同一命令不会被两个执行入口重复结算。 */
+    private void dispatchAccepted(LoadingPickService.CompletionAccepted accepted) {
+        try {
+            LoadingCompletionCommandEntity command = commands.command(accepted.commandId());
+            if (command != null) process(command, "immediate", accepted.acceptedAtNanos());
+        } catch (RuntimeException exception) {
+            log.warn("pda_completion_wakeup_failed commandId={}", accepted.commandId(), exception);
+        }
+    }
+
+    /** 扫描到期或租约过期命令，覆盖唤醒丢失、进程重启及失败退避恢复。 */
+    @Scheduled(fixedDelayString = "${baiyue.firstleg.pda-completion.fixed-delay-ms:2000}")
+    public void dispatch() {
+        for (LoadingCompletionCommandEntity candidate : commands.due(10)) {
+            process(candidate, "scheduled", System.nanoTime());
+        }
+    }
+
+    /** 保留租约、检查点和失败恢复语义，记录领取及实际处理耗时。 */
+    private void process(LoadingCompletionCommandEntity command, String source, long queuedAt) {
+        // 每次领取使用独立所有者，避免旧执行线程在租约过期、同进程重新领取后继续写入。
+        String leaseOwner = "pda-completion-" + UUID.randomUUID();
+        if (!commands.claim(command.getId(), leaseOwner, LocalDateTime.now().plusMinutes(10))) return;
+        long started = System.nanoTime();
+        boolean succeeded = false;
+        log.info("pda_completion_started commandId={} taskId={} source={} wakeupMs={}",
+            command.getId(), command.getPickTaskId(), source, (started - queuedAt) / 1_000_000);
+        try {
+            loadingPicks.processCompletion(command, leaseOwner);
+            succeeded = true;
+        } catch (RuntimeException exception) {
+            handleFailure(command, leaseOwner, exception);
+        } finally {
+            log.info("pda_completion_finished commandId={} taskId={} source={} durationMs={} succeeded={}",
+                command.getId(), command.getPickTaskId(), source, (System.nanoTime() - started) / 1_000_000,
+                succeeded);
+        }
+    }
+
+    /** 确定性失败关闭任务，其余故障按原退避与最大次数恢复。 */
+    private void handleFailure(LoadingCompletionCommandEntity command, String leaseOwner, RuntimeException exception) {
        Throwable cause = exception instanceof LoadingPickService.CompletionProcessingException
            && exception.getCause() != null ? exception.getCause() : exception;
        String stage = exception instanceof LoadingPickService.CompletionProcessingException staged
@@ -53,7 +93,7 @@ public class LoadingCompletionWorker {
        int attempt = command.getAttemptCount() == null ? 1 : command.getAttemptCount() + 1;
        boolean terminal = isDeterministicLocalBusinessFailure(stage, cause) || attempt >= MAX_ATTEMPTS;
        LocalDateTime retryAt = LocalDateTime.now().plusSeconds(Math.min(300L, 15L << Math.min(attempt - 1, 4)));
-        boolean recorded = commands.fail(command.getId(), workerId, terminal ? "FAILED" : "RETRYABLE", retryAt,
+        boolean recorded = commands.fail(command.getId(), leaseOwner, terminal ? "FAILED" : "RETRYABLE", retryAt,
            stage, code, requestId, traceId);
        if (terminal && recorded) {
            picks.failCompletion(command.getPickTaskId());
@@ -63,6 +103,7 @@ public class LoadingCompletionWorker {
            command.getOperationId(), stage, code, requestId, traceId, attempt, terminal, cause);
    }

+    /** 仅将已明确不可重试的本地业务门禁判为终态。 */
    private static boolean isDeterministicLocalBusinessFailure(String stage, Throwable cause) {
        if (!(cause instanceof BizException business)) {
            return false;
@@ -56,6 +56,7 @@ import jakarta.annotation.Resource;
 import org.springframework.dao.DuplicateKeyException;
 import org.springframework.stereotype.Service;
 import org.springframework.beans.factory.annotation.Value;
+import org.springframework.context.ApplicationEventPublisher;
 import org.springframework.transaction.support.TransactionTemplate;
 import org.springframework.transaction.annotation.Transactional;
 import org.springframework.util.StringUtils;
@@ -87,6 +88,8 @@ public class LoadingPickService {
    @Resource
    private LoadingCompletionCommandRepository completionCommands;
    @Resource
+    private ApplicationEventPublisher completionEvents;
+    @Resource
    private TransactionTemplate completionTransaction;
    @Resource
    private SmartLoadingRepository smartLoadingRepository;
@@ -552,6 +555,7 @@ public class LoadingPickService {
                    || !completionCommands.resume(replay.getId()) || repository.resumeCompletion(taskId) != 1) {
                    throw conflict("装柜完成命令状态已变化，请刷新后重试");
                }
+                completionEvents.publishEvent(new CompletionAccepted(replay.getId(), System.nanoTime()));
            }
            return view(requiredTask(taskId), null);
        }
@@ -598,9 +602,14 @@ public class LoadingPickService {
        if (repository.acceptCompletion(taskId, task.getVersion()) != 1) {
            throw conflict("PDA任务版本已变化，请刷新后复核");
        }
+        // 提交后立即唤醒仍经持久化租约领取；回滚不得触发结算，定时扫描继续负责故障恢复。
+        completionEvents.publishEvent(new CompletionAccepted(command.getId(), System.nanoTime()));
        return view(requiredTask(taskId), null);
    }

+    /** 本进程事务提交后的唤醒信号，权威命令和恢复事实仍保存在数据库。 */
+    public record CompletionAccepted(long commandId, long acceptedAtNanos) {}
+
    private void requireCompletionContainerNumber(long taskId) {
        ContainerBookingEntity booking = repository.activeBookingByTask(taskId);
        if (booking == null || !StringUtils.hasText(booking.getContainerNo())) {
@@ -613,7 +622,7 @@ public class LoadingPickService {
        }
    }

-    /** Called only by the completion worker, after its durable lease has committed. */
+    /** 仅在持久化租约领取成功后执行，远程结算不占用受理事务。 */
    public void processCompletion(LoadingCompletionCommandEntity command, String worker) {
        long taskId = command.getPickTaskId();
        inboundHoldGuard.requireTaskNotHeld(taskId);
@@ -625,55 +634,55 @@ public class LoadingPickService {
            .toList();
        if (owners.isEmpty()) throw new CompletionProcessingException("OWNER_DISCOVERY", conflict("PDA任务未关联有效入库单"));
        List<GroupSnapshot> taskGroups = coloadGroups(owners);
-        runCompletionStage("CABINET_EVIDENCE", () ->
+        runCompletionStage(taskId, "CABINET_EVIDENCE", () ->
            cabinetEvidenceService.requireComplete(task.getContainerBookingId()));
-        runCompletionStage("COMPLETED_EVENT_READY", () ->
+        runCompletionStage(taskId, "COMPLETED_EVENT_READY", () ->
            loadingListService.requireCompletedEventReady(task.getLoadingPlanId()));

-        // Phase 1 is read-only: cabinet evidence is checked once, then every owner must pass its business gates
-        // before any warehouse resource or inbound status can be changed. This prevents a later customer gate from
-        // leaving earlier customers partially completed.
+        // 全柜所有客户先通过只读门禁，再开始资源结算，避免后续客户失败造成前序客户局部完成。
        for (int index = 0; index < owners.size(); index++) {
            requireCompletionLease(command.getId(), worker);
            LoadingPickItemMapper.InboundOwner owner = owners.get(index);
            String checkpoint = completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId());
            if (!checkpointAtLeast(checkpoint, "SETTLED")) {
-                runCompletionStage("OWNER_READY", () -> loadingDeliveryService.requirePdaCompletionReady(
+                runCompletionStage(taskId, "OWNER_READY", () -> loadingDeliveryService.requirePdaCompletionReady(
                    owner.tenantId(), owner.inboundId()));
                if (!checkpointAtLeast(checkpoint, "READY")) {
-                    requireCompletionLease(command.getId(), worker);
-                    completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId(),
+                    recordCompletionCheckpoint(command.getId(), worker, owner.tenantId(), owner.inboundId(),
                        index + 1, "READY");
                }
            }
        }

-        // Phase 2 is recoverable by per-owner checkpoints and stable idempotency keys. It starts only after the
-        // complete cabinet passed phase 1, while prior deployments' completed checkpoints remain safely resumable.
+        // 全柜门禁通过后，按客户检查点和稳定幂等键逐步结算，已完成的检查点可安全续做。
        for (int index = 0; index < owners.size(); index++) {
            requireCompletionLease(command.getId(), worker);
            LoadingPickItemMapper.InboundOwner owner = owners.get(index);
            String checkpoint = completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId());
            if (!checkpointAtLeast(checkpoint, "SETTLED")) {
-                runCompletionStage("WAREHOUSE_SETTLEMENT", () -> settlementService.settleOwner(
+                runCompletionStage(taskId, "WAREHOUSE_SETTLEMENT", () -> settlementService.settleOwner(
                    taskId, owner.inboundId(), command.getOperatorId(), command.getOperatorName()));
-                requireCompletionLease(command.getId(), worker);
-                completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId(), index + 1, "SETTLED");
+                recordCompletionCheckpoint(command.getId(), worker, owner.tenantId(), owner.inboundId(), index + 1, "SETTLED");
            }
            if (!checkpointAtLeast(checkpoint, "INBOUND_COMPLETED")) {
-                runCompletionStage("INBOUND_COMPLETE", () -> loadingDeliveryService.completeAfterPdaSettlement(
+                runCompletionStage(taskId, "INBOUND_COMPLETE", () -> loadingDeliveryService.completeAfterPdaSettlement(
                    owner.tenantId(), owner.inboundId(),
                    command.getOperatorId(), command.getOperatorName(),
                    "PDA-" + command.getOperationId() + '-' + owner.inboundId(), command.getRemark()));
-                requireCompletionLease(command.getId(), worker);
-                completionCommands.checkpoint(command.getId(), owner.tenantId(), owner.inboundId(), index + 1,
+                recordCompletionCheckpoint(command.getId(), worker, owner.tenantId(), owner.inboundId(), index + 1,
                    "INBOUND_COMPLETED");
            }
        }
-        completionTransaction.executeWithoutResult(ignored -> finalizeCompletion(command, worker, task, taskGroups));
+        long transactionStarted = System.nanoTime();
+        try {
+            completionTransaction.executeWithoutResult(ignored -> finalizeCompletion(command, worker, task, taskGroups));
+        } finally {
+            log.info("pda_completion_transaction taskId={} durationMs={}", taskId,
+                (System.nanoTime() - transactionStarted) / 1_000_000);
+        }
    }

-    /** Final Firstleg convergence only; all remote owner settlement calls have completed before this short transaction. */
+    /** 远程结算完成后，仅在短事务内收敛 Firstleg 本地完成事实。 */
    private void finalizeCompletion(LoadingCompletionCommandEntity command, String worker,
                                    LoadingPickTaskEntity task, List<GroupSnapshot> taskGroups) {
        long taskId = task.getId();
@@ -688,11 +697,11 @@ public class LoadingPickService {
            insertOperation(taskId, command.getOperationId(), command.getRequestHash(), "COMPLETE_LOADING",
                command.getOperatorId(), command.getOperatorName());
        }
-        runCompletionStage("PLAN_COMPLETE", () -> loadingListService.finishFromPda(task.getLoadingPlanId(), taskId,
+        runCompletionStage(taskId, "PLAN_COMPLETE", () -> loadingListService.finishFromPda(task.getLoadingPlanId(), taskId,
            command.getOperatorId(), command.getOperatorName()));
-        runCompletionStage("COMPLETED_EVENT", () -> loadingListService.publishCompletedEvent(task.getLoadingPlanId()));
+        runCompletionStage(taskId, "COMPLETED_EVENT", () -> loadingListService.publishCompletedEvent(task.getLoadingPlanId()));
        for (GroupSnapshot group : taskGroups) {
-            runCompletionStage("COLOAD_CONSUME", () -> coloadGroups.consumeWholeGroup(group.groupId(),
+            runCompletionStage(taskId, "COLOAD_CONSUME", () -> coloadGroups.consumeWholeGroup(group.groupId(),
                task.getLoadingPlanId(), "PDA-CONSUME-" + hash(command.getOperationId() + '|'
                    + group.groupId()).substring(0, 48), command.getOperatorId(), command.getOperatorName()));
        }
@@ -750,6 +759,14 @@ public class LoadingPickService {
        }
    }

+    /** 检查点失去当前有效租约时立即停止，不再推进后续客户或柜次。 */
+    private void recordCompletionCheckpoint(long commandId, String worker, long tenantId, long inboundId,
+                                            int sequence, String stage) {
+        if (!completionCommands.checkpoint(commandId, worker, tenantId, inboundId, sequence, stage)) {
+            throw new CompletionProcessingException("LEASE_LOST", conflict("装柜完成命令租约已变化"));
+        }
+    }
+
    private static void requireSameCompletionCommand(LoadingCompletionCommandEntity command, long taskId,
                                                     String requestHash, long operatorId) {
        if (command == null || !Long.valueOf(taskId).equals(command.getPickTaskId())
@@ -764,11 +781,18 @@ public class LoadingPickService {
        return checkpoint != null && stages.indexOf(checkpoint) >= stages.indexOf(target);
    }

-    private static void runCompletionStage(String stage, Runnable action) {
+    /** 记录实际阶段耗时，区分业务处理与调度、前端刷新等待。 */
+    private static void runCompletionStage(long taskId, String stage, Runnable action) {
+        long started = System.nanoTime();
+        boolean succeeded = false;
        try {
            action.run();
+            succeeded = true;
        } catch (RuntimeException exception) {
            throw new CompletionProcessingException(stage, exception);
+        } finally {
+            log.info("pda_completion_stage taskId={} stage={} durationMs={} succeeded={}",
+                taskId, stage, (System.nanoTime() - started) / 1_000_000, succeeded);
        }
    }

@@ -9,6 +9,25 @@ import java.util.List;

@Mapper
 public interface ContainerCalendarSourceMapper {
+    /** 按明确来源柜读取与预约日历相同的到港事实，实际到港优先。 */
+    @Select("""
+        <script>
+        SELECT c.id containerBookingId,c.cabinet_no cabinetNo,c.container_no containerNo,
+          c.vessel_name vesselName,c.voyage_no voyageNo,c.destination_port_name destinationPortName,
+          c.destination_warehouse_code destinationWarehouseCode,
+          COALESCE(n.actual_at,c.actual_port_arrival_at,c.estimated_port_arrival_at) arrivalAt,
+          CASE WHEN COALESCE(n.actual_at,c.actual_port_arrival_at) IS NOT NULL THEN 'ACTUAL' ELSE 'ESTIMATED' END arrivalType
+        FROM fl_container_booking c
+        LEFT JOIN fl_carrier_schedule_node_fact n ON n.id=(
+          SELECT f.id FROM fl_carrier_schedule_node_fact f WHERE f.container_booking_id=c.id
+            AND f.standard_node='ARRIVED_DESTINATION_PORT' AND f.actual_at IS NOT NULL
+          ORDER BY f.observed_at DESC,f.id DESC LIMIT 1)
+        WHERE c.record_status='ACTIVE' AND c.id IN
+        <foreach collection='ids' item='id' open='(' separator=',' close=')'>#{id}</foreach>
+        </script>
+        """)
+    List<ContainerCalendarSource> byIds(@Param("ids") List<Long> ids);
+
    /** 同时选出到港、缺日期和可能还柜的有效出仓柜，最终日期由业务服务复核。 */
    @Select("""
        SELECT c.id containerBookingId,c.cabinet_no cabinetNo,c.container_no containerNo,
@@ -11,6 +11,8 @@ public class ContainerCalendarSourceRepository {
    private final ContainerCalendarSourceMapper mapper;
    /** 使用本服务 Mapper 读取日历所需柜级来源。 */
    public ContainerCalendarSourceRepository(ContainerCalendarSourceMapper mapper) { this.mapper = mapper; }
+    /** 内部批量读取明确柜次，日期口径与平台日历一致。 */
+    public List<ContainerCalendarSource> byIds(List<Long> ids) { return mapper.byIds(ids); }
    /** 到港前移两天覆盖默认到仓，直送还柜候选额外留一天覆盖夏令时。 */
    public List<ContainerCalendarSource> sources(LocalDate from, LocalDate to) {
        return mapper.sources(from.atStartOfDay(), from.minusDays(2).atStartOfDay(),