优化

firstleg/src/main/resources/openapi/customs-v1.yaml

@@ -55,6 +55,8 @@ paths:
     parameters: [{$ref: '#/components/parameters/CaseId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
     post:
       summary: Submit to customs agent and freeze approved file versions in a batch snapshot
+      description: customsAgentId must identify an ACTIVE Warehouse supplier in category CUSTOMS; the persisted agent name is resolved server-side and free text cannot bypass supplier validation.
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/SubmitBatchRequest'}}}}
       responses: {'200': {description: Submission batch}}
   /api/platform/v1/customs/submission-batches/{batchId}/receipts:
     parameters:
@@ -91,3 +93,13 @@ components:
       in: path
       required: true
       schema: {type: string, pattern: '^[1-9][0-9]*$'}
+  schemas:
+    SubmitBatchRequest:
+      type: object
+      required: [customsAgentId, expectedVersion]
+      properties:
+        customsAgentId: {type: integer, format: int64, minimum: 1, description: ACTIVE Warehouse supplier ID validated as CUSTOMS.}
+        customsAgentName: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint; persisted name always comes from Warehouse.}
+        externalReference: {type: string, maxLength: 128, nullable: true}
+        note: {type: string, maxLength: 500, nullable: true}
+        expectedVersion: {type: integer, minimum: 0}

firstleg/src/main/resources/openapi/ocean-bookings-v1.yaml

@@ -52,6 +52,8 @@ components:
         channelCode: {type: string, maxLength: 64, description: Selected from GET /api/platform/v1/ocean-bookings/channels; server validates it against the current ACTIVE price book and freezes channelName.}
         warehouseId: {type: integer, format: int64, minimum: 1}
         warehouseName: {type: string, maxLength: 128}
+        bookingAgentId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional ACTIVE Warehouse supplier ID validated as BOOKING with INTERNATIONAL scope.}
+        bookingAgentName: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint only; the persisted snapshot always comes from Warehouse and cannot be supplied without bookingAgentId.}
         serviceTerm: {type: string, maxLength: 32, description: Required free-text Service Term snapshot, for example CY-CY.}
         freightTerm: {type: string, maxLength: 32, description: Required free-text Freight Term snapshot, for example NINGBO.}
         billOfLadingNo: {type: string, maxLength: 128, description: Required offline-confirmed bill of lading snapshot.}

firstleg/src/main/resources/openapi/truck-appointments-v1.yaml

@@ -160,6 +160,8 @@ components:
         oceanBookingId: {type: integer, format: int64, minimum: 1}
         containerBookingId: {type: integer, format: int64, minimum: 1}
         loadingPlanId: {type: integer, format: int64, minimum: 1}
+        carrierId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional ACTIVE Warehouse supplier ID validated as TRUCKING.}
+        carrierName: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint only; the persisted snapshot comes from Warehouse and cannot be supplied without carrierId.}
         plannedLoadingAt: {type: string, format: date-time}
         expectedVersion: {type: integer, minimum: 0}
     DetailStableReferences: