优化

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

@@ -68,6 +68,33 @@ paths:
       parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
       responses:
         '200': {$ref: '#/components/responses/ConfirmedDetailResponse'}
+  /api/platform/v1/first-leg/loading-lists/{planId}/customs:
+    get:
+      summary: 查询装柜清单出口报关文档
+      x-permission: platform:firstleg:loading-list:view
+      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
+      responses:
+        '200': {$ref: '#/components/responses/BusinessDocumentResponse'}
+  /api/platform/v1/first-leg/loading-lists/{planId}/customs/document:
+    post:
+      summary: 上传或替换装柜清单出口报关文档
+      x-permission: platform:firstleg:customs:manage
+      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/DocumentAttachRequest'}}}
+      responses:
+        '200': {$ref: '#/components/responses/BusinessDocumentResponse'}
+  /api/platform/v1/first-leg/loading-lists/{planId}/customs/complete:
+    post:
+      summary: 点击完成出口报关
+      x-permission: platform:firstleg:customs:manage
+      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/DocumentCompleteRequest'}}}
+      responses:
+        '200': {$ref: '#/components/responses/BusinessDocumentResponse'}
 components:
   parameters:
     PlanId:
@@ -132,6 +159,9 @@ components:
     ConfirmedDetailResponse:
       description: 装柜清单详情查询或确认成功，也可能返回业务失败
       content: {application/json: {schema: {$ref: '#/components/schemas/ConfirmedDetailEnvelope'}}}
+    BusinessDocumentResponse:
+      description: 报关文档查询或操作结果
+      content: {application/json: {schema: {$ref: '#/components/schemas/BusinessDocumentEnvelope'}}}
   schemas:
     LongId:
       type: string
@@ -182,6 +212,14 @@ components:
             data:
               allOf: [{$ref: '#/components/schemas/ConfirmedDetail'}]
               nullable: true
+    BusinessDocumentEnvelope:
+      allOf:
+        - {$ref: '#/components/schemas/ApiEnvelope'}
+        - type: object
+          properties:
+            data:
+              allOf: [{$ref: '#/components/schemas/BusinessDocument'}]
+              nullable: true
     PreloadPage:
       type: object
       required: [records, page, size, total, pages]
@@ -319,3 +357,34 @@ components:
         voyageNo: {type: string, maxLength: 64, nullable: true, description: 航次}
         expectedVersion: {type: integer, format: int32, minimum: 0, description: 当前乐观锁版本}
         operationReason: {type: string, maxLength: 500, nullable: true, description: 操作原因}
+    DocumentAttachRequest:
+      type: object
+      required: [fileId, expectedVersion]
+      additionalProperties: false
+      properties:
+        fileId: {$ref: '#/components/schemas/LongId'}
+        expectedVersion: {type: integer, format: int32, minimum: 0}
+        operationReason: {type: string, maxLength: 500, nullable: true}
+    DocumentCompleteRequest:
+      type: object
+      required: [expectedVersion]
+      additionalProperties: false
+      properties:
+        expectedVersion: {type: integer, format: int32, minimum: 0}
+        operationReason: {type: string, maxLength: 500, nullable: true}
+    BusinessDocument:
+      type: object
+      required: [id, documentType, fileId, fileName, fileHash, uploadedBy, uploadedAt, version]
+      properties:
+        id: {$ref: '#/components/schemas/LongId'}
+        documentType: {type: string, enum: [CUSTOMS_DECLARATION]}
+        fileId: {$ref: '#/components/schemas/LongId'}
+        fileName: {type: string}
+        fileHash: {type: string, pattern: '^[0-9a-fA-F]{64}$'}
+        uploadedBy: {$ref: '#/components/schemas/LongId'}
+        uploadedByName: {type: string, nullable: true}
+        uploadedAt: {type: string, format: date-time}
+        completedBy: {$ref: '#/components/schemas/NullableLongId'}
+        completedByName: {type: string, nullable: true}
+        completedAt: {type: string, format: date-time, nullable: true}
+        version: {type: integer, format: int32, minimum: 0}