优化

2026-08-12 20:36:11 +08:00
parent 0380c0553b
commit 0ed1531683
26 changed files with 1690 additions and 15 deletions
@@ -243,6 +243,27 @@ paths:
      responses:
        '200': {description: 成功或状态、版本、重复号冲突}
        '403': {description: 无货柜编辑权限}
+  /api/platform/v1/containers/{id}/clearance:
+    get:
+      summary: 查询货柜目的港清关资料
+      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
+      responses: {'200': {description: 成功或货柜不存在}}
+  /api/platform/v1/containers/{id}/clearance/document:
+    post:
+      summary: 上传或替换货柜目的港清关资料
+      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/ContainerDocumentAttachRequest'}}}
+      responses: {'200': {description: 成功、文件归属不匹配或版本冲突}}
+  /api/platform/v1/containers/{id}/clearance/complete:
+    post:
+      summary: 点击完成目的港清关
+      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content: {application/json: {schema: {$ref: '#/components/schemas/ContainerDocumentCompleteRequest'}}}
+      responses: {'200': {description: 成功、未上传资料或版本冲突}}
  /api/platform/v1/first-leg/smart-loading/plans/by-booking/{bookingId}:
    get:
      summary: 按货柜恢复智能装柜草稿
@@ -1034,6 +1055,19 @@ components:
        voyageNo: {type: string, maxLength: 64, nullable: true}
        version: {type: integer, minimum: 0}
        reason: {type: string, maxLength: 500}
+    ContainerDocumentAttachRequest:
+      type: object
+      required: [fileId, expectedVersion]
+      properties:
+        fileId: {type: string, pattern: '^[1-9][0-9]*$'}
+        expectedVersion: {type: integer, minimum: 0}
+        operationReason: {type: string, maxLength: 500, nullable: true}
+    ContainerDocumentCompleteRequest:
+      type: object
+      required: [expectedVersion]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        operationReason: {type: string, maxLength: 500, nullable: true}
    MerchantInboundBillingEnvelope:
      type: object
      properties:
@@ -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}