优化

firstleg/src/main/java/com/baiyue/firstleg/client/LoadingDocumentFileClient.java

@@ -4,12 +4,21 @@ import com.baiyue.common.core.api.ApiResponse;
 import org.springframework.cloud.openfeign.FeignClient;
 import org.springframework.web.bind.annotation.GetMapping;
 import org.springframework.web.bind.annotation.PathVariable;
+import org.springframework.web.bind.annotation.PostMapping;
 import org.springframework.web.bind.annotation.RequestHeader;
+import org.springframework.web.bind.annotation.RequestPart;
+import org.springframework.web.multipart.MultipartFile;
 
 /** Validates that a referenced File object belongs to the exact loading business resource. */
 @FeignClient(name = "file-service", contextId = "firstlegLoadingDocumentFileClient",
     url = "${baiyue.clients.file.url:}", path = "/internal/file/v1/business-files")
 public interface LoadingDocumentFileClient {
+    @PostMapping(value = "/{tenantId}/{businessType}/{businessId}", consumes = "multipart/form-data")
+    ApiResponse<Metadata> upload(@RequestHeader("X-Internal-Service-Token") String token,
+                                 @RequestHeader("X-Operator-Id") long operatorId,
+                                 @PathVariable long tenantId, @PathVariable String businessType,
+                                 @PathVariable String businessId, @RequestPart("file") MultipartFile file);
+
     @GetMapping("/{tenantId}/{businessType}/{businessId}/{fileId}")
     ApiResponse<Metadata> metadata(@RequestHeader("X-Internal-Service-Token") String token,
                                    @PathVariable long tenantId, @PathVariable String businessType,

firstleg/src/main/java/com/baiyue/firstleg/controller/PlatformContainerController.java

@@ -19,11 +19,15 @@ import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.Resource;
 import jakarta.validation.Valid;
+import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.Positive;
+import jakarta.validation.constraints.Size;
+import org.springframework.http.MediaType;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import org.springframework.validation.annotation.Validated;
 import org.springframework.web.bind.annotation.*;
+import org.springframework.web.multipart.MultipartFile;
 
 @Tag(name = "货柜基础资料") @Validated @RestController
 @RequestMapping("/api/platform/v1/containers")
@@ -87,6 +91,20 @@ public class PlatformContainerController {
             id, user.userId(), user.username(), key, request));
     }
 
+    @PostMapping(value = "/{id}/clearance/document/upload", consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @PreAuthorize("hasAuthority('platform:firstleg:customs:manage')")
+    @Operation(summary = "直接上传或替换货柜目的港清关资料")
+    public ApiResponse<BusinessDocument> uploadClearance(
+        @AuthenticationPrincipal AuthenticatedUser user, @PathVariable @Positive long id,
+        @RequestHeader("Idempotency-Key") String key,
+        @RequestPart("file") MultipartFile file,
+        @RequestPart("expectedVersion") @Min(0) int expectedVersion,
+        @RequestPart(value = "operationReason", required = false) @Size(max = 500) String operationReason) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(loadingLists.uploadContainerClearance(
+            id, user.userId(), user.username(), key, expectedVersion, operationReason, file));
+    }
+
     @PostMapping("/{id}/clearance/complete")
     @PreAuthorize("hasAuthority('platform:firstleg:customs:manage')")
     @Operation(summary = "确认货柜目的港清关完成")

firstleg/src/main/java/com/baiyue/firstleg/controller/PlatformLoadingListController.java

@@ -19,7 +19,10 @@ import io.swagger.v3.oas.annotations.Operation;
 import io.swagger.v3.oas.annotations.tags.Tag;
 import jakarta.annotation.Resource;
 import jakarta.validation.Valid;
+import jakarta.validation.constraints.Min;
 import jakarta.validation.constraints.Positive;
+import jakarta.validation.constraints.Size;
+import org.springframework.http.MediaType;
 import org.springframework.security.access.prepost.PreAuthorize;
 import org.springframework.security.core.annotation.AuthenticationPrincipal;
 import org.springframework.validation.annotation.Validated;
@@ -32,6 +35,8 @@ import org.springframework.web.bind.annotation.RequestHeader;
 import org.springframework.web.bind.annotation.RequestMapping;
 import org.springframework.web.bind.annotation.RequestParam;
 import org.springframework.web.bind.annotation.RestController;
+import org.springframework.web.bind.annotation.RequestPart;
+import org.springframework.web.multipart.MultipartFile;
 
 /** 基于同一装柜计划聚合提供平台预装清单和已确认装柜清单。 */
 @Tag(name = "平台预装与装柜清单", description = "预装单向推进和已确认装柜清单只读查询")
@@ -116,6 +121,21 @@ public class PlatformLoadingListController {
             planId, warehouseId, user.userId(), user.username(), key, request));
     }
 
+    @Operation(summary = "直接上传或替换装柜清单出口报关文档")
+    @PostMapping(value = "/loading-lists/{planId}/customs/document/upload",
+        consumes = MediaType.MULTIPART_FORM_DATA_VALUE)
+    @PreAuthorize("hasAuthority('platform:firstleg:customs:manage')")
+    public ApiResponse<BusinessDocument> uploadDeclaration(
+        @AuthenticationPrincipal AuthenticatedUser user, @PathVariable @Positive long planId,
+        @RequestParam @Positive long warehouseId, @RequestHeader("Idempotency-Key") String key,
+        @RequestPart("file") MultipartFile file,
+        @RequestPart("expectedVersion") @Min(0) int expectedVersion,
+        @RequestPart(value = "operationReason", required = false) @Size(max = 500) String operationReason) {
+        FirstlegScopeGuard.platform(user);
+        return ApiResponse.success(service.uploadLoadingDeclaration(planId, warehouseId,
+            user.userId(), user.username(), key, expectedVersion, operationReason, file));
+    }
+
     @Operation(summary = "确认装柜清单出口报关完成")
     @PostMapping("/loading-lists/{planId}/customs/complete")
     @PreAuthorize("hasAuthority('platform:firstleg:customs:manage')")

firstleg/src/main/java/com/baiyue/firstleg/customs/service/CustomsDispatchGateContributor.java

@@ -1,7 +1,7 @@
 package com.baiyue.firstleg.customs.service;
 
-import com.baiyue.firstleg.customs.entity.CustomsCaseEntity;
-import com.baiyue.firstleg.customs.repository.CustomsRepository;
+import com.baiyue.firstleg.entity.ContainerDocumentEntity;
+import com.baiyue.firstleg.repository.LoadingListRepository;
 import com.baiyue.firstleg.outbound.dispatch.dto.OutboundDispatchDtos.GateItem;
 import com.baiyue.firstleg.outbound.dispatch.gate.OutboundDispatchGateContributor;
 import jakarta.annotation.Resource;
@@ -9,7 +9,7 @@ import org.springframework.stereotype.Component;
 
 @Component
 public class CustomsDispatchGateContributor implements OutboundDispatchGateContributor {
-    @Resource private CustomsRepository repository;
+    @Resource private LoadingListRepository repository;
 
     @Override public String code() { return "CUSTOMS_CLEARANCE"; }
 
@@ -18,13 +18,12 @@ public class CustomsDispatchGateContributor implements OutboundDispatchGateContr
         if (context.tenantId() <= 0 || context.customerId() <= 0) {
             return gate(false, "INVALID_CUSTOMER_SCOPE");
         }
-        CustomsCaseEntity value = repository.gateCase(context.tenantId(), context.orderId(), context.inboundId(),
-            context.containerBookingId());
+        ContainerDocumentEntity value = repository.document(context.containerBookingId(), "CUSTOMS_DECLARATION");
         if (value == null) return gate(false, "MISSING");
-        return gate("CLEARANCE_COMPLETED".equals(value.getStatus()), value.getStatus());
+        return gate(value.getCompletedAt() != null, value.getCompletedAt() == null ? "UPLOADED" : "COMPLETED");
     }
 
     private static GateItem gate(boolean passed, String actual) {
-        return new GateItem("CUSTOMS_CLEARANCE", "报关放行", passed, actual, "CLEARANCE_COMPLETED");
+        return new GateItem("CUSTOMS_CLEARANCE", "报关完成", passed, actual, "COMPLETED");
     }
 }

firstleg/src/main/java/com/baiyue/firstleg/domain/InboundProcessStatus.java

@@ -18,12 +18,9 @@ public final class InboundProcessStatus {
     public static final String FEE_CONFIRMING = "FEE_CONFIRMING";
     /** 费用已确认，正在执行托盘、库位占用和入库收口。 */
     public static final String INBOUNDING = "INBOUNDING";
-    /** 已入库完成，费用已发送给客户。 */
+    /** 历史已入库终态；存量数据仍允许进入分柜。 */
     public static final String INBOUNDED = "INBOUNDED";
-    /**
-     * 历史兼容状态。二、三期已统一使用 {@link #INBOUNDED}，不得再写入或对外返回此值。
-     */
-    @Deprecated(forRemoval = false)
+    /** 入库和费用发布完成，等待分柜。 */
     public static final String WAIT_SPLIT = "WAIT_SPLIT";
     /** 已进入装柜作业，PDA 可执行拣货。 */
     public static final String LOADING = "LOADING";
@@ -36,7 +33,7 @@ public final class InboundProcessStatus {
 
     public static final Set<String> VALUES = Set.of(
         WAIT_MEASURE, MEASURING, MEASURE_PENDING, MEASURE_REJECTED,
-        WAIT_PRICING, FEE_CONFIRMING, INBOUNDING, INBOUNDED,
+        WAIT_PRICING, FEE_CONFIRMING, INBOUNDING, INBOUNDED, WAIT_SPLIT,
         LOADING, LOADED, DELIVERED, VOIDED
     );
 

firstleg/src/main/java/com/baiyue/firstleg/dto/UnifiedInboundQuery.java

@@ -14,7 +14,7 @@ public record UnifiedInboundQuery(
     Long tenantId,
     @Size(max = 64) String keyword,
     @Size(max = 64) String orderNo,
-    @Schema(allowableValues = {"PENDING_REVIEW", "WAIT_MEASURE", "INBOUNDED",
+    @Schema(allowableValues = {"PENDING_REVIEW", "WAIT_MEASURE", "INBOUNDED", "WAIT_SPLIT",
         "LOADING", "LOADED", "DELIVERED"})
     @Size(max = 32) String mainStatus,
     Long customerId,

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

@@ -16,27 +16,16 @@ public interface LoadingCompletionGateMapper {
           COALESCE(SUM(CASE WHEN EXISTS (
             SELECT 1 FROM fl_truck_appointment t
             WHERE t.container_booking_id=p.container_booking_id AND t.loading_plan_id=p.id
-              AND t.status='COMPLETED') THEN 1 ELSE 0 END),0) truckReady,
-          COALESCE(SUM(CASE WHEN EXISTS (
-            SELECT 1 FROM fl_customs_case c
-            JOIN fl_customs_receipt r ON r.customs_case_id=c.id
-            WHERE c.tenant_id=l.tenant_id AND c.inbound_id=l.inbound_id
-              AND c.container_booking_id=p.container_booking_id
-              AND c.status='CLEARANCE_COMPLETED' AND r.receipt_type='RELEASED' AND r.file_id IS NOT NULL
-              AND NOT EXISTS (SELECT 1 FROM fl_customs_receipt newer
-                WHERE newer.submission_batch_id=r.submission_batch_id
-                  AND newer.receipt_type=r.receipt_type AND newer.receipt_version>r.receipt_version))
-            THEN 1 ELSE 0 END),0) customsReady
+              AND t.status='COMPLETED') THEN 1 ELSE 0 END),0) truckReady
         FROM fl_preload_loading_plan_link l
         JOIN fl_loading_plan p ON p.id=l.loading_plan_id
         WHERE l.tenant_id=#{tenantId} AND l.inbound_id=#{inboundId}
         """)
     GateSnapshot snapshot(@Param("tenantId") long tenantId, @Param("inboundId") long inboundId);
 
-    record GateSnapshot(Integer linkCount, Integer oceanReady, Integer truckReady, Integer customsReady) {
+    record GateSnapshot(Integer linkCount, Integer oceanReady, Integer truckReady) {
         public boolean allBookingReady() { return count(linkCount) > 0 && count(linkCount) == count(oceanReady); }
         public boolean allTruckReady() { return count(linkCount) > 0 && count(linkCount) == count(truckReady); }
-        public boolean allCustomsReady() { return count(linkCount) > 0 && count(linkCount) == count(customsReady); }
         private static int count(Integer value) { return value == null ? 0 : value; }
     }
 }

firstleg/src/main/java/com/baiyue/firstleg/loading/service/LoadingCompletionGateService.java

@@ -11,14 +11,13 @@ import org.springframework.stereotype.Service;
 public class LoadingCompletionGateService {
     @Resource private LoadingCompletionGateMapper mapper;
 
-    public void requireBookingTransportAndCustoms(long tenantId, long inboundId) {
+    public void requireBookingAndTransport(long tenantId, long inboundId) {
         LoadingCompletionGateMapper.GateSnapshot gate = mapper.snapshot(tenantId, inboundId);
         if (gate == null || gate.linkCount() == null || gate.linkCount() == 0) {
             throw blocked("未找到有效柜次关联");
         }
         if (!gate.allBookingReady()) throw blocked("订舱尚未完成（必须为 RELEASED）");
         if (!gate.allTruckReady()) throw blocked("拖车尚未完成（必须为 COMPLETED）");
-        if (!gate.allCustomsReady()) throw blocked("缺少有效报关 RELEASED 放行回执");
     }
 
     private static BizException blocked(String message) {

firstleg/src/main/java/com/baiyue/firstleg/loading/service/LoadingDeliveryService.java

@@ -111,7 +111,7 @@ public class LoadingDeliveryService {
         }
         if (!"LOADING".equals(inbound.processStatus())) throw new BizException(ResultCode.CONFLICT, "当前订单不在装柜中");
         loadingModelBridge.requireCompleted(tenantId, inboundId);
-        completionGate.requireBookingTransportAndCustoms(tenantId, inboundId);
+        completionGate.requireBookingAndTransport(tenantId, inboundId);
         requireCompletedPicking(tenantId, inboundId);
         requireCompletionEvidence(tenantId, inboundId);
         if (repository.completeLoading(tenantId, inboundId, operatorId, request.expectedVersion()) != 1) throw concurrent();
@@ -132,7 +132,7 @@ public class LoadingDeliveryService {
             throw new BizException(ResultCode.CONFLICT, "实装履约分片不在装柜中");
         }
         loadingModelBridge.requireCompleted(tenantId, target.sourceInboundId());
-        completionGate.requireBookingTransportAndCustoms(tenantId, target.sourceInboundId());
+        completionGate.requireBookingAndTransport(tenantId, target.sourceInboundId());
         requireCompletedPicking(tenantId, target.sourceInboundId());
         requireCompletionEvidence(tenantId, target.sourceInboundId());
         if (repository.completeLoadedChild(tenantId, target.sourceInboundId(), operatorId,

firstleg/src/main/java/com/baiyue/firstleg/mapper/ContainerBookingMapper.java

@@ -92,6 +92,10 @@ public interface ContainerBookingMapper extends BaseMapper<ContainerBookingEntit
         WHERE id=#{id} AND version=#{expectedVersion}
           AND NOT EXISTS (SELECT 1 FROM fl_loading_plan p
             WHERE p.container_booking_id=fl_container_booking.id AND p.plan_status='COMPLETED')
+          AND (#{containerNo} IS NOT NULL OR NOT EXISTS (
+            SELECT 1 FROM fl_loading_pick_task t
+            JOIN fl_loading_plan p ON p.id=t.loading_plan_id
+            WHERE p.container_booking_id=fl_container_booking.id))
         """)
     int updateTransport(@Param("id") long id, @Param("containerNo") String containerNo,
                         @Param("voyageNo") String voyageNo, @Param("expectedVersion") int expectedVersion,

firstleg/src/main/java/com/baiyue/firstleg/mapper/InboundOrderMapper.java

@@ -11,7 +11,7 @@ import org.apache.ibatis.annotations.Update;
 public interface InboundOrderMapper extends BaseMapper<InboundOrderEntity> {
     @Update("""
         UPDATE fl_inbound_order
-           SET process_status = 'INBOUNDED', measure_review_status = 'APPROVED',
+           SET process_status = 'WAIT_PRICING', measure_review_status = 'APPROVED',
                actual_gross_weight_kg = (SELECT COALESCE(SUM(item.total_weight_kg), 0)
                    FROM fl_inbound_measurement_item item
                   WHERE item.tenant_id = #{tenantId} AND item.measurement_id = #{measurementId}),
@@ -21,7 +21,6 @@ public interface InboundOrderMapper extends BaseMapper<InboundOrderEntity> {
                volume_weight_kg = (SELECT COALESCE(SUM(item.volume_weight_kg), 0)
                    FROM fl_inbound_measurement_item item
                   WHERE item.tenant_id = #{tenantId} AND item.measurement_id = #{measurementId}),
-               inbounded_at = COALESCE(inbounded_at, CURRENT_TIMESTAMP(3)),
                updated_by = #{operatorId}, version = version + 1
          WHERE tenant_id = #{tenantId} AND id = #{inboundId} AND deleted = 0
            AND process_status = 'MEASURE_PENDING' AND measure_review_status = 'PENDING'
@@ -69,7 +68,7 @@ public interface InboundOrderMapper extends BaseMapper<InboundOrderEntity> {
 
     @Update("""
         UPDATE fl_inbound_order
-           SET process_status = 'INBOUNDED', fee_status = 'SENT', notification_status = 'PENDING',
+           SET process_status = 'WAIT_SPLIT', fee_status = 'SENT', notification_status = 'PENDING',
                inbounded_at = CURRENT_TIMESTAMP(3), updated_by = #{operatorId}, version = version + 1
          WHERE tenant_id = #{tenantId} AND id = #{inboundId} AND deleted = 0
            AND process_status = 'INBOUNDING' AND fee_status = 'CONFIRMED'

firstleg/src/main/java/com/baiyue/firstleg/mapper/LoadingListQueryMapper.java

@@ -213,6 +213,8 @@ public interface LoadingListQueryMapper {
                b.updated_by = #{operatorId}, b.updated_by_name = #{operatorName},
                b.updated_at = CURRENT_TIMESTAMP(3), b.version = b.version + 1
          WHERE p.id = #{planId} AND p.plan_status = 'LOADING'
+           AND (#{containerNo} IS NOT NULL OR NOT EXISTS (
+             SELECT 1 FROM fl_loading_pick_task t WHERE t.loading_plan_id = p.id))
         """)
     int updateTransport(@Param("planId") long planId, @Param("containerNo") String containerNo,
                         @Param("voyageNo") String voyageNo, @Param("operatorId") long operatorId,

firstleg/src/main/java/com/baiyue/firstleg/mapper/SmartLoadingCandidateMapper.java

@@ -23,7 +23,7 @@ import com.baiyue.firstleg.dto.SmartLoadingDtos.Candidate; import org.apache.iba
       AND m.id=(SELECT MAX(m2.id) FROM fl_inbound_measurement m2
                  WHERE m2.tenant_id=o.tenant_id AND m2.inbound_id=o.id AND m2.status='APPROVED')
     JOIN fl_inbound_measurement_item i ON i.tenant_id=o.tenant_id AND i.measurement_id=m.id
-   WHERE o.warehouse_id=#{warehouseId} AND o.process_status='INBOUNDED'
+   WHERE o.warehouse_id=#{warehouseId} AND o.process_status IN ('WAIT_SPLIT','INBOUNDED')
      AND (o.inbound_role='MASTER' OR (o.split_purpose='REMAINDER' AND o.split_status='NOT_SPLIT'))
      AND i.inbound_detail_id IS NOT NULL
      AND i.package_count>COALESCE((SELECT SUM(li.package_count) FROM fl_loading_plan_item li
@@ -61,7 +61,7 @@ import com.baiyue.firstleg.dto.SmartLoadingDtos.Candidate; import org.apache.iba
       AND m.id=(SELECT MAX(m2.id) FROM fl_inbound_measurement m2
                  WHERE m2.tenant_id=o.tenant_id AND m2.inbound_id=o.id AND m2.status='APPROVED')
     JOIN fl_inbound_measurement_item i ON i.tenant_id=o.tenant_id AND i.measurement_id=m.id
-   WHERE o.warehouse_id=#{warehouseId} AND o.id=#{inboundId} AND o.process_status='INBOUNDED'
+   WHERE o.warehouse_id=#{warehouseId} AND o.id=#{inboundId} AND o.process_status IN ('WAIT_SPLIT','INBOUNDED')
      AND (o.inbound_role='MASTER' OR (o.split_purpose='REMAINDER' AND o.split_status='NOT_SPLIT'))
      AND i.inbound_detail_id=#{detailId}
    ORDER BY m.id DESC LIMIT 1 FOR UPDATE

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

@@ -209,7 +209,7 @@ public class FbaPricingRepository {
             .eq(InboundPricingEntity::getProcessStatus, processStatus)
             .in(InboundPricingEntity::getFeeStatus, List.of("UNPRICED", "CALCULATED"))
             .set(InboundPricingEntity::getFeeStatus, "CALCULATED");
-        if (!"INBOUNDED".equals(processStatus)) {
+        if (!List.of("WAIT_SPLIT", "INBOUNDED").contains(processStatus)) {
             update.set(InboundPricingEntity::getProcessStatus, "FEE_CONFIRMING");
         }
         if ("KG".equals(chargeMode)) update.set(InboundPricingEntity::getChargeableWeightKg, chargeable);
@@ -229,7 +229,7 @@ public class FbaPricingRepository {
     public int markInboundConfirmed(long tenantId, long inboundId) {
         return inbounds.update(null, new LambdaUpdateWrapper<InboundPricingEntity>()
             .eq(InboundPricingEntity::getTenantId, tenantId).eq(InboundPricingEntity::getId, inboundId)
-            .in(InboundPricingEntity::getProcessStatus, List.of("FEE_CONFIRMING", "INBOUNDED"))
+            .in(InboundPricingEntity::getProcessStatus, List.of("FEE_CONFIRMING", "WAIT_SPLIT", "INBOUNDED"))
             .eq(InboundPricingEntity::getFeeStatus, "CALCULATED")
             .set(InboundPricingEntity::getFeeStatus, "CONFIRMED"));
     }

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

@@ -58,7 +58,8 @@ public class AutomaticInboundCompletionService {
     }
 
     private static boolean completed(InboundOrderEntity order) {
-        return "INBOUNDED".equals(order.getProcessStatus()) && "SENT".equals(order.getFeeStatus());
+        return ("WAIT_SPLIT".equals(order.getProcessStatus()) || "INBOUNDED".equals(order.getProcessStatus()))
+            && "SENT".equals(order.getFeeStatus());
     }
 
     private InboundOrderEntity requireOrder(long tenantId, long inboundId) {

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

@@ -16,6 +16,7 @@ import com.baiyue.firstleg.entity.LoadingPlanEntity;
 import com.baiyue.firstleg.entity.ContainerTransportHistoryEntity;
 import com.baiyue.firstleg.mapper.ContainerTransportHistoryMapper;
 import com.baiyue.firstleg.repository.ContainerRepository;
+import com.baiyue.firstleg.repository.LoadingPickRepository;
 import com.baiyue.firstleg.repository.SmartLoadingRepository;
 import jakarta.annotation.Resource;
 import org.springframework.beans.factory.annotation.Autowired;
@@ -31,6 +32,7 @@ public class ContainerService {
     @Resource private ContainerRepository repository;
     @Resource private WarehouseMasterDataClient warehouses;
     @Resource private SmartLoadingRepository smartLoadingRepository;
+    @Resource private LoadingPickRepository loadingPickRepository;
     @Resource private LoadingPickService loadingPickService;
     @Autowired(required = false) private ContainerTransportHistoryMapper transportHistories;
     @Value("${baiyue.security.internal-service-token:}") private String internalToken;
@@ -86,6 +88,10 @@ public class ContainerService {
         requireVersion(current, request.version());
         if (status(current) == SmartLoadingStatus.COMPLETED) throw conflict("装柜完成后货柜全部只读，不能修改");
         String containerNo = trim(request.containerNo());
+        LoadingPlanEntity plan = smartLoadingRepository.planByBooking(id);
+        if (containerNo == null && plan != null && loadingPickRepository.taskByPlan(plan.getId()) != null) {
+            throw conflict("PDA拣货任务已创建，不能清空真实集装箱号");
+        }
         if (repository.containerNoExists(containerNo, id)) throw conflict("集装箱号已存在");
         try {
             if (repository.updateTransport(id, containerNo, trim(request.voyageNo()), request.version(),

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

@@ -82,8 +82,8 @@ public class FbaPricingService {
             throw conflict("入库单状态已变化，费用试算未保存");
         }
         complete(token, fee.getId(), now);
-        String nextStatus = "INBOUNDED".equals(inbound.getProcessStatus())
-            ? "INBOUNDED" : "FEE_CONFIRMING";
+        String nextStatus = isCompletedInbound(inbound.getProcessStatus())
+            ? inbound.getProcessStatus() : "FEE_CONFIRMING";
         return response(inbound, fee, rate.getUnitPrice(), nextStatus);
     }
 
@@ -114,8 +114,8 @@ public class FbaPricingService {
         String hash = hash("SEND", inboundId, current.getId().toString());
         InboundPricingIdempotencyEntity token = beginIdempotency(
             tenantId, operatorId, inboundId, "FEE_SEND", idempotencyKey, hash);
-        String nextProcessStatus = "INBOUNDED".equals(inbound.getProcessStatus())
-            ? "INBOUNDED" : "WAIT_PALLET";
+        String nextProcessStatus = isCompletedInbound(inbound.getProcessStatus())
+            ? inbound.getProcessStatus() : "WAIT_PALLET";
         if ("COMPLETED".equals(token.getStatus())) {
             feeDetails.publishFreight(tenantId, inboundId, token.getResultResourceId(),
                 operatorId, null, LocalDateTime.now(clock));
@@ -144,7 +144,7 @@ public class FbaPricingService {
                                                AdjustFeeRequest request, String idempotencyKey) {
         InboundPricingEntity inbound = repository.findInbound(tenantId, inboundId);
         if (inbound == null) throw new BizException(ResultCode.NOT_FOUND, "入库单不存在");
-        if (!"INBOUNDED".equals(inbound.getProcessStatus()) || !"SENT".equals(inbound.getFeeStatus())) {
+        if (!isCompletedInbound(inbound.getProcessStatus()) || !"SENT".equals(inbound.getFeeStatus())) {
             throw conflict("只能修改已完成入库且已发布的费用");
         }
         InboundFeeEntity current = repository.findLatestFee(tenantId, inboundId);
@@ -156,7 +156,7 @@ public class FbaPricingService {
         InboundPricingIdempotencyEntity token = beginIdempotency(tenantId, operatorId, inboundId,
             "FEE_ADJUST", idempotencyKey, hash("ADJUST", inboundId, discriminator));
         if ("COMPLETED".equals(token.getStatus())) {
-            return response(tenantId, token.getResultResourceId(), "INBOUNDED");
+            return response(tenantId, token.getResultResourceId(), inbound.getProcessStatus());
         }
 
         LocalDateTime now = LocalDateTime.now(clock);
@@ -204,12 +204,12 @@ public class FbaPricingService {
         financeOutbox.publishInbound(FinanceFeeSourceOutboxService.ADJUSTED,
             tenantId, inboundId, adjusted.getId(), nextVersion, now);
         complete(token, adjusted.getId(), now);
-        return response(tenantId, adjusted.getId(), "INBOUNDED");
+        return response(tenantId, adjusted.getId(), inbound.getProcessStatus());
     }
 
     private InboundPricingEntity requireEligibleInbound(long tenantId, long inboundId) {
         InboundPricingEntity inbound = requireApprovedInbound(tenantId, inboundId);
-        if (!List.of("WAIT_PRICING", "FEE_CONFIRMING", "INBOUNDED").contains(inbound.getProcessStatus())
+        if (!List.of("WAIT_PRICING", "FEE_CONFIRMING", "WAIT_SPLIT", "INBOUNDED").contains(inbound.getProcessStatus())
             || !List.of("UNPRICED", "CALCULATED").contains(inbound.getFeeStatus())) {
             throw conflict("当前入库单状态不允许费用试算");
         }
@@ -234,6 +234,10 @@ public class FbaPricingService {
         return inbound;
     }
 
+    private static boolean isCompletedInbound(String processStatus) {
+        return "WAIT_SPLIT".equals(processStatus) || "INBOUNDED".equals(processStatus);
+    }
+
     private static PricingDestinationType destinationType(InboundPricingEntity inbound) {
         try {
             return PricingDestinationType.valueOf(inbound.getDestinationType());

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

@@ -93,7 +93,7 @@ public class InboundCompletionOrchestrator {
         var published = feeDetails.publishFreight(tenantId, inboundId, feeId, operatorId,
             operatorName, LocalDateTime.now());
         repository.insertHistory(MeasurementReviewService.history(tenantId, inboundId,
-            "INBOUNDING", "INBOUNDED", "SEND_FEE_COMPLETE", null, operatorId, operatorName));
+            "INBOUNDING", "WAIT_SPLIT", "SEND_FEE_COMPLETE", null, operatorId, operatorName));
         financeOutbox.publishInbound(FinanceFeeSourceOutboxService.PUBLISHED, tenantId,
             inboundId, feeId, published.getSourceFeeVersion(), LocalDateTime.now());
         idempotency.complete(context, inboundId);

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

@@ -30,6 +30,7 @@ import org.springframework.dao.DuplicateKeyException;
 import org.springframework.stereotype.Service;
 import org.springframework.transaction.annotation.Transactional;
 import org.springframework.util.StringUtils;
+import org.springframework.web.multipart.MultipartFile;
 
 import java.nio.charset.StandardCharsets;
 import java.security.MessageDigest;
@@ -103,7 +104,18 @@ public class LoadingListService {
                                                       String key, DocumentAttachRequest request) {
         AggregateRow plan = requireBookingPlan(bookingId);
         return attachDocument(plan, DESTINATION_CLEARANCE, CLEARANCE_FILE_TYPE,
-            Long.toString(bookingId), operatorId, operatorName, key, request);
+            bookingId, Long.toString(bookingId), operatorId, operatorName, key, request);
+    }
+
+    @Transactional
+    @BusinessAudit(event = "CONTAINER_CLEARANCE_DOCUMENT_UPLOAD", resourceType = "CONTAINER",
+        resourceId = "#bookingId", description = "直接上传目的港清关资料")
+    public BusinessDocument uploadContainerClearance(long bookingId, long operatorId, String operatorName,
+                                                       String key, int expectedVersion, String operationReason,
+                                                       MultipartFile file) {
+        AggregateRow plan = requireBookingPlan(bookingId);
+        return uploadDocument(plan, DESTINATION_CLEARANCE, CLEARANCE_FILE_TYPE, bookingId,
+            Long.toString(bookingId), operatorId, operatorName, key, expectedVersion, operationReason, file);
     }
 
     @Transactional
@@ -111,7 +123,7 @@ public class LoadingListService {
         resourceId = "#bookingId", description = "确认目的港清关完成")
     public BusinessDocument completeContainerClearance(long bookingId, long operatorId, String operatorName,
                                                         String key, DocumentCompleteRequest request) {
-        return completeDocument(requireBookingPlan(bookingId), DESTINATION_CLEARANCE,
+        return completeDocument(requireBookingPlan(bookingId), DESTINATION_CLEARANCE, bookingId,
             operatorId, operatorName, key, request);
     }
 
@@ -132,7 +144,20 @@ public class LoadingListService {
         requireWarehouse(plan, warehouseId);
         requireCompletedPlan(plan);
         return attachDocument(plan, CUSTOMS_DECLARATION, DECLARATION_FILE_TYPE,
-            Long.toString(planId), operatorId, operatorName, key, request);
+            planId, Long.toString(planId), operatorId, operatorName, key, request);
+    }
+
+    @Transactional
+    @BusinessAudit(event = "LOADING_CUSTOMS_DOCUMENT_UPLOAD", resourceType = "LOADING_PLAN",
+        resourceId = "#planId", description = "直接上传出口报关文档")
+    public BusinessDocument uploadLoadingDeclaration(long planId, long warehouseId, long operatorId,
+                                                       String operatorName, String key, int expectedVersion,
+                                                       String operationReason, MultipartFile file) {
+        AggregateRow plan = requirePlan(planId);
+        requireWarehouse(plan, warehouseId);
+        requireCompletedPlan(plan);
+        return uploadDocument(plan, CUSTOMS_DECLARATION, DECLARATION_FILE_TYPE, planId,
+            Long.toString(planId), operatorId, operatorName, key, expectedVersion, operationReason, file);
     }
 
     @Transactional
@@ -144,28 +169,55 @@ public class LoadingListService {
         AggregateRow plan = requirePlan(planId);
         requireWarehouse(plan, warehouseId);
         requireCompletedPlan(plan);
-        return completeDocument(plan, CUSTOMS_DECLARATION, operatorId, operatorName, key, request);
+        return completeDocument(plan, CUSTOMS_DECLARATION, planId, operatorId, operatorName, key, request);
     }
 
     private BusinessDocument attachDocument(AggregateRow plan, String documentType, String businessType,
-                                              String businessId, long operatorId, String operatorName,
+                                              long identityId, String businessId, long operatorId, String operatorName,
                                               String key, DocumentAttachRequest request) {
-        String requestHash = sha256("ATTACH|" + documentType + '|' + plan.getPlanId() + '|'
+        String requestHash = sha256("ATTACH|" + documentType + '|' + identityId + '|'
             + request.fileId() + '|' + request.expectedVersion() + '|' + trim(request.operationReason()));
-        String operationId = operationId("ATTACH_" + documentType, plan.getPlanId(), key);
+        String operationId = operationId("ATTACH_" + documentType, identityId, key);
         HistoryRow replay = repository.history(operationId);
         if (replay != null) {
             requireSameRequest(replay, requestHash);
             return requireDocument(plan.getContainerBookingId(), documentType);
         }
         ContainerDocumentEntity current = repository.document(plan.getContainerBookingId(), documentType);
-        if (current == null && request.expectedVersion() != 0) throw conflict("资料版本已变化，请刷新后重试");
-        if (current != null && !java.util.Objects.equals(current.getVersion(), request.expectedVersion())) {
-            throw conflict("资料版本已变化，请刷新后重试");
-        }
-        if (current != null && current.getCompletedAt() != null) throw conflict("已完成的资料不可替换");
+        requireReplaceableDocument(current, request.expectedVersion());
         LoadingDocumentFileClient.Metadata metadata = validateDocumentFile(
             businessType, businessId, request.fileId());
+        return persistDocument(plan, documentType, current, metadata, operatorId, operatorName,
+            operationId, "ATTACH_" + documentType, requestHash, request.operationReason());
+    }
+
+    private BusinessDocument uploadDocument(AggregateRow plan, String documentType, String businessType,
+                                              long identityId, String businessId, long operatorId,
+                                              String operatorName, String key, int expectedVersion,
+                                              String operationReason, MultipartFile file) {
+        requireUploadFile(file);
+        String fileHash = multipartHash(file);
+        String requestHash = sha256("UPLOAD|" + documentType + '|' + identityId + '|'
+            + expectedVersion + '|' + trim(operationReason) + '|' + fileHash);
+        String operationId = operationId("UPLOAD_" + documentType, identityId, key);
+        HistoryRow replay = repository.history(operationId);
+        if (replay != null) {
+            requireSameRequest(replay, requestHash);
+            return requireDocument(plan.getContainerBookingId(), documentType);
+        }
+        ContainerDocumentEntity current = repository.document(plan.getContainerBookingId(), documentType);
+        requireReplaceableDocument(current, expectedVersion);
+        LoadingDocumentFileClient.Metadata metadata = uploadDocumentFile(
+            businessType, businessId, operatorId, file, fileHash);
+        return persistDocument(plan, documentType, current, metadata, operatorId, operatorName,
+            operationId, "UPLOAD_" + documentType, requestHash, operationReason);
+    }
+
+    private BusinessDocument persistDocument(AggregateRow plan, String documentType,
+                                               ContainerDocumentEntity current,
+                                               LoadingDocumentFileClient.Metadata metadata,
+                                               long operatorId, String operatorName, String operationId,
+                                               String actionType, String requestHash, String operationReason) {
         Map<String, Object> beforeSnapshot = documentSnapshot(current);
         ContainerDocumentEntity value = current == null ? new ContainerDocumentEntity() : current;
         if (current == null) value.setId(IdWorker.getId());
@@ -179,19 +231,19 @@ public class LoadingListService {
             throw conflict("资料已被其他操作上传，请刷新后重试");
         }
         ContainerDocumentEntity saved = requireDocumentEntity(plan.getContainerBookingId(), documentType);
-        repository.appendHistory(plan.getPlanId(), operationId, "ATTACH_" + documentType,
+        repository.appendHistory(plan.getPlanId(), operationId, actionType,
             plan.getPlanStatus(), plan.getPlanStatus(), json(beforeSnapshot),
             json(values("requestHash", requestHash, "document", documentSnapshot(saved))),
-            operatorId, trim(operatorName), trim(request.operationReason()));
+            operatorId, trim(operatorName), trim(operationReason));
         return document(saved);
     }
 
-    private BusinessDocument completeDocument(AggregateRow plan, String documentType, long operatorId,
+    private BusinessDocument completeDocument(AggregateRow plan, String documentType, long identityId, long operatorId,
                                                 String operatorName, String key,
                                                 DocumentCompleteRequest request) {
-        String requestHash = sha256("COMPLETE|" + documentType + '|' + plan.getPlanId() + '|'
+        String requestHash = sha256("COMPLETE|" + documentType + '|' + identityId + '|'
             + request.expectedVersion() + '|' + trim(request.operationReason()));
-        String operationId = operationId("COMPLETE_" + documentType, plan.getPlanId(), key);
+        String operationId = operationId("COMPLETE_" + documentType, identityId, key);
         HistoryRow replay = repository.history(operationId);
         if (replay != null) {
             requireSameRequest(replay, requestHash);
@@ -224,7 +276,8 @@ public class LoadingListService {
                 || !businessType.equals(response.data().businessType())
                 || !businessId.equals(response.data().businessId())
                 || !StringUtils.hasText(response.data().fileName())
-                || !StringUtils.hasText(response.data().sha256())) {
+                || response.data().sha256() == null
+                || !response.data().sha256().matches("[0-9a-fA-F]{64}")) {
                 throw badRequest("附件不存在、归属不匹配或文件元数据不完整");
             }
             return response.data();
@@ -233,6 +286,48 @@ public class LoadingListService {
         }
     }
 
+    private LoadingDocumentFileClient.Metadata uploadDocumentFile(String businessType, String businessId,
+                                                                    long operatorId, MultipartFile file,
+                                                                    String expectedHash) {
+        try {
+            var uploaded = documentFiles.upload(internalToken, operatorId, 0, businessType, businessId, file);
+            if (uploaded == null || !uploaded.successful() || uploaded.data() == null
+                || uploaded.data().fileId() == null || uploaded.data().fileId() <= 0) {
+                throw badRequest("附件上传失败");
+            }
+            LoadingDocumentFileClient.Metadata metadata = validateDocumentFile(
+                businessType, businessId, uploaded.data().fileId());
+            if (!expectedHash.equalsIgnoreCase(metadata.sha256())) {
+                throw badRequest("附件内容哈希校验失败");
+            }
+            return metadata;
+        } catch (FeignException exception) {
+            throw new BizException(ResultCode.SERVICE_UNAVAILABLE, "文件服务暂不可用");
+        }
+    }
+
+    private static void requireReplaceableDocument(ContainerDocumentEntity current, int expectedVersion) {
+        if (current == null && expectedVersion != 0) throw conflict("资料版本已变化，请刷新后重试");
+        if (current != null && !java.util.Objects.equals(current.getVersion(), expectedVersion)) {
+            throw conflict("资料版本已变化，请刷新后重试");
+        }
+        if (current != null && current.getCompletedAt() != null) throw conflict("已完成的资料不可替换");
+    }
+
+    private static void requireUploadFile(MultipartFile file) {
+        if (file == null || file.isEmpty()) throw badRequest("必须选择上传文件");
+    }
+
+    private static String multipartHash(MultipartFile file) {
+        try {
+            return HexFormat.of().formatHex(MessageDigest.getInstance("SHA-256").digest(file.getBytes()));
+        } catch (java.io.IOException exception) {
+            throw badRequest("读取上传文件失败");
+        } catch (NoSuchAlgorithmException exception) {
+            throw new IllegalStateException(exception);
+        }
+    }
+
     private AggregateRow requireBookingPlan(long bookingId) {
         AggregateRow row = repository.aggregateByBooking(bookingId);
         if (row == null) throw notFound("货柜或关联装柜计划不存在");
@@ -286,6 +381,9 @@ public class LoadingListService {
         }
 
         requireLoadingMutable(before);
+        if (containerNo == null && pickRepository.taskByPlan(planId) != null) {
+            throw conflict("PDA拣货任务已创建，不能清空真实集装箱号");
+        }
         if (repository.updateTransport(planId, request.expectedVersion(), containerNo, voyageNo,
             operatorId, trim(operatorName)) != 1) {
             throw conflict("预装计划已被其他操作修改，请刷新后重试");

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

@@ -21,8 +21,7 @@ import java.time.LocalDateTime;
 import java.math.BigDecimal;
 
 /**
- * 测量审核应用服务。客服确认测量数据后将入库单推进到产品主状态 INBOUNDED；
- * 计费、库位和其他资料不作为本版本的强制门禁。
+ * 测量审核应用服务。审核通过后进入内部计费编排，完成费用发布和入库后再进入 WAIT_SPLIT。
  */
 @Service
 public class MeasurementReviewService {
@@ -100,7 +99,7 @@ public class MeasurementReviewService {
         repository.insertReview(reviewRecord(tenantId, inboundId, request.measurementId(), result,
             request.reason(), false, null, false, operatorId, operatorName));
         repository.insertHistory(history(tenantId, inboundId, "MEASURE_PENDING",
-            approved ? "INBOUNDED" : "MEASURE_REJECTED",
+            approved ? "WAIT_PRICING" : "MEASURE_REJECTED",
             approved ? "MEASURE_APPROVE" : "MEASURE_REJECT", request.reason(), operatorId, operatorName));
         idempotency.complete(context, inboundId);
     }

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

@@ -28,9 +28,7 @@ import java.util.stream.Collectors;
 @Service
 public class UnifiedInboundQueryService {
     private static final Set<String> MAIN_STATUSES = Set.of(
-        "PENDING_REVIEW", "WAIT_MEASURE", "INBOUNDED", "LOADING", "LOADED", "DELIVERED");
-    /** 仅兼容旧客户端筛选值，响应和 OpenAPI 均只使用 INBOUNDED。 */
-    private static final String LEGACY_WAIT_SPLIT = "WAIT_SPLIT";
+        "PENDING_REVIEW", "WAIT_MEASURE", "INBOUNDED", "WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED");
     private static final Set<String> REVIEW_STATUSES = Set.of("UNRECORDED", "PENDING", "APPROVED", "REJECTED");
 
     @Resource private InboundOrderRepository inbounds;
@@ -140,9 +138,9 @@ public class UnifiedInboundQueryService {
     static String mainStatus(String status) {
         if (status == null) return null;
         return switch (status) {
-            case "WAIT_MEASURE", "MEASURING", "MEASURE_PENDING", "MEASURE_REJECTED" -> "WAIT_MEASURE";
-            case "WAIT_PRICING", "FEE_CONFIRMING", "INBOUNDING", "INBOUNDED", LEGACY_WAIT_SPLIT -> "INBOUNDED";
-            case "LOADING", "LOADED", "DELIVERED" -> status;
+            case "WAIT_MEASURE", "MEASURING", "MEASURE_PENDING", "MEASURE_REJECTED",
+                 "WAIT_PRICING", "FEE_CONFIRMING", "INBOUNDING" -> "WAIT_MEASURE";
+            case "INBOUNDED", "WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED" -> status;
             default -> null;
         };
     }
@@ -152,7 +150,7 @@ public class UnifiedInboundQueryService {
         return switch (mainStatus) {
             case "PENDING_REVIEW" -> "APPROVE_ORDER";
             case "WAIT_MEASURE" -> "MEASURE_PENDING".equals(processStatus) ? "CONFIRM_MEASUREMENT" : null;
-            case "INBOUNDED" -> !("INBOUNDED".equals(processStatus) || LEGACY_WAIT_SPLIT.equals(processStatus)) ? null
+            case "INBOUNDED", "WAIT_SPLIT" -> !("INBOUNDED".equals(processStatus) || "WAIT_SPLIT".equals(processStatus)) ? null
                 : "CONFIRMED".equals(preloadStatus) ? null
                 : preloadStatus == null ? "SMART_SPLIT" : "CONFIRM_PRELOAD";
             case "LOADING" -> "COMPLETE_LOADING";
@@ -169,8 +167,10 @@ public class UnifiedInboundQueryService {
     private List<String> internalStatuses(String mainStatus) {
         if (!StringUtils.hasText(mainStatus)) return List.of();
         return switch (mainStatus) {
-            case "WAIT_MEASURE" -> List.of("WAIT_MEASURE", "MEASURING", "MEASURE_PENDING", "MEASURE_REJECTED");
-            case "INBOUNDED", LEGACY_WAIT_SPLIT -> List.of("WAIT_PRICING", "FEE_CONFIRMING", "INBOUNDING", "INBOUNDED", LEGACY_WAIT_SPLIT);
+            case "WAIT_MEASURE" -> List.of("WAIT_MEASURE", "MEASURING", "MEASURE_PENDING", "MEASURE_REJECTED",
+                "WAIT_PRICING", "FEE_CONFIRMING", "INBOUNDING");
+            case "INBOUNDED" -> List.of("INBOUNDED");
+            case "WAIT_SPLIT" -> List.of("WAIT_SPLIT");
             case "LOADING", "LOADED", "DELIVERED" -> List.of(mainStatus);
             default -> List.of("__NO_MATCH__");
         };
@@ -189,7 +189,7 @@ public class UnifiedInboundQueryService {
     private void validate(UnifiedInboundQuery query) {
         if (StringUtils.hasText(query.mainStatus())
             && !MAIN_STATUSES.contains(query.mainStatus())
-            && !LEGACY_WAIT_SPLIT.equals(query.mainStatus())) {
+            ) {
             throw new com.baiyue.common.core.exception.BizException(
                 com.baiyue.common.core.api.ResultCode.BAD_REQUEST, "统一订单主状态不合法");
         }

firstleg/src/main/java/com/baiyue/firstleg/split/mapper/SplitInboundMapper.java

@@ -13,7 +13,7 @@ public interface SplitInboundMapper {
 
     @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='INBOUNDED' AND version=#{expectedVersion}")
+        + "AND process_status IN ('WAIT_SPLIT','INBOUNDED') AND version=#{expectedVersion}")
     int beginLoading(@Param("tenantId") long tenantId, @Param("inboundId") long inboundId,
                      @Param("operatorId") long operatorId, @Param("expectedVersion") int expectedVersion);
 

firstleg/src/main/java/com/baiyue/firstleg/split/service/SplitPreloadService.java

@@ -44,7 +44,7 @@ public class SplitPreloadService {
         SplitActionResponse replay = claimOrReplay(tenantId, inboundId, operatorId, SMART_SPLIT, key);
         if (replay != null) return replay;
         InboundSnapshot inbound = requireInbound(tenantId, inboundId);
-        if (!"INBOUNDED".equals(inbound.processStatus())) {
+        if (!isWaitingSplit(inbound.processStatus())) {
             throw new BizException(ResultCode.CONFLICT, "仅待分柜订单可以生成预装清单");
         }
         PreloadPlanEntity plan = repository.findPlan(tenantId, inboundId);
@@ -69,7 +69,7 @@ public class SplitPreloadService {
         }
         PreloadPlanResponse result = response(repository.findPlan(tenantId, inboundId));
         return complete(tenantId, inboundId, operatorId, SMART_SPLIT, key,
-            new SplitActionResponse("INBOUNDED", result));
+            new SplitActionResponse("WAIT_SPLIT", result));
     }
 
     @Transactional
@@ -85,12 +85,12 @@ public class SplitPreloadService {
             // confirmation is submitted; retain the linked-container hard gate.
             loadingModelBridge.requireStarted(tenantId, inboundId);
         } else {
-            requireStatus(inbound, "INBOUNDED", "仅待分柜订单可以提交预装清单确认");
+            requireWaitingSplit(inbound, "仅待分柜订单可以提交预装清单确认");
         }
         PreloadPlanEntity plan = requirePlan(tenantId, inboundId);
         if (PreloadStatus.CONFIRMING.equals(plan.getStatus())) {
             return complete(tenantId, inboundId, operatorId, START_CONFIRMING, key,
-                new SplitActionResponse(loading ? "LOADING" : "INBOUNDED", response(plan)));
+                new SplitActionResponse(loading ? "LOADING" : "WAIT_SPLIT", response(plan)));
         }
         if (!PreloadStatus.PENDING.equals(plan.getStatus())
             || repository.changePlanStatus(tenantId, inboundId, PreloadStatus.PENDING,
@@ -98,7 +98,7 @@ public class SplitPreloadService {
             throw concurrent();
         }
         return complete(tenantId, inboundId, operatorId, START_CONFIRMING, key,
-            new SplitActionResponse(loading ? "LOADING" : "INBOUNDED",
+            new SplitActionResponse(loading ? "LOADING" : "WAIT_SPLIT",
                 response(repository.findPlan(tenantId, inboundId))));
     }
 
@@ -114,7 +114,7 @@ public class SplitPreloadService {
             return complete(tenantId, inboundId, operatorId, CONFIRM_PRELOAD, key,
                 new SplitActionResponse("LOADING", response(repository.findPlan(tenantId, inboundId))));
         }
-        requireStatus(inbound, "INBOUNDED", "仅待分柜订单可以确认预装清单");
+        requireWaitingSplit(inbound, "仅待分柜订单可以确认预装清单");
         PreloadPlanEntity plan = requirePlan(tenantId, inboundId);
         if (PreloadStatus.CONFIRMED.equals(plan.getStatus())) {
             throw new BizException(ResultCode.CONFLICT, "预装清单已确认但订单状态尚未推进，请刷新重试");
@@ -127,7 +127,7 @@ public class SplitPreloadService {
         if (repository.beginLoading(tenantId, inboundId, operatorId, inbound.version()) != 1) {
             throw concurrent();
         }
-        addHistory(tenantId, inboundId, "INBOUNDED", "LOADING", CONFIRM_PRELOAD,
+        addHistory(tenantId, inboundId, inbound.processStatus(), "LOADING", CONFIRM_PRELOAD,
             operatorId, operatorName);
         return complete(tenantId, inboundId, operatorId, CONFIRM_PRELOAD, key,
             new SplitActionResponse("LOADING", response(repository.findPlan(tenantId, inboundId))));
@@ -172,8 +172,12 @@ public class SplitPreloadService {
         return plan;
     }
 
-    private static void requireStatus(InboundSnapshot inbound, String expected, String message) {
-        if (!expected.equals(inbound.processStatus())) throw new BizException(ResultCode.CONFLICT, message);
+    private static void requireWaitingSplit(InboundSnapshot inbound, String message) {
+        if (!isWaitingSplit(inbound.processStatus())) throw new BizException(ResultCode.CONFLICT, message);
+    }
+
+    private static boolean isWaitingSplit(String status) {
+        return "WAIT_SPLIT".equals(status) || "INBOUNDED".equals(status);
     }
 
     private void addHistory(long tenantId, long inboundId, String from, String to, String action,

firstleg/src/main/resources/db/phase3-inbounded-status-unification.sql

@@ -1,4 +1,4 @@
--- 二、三期对外统一使用 INBOUNDED。历史 WAIT_SPLIT 仅由查询适配为 INBOUNDED，
+-- 新完成入库记录使用 WAIT_SPLIT，存量 INBOUNDED 继续作为可分柜兼容状态。
 -- 本脚本不改写业务主表或历史状态，避免影响既有审计记录。
 USE baiyue_firstleg;
 
@@ -13,7 +13,7 @@ BEGIN
           WHERE table_schema = 'baiyue_firstleg' AND table_name = 'fl_inbound_status_history'
             AND column_name IN ('from_status', 'to_status')) <> 2 THEN
     SIGNAL SQLSTATE '45000'
-      SET MESSAGE_TEXT = 'INBOUNDED 兼容校验失败：入库状态字段不完整';
+      SET MESSAGE_TEXT = 'WAIT_SPLIT/INBOUNDED 兼容校验失败：入库状态字段不完整';
   END IF;
 END$$
 DELIMITER ;

firstleg/src/main/resources/db/phase3-simple-customs-document-migration.sql

@@ -28,6 +28,43 @@ PREPARE statement FROM @ddl; EXECUTE statement; DEALLOCATE PREPARE statement;
 ALTER TABLE fl_container_document ADD CONSTRAINT chk_container_document_type
   CHECK (document_type IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION', 'DELIVERY_ORDER', 'PICKUP_ORDER'));
 
+-- Keep the container master immutable after loading; only the two document rows remain operable.
+DROP TRIGGER IF EXISTS trg_container_booking_before_update;
+DELIMITER $$
+CREATE TRIGGER trg_container_booking_before_update BEFORE UPDATE ON fl_container_booking FOR EACH ROW
+BEGIN
+  DECLARE current_plan_status VARCHAR(24);
+  SELECT MAX(plan_status) INTO current_plan_status FROM fl_loading_plan WHERE container_booking_id=OLD.id;
+  IF current_plan_status='COMPLETED' THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='装柜完成后货柜全部只读，不允许修改';
+  END IF;
+  IF current_plan_status='LOADING' AND (
+       NOT (OLD.id <=> NEW.id) OR NOT (OLD.booking_no <=> NEW.booking_no)
+    OR NOT (OLD.cabinet_no <=> NEW.cabinet_no) OR NOT (OLD.channel_code <=> NEW.channel_code)
+    OR NOT (OLD.channel_name <=> NEW.channel_name) OR NOT (OLD.ocean_booking_id <=> NEW.ocean_booking_id)
+    OR NOT (OLD.ocean_booking_requirement_id <=> NEW.ocean_booking_requirement_id)
+    OR NOT (OLD.warehouse_id <=> NEW.warehouse_id) OR NOT (OLD.warehouse_name <=> NEW.warehouse_name)
+    OR NOT (OLD.bill_of_lading_no <=> NEW.bill_of_lading_no) OR NOT (OLD.vessel_name <=> NEW.vessel_name)
+    OR NOT (OLD.container_type <=> NEW.container_type) OR NOT (OLD.shipping_company_id <=> NEW.shipping_company_id)
+    OR NOT (OLD.shipping_company_name <=> NEW.shipping_company_name)
+    OR NOT (OLD.departure_port_code <=> NEW.departure_port_code) OR NOT (OLD.departure_port_name <=> NEW.departure_port_name)
+    OR NOT (OLD.destination_port_code <=> NEW.destination_port_code) OR NOT (OLD.destination_port_name <=> NEW.destination_port_name)
+    OR NOT (OLD.destination_warehouse_code <=> NEW.destination_warehouse_code)
+    OR NOT (OLD.destination_warehouse_name <=> NEW.destination_warehouse_name)
+    OR NOT (OLD.capacity_cbm <=> NEW.capacity_cbm) OR NOT (OLD.max_weight_kg <=> NEW.max_weight_kg)
+    OR NOT (OLD.terminal_trucking_company <=> NEW.terminal_trucking_company) OR NOT (OLD.loading_at <=> NEW.loading_at)
+    OR NOT (OLD.estimated_sailing_at <=> NEW.estimated_sailing_at) OR NOT (OLD.actual_sailing_at <=> NEW.actual_sailing_at)
+    OR NOT (OLD.estimated_port_arrival_at <=> NEW.estimated_port_arrival_at)
+    OR NOT (OLD.actual_port_arrival_at <=> NEW.actual_port_arrival_at)
+    OR NOT (OLD.estimated_warehouse_arrival_at <=> NEW.estimated_warehouse_arrival_at)
+    OR NOT (OLD.actual_warehouse_arrival_at <=> NEW.actual_warehouse_arrival_at)
+    OR NOT (OLD.created_by <=> NEW.created_by) OR NOT (OLD.created_by_name <=> NEW.created_by_name)
+    OR NOT (OLD.created_at <=> NEW.created_at)) THEN
+    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT='装柜中仅允许修改集装箱号与航次';
+  END IF;
+END$$
+DELIMITER ;
+
 DROP TRIGGER IF EXISTS trg_container_document_before_insert;
 DELIMITER $$
 CREATE TRIGGER trg_container_document_before_insert BEFORE INSERT ON fl_container_document FOR EACH ROW

firstleg/src/main/resources/db/phase3-smart-loading-schema.sql

@@ -562,8 +562,7 @@ BEGIN
   DECLARE current_plan_status VARCHAR(24);
   SELECT MAX(plan_status) INTO current_plan_status
     FROM fl_loading_plan WHERE container_booking_id = OLD.id;
-  IF current_plan_status = 'COMPLETED'
-     AND NEW.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION') THEN
+  IF current_plan_status = 'COMPLETED' THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '装柜完成后货柜全部只读，不允许修改';
   END IF;
   IF current_plan_status = 'LOADING' AND (
@@ -927,7 +926,7 @@ BEGIN
   SELECT MAX(plan_status) INTO current_plan_status FROM fl_loading_plan
    WHERE container_booking_id = NEW.container_booking_id;
   IF current_plan_status = 'COMPLETED'
-     AND OLD.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION') THEN
+     AND NEW.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION') THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '装柜完成后货柜文件不可新增';
   END IF;
 END$$
@@ -942,7 +941,8 @@ BEGIN
   DECLARE current_plan_status VARCHAR(24);
   SELECT MAX(plan_status) INTO current_plan_status FROM fl_loading_plan
    WHERE container_booking_id = OLD.container_booking_id;
-  IF current_plan_status = 'COMPLETED' THEN
+  IF current_plan_status = 'COMPLETED'
+     AND OLD.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION') THEN
     SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '装柜完成后货柜文件不可修改';
   END IF;
 END$$

firstleg/src/main/resources/openapi/firstleg-v1.yaml

@@ -68,8 +68,8 @@ paths:
     post:
       summary: 按统一订单条件分页查询履约摘要（Order 内部）
       description: >-
-        mainStatus 接受六态产品状态；历史 WAIT_SPLIT 仅作为兼容筛选值，按 INBOUNDED 范围查询。
-        所有响应 mainStatus 均归并为六态产品状态，不返回 WAIT_SPLIT。
+        mainStatus 接受七态产品状态；WAIT_SPLIT 为正式待分柜状态，INBOUNDED 仅兼容存量已入库记录。
+        计费与入库处理中状态在完成前仍归并为 WAIT_MEASURE，不提前开放分柜。
       security:
         - internalServiceToken: []
       requestBody:
@@ -102,7 +102,7 @@ paths:
   /internal/firstleg/v1/inbounds/unified-orders/detail:
     post:
       summary: 按订单 ID 查询统一履约详情（Order 内部）
-      description: 时间线保留 Firstleg 内部 fromStatus/toStatus；summary.mainStatus 始终使用六态产品状态。
+      description: 时间线保留 Firstleg 内部 fromStatus/toStatus；summary.mainStatus 使用七态产品状态。
       security:
         - internalServiceToken: []
       requestBody:
@@ -258,6 +258,17 @@ paths:
         required: true
         content: {application/json: {schema: {$ref: '#/components/schemas/ContainerDocumentAttachRequest'}}}
       responses: {'200': {description: 成功、文件归属不匹配或版本冲突}}
+  /api/platform/v1/containers/{id}/clearance/document/upload:
+    post:
+      summary: 直接选择文件上传或替换货柜目的港清关资料
+      description: Firstleg 使用内部服务令牌上传 File，浏览器不得传递 fileId 或内部令牌；旧 JSON document 接口仅兼容存量调用。
+      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema: {$ref: '#/components/schemas/ContainerDocumentUploadRequest'}
+      responses: {'200': {description: 成功、文件上传失败或版本冲突}}
   /api/platform/v1/containers/{id}/clearance/complete:
     post:
       summary: 点击完成目的港清关
@@ -645,8 +656,8 @@ components:
   schemas:
     UnifiedMainStatus:
       type: string
-      enum: [PENDING_REVIEW, WAIT_MEASURE, INBOUNDED, LOADING, LOADED, DELIVERED]
-      description: 产品主状态；历史内部状态 WAIT_SPLIT 在响应中统一归并为 INBOUNDED
+      enum: [PENDING_REVIEW, WAIT_MEASURE, INBOUNDED, WAIT_SPLIT, LOADING, LOADED, DELIVERED]
+      description: 七态产品主状态；WAIT_SPLIT 为正式待分柜状态，INBOUNDED 仅兼容存量已入库记录
     UnifiedInboundQuery:
       type: object
       properties:
@@ -657,7 +668,7 @@ components:
           type: string
           enum: [PENDING_REVIEW, WAIT_MEASURE, INBOUNDED, LOADING, LOADED, DELIVERED, WAIT_SPLIT]
           nullable: true
-          description: WAIT_SPLIT 仅为历史兼容筛选值，等价于 INBOUNDED
+          description: WAIT_SPLIT 与 INBOUNDED 为独立筛选值
         customerId: {type: integer, format: int64, nullable: true}
         receivingWarehouseId: {type: integer, format: int64, nullable: true}
         destinationWarehouseId: {type: integer, format: int64, nullable: true}
@@ -756,7 +767,7 @@ components:
         orderId: {type: integer, format: int64, nullable: true}
         orderNo: {type: string, nullable: true}
         inboundCode: {type: string, nullable: true}
-        processStatus: {type: string, nullable: true, description: Firstleg 内部状态，历史数据可能为 WAIT_SPLIT}
+        processStatus: {type: string, nullable: true, description: Firstleg 内部状态；新入库完成记录进入 WAIT_SPLIT，历史记录可能为 INBOUNDED}
         orderStatusSnapshot: {type: string, nullable: true}
         measureReviewStatus: {type: string, nullable: true}
         feeStatus: {type: string, nullable: true}
@@ -1054,7 +1065,7 @@ components:
       type: object
       required: [version, reason]
       properties:
-        containerNo: {type: string, maxLength: 64, nullable: true}
+        containerNo: {type: string, maxLength: 64, nullable: true, description: 真实集装箱号；PDA任务创建前可空，任务创建后允许替换但禁止清空}
         voyageNo: {type: string, maxLength: 64, nullable: true}
         version: {type: integer, minimum: 0}
         reason: {type: string, maxLength: 500}
@@ -1071,6 +1082,14 @@ components:
       properties:
         expectedVersion: {type: integer, minimum: 0}
         operationReason: {type: string, maxLength: 500, nullable: true}
+    ContainerDocumentUploadRequest:
+      type: object
+      required: [file, expectedVersion]
+      additionalProperties: false
+      properties:
+        file: {type: string, format: binary, description: 用户直接选择的清关资料}
+        expectedVersion: {type: integer, minimum: 0, description: 当前文档乐观锁版本，首次上传为 0}
+        operationReason: {type: string, maxLength: 500, nullable: true}
     MerchantInboundBillingEnvelope:
       type: object
       properties:

firstleg/src/main/resources/openapi/loading-lists-v1.yaml

@@ -85,6 +85,19 @@ paths:
         content: {application/json: {schema: {$ref: '#/components/schemas/DocumentAttachRequest'}}}
       responses:
         '200': {$ref: '#/components/responses/BusinessDocumentResponse'}
+  /api/platform/v1/first-leg/loading-lists/{planId}/customs/document/upload:
+    post:
+      summary: 直接选择文件上传或替换装柜清单出口报关文档
+      description: Firstleg 使用内部服务令牌上传 File，浏览器不得传递 fileId 或内部令牌；旧 JSON document 接口仅兼容存量调用。
+      x-permission: platform:firstleg:customs:manage
+      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema: {$ref: '#/components/schemas/DocumentUploadRequest'}
+      responses:
+        '200': {$ref: '#/components/responses/BusinessDocumentResponse'}
   /api/platform/v1/first-leg/loading-lists/{planId}/customs/complete:
     post:
       summary: 点击完成出口报关
@@ -353,7 +366,7 @@ components:
       required: [expectedVersion]
       additionalProperties: false
       properties:
-        containerNo: {type: string, maxLength: 64, nullable: true, description: 集装箱号}
+        containerNo: {type: string, maxLength: 64, nullable: true, description: 真实集装箱号；PDA任务创建前可空，任务创建后允许替换但禁止清空}
         voyageNo: {type: string, maxLength: 64, nullable: true, description: 航次}
         expectedVersion: {type: integer, format: int32, minimum: 0, description: 当前乐观锁版本}
         operationReason: {type: string, maxLength: 500, nullable: true, description: 操作原因}
@@ -372,6 +385,14 @@ components:
       properties:
         expectedVersion: {type: integer, format: int32, minimum: 0}
         operationReason: {type: string, maxLength: 500, nullable: true}
+    DocumentUploadRequest:
+      type: object
+      required: [file, expectedVersion]
+      additionalProperties: false
+      properties:
+        file: {type: string, format: binary, description: 用户直接选择的报关文档}
+        expectedVersion: {type: integer, format: int32, minimum: 0, description: 当前文档乐观锁版本，首次上传为 0}
+        operationReason: {type: string, maxLength: 500, nullable: true}
     BusinessDocument:
       type: object
       required: [id, documentType, fileId, fileName, fileHash, uploadedBy, uploadedAt, version]

firstleg/src/test/java/com/baiyue/firstleg/controller/ContainerControllerContractTest.java

@@ -21,6 +21,7 @@ class ContainerControllerContractTest {
         assertPermission("create", "platform:firstleg:container:create");
         assertPermission("updateDraft", "platform:firstleg:container:edit");
         assertPermission("updateTransport", "platform:firstleg:container:edit");
+        assertPermission("uploadClearance", "platform:firstleg:customs:manage");
     }
 
     @Test
@@ -33,6 +34,9 @@ class ContainerControllerContractTest {
 
         assertThat(section)
             .contains("/api/platform/v1/containers/{id}/transport:")
+            .contains("/api/platform/v1/containers/{id}/clearance/document/upload:")
+            .contains("multipart/form-data")
+            .contains("ContainerDocumentUploadRequest")
             .contains("platform:firstleg:container:list")
             .contains("EDITING")
             .contains("WAIT_LOADING")

firstleg/src/test/java/com/baiyue/firstleg/controller/LoadingListControllerContractTest.java

@@ -13,6 +13,7 @@ import org.junit.jupiter.api.Test;
 import org.yaml.snakeyaml.Yaml;
 import org.springframework.core.io.ClassPathResource;
 import org.springframework.security.access.prepost.PreAuthorize;
+import org.springframework.web.multipart.MultipartFile;
 
 import java.lang.reflect.Method;
 import java.lang.reflect.RecordComponent;
@@ -37,6 +38,8 @@ class LoadingListControllerContractTest {
         authority("declaration", "platform:firstleg:loading-list:view", AuthenticatedUser.class, long.class, long.class);
         authority("attachDeclaration", "platform:firstleg:customs:manage", AuthenticatedUser.class,
             long.class, long.class, String.class, DocumentAttachRequest.class);
+        authority("uploadDeclaration", "platform:firstleg:customs:manage", AuthenticatedUser.class,
+            long.class, long.class, String.class, MultipartFile.class, int.class, String.class);
         authority("completeDeclaration", "platform:firstleg:customs:manage", AuthenticatedUser.class,
             long.class, long.class, String.class, DocumentCompleteRequest.class);
     }
@@ -101,6 +104,7 @@ class LoadingListControllerContractTest {
             "/api/platform/v1/first-leg/loading-lists/{planId}",
             "/api/platform/v1/first-leg/loading-lists/{planId}/customs",
             "/api/platform/v1/first-leg/loading-lists/{planId}/customs/document",
+            "/api/platform/v1/first-leg/loading-lists/{planId}/customs/document/upload",
             "/api/platform/v1/first-leg/loading-lists/{planId}/customs/complete");
         Map<String, Object> components = stringMap(document.get("components"));
         Map<String, Object> schemas = stringMap(components.get("schemas"));
@@ -108,7 +112,9 @@ class LoadingListControllerContractTest {
             "LongId", "PreloadPage", "ConfirmedPage", "Customer", "PreloadSummary",
             "ConfirmedSummary", "LoadingItem", "OperationHistory", "PreloadDetail",
             "ConfirmedDetail", "TransportUpdateRequest", "BusinessDocumentEnvelope",
-            "DocumentAttachRequest", "DocumentCompleteRequest", "BusinessDocument");
+            "DocumentAttachRequest", "DocumentUploadRequest", "DocumentCompleteRequest", "BusinessDocument");
+        assertThat(properties(schemas, "DocumentUploadRequest"))
+            .containsOnlyKeys("file", "expectedVersion", "operationReason");
         assertThat(paths)
             .doesNotContainKey("/api/platform/v1/first-leg/loading-plans/{planId}/complete");
         assertThat(stringMap(schemas.get("LongId"))).containsEntry("type", "string");

firstleg/src/test/java/com/baiyue/firstleg/controller/UnifiedInboundOpenApiContractTest.java

@@ -12,7 +12,7 @@ import static org.assertj.core.api.Assertions.assertThat;
 
 class UnifiedInboundOpenApiContractTest {
     @Test
-    void documentsInternalUnifiedOrderEndpointsAndLegacyWaitSplitMapping() throws Exception {
+    void documentsInternalUnifiedOrderEndpointsAndSevenStatuses() throws Exception {
         String yaml = new ClassPathResource("openapi/firstleg-v1.yaml")
             .getContentAsString(StandardCharsets.UTF_8);
         Map<String, Object> document = stringMap(new Yaml().load(yaml));
@@ -25,13 +25,13 @@ class UnifiedInboundOpenApiContractTest {
         Map<String, Object> schemas = stringMap(stringMap(document.get("components")).get("schemas"));
         Map<String, Object> responseStatus = stringMap(schemas.get("UnifiedMainStatus"));
         assertThat(stringList(responseStatus.get("enum"))).containsExactly(
-            "PENDING_REVIEW", "WAIT_MEASURE", "INBOUNDED", "LOADING", "LOADED", "DELIVERED");
+            "PENDING_REVIEW", "WAIT_MEASURE", "INBOUNDED", "WAIT_SPLIT", "LOADING", "LOADED", "DELIVERED");
         assertThat(responseStatus.get("description").toString()).contains("WAIT_SPLIT", "INBOUNDED");
 
         Map<String, Object> query = stringMap(schemas.get("UnifiedInboundQuery"));
         Map<String, Object> queryStatus = stringMap(stringMap(query.get("properties")).get("mainStatus"));
         assertThat(stringList(queryStatus.get("enum"))).contains("WAIT_SPLIT");
-        assertThat(queryStatus.get("description").toString()).contains("INBOUNDED");
+        assertThat(queryStatus.get("description").toString()).contains("WAIT_SPLIT", "INBOUNDED", "独立");
 
         Map<String, Object> inbound = stringMap(schemas.get("UnifiedInboundOrderSummary"));
         assertThat(stringMap(inbound.get("properties"))).containsKeys(

firstleg/src/test/java/com/baiyue/firstleg/customs/service/CustomsDispatchGateContributorTest.java

@@ -1,7 +1,7 @@
 package com.baiyue.firstleg.customs.service;
 
-import com.baiyue.firstleg.customs.entity.CustomsCaseEntity;
-import com.baiyue.firstleg.customs.repository.CustomsRepository;
+import com.baiyue.firstleg.entity.ContainerDocumentEntity;
+import com.baiyue.firstleg.repository.LoadingListRepository;
 import com.baiyue.firstleg.outbound.dispatch.gate.OutboundDispatchGateContributor.Context;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
@@ -11,7 +11,7 @@ import static org.assertj.core.api.Assertions.assertThat;
 import static org.mockito.Mockito.*;
 
 class CustomsDispatchGateContributorTest {
-    @Mock CustomsRepository repository;
+    @Mock LoadingListRepository repository;
     @InjectMocks CustomsDispatchGateContributor contributor;
 
     @BeforeEach void setUp() { MockitoAnnotations.openMocks(this); }
@@ -22,12 +22,16 @@ class CustomsDispatchGateContributorTest {
             .isEqualTo("INVALID_CUSTOMER_SCOPE");
     }
 
-    @Test void passesOnlyReleasedTerminalState() {
-        CustomsCaseEntity value = new CustomsCaseEntity(); value.setStatus("RECEIPT_AVAILABLE");
-        when(repository.gateCase(10001L, 21L, 31L, 81L)).thenReturn(value);
+    @Test void passesOnlyCompletedSimpleDeclaration() {
+        ContainerDocumentEntity value = new ContainerDocumentEntity();
+        when(repository.document(81L, "CUSTOMS_DECLARATION")).thenReturn(value);
         assertThat(contributor.assess(context()).passed()).isFalse();
-        value.setStatus("CLEARANCE_COMPLETED");
-        assertThat(contributor.assess(context()).passed()).isTrue();
+        value.setCompletedAt(java.time.LocalDateTime.now());
+        assertThat(contributor.assess(context()))
+            .satisfies(item -> {
+                assertThat(item.passed()).isTrue();
+                assertThat(item.requirement()).isEqualTo("COMPLETED");
+            });
     }
 
     private static Context context() { return new Context(10001L, 10002L, 21L, 31L, 81L, 91L, null); }

firstleg/src/test/java/com/baiyue/firstleg/loading/mapper/LoadingCompletionGateSqlContractTest.java

@@ -7,7 +7,7 @@ import static org.assertj.core.api.Assertions.assertThat;
 
 class LoadingCompletionGateSqlContractTest {
     @Test
-    void requiresEveryLinkedContainerToPassBookingTruckAndCustomsReceiptGates() throws Exception {
+    void requiresEveryLinkedContainerToPassBookingAndTruckGates() throws Exception {
         Select select = LoadingCompletionGateMapper.class
             .getDeclaredMethod("snapshot", long.class, long.class).getAnnotation(Select.class);
         String sql = String.join(" ", select.value()).replaceAll("\\s+", " ");
@@ -19,13 +19,9 @@ class LoadingCompletionGateSqlContractTest {
             .contains("b.status='RELEASED'")
             .contains("fl_truck_appointment")
             .contains("t.status='COMPLETED'")
-            .contains("fl_customs_case")
-            .contains("fl_customs_receipt")
-            .contains("c.status='CLEARANCE_COMPLETED'")
-            .contains("r.receipt_type='RELEASED'")
-            .contains("r.file_id IS NOT NULL")
-            .contains("newer.receipt_version>r.receipt_version")
             .contains("l.tenant_id=#{tenantId} AND l.inbound_id=#{inboundId}")
+            .doesNotContain("truckReady, FROM")
+            .doesNotContain("fl_customs_case", "fl_customs_receipt", "customsReady")
             .doesNotContain("<", ">");
     }
 }

firstleg/src/test/java/com/baiyue/firstleg/loading/service/LoadingDeliveryServiceTest.java

@@ -79,7 +79,7 @@ class LoadingDeliveryServiceTest {
         LoadingActionResponse result = service.completeLoading(10, 20, 7, "admin", "k1", new CompleteLoadingRequest(3, null));
         assertThat(result.mainStatus()).isEqualTo("LOADED");
         verify(loadingModelBridge).requireCompleted(10, 20);
-        verify(completionGate).requireBookingTransportAndCustoms(10, 20);
+        verify(completionGate).requireBookingAndTransport(10, 20);
         verify(histories).insert(any(InboundStatusHistoryEntity.class));
     }
 
@@ -113,7 +113,7 @@ class LoadingDeliveryServiceTest {
 
         assertThat(result.mainStatus()).isEqualTo("LOADED");
         verify(loadingModelBridge).requireCompleted(10, 20);
-        verify(completionGate).requireBookingTransportAndCustoms(10, 20);
+        verify(completionGate).requireBookingAndTransport(10, 20);
         verify(repository).completeLoadedChild(10, 20, 7, 3);
         verify(repository).aggregateRootLoaded(10, 20, 7);
         verify(histories).insert(argThat((InboundStatusHistoryEntity history) ->
@@ -172,7 +172,7 @@ class LoadingDeliveryServiceTest {
         verify(repository).completeLoadedChild(10, 20, 7, 5);
         verify(repository).aggregateRootLoaded(10, 10, 7);
         verify(loadingModelBridge).requireCompleted(10, 20);
-        verify(completionGate).requireBookingTransportAndCustoms(10, 20);
+        verify(completionGate).requireBookingAndTransport(10, 20);
         verify(histories).insert(any(InboundStatusHistoryEntity.class));
         verify(repository).completeOperation(10L, 20L, 7L, "COMPLETE_LOADING", "slice-replay", resultJson.get());
     }

firstleg/src/test/java/com/baiyue/firstleg/repository/ContainerBookingMapperContractTest.java

@@ -44,6 +44,8 @@ class ContainerBookingMapperContractTest {
             .contains("capacity_cbm")
             .contains("p.plan_status!='EDITING'")
             .contains("p.plan_status='COMPLETED'")
+            .contains("#{containerNo} IS NOT NULL")
+            .contains("fl_loading_pick_task")
             .contains("version=#{expectedVersion}")
             .doesNotContain("<")
             .doesNotContain(">");

firstleg/src/test/java/com/baiyue/firstleg/repository/InboundOrderStatusSqlContractTest.java

@@ -0,0 +1,31 @@
+package com.baiyue.firstleg.repository;
+
+import com.baiyue.firstleg.mapper.InboundOrderMapper;
+import org.apache.ibatis.annotations.Update;
+import org.junit.jupiter.api.Test;
+
+import java.lang.reflect.Method;
+import java.util.Arrays;
+
+import static org.assertj.core.api.Assertions.assertThat;
+
+class InboundOrderStatusSqlContractTest {
+    @Test
+    void advancesThroughPricingBeforeOpeningWaitSplit() {
+        assertThat(sql("approveMeasurement"))
+            .contains("process_status = 'WAIT_PRICING'")
+            .doesNotContain("inbounded_at =");
+        assertThat(sql("completeInbound"))
+            .contains("process_status = 'WAIT_SPLIT'")
+            .contains("inbounded_at = CURRENT_TIMESTAMP(3)")
+            .contains("process_status = 'INBOUNDING'");
+    }
+
+    private static String sql(String methodName) {
+        Method method = Arrays.stream(InboundOrderMapper.class.getDeclaredMethods())
+            .filter(candidate -> candidate.getName().equals(methodName))
+            .findFirst()
+            .orElseThrow();
+        return String.join(" ", method.getAnnotation(Update.class).value());
+    }
+}

firstleg/src/test/java/com/baiyue/firstleg/repository/InboundStatusUnificationSqlContractTest.java

@@ -18,11 +18,13 @@ class InboundStatusUnificationSqlContractTest {
 
         assertThat(module)
             .contains("CREATE PROCEDURE assert_inbounded_compatibility()")
-            .contains("二、三期对外统一使用 INBOUNDED")
+            .contains("新完成入库记录使用 WAIT_SPLIT")
+            .contains("存量 INBOUNDED")
             .doesNotContain("UPDATE fl_inbound_order")
             .doesNotContain("UPDATE fl_inbound_status_history");
         assertThat(unified)
-            .contains("二、三期对外统一使用 INBOUNDED")
+            .contains("新完成入库记录使用 WAIT_SPLIT")
+            .contains("存量 INBOUNDED")
             .doesNotContain("SET process_status = 'INBOUNDED'")
             .doesNotContain("SET from_status = 'INBOUNDED'")
             .doesNotContain("SET to_status = 'INBOUNDED'");

firstleg/src/test/java/com/baiyue/firstleg/repository/LoadingListQueryMapperContractTest.java

@@ -60,6 +60,8 @@ class LoadingListQueryMapperContractTest {
             .contains("version = version + 1");
         assertThat(transport)
             .contains("SET b.container_no = #{containerNo}, b.voyage_no = #{voyageNo}")
+            .contains("#{containerNo} IS NOT NULL")
+            .contains("fl_loading_pick_task")
             .doesNotContain("DELETE")
             .doesNotContain("fl_loading_plan_item");
         assertThat(advance)

firstleg/src/test/java/com/baiyue/firstleg/repository/Phase3FinalUnifiedSqlContractTest.java

@@ -84,7 +84,7 @@ class Phase3FinalUnifiedSqlContractTest {
             "-- 来源：iam/src/main/resources/db/phase3-warehouse-roles.sql",
             "firstleg/src/main/resources/db/phase3-carrier-schedule-query-schema.sql");
         assertBlock(unified, "-- 来源：iam/src/main/resources/db/phase3-warehouse-roles.sql",
-            "-- 二、三期对外统一使用 INBOUNDED；历史 WAIT_SPLIT 仅由查询适配为 INBOUNDED，统一迁移不改写主表或历史状态。",
+            "-- 新完成入库记录使用 WAIT_SPLIT；存量 INBOUNDED 继续作为可分柜兼容状态，统一迁移不改写主表或历史状态。",
             "iam/src/main/resources/db/phase3-warehouse-roles.sql");
     }
 

firstleg/src/test/java/com/baiyue/firstleg/repository/SmartLoadingCandidateMapperContractTest.java

@@ -21,7 +21,7 @@ class SmartLoadingCandidateMapperContractTest {
             .contains("m2.status='APPROVED'")
             .contains("i.inbound_detail_id IS NOT NULL")
             .contains("o.warehouse_id=#{warehouseId}")
-            .contains("o.process_status='INBOUNDED'")
+            .contains("o.process_status IN ('WAIT_SPLIT','INBOUNDED')")
             .contains("SELECT SUM(li.package_count)")
             .contains("li.deleted=0")
             .contains("ORDER BY o.inbounded_at ASC, o.id ASC, i.id ASC");
@@ -38,7 +38,7 @@ class SmartLoadingCandidateMapperContractTest {
             .contains("m.status='APPROVED'")
             .contains("SELECT MAX(m2.id)")
             .contains("o.warehouse_id=#{warehouseId}")
-            .contains("o.process_status='INBOUNDED'")
+            .contains("o.process_status IN ('WAIT_SPLIT','INBOUNDED')")
             .contains("SELECT SUM(li.package_count)")
             .contains("FOR UPDATE");
     }

firstleg/src/test/java/com/baiyue/firstleg/repository/SmartLoadingSqlContractTest.java

@@ -73,6 +73,30 @@ class SmartLoadingSqlContractTest {
             .contains("version INT UNSIGNED NOT NULL DEFAULT 0 COMMENT '乐观锁版本号'");
     }
 
+    @Test
+    @DisplayName("清关与报关采用柜次级文件、一键完成和真实文件哈希")
+    void shouldProvideSimpleCustomsDocuments() throws Exception {
+        assertSimpleCustomsDocumentContract(migration());
+        assertSimpleCustomsDocumentContract(unifiedMigration());
+        assertThat(Files.readString(Path.of("src/main/resources/db/phase3-simple-customs-document-migration.sql"),
+            StandardCharsets.UTF_8))
+            .contains("CREATE TRIGGER trg_container_booking_before_update")
+            .contains("IF current_plan_status='COMPLETED' THEN")
+            .contains("NEW.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION')")
+            .contains("OLD.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION')");
+    }
+
+    private static void assertSimpleCustomsDocumentContract(String sql) {
+        assertThat(sql)
+            .contains("'DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION', 'DELIVERY_ORDER', 'PICKUP_ORDER'")
+            .contains("file_hash VARCHAR(64) NULL")
+            .contains("completed_by BIGINT UNSIGNED NULL")
+            .contains("completed_at DATETIME(3) NULL")
+            .contains("NEW.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION')")
+            .contains("OLD.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION')")
+            .doesNotContain("OLD.document_type NOT IN ('DESTINATION_CLEARANCE', 'CUSTOMS_DECLARATION') THEN\n    SIGNAL SQLSTATE '45000' SET MESSAGE_TEXT = '装柜完成后货柜全部只读");
+    }
+
     @Test
     @DisplayName("平台菜单按钮权限使用统一前缀并授权运营角色")
     void shouldProvidePlatformPermissions() throws Exception {

firstleg/src/test/java/com/baiyue/firstleg/service/ContainerServiceTest.java

@@ -8,8 +8,10 @@ import com.baiyue.firstleg.dto.ContainerDtos.SaveRequest;
 import com.baiyue.firstleg.dto.ContainerDtos.TransportUpdateRequest;
 import com.baiyue.firstleg.entity.ContainerBookingEntity;
 import com.baiyue.firstleg.entity.LoadingPlanEntity;
+import com.baiyue.firstleg.entity.LoadingPickTaskEntity;
 import com.baiyue.firstleg.mapper.ContainerTransportHistoryMapper;
 import com.baiyue.firstleg.repository.ContainerRepository;
+import com.baiyue.firstleg.repository.LoadingPickRepository;
 import com.baiyue.firstleg.repository.SmartLoadingRepository;
 import jakarta.annotation.Resource;
 import org.junit.jupiter.api.DisplayName;
@@ -37,6 +39,7 @@ class ContainerServiceTest {
     @MockBean private ContainerRepository repository;
     @MockBean private WarehouseMasterDataClient warehouses;
     @MockBean private SmartLoadingRepository smartLoadingRepository;
+    @MockBean private LoadingPickRepository loadingPickRepository;
     @MockBean private LoadingPickService loadingPickService;
     @MockBean private ContainerTransportHistoryMapper transportHistories;
     @Resource private ContainerService service;
@@ -145,6 +148,25 @@ class ContainerServiceTest {
             org.mockito.ArgumentMatchers.eq("admin"), any());
     }
 
+    @Test
+    @DisplayName("PDA任务创建后禁止清空真实集装箱号")
+    void rejectsClearingContainerNumberAfterPdaTaskStarts() {
+        ContainerBookingEntity current = booking("LOADING", 2);
+        LoadingPlanEntity plan = new LoadingPlanEntity();
+        plan.setId(31L);
+        when(repository.find(11L)).thenReturn(current);
+        when(smartLoadingRepository.planByBooking(11L)).thenReturn(plan);
+        when(loadingPickRepository.taskByPlan(31L)).thenReturn(new LoadingPickTaskEntity());
+
+        assertThatThrownBy(() -> service.updateTransport(11L, 9L, "admin",
+            new TransportUpdateRequest(null, "V002", 2)))
+            .isInstanceOf(BizException.class)
+            .hasMessageContaining("不能清空真实集装箱号");
+
+        verify(repository, never()).updateTransport(any(Long.class), any(), any(),
+            any(Integer.class), any(Long.class), any());
+    }
+
     @Test
     @DisplayName("已确认货柜全部只读")
     void rejectsConfirmedUpdate() {

firstleg/src/test/java/com/baiyue/firstleg/service/FbaPricingServiceTest.java

@@ -114,7 +114,7 @@ class FbaPricingServiceTest {
     void calculatesAtWaitSplitWithoutRollingBackProcessStatus() {
         readyRepository();
         InboundPricingEntity inbound = inbound("100.000", "1.0000");
-        inbound.setProcessStatus("INBOUNDED");
+        inbound.setProcessStatus("WAIT_SPLIT");
         when(repository.findInbound(TENANT, INBOUND)).thenReturn(inbound);
         when(priceBookEstimator.estimate(any())).thenReturn(
             estimate("KG", "167.000", "2.000000", "334.00", "0.00"));
@@ -122,8 +122,8 @@ class FbaPricingServiceTest {
         FeeSnapshotResponse response = service.calculate(TENANT, OPERATOR, INBOUND, NOW, "wait-split");
 
         assertThat(response.feeStatus()).isEqualTo("CALCULATED");
-        assertThat(response.nextProcessStatus()).isEqualTo("INBOUNDED");
-        verify(repository).markInboundCalculated(TENANT, INBOUND, "INBOUNDED", "KG",
+        assertThat(response.nextProcessStatus()).isEqualTo("WAIT_SPLIT");
+        verify(repository).markInboundCalculated(TENANT, INBOUND, "WAIT_SPLIT", "KG",
             new BigDecimal("167.000"));
     }
 
@@ -131,7 +131,7 @@ class FbaPricingServiceTest {
     @DisplayName("待分柜边界确认费用后仍保持主流程状态")
     void confirmsAtWaitSplitWithoutRollingBackProcessStatus() {
         InboundPricingEntity inbound = inbound("10.000", "1.0000");
-        inbound.setProcessStatus("INBOUNDED");
+        inbound.setProcessStatus("WAIT_SPLIT");
         inbound.setFeeStatus("CALCULATED");
         InboundFeeEntity fee = savedFee("CALCULATED");
         when(repository.findLatestFee(TENANT, INBOUND)).thenReturn(fee);
@@ -148,7 +148,7 @@ class FbaPricingServiceTest {
         FeeSnapshotResponse response = service.confirm(
             TENANT, OPERATOR, INBOUND, "confirm-wait-split");
 
-        assertThat(response.nextProcessStatus()).isEqualTo("INBOUNDED");
+        assertThat(response.nextProcessStatus()).isEqualTo("WAIT_SPLIT");
         verify(repository).markInboundConfirmed(TENANT, INBOUND);
     }
 

firstleg/src/test/java/com/baiyue/firstleg/service/LoadingListServiceTest.java

@@ -24,6 +24,7 @@ import org.springframework.boot.test.context.TestConfiguration;
 import org.springframework.boot.test.mock.mockito.MockBean;
 import org.springframework.context.annotation.Bean;
 import org.springframework.test.context.junit.jupiter.SpringJUnitConfig;
+import org.springframework.mock.web.MockMultipartFile;
 
 import java.util.List;
 
@@ -102,6 +103,23 @@ class LoadingListServiceTest {
         verify(repository, never()).updateTransport(eq(10L), eq(5), anyString(), anyString(), eq(9L), anyString());
     }
 
+    @Test
+    void shouldRejectClearingContainerNumberAfterPdaTaskStarts() {
+        AggregateRow before = row("LOADING", 3);
+        when(repository.history(anyString())).thenReturn(null);
+        when(repository.aggregate(10L)).thenReturn(before);
+        when(pickRepository.taskByPlan(10L)).thenReturn(new com.baiyue.firstleg.entity.LoadingPickTaskEntity());
+
+        assertThatThrownBy(() -> service.updateTransport(10L, 100L, 9L, "operator", "key-1",
+            new TransportUpdateRequest(null, "023E", 3, "清空测试")))
+            .isInstanceOf(BizException.class)
+            .hasMessageContaining("不能清空真实集装箱号");
+        verify(repository, never()).updateTransport(eq(10L), eq(3),
+            org.mockito.ArgumentMatchers.nullable(String.class),
+            org.mockito.ArgumentMatchers.nullable(String.class), eq(9L),
+            org.mockito.ArgumentMatchers.nullable(String.class));
+    }
+
     @Test
     void shouldCompleteLoadingAfterAllPdaItemsPicked() {
         AggregateRow before = row("LOADING", 2);
@@ -206,14 +224,16 @@ class LoadingListServiceTest {
             .thenReturn(null, document(40L, LoadingListService.DESTINATION_CLEARANCE, 0, false));
         when(documentFiles.metadata(anyString(), eq(0L), eq("CONTAINER_CLEARANCE_DOCUMENT"),
             eq("30"), eq(99L))).thenReturn(ApiResponse.success(new LoadingDocumentFileClient.Metadata(
-            99L, 0L, "CONTAINER_CLEARANCE_DOCUMENT", "30", "clearance.pdf", "abc", "application/pdf", 20L)));
+            99L, 0L, "CONTAINER_CLEARANCE_DOCUMENT", "30", "clearance.pdf", hash(), "application/pdf", 20L)));
         when(repository.createDocument(org.mockito.ArgumentMatchers.any())).thenReturn(1);
 
         var result = service.attachContainerClearance(30L, 9L, "operator", "key-clearance",
             new DocumentAttachRequest(99L, 0, "上传清关资料"));
 
         assertThat(result.fileName()).isEqualTo("clearance.pdf");
-        verify(repository).appendHistory(eq(10L), anyString(), eq("ATTACH_DESTINATION_CLEARANCE"),
+        verify(repository).appendHistory(eq(10L),
+            eq("PL-" + sha256("ATTACH_DESTINATION_CLEARANCE|30|key-clearance")),
+            eq("ATTACH_DESTINATION_CLEARANCE"),
             eq("LOADING"), eq("LOADING"), anyString(), anyString(), eq(9L), eq("operator"),
             eq("上传清关资料"));
     }
@@ -241,7 +261,7 @@ class LoadingListServiceTest {
         when(repository.document(30L, LoadingListService.DESTINATION_CLEARANCE)).thenReturn(null);
         when(documentFiles.metadata(anyString(), eq(0L), eq("CONTAINER_CLEARANCE_DOCUMENT"),
             eq("30"), eq(99L))).thenReturn(ApiResponse.success(new LoadingDocumentFileClient.Metadata(
-            99L, 0L, "CONTAINER_CLEARANCE_DOCUMENT", "different-booking", "clearance.pdf", "abc",
+            99L, 0L, "CONTAINER_CLEARANCE_DOCUMENT", "different-booking", "clearance.pdf", hash(),
             "application/pdf", 20L)));
 
         assertThatThrownBy(() -> service.attachContainerClearance(30L, 9L, "operator", "key",
@@ -306,6 +326,121 @@ class LoadingListServiceTest {
             org.mockito.ArgumentMatchers.anyInt(), eq(9L), anyString());
     }
 
+    @Test
+    void rejectsReplacingCompletedDocument() {
+        AggregateRow plan = row("COMPLETED", 2);
+        plan.setContainerBookingId(30L);
+        when(repository.aggregate(10L)).thenReturn(plan);
+        when(repository.history(anyString())).thenReturn(null);
+        when(repository.document(30L, LoadingListService.CUSTOMS_DECLARATION))
+            .thenReturn(document(40L, LoadingListService.CUSTOMS_DECLARATION, 4, true));
+
+        assertThatThrownBy(() -> service.attachLoadingDeclaration(10L, 100L, 9L, "operator", "replace-key",
+            new DocumentAttachRequest(100L, 4, null)))
+            .isInstanceOf(BizException.class)
+            .extracting(error -> ((BizException) error).getResultCode())
+            .isEqualTo(ResultCode.CONFLICT);
+        verify(documentFiles, never()).metadata(anyString(), eq(0L), anyString(), anyString(), eq(100L));
+    }
+
+    @Test
+    void uploadsContainerClearanceThroughInternalFileClientAndAssociatesMetadata() {
+        AggregateRow plan = row("LOADING", 2);
+        plan.setContainerBookingId(30L);
+        byte[] content = "clearance-document".getBytes(java.nio.charset.StandardCharsets.UTF_8);
+        String contentHash = sha256Bytes(content);
+        var file = new MockMultipartFile("file", "clearance.pdf", "application/pdf", content);
+        var metadata = new LoadingDocumentFileClient.Metadata(99L, 0L,
+            "CONTAINER_CLEARANCE_DOCUMENT", "30", "clearance.pdf", contentHash, "application/pdf",
+            (long) content.length);
+        when(repository.aggregateByBooking(30L)).thenReturn(plan);
+        when(repository.history(anyString())).thenReturn(null);
+        ContainerDocumentEntity saved = document(40L, LoadingListService.DESTINATION_CLEARANCE, 0, false);
+        saved.setFileHash(contentHash);
+        when(repository.document(30L, LoadingListService.DESTINATION_CLEARANCE)).thenReturn(null, saved);
+        when(documentFiles.upload(anyString(), eq(9L), eq(0L), eq("CONTAINER_CLEARANCE_DOCUMENT"),
+            eq("30"), eq(file))).thenReturn(ApiResponse.success(metadata));
+        when(documentFiles.metadata(anyString(), eq(0L), eq("CONTAINER_CLEARANCE_DOCUMENT"),
+            eq("30"), eq(99L))).thenReturn(ApiResponse.success(metadata));
+        when(repository.createDocument(org.mockito.ArgumentMatchers.any())).thenReturn(1);
+
+        var result = service.uploadContainerClearance(
+            30L, 9L, "operator", "upload-key", 0, "直接上传", file);
+
+        assertThat(result.fileHash()).isEqualTo(contentHash);
+        verify(documentFiles).upload(anyString(), eq(9L), eq(0L), eq("CONTAINER_CLEARANCE_DOCUMENT"),
+            eq("30"), eq(file));
+        verify(repository).appendHistory(eq(10L),
+            eq("PL-" + sha256("UPLOAD_DESTINATION_CLEARANCE|30|upload-key")),
+            eq("UPLOAD_DESTINATION_CLEARANCE"), eq("LOADING"), eq("LOADING"), anyString(),
+            anyString(), eq(9L), eq("operator"), eq("直接上传"));
+    }
+
+    @Test
+    void multipartReplayDoesNotUploadFileAgain() {
+        AggregateRow plan = row("LOADING", 2);
+        plan.setContainerBookingId(30L);
+        byte[] content = "clearance-document".getBytes(java.nio.charset.StandardCharsets.UTF_8);
+        var file = new MockMultipartFile("file", "clearance.pdf", "application/pdf", content);
+        String requestHash = sha256("UPLOAD|DESTINATION_CLEARANCE|30|0|null|" + sha256Bytes(content));
+        HistoryRow replay = new HistoryRow();
+        replay.setAfterSnapshot("{\"requestHash\":\"" + requestHash + "\"}");
+        when(repository.aggregateByBooking(30L)).thenReturn(plan);
+        when(repository.history(anyString())).thenReturn(replay);
+        when(repository.document(30L, LoadingListService.DESTINATION_CLEARANCE))
+            .thenReturn(document(40L, LoadingListService.DESTINATION_CLEARANCE, 0, false));
+
+        service.uploadContainerClearance(30L, 9L, "operator", "upload-key", 0, null, file);
+
+        verify(documentFiles, never()).upload(anyString(), eq(9L), eq(0L), anyString(), anyString(), eq(file));
+    }
+
+    @Test
+    void uploadsLoadingDeclarationWithPlanIdentityAndWarehouseScope() {
+        AggregateRow plan = row("COMPLETED", 2);
+        plan.setContainerBookingId(30L);
+        byte[] content = "customs-declaration".getBytes(java.nio.charset.StandardCharsets.UTF_8);
+        String contentHash = sha256Bytes(content);
+        var file = new MockMultipartFile("file", "customs.pdf", "application/pdf", content);
+        var metadata = new LoadingDocumentFileClient.Metadata(101L, 0L,
+            "LOADING_CUSTOMS_DOCUMENT", "10", "customs.pdf", contentHash, "application/pdf",
+            (long) content.length);
+        ContainerDocumentEntity saved = document(41L, LoadingListService.CUSTOMS_DECLARATION, 0, false);
+        saved.setFileId(101L); saved.setFileName("customs.pdf"); saved.setFileHash(contentHash);
+        when(repository.aggregate(10L)).thenReturn(plan);
+        when(repository.history(anyString())).thenReturn(null);
+        when(repository.document(30L, LoadingListService.CUSTOMS_DECLARATION)).thenReturn(null, saved);
+        when(documentFiles.upload(anyString(), eq(9L), eq(0L), eq("LOADING_CUSTOMS_DOCUMENT"),
+            eq("10"), eq(file))).thenReturn(ApiResponse.success(metadata));
+        when(documentFiles.metadata(anyString(), eq(0L), eq("LOADING_CUSTOMS_DOCUMENT"),
+            eq("10"), eq(101L))).thenReturn(ApiResponse.success(metadata));
+        when(repository.createDocument(org.mockito.ArgumentMatchers.any())).thenReturn(1);
+
+        var result = service.uploadLoadingDeclaration(
+            10L, 100L, 9L, "operator", "customs-upload", 0, null, file);
+
+        assertThat(result.documentType()).isEqualTo(LoadingListService.CUSTOMS_DECLARATION);
+        verify(documentFiles).upload(anyString(), eq(9L), eq(0L), eq("LOADING_CUSTOMS_DOCUMENT"),
+            eq("10"), eq(file));
+    }
+
+    @Test
+    void rejectsReusedIdempotencyKeyWithDifferentAttachRequest() {
+        AggregateRow plan = row("LOADING", 2);
+        plan.setContainerBookingId(30L);
+        HistoryRow replay = new HistoryRow();
+        replay.setAfterSnapshot("{\"requestHash\":\"different\"}");
+        when(repository.aggregateByBooking(30L)).thenReturn(plan);
+        when(repository.history(anyString())).thenReturn(replay);
+
+        assertThatThrownBy(() -> service.attachContainerClearance(30L, 9L, "operator", "reused-key",
+            new DocumentAttachRequest(100L, 0, null)))
+            .isInstanceOf(BizException.class)
+            .extracting(error -> ((BizException) error).getResultCode())
+            .isEqualTo(ResultCode.CONFLICT);
+        verify(repository, never()).createDocument(org.mockito.ArgumentMatchers.any());
+    }
+
     private static AggregateRow row(String status, int version) {
         AggregateRow row = new AggregateRow();
         row.setPlanId(10L);
@@ -319,10 +454,31 @@ class LoadingListServiceTest {
     private static ContainerDocumentEntity document(long id, String type, int version, boolean completed) {
         ContainerDocumentEntity value = new ContainerDocumentEntity();
         value.setId(id); value.setContainerBookingId(30L); value.setDocumentType(type);
-        value.setFileId(99L); value.setFileName("clearance.pdf"); value.setFileHash("abc");
+        value.setFileId(99L); value.setFileName("clearance.pdf"); value.setFileHash(hash());
         value.setUploadedBy(9L); value.setUploadedByName("operator"); value.setVersion(version);
         value.setCreatedAt(java.time.LocalDateTime.now());
         if (completed) value.setCompletedAt(java.time.LocalDateTime.now());
         return value;
     }
+
+    private static String hash() { return "a".repeat(64); }
+
+    private static String sha256Bytes(byte[] value) {
+        try {
+            return java.util.HexFormat.of().formatHex(
+                java.security.MessageDigest.getInstance("SHA-256").digest(value));
+        } catch (java.security.NoSuchAlgorithmException exception) {
+            throw new IllegalStateException(exception);
+        }
+    }
+
+    private static String sha256(String value) {
+        try {
+            byte[] digest = java.security.MessageDigest.getInstance("SHA-256")
+                .digest(value.getBytes(java.nio.charset.StandardCharsets.UTF_8));
+            return java.util.HexFormat.of().formatHex(digest);
+        } catch (java.security.NoSuchAlgorithmException exception) {
+            throw new IllegalStateException(exception);
+        }
+    }
 }

firstleg/src/test/java/com/baiyue/firstleg/service/MeasurementReviewServiceTest.java

@@ -78,7 +78,7 @@ class MeasurementReviewServiceTest {
             ArgumentCaptor.forClass(InboundStatusHistoryEntity.class);
         verify(fixture.repository).insertHistory(history.capture());
         assertThat(history.getValue().getFromStatus()).isEqualTo("MEASURE_PENDING");
-        assertThat(history.getValue().getToStatus()).isEqualTo("INBOUNDED");
+        assertThat(history.getValue().getToStatus()).isEqualTo("WAIT_PRICING");
     }
 
     @Test

firstleg/src/test/java/com/baiyue/firstleg/service/UnifiedInboundQueryServiceTest.java

@@ -28,10 +28,10 @@ class UnifiedInboundQueryServiceTest {
         assertThat(UnifiedInboundQueryService.mainStatus("MEASURING")).isEqualTo("WAIT_MEASURE");
         assertThat(UnifiedInboundQueryService.mainStatus("MEASURE_PENDING")).isEqualTo("WAIT_MEASURE");
         assertThat(UnifiedInboundQueryService.mainStatus("MEASURE_REJECTED")).isEqualTo("WAIT_MEASURE");
-        assertThat(UnifiedInboundQueryService.mainStatus("WAIT_PRICING")).isEqualTo("INBOUNDED");
-        assertThat(UnifiedInboundQueryService.mainStatus("FEE_CONFIRMING")).isEqualTo("INBOUNDED");
-        assertThat(UnifiedInboundQueryService.mainStatus("INBOUNDING")).isEqualTo("INBOUNDED");
-        assertThat(UnifiedInboundQueryService.mainStatus("WAIT_SPLIT")).isEqualTo("INBOUNDED");
+        assertThat(UnifiedInboundQueryService.mainStatus("WAIT_PRICING")).isEqualTo("WAIT_MEASURE");
+        assertThat(UnifiedInboundQueryService.mainStatus("FEE_CONFIRMING")).isEqualTo("WAIT_MEASURE");
+        assertThat(UnifiedInboundQueryService.mainStatus("INBOUNDING")).isEqualTo("WAIT_MEASURE");
+        assertThat(UnifiedInboundQueryService.mainStatus("WAIT_SPLIT")).isEqualTo("WAIT_SPLIT");
         assertThat(UnifiedInboundQueryService.mainStatus("INBOUNDED")).isEqualTo("INBOUNDED");
         assertThat(UnifiedInboundQueryService.mainStatus("LOADING")).isEqualTo("LOADING");
         assertThat(UnifiedInboundQueryService.mainStatus("LOADED")).isEqualTo("LOADED");
@@ -50,21 +50,21 @@ class UnifiedInboundQueryServiceTest {
             .isEqualTo("CONFIRM_PRELOAD");
         assertThat(UnifiedInboundQueryService.nextAction("INBOUNDED", "INBOUNDING", null)).isNull();
         assertThat(UnifiedInboundQueryService.nextAction("INBOUNDED", "INBOUNDED", "CONFIRMED")).isNull();
-        assertThat(UnifiedInboundQueryService.nextAction("INBOUNDED", "WAIT_SPLIT", null))
+        assertThat(UnifiedInboundQueryService.nextAction("WAIT_SPLIT", "WAIT_SPLIT", null))
             .isEqualTo("SMART_SPLIT");
         assertThat(UnifiedInboundQueryService.nextAction("LOADED", "LOADED", null)).isNull();
         assertThat(UnifiedInboundQueryService.nextAction("DELIVERED", "DELIVERED", null)).isNull();
     }
 
     @Test
-    void inboundedFilterIncludesHistoricalWaitSplitRows() throws Exception {
+    void inboundedAndWaitSplitFiltersRemainDistinct() throws Exception {
         var method = UnifiedInboundQueryService.class.getDeclaredMethod("internalStatuses", String.class);
         method.setAccessible(true);
 
         assertThat(method.invoke(new UnifiedInboundQueryService(), "INBOUNDED"))
-            .isEqualTo(java.util.List.of("WAIT_PRICING", "FEE_CONFIRMING", "INBOUNDING", "INBOUNDED", "WAIT_SPLIT"));
+            .isEqualTo(java.util.List.of("INBOUNDED"));
         assertThat(method.invoke(new UnifiedInboundQueryService(), "WAIT_SPLIT"))
-            .isEqualTo(java.util.List.of("WAIT_PRICING", "FEE_CONFIRMING", "INBOUNDING", "INBOUNDED", "WAIT_SPLIT"));
+            .isEqualTo(java.util.List.of("WAIT_SPLIT"));
     }
 
     @Test

firstleg/src/test/java/com/baiyue/firstleg/split/service/SplitPreloadServiceTest.java

@@ -47,19 +47,19 @@ class SplitPreloadServiceTest {
     @Test
     void smartSplitCreatesEditablePendingPlan() {
         when(repository.claimOperation(anyLong(), anyLong(), anyLong(), anyString(), anyString())).thenReturn(true);
-        when(repository.findInbound(10, 20)).thenReturn(new InboundSnapshot(20L, 10L, "INBOUNDED", 3));
+        when(repository.findInbound(10, 20)).thenReturn(new InboundSnapshot(20L, 10L, "WAIT_SPLIT", 3));
         when(repository.findPlan(10, 20)).thenReturn(null);
         SmartSplitRequest request = new SmartSplitRequest(0,
             List.of(new PreloadItem("C1", "A", 2, BigDecimal.ONE, null)), "r");
         SplitActionResponse result = service.smartSplit(10, 20, 7, "admin", "k2", request);
-        assertThat(result.mainStatus()).isEqualTo("INBOUNDED");
+        assertThat(result.mainStatus()).isEqualTo("WAIT_SPLIT");
         verify(repository).createPlan(any(PreloadPlanEntity.class));
     }
 
     @Test
     void confirmsPlanAndMovesInboundToLoading() {
         when(repository.claimOperation(anyLong(), anyLong(), anyLong(), anyString(), anyString())).thenReturn(true);
-        when(repository.findInbound(10, 20)).thenReturn(new InboundSnapshot(20L, 10L, "INBOUNDED", 4));
+        when(repository.findInbound(10, 20)).thenReturn(new InboundSnapshot(20L, 10L, "WAIT_SPLIT", 4));
         PreloadPlanEntity plan = new PreloadPlanEntity();
         plan.setTenantId(10L); plan.setInboundId(20L); plan.setStatus("CONFIRMING"); plan.setVersion(1);
         plan.setItemsJson("[]");