优化

2026-08-13 11:57:33 +08:00
parent 5a48992d78
commit 16dc03a2e2
102 changed files with 3656 additions and 120 deletions
@@ -210,7 +210,7 @@ paths:
  /api/platform/v1/containers/{id}:
    get:
      summary: 查询平台货柜详情
-      description: 需要 platform:firstleg:container:view 权限
+      description: 需要 platform:firstleg:container:list 权限
      parameters:
        - {$ref: '#/components/parameters/ContainerBookingId'}
      responses:
@@ -25,8 +25,8 @@ paths:
  /api/platform/v1/first-leg/loading-plans/{planId}:
    get:
      summary: 查询预装清单详情
+      x-permission: platform:firstleg:preload:list
      description: 返回同一装柜计划的汇总、冻结明细和完整操作历史。
-      x-permission: platform:firstleg:preload:view
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
      responses:
        '200': {$ref: '#/components/responses/PreloadDetailResponse'}
@@ -63,15 +63,16 @@ paths:
  /api/platform/v1/first-leg/loading-lists/{planId}:
    get:
      summary: 查询装柜清单详情
-      description: 返回已确认计划的汇总、冻结明细和操作历史，全部只读。
-      x-permission: platform:firstleg:loading-list:view
+      description: 返回已确认计划的汇总、冻结明细和操作历史，全部只读；查看权限与分页列表权限独立。
+      x-permission: platform:firstleg:loading-list:list
      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
+      x-permission: platform:firstleg:loading-list:list
+      description: 查询出口报关文档；写入与完成继续要求 platform:firstleg:customs:manage。
      parameters: [{$ref: '#/components/parameters/PlanId'}, {$ref: '#/components/parameters/WarehouseId'}]
      responses:
        '200': {$ref: '#/components/responses/BusinessDocumentResponse'}
@@ -0,0 +1,60 @@
+openapi: 3.0.3
+info: {title: Firstleg Container Overview API, version: 1.0.0}
+paths:
+  /api/platform/v1/containers/{id}/overview:
+    get:
+      operationId: getContainerOverview
+      description: '权限：platform:firstleg:container:list'
+      parameters: [{$ref: '#/components/parameters/ContainerId'}]
+      responses: {'200': {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/OverviewEnvelope'}}}}}
+  /api/platform/v1/containers/{id}/exception:
+    parameters: [{$ref: '#/components/parameters/ContainerId'}]
+    post: {operationId: markContainerException, description: '权限：platform:firstleg:container:edit', parameters: [{name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}], requestBody: {$ref: '#/components/requestBodies/ExceptionRequest'}, responses: {'200': {description: OK}}}
+    delete: {operationId: cancelContainerException, description: '权限：platform:firstleg:container:edit', parameters: [{name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 128}}], requestBody: {$ref: '#/components/requestBodies/ExceptionRequest'}, responses: {'200': {description: OK}}}
+  /api/platform/v1/containers/{id}/documents/{documentType}:
+    get:
+      operationId: getContainerDocument
+      description: '权限：platform:firstleg:container:list；仅DO/PU，completed恒为false'
+      parameters: [{$ref: '#/components/parameters/ContainerId'}, {$ref: '#/components/parameters/DocumentType'}]
+      responses: {'200': {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentEnvelope'}}}}}
+  /api/platform/v1/containers/{id}/documents/{documentType}/upload:
+    post:
+      operationId: uploadContainerDocument
+      description: '权限：platform:firstleg:container:edit；仅DO/PU，无完成动作'
+      parameters: [{$ref: '#/components/parameters/ContainerId'}, {$ref: '#/components/parameters/DocumentType'}, {name: Idempotency-Key, in: header, required: true, schema: {type: string}}]
+      requestBody: {required: true, content: {multipart/form-data: {schema: {type: object, required: [file, expectedVersion], properties: {file: {type: string, format: binary}, expectedVersion: {type: integer, minimum: 0}, operationReason: {type: string, maxLength: 500}}}}}}
+      responses: {'200': {description: OK, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentEnvelope'}}}}}
+  /api/platform/v1/containers/{id}/documents/{documentType}/{fileId}/download:
+    get:
+      operationId: downloadContainerDocument
+      description: '权限：platform:firstleg:container:list；Firstleg代理File内部下载，不向调用方暴露内部令牌'
+      parameters: [{$ref: '#/components/parameters/ContainerId'}, {$ref: '#/components/parameters/DocumentType'}, {name: fileId, in: path, required: true, schema: {type: integer, format: int64}}]
+      responses: {'200': {description: file bytes, content: {application/octet-stream: {schema: {type: string, format: binary}}}}}
+components:
+  parameters:
+    ContainerId: {name: id, in: path, required: true, schema: {type: integer, format: int64}}
+    DocumentType: {name: documentType, in: path, required: true, schema: {type: string, enum: [DELIVERY_ORDER, PICKUP_ORDER]}, description: '通用单证仅支持DO/PU；清关使用 /clearance，出口报关使用 loading-list 专用接口'}
+  requestBodies:
+    ExceptionRequest: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ExceptionRequest'}}}}
+  schemas:
+    OverviewEnvelope: {type: object, properties: {code: {type: string}, message: {type: string}, data: {$ref: '#/components/schemas/Overview'}}}
+    DocumentEnvelope: {type: object, properties: {code: {type: string}, message: {type: string}, data: {$ref: '#/components/schemas/Document'}}}
+    Overview:
+      type: object
+      properties:
+        container: {$ref: '#/components/schemas/Container'}
+        loadingPlanId: {type: integer, format: int64}
+        pda: {$ref: '#/components/schemas/PdaSummary'}
+        documents: {type: array, items: {$ref: '#/components/schemas/Document'}}
+        exception: {$ref: '#/components/schemas/ExceptionState'}
+        exceptionHistory: {type: array, items: {$ref: '#/components/schemas/ExceptionHistory'}}
+        timeline: {type: array, items: {$ref: '#/components/schemas/TimelineEntry'}}
+    Container: {type: object, properties: {id: {type: integer, format: int64}, bookingNo: {type: string}, cabinetNo: {type: string}, containerNo: {type: string}, status: {type: string}, warehouseId: {type: integer, format: int64}, warehouseName: {type: string}, voyageNo: {type: string}, vesselName: {type: string}, version: {type: integer, minimum: 0}}}
+    PdaSummary: {type: object, properties: {taskId: {type: integer, format: int64}, loadingPlanId: {type: integer, format: int64}, containerBookingId: {type: integer, format: int64}, taskStatus: {type: string}, taskVersion: {type: integer}, itemCount: {type: integer}, completedItemCount: {type: integer}, unresolvedItemCount: {type: integer}, photoCounts: {type: array, items: {$ref: '#/components/schemas/PhotoCount'}}, photos: {type: array, items: {$ref: '#/components/schemas/Photo'}}, exceptionReasons: {type: array, items: {type: string}}}}
+    PhotoCount: {type: object, properties: {evidenceType: {type: string}, count: {type: integer}}}
+    Photo: {type: object, properties: {evidenceId: {type: integer, format: int64}, tenantId: {type: integer, format: int64}, inboundId: {type: integer, format: int64}, evidenceType: {type: string}, fileId: {type: integer, format: int64}, fileName: {type: string}, status: {type: string}, downloadPath: {type: string}, uploadedAt: {type: string, format: date-time}}}
+    Document: {type: object, properties: {id: {type: integer, format: int64}, documentType: {type: string}, fileId: {type: integer, format: int64}, fileName: {type: string}, fileHash: {type: string}, uploadedBy: {type: integer, format: int64}, uploadedByName: {type: string}, uploadedAt: {type: string, format: date-time}, version: {type: integer}, completed: {type: boolean}}}
+    ExceptionState: {type: object, properties: {active: {type: boolean}, reason: {type: string}, markedBy: {type: integer, format: int64}, markedByName: {type: string}, markedAt: {type: string, format: date-time}}}
+    ExceptionHistory: {type: object, properties: {id: {type: integer, format: int64}, action: {type: string, enum: [MARK, CANCEL]}, reason: {type: string}, operatorId: {type: integer, format: int64}, operatorName: {type: string}, occurredAt: {type: string, format: date-time}}}
+    TimelineEntry: {type: object, properties: {eventType: {type: string}, detail: {type: string}, operatorId: {type: integer, format: int64}, operatorName: {type: string}, occurredAt: {type: string, format: date-time}}}
+    ExceptionRequest: {type: object, required: [expectedVersion, reason], properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, maxLength: 500}}}