优化

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]