优化

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]