优化

firstleg/src/main/java/com/baiyue/firstleg/loading/mapper/LoadingInboundMapper.java

@@ -11,6 +11,12 @@ public interface LoadingInboundMapper {
         + "FROM fl_inbound_order WHERE tenant_id=#{tenantId} AND id=#{inboundId} AND deleted=0")
     Snapshot find(@Param("tenantId") long tenantId, @Param("inboundId") long inboundId);
 
+    @Update("UPDATE fl_inbound_order SET process_status='LOADING', updated_by=#{operatorId}, "
+        + "version=version+1 WHERE tenant_id=#{tenantId} AND id=#{inboundId} AND deleted=0 "
+        + "AND process_status='WAIT_SPLIT' AND version=#{expectedVersion}")
+    int beginLoading(@Param("tenantId") long tenantId, @Param("inboundId") long inboundId,
+                     @Param("operatorId") long operatorId, @Param("expectedVersion") int expectedVersion);
+
     @Select("""
         SELECT batch.source_inbound_id AS sourceInboundId,
                batch.loaded_child_inbound_id AS loadedChildInboundId,

firstleg/src/main/java/com/baiyue/firstleg/repository/LoadingPickRepository.java

@@ -17,6 +17,7 @@ import com.baiyue.firstleg.entity.LoadingPickAssignmentEntity;
 import com.baiyue.firstleg.entity.LoadingPickOperationEntity;
 import com.baiyue.firstleg.entity.LoadingPickReviewEntity;
 import com.baiyue.firstleg.loading.mapper.InboundLoadingPickTaskMapper;
+import com.baiyue.firstleg.loading.mapper.LoadingInboundMapper;
 import com.baomidou.mybatisplus.core.toolkit.IdWorker;
 import jakarta.annotation.Resource;
 import org.springframework.stereotype.Repository;
@@ -40,6 +41,8 @@ public class LoadingPickRepository {
     private LoadingPickOperationMapper operations;
     @Resource
     private InboundLoadingPickTaskMapper inboundProjections;
+    @Resource
+    private LoadingInboundMapper inbounds;
 
     public LoadingPickTaskEntity task(long taskId) {
         return tasks.selectById(taskId);
@@ -209,6 +212,18 @@ public class LoadingPickRepository {
         return items.selectInboundProgress(tenantId, inboundId);
     }
 
+    public List<LoadingPickItemMapper.InboundOwner> inboundOwners(long taskId) {
+        return items.selectInboundOwners(taskId);
+    }
+
+    public LoadingInboundMapper.Snapshot inbound(long tenantId, long inboundId) {
+        return inbounds.find(tenantId, inboundId);
+    }
+
+    public int beginInboundLoading(long tenantId, long inboundId, long operatorId, int expectedVersion) {
+        return inbounds.beginLoading(tenantId, inboundId, operatorId, expectedVersion);
+    }
+
     public int settlePartial(long planItemId, long pickItemId, int pickedCount, int plannedCount,
                              long operatorId, String operatorName) {
         if (items.settlePartialPlanItem(planItemId, pickedCount, plannedCount,

firstleg/src/main/java/com/baiyue/firstleg/service/LoadingPickService.java

@@ -30,6 +30,9 @@ import com.baiyue.firstleg.entity.LoadingPickReviewEntity;
 import com.baiyue.firstleg.entity.LoadingPickTaskEntity;
 import com.baiyue.firstleg.entity.LoadingPlanItemEntity;
 import com.baiyue.firstleg.entity.LoadingPlanHistoryEntity;
+import com.baiyue.firstleg.entity.InboundStatusHistoryEntity;
+import com.baiyue.firstleg.loading.mapper.LoadingInboundMapper;
+import com.baiyue.firstleg.mapper.InboundStatusHistoryMapper;
 import com.baiyue.firstleg.mapper.LoadingPickItemMapper.CartonLabelRow;
 import com.baiyue.firstleg.repository.LoadingPickRepository;
 import com.baiyue.firstleg.repository.SmartLoadingRepository;
@@ -70,6 +73,8 @@ public class LoadingPickService {
     @Resource
     private LoadingListService loadingListService;
     @Resource
+    private InboundStatusHistoryMapper inboundHistories;
+    @Resource
     private PdaPickSettlementService settlementService;
     @Resource
     private WarehousePalletLocationClient warehouse;
@@ -451,21 +456,53 @@ public class LoadingPickService {
 
     /** 进入PDA拣货任务即将预装柜计划推进为拣货中；状态推进和历史写入保持幂等。 */
     private void startPickingIfNeeded(LoadingPickTaskEntity task, long operatorId, String operatorName) {
-        if (smartLoadingRepository.startPicking(task.getLoadingPlanId(), operatorId, operatorName) != 1) {
-            return;
+        if (smartLoadingRepository.startPicking(task.getLoadingPlanId(), operatorId, operatorName) == 1) {
+            LoadingPlanHistoryEntity history = new LoadingPlanHistoryEntity();
+            history.setLoadingPlanId(task.getLoadingPlanId());
+            history.setOperationId("PDA-START-" + task.getId());
+            history.setActionType("START_LOADING");
+            history.setFromStatus("EDITING");
+            history.setToStatus("LOADING");
+            history.setBeforeSnapshot("{\"source\":\"PDA\"}");
+            history.setAfterSnapshot("{\"source\":\"PDA\",\"status\":\"LOADING\"}");
+            history.setOperatorId(operatorId);
+            history.setOperatorName(operatorName);
+            history.setOperationReason("进入PDA拣货任务");
+            smartLoadingRepository.insert(history);
+        }
+        for (var owner : repository.inboundOwners(task.getId())) {
+            if (owner.tenantId() == null || owner.inboundId() == null) {
+                throw conflict("PDA明细缺少入库单归属");
+            }
+            LoadingInboundMapper.Snapshot inbound = repository.inbound(owner.tenantId(), owner.inboundId());
+            if (inbound == null || inbound.processStatus() == null) {
+                throw conflict("PDA关联入库单不存在");
+            }
+            if ("LOADING".equals(inbound.processStatus())) {
+                continue;
+            }
+            if (!"WAIT_SPLIT".equals(inbound.processStatus()) || inbound.version() == null) {
+                throw conflict("入库单当前状态不能进入装柜阶段");
+            }
+            if (repository.beginInboundLoading(owner.tenantId(), owner.inboundId(), operatorId,
+                inbound.version()) != 1) {
+                LoadingInboundMapper.Snapshot refreshed = repository.inbound(owner.tenantId(), owner.inboundId());
+                if (refreshed == null || !"LOADING".equals(refreshed.processStatus())) {
+                    throw conflict("入库单状态已变化，请刷新后重试");
+                }
+                continue;
+            }
+            InboundStatusHistoryEntity history = new InboundStatusHistoryEntity();
+            history.setTenantId(owner.tenantId());
+            history.setInboundId(owner.inboundId());
+            history.setFromStatus("WAIT_SPLIT");
+            history.setToStatus("LOADING");
+            history.setAction("PDA_START_LOADING");
+            history.setReason("进入PDA拣货任务");
+            history.setOperatorId(operatorId);
+            history.setOperatorName(operatorName);
+            inboundHistories.insert(history);
         }
-        LoadingPlanHistoryEntity history = new LoadingPlanHistoryEntity();
-        history.setLoadingPlanId(task.getLoadingPlanId());
-        history.setOperationId("PDA-START-" + task.getId());
-        history.setActionType("START_LOADING");
-        history.setFromStatus("EDITING");
-        history.setToStatus("LOADING");
-        history.setBeforeSnapshot("{\"source\":\"PDA\"}");
-        history.setAfterSnapshot("{\"source\":\"PDA\",\"status\":\"LOADING\"}");
-        history.setOperatorId(operatorId);
-        history.setOperatorName(operatorName);
-        history.setOperationReason("进入PDA拣货任务");
-        smartLoadingRepository.insert(history);
     }
 
     private LoadingPickTaskEntity requiredTask(long taskId) {

firstleg/src/main/resources/openapi/phase3-loading-delivery-v1.yaml

@@ -6,11 +6,13 @@ paths:
   /api/platform/v1/inbounds/{inboundId}/loading/evidence/pda:
     get:
       summary: List loading evidence for the active PDA worker
+      description: Requires the associated inbound to have entered the loading stage. PDA workflowStatus AWAITING_REVIEW does not bypass this gate; canonical claim or picking advances WAIT_SPLIT to LOADING.
       parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}]
       responses:
         '200': {description: Business envelope; requires platform:firstleg:pda:work}
     post:
       summary: Append one PDA-captured loading evidence photo
+      description: Requires the associated inbound process status to be LOADING. PDA workflowStatus AWAITING_REVIEW is a review projection and does not replace the inbound loading-stage gate.
       parameters: [{$ref: '#/components/parameters/InboundId'}, {$ref: '#/components/parameters/TenantId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody:
         required: true

firstleg/src/main/resources/openapi/phase3-pda-convergence-v1.yaml

@@ -38,6 +38,7 @@ paths:
   /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/claim:
     post:
       summary: Atomically claim an unassigned task for the authenticated operator
+      description: Claiming the canonical PDA task idempotently starts its plan and advances every associated inbound from WAIT_SPLIT to LOADING with optimistic locking; workflowStatus may later become AWAITING_REVIEW while the task remains LOADING until manual completion.
       parameters: [{$ref: '#/components/parameters/TaskId'}]
       requestBody:
         required: true
@@ -66,6 +67,7 @@ paths:
   /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/items/{itemId}/pick:
     post:
       summary: Increment a picked item owned by the authenticated assignee
+      description: The first successful pick also repairs the same WAIT_SPLIT to LOADING transition when the plan was already started, without using containerNo as an association key.
       parameters: [{$ref: '#/components/parameters/TaskId'}, {$ref: '#/components/parameters/ItemId'}]
       responses: {'200': {description: Updated task}}
   /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/items/{itemId}/partial:
@@ -81,6 +83,7 @@ paths:
   /api/platform/v1/first-leg/pda-loading/tasks/{taskId}/batch:
     post:
       summary: Atomically submit the complete online PDA draft once
+      description: A batch containing PICK or PARTIAL idempotently advances associated inbound process status to LOADING before evidence operations become available.
       parameters:
         - {$ref: '#/components/parameters/TaskId'}
         - {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}