feat(firstleg): enforce booking-owned truck workflow

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

@@ -1,5 +1,8 @@
 openapi: 3.0.3
-info: {title: Ocean Booking API, version: 2.0.0}
+info:
+  title: Ocean Booking API
+  version: 2.1.0
+  description: Booking-owned files use File businessType OCEAN_BOOKING_DOCUMENT and businessId=oceanBookingId. Release requires at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file. Released bookings and their file links are permanently read-only.
 paths:
   /api/platform/v1/ocean-bookings:
     get:
@@ -29,10 +32,76 @@ paths:
   /api/platform/v1/ocean-bookings/{oceanBookingId}/release:
     post:
       summary: Validate and permanently release a DRAFT
-      description: Release validates the persisted aggregate and never requires or creates a real container number.
+      description: Release validates the persisted aggregate plus at least one active booking-owned BOOKING_CONFIRMATION or BILL_OF_LADING file. It never requires or creates a real container number.
       parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ReleaseRequest'}}}}
       responses: {'200': {description: RELEASED detail}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/documents:
+    get:
+      summary: List current and invalidated booking-owned file references
+      x-permission: platform:firstleg:ocean-booking:list
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}]
+      responses:
+        '200': {description: Booking document history, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentListResponse'}}}}
+    post:
+      summary: Reference an existing File object in a DRAFT booking
+      description: File scope must be customerId + OCEAN_BOOKING_DOCUMENT + oceanBookingId. The booking version is incremented atomically.
+      x-permission: platform:firstleg:ocean-booking:edit
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentRequest'}}}}
+      responses:
+        '200': {description: Created reference and latest booking version, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentMutationResponse'}}}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/documents/upload:
+    post:
+      summary: Upload and associate a file with a DRAFT booking
+      description: Uploads through File businessType OCEAN_BOOKING_DOCUMENT and increments the booking version atomically.
+      x-permission: platform:firstleg:ocean-booking:edit
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              type: object
+              required: [expectedVersion, documentType, file]
+              properties:
+                expectedVersion: {type: integer, minimum: 0}
+                documentType: {$ref: '#/components/schemas/DocumentType'}
+                file: {type: string, format: binary}
+      responses:
+        '200': {description: Created reference and latest booking version, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentMutationResponse'}}}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/documents/{documentId}:
+    delete:
+      summary: Logically invalidate a booking file reference while DRAFT
+      description: The File object and immutable reference history are retained; RELEASED bookings are read-only.
+      x-permission: platform:firstleg:ocean-booking:edit
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/DocumentId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentActionRequest'}}}}
+      responses:
+        '200': {description: Invalidation result and latest booking version, content: {application/json: {schema: {$ref: '#/components/schemas/DocumentInvalidationResponse'}}}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/documents/{documentId}/download:
+    get:
+      summary: Download an active booking-owned file
+      x-permission: platform:firstleg:ocean-booking:list
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/DocumentId'}]
+      responses:
+        '200': {description: Original file bytes, content: {application/octet-stream: {schema: {type: string, format: binary}}}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/prints/shipping-instruction:
+    get:
+      summary: Render the released booking as an export shipping instruction PDF
+      description: Firstleg maps the authoritative released aggregate to SEA_FREIGHT_SHIPPING_INSTRUCTION_A4_V1 and synchronously proxies the generated PDF.
+      x-permission: platform:firstleg:ocean-booking:list
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}]
+      responses:
+        '200': {description: PDF or a business-error JSON envelope, content: {application/pdf: {schema: {type: string, format: binary}}, application/json: {schema: {type: object}}}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/prints/bill-of-lading-confirmation:
+    get:
+      summary: Render the released booking as a bill-of-lading confirmation PDF
+      description: Firstleg maps the authoritative released aggregate to BILL_OF_LADING_CONFIRMATION_A4_V1 and synchronously proxies the generated PDF.
+      x-permission: platform:firstleg:ocean-booking:list
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}]
+      responses:
+        '200': {description: PDF or a business-error JSON envelope, content: {application/pdf: {schema: {type: string, format: binary}}, application/json: {schema: {type: object}}}}
   /api/platform/v1/ocean-bookings/link-candidates:
     get:
       summary: Page released booking requirement candidates for one container
@@ -84,6 +153,7 @@ paths:
 components:
   parameters:
     OceanBookingId: {name: oceanBookingId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
+    DocumentId: {name: documentId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
     IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
   schemas:
     CreateRequest: {type: object, required: [expectedVersion, data], properties: {expectedVersion: {type: integer, enum: [0]}, data: {$ref: '#/components/schemas/DraftData'}}}
@@ -131,6 +201,55 @@ components:
     ContainerRequirementRequest: {type: object, required: [containerType, containerKind, quantity, capacityCbm, maxWeightKg], properties: {containerType: {type: string}, containerKind: {type: string}, quantity: {type: integer, minimum: 1}, capacityCbm: {type: number, exclusiveMinimum: true, minimum: 0}, maxWeightKg: {type: number, exclusiveMinimum: true, minimum: 0}}}
     ReleaseRequest: {type: object, required: [expectedVersion], properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, nullable: true}}}
     ActionRequest: {type: object, required: [expectedVersion], properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, nullable: true}}}
+    DocumentType: {type: string, enum: [BOOKING_CONFIRMATION, BILL_OF_LADING]}
+    DocumentRequest:
+      type: object
+      required: [expectedVersion, fileId, documentType]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        fileId: {type: integer, format: int64, minimum: 1}
+        documentType: {$ref: '#/components/schemas/DocumentType'}
+    DocumentActionRequest: {type: object, required: [expectedVersion], properties: {expectedVersion: {type: integer, minimum: 0}}}
+    OceanBookingDocument:
+      type: object
+      required: [id, oceanBookingId, fileId, documentType, fileName, valid, uploadedBy, uploadedAt]
+      properties:
+        id: {type: integer, format: int64}
+        oceanBookingId: {type: integer, format: int64}
+        fileId: {type: integer, format: int64}
+        documentType: {$ref: '#/components/schemas/DocumentType'}
+        fileName: {type: string}
+        fileHash: {type: string, nullable: true}
+        sizeBytes: {type: integer, format: int64, nullable: true}
+        contentType: {type: string, nullable: true}
+        valid: {type: boolean}
+        uploadedBy: {type: integer, format: int64}
+        uploadedByName: {type: string, nullable: true}
+        uploadedAt: {type: string, format: date-time}
+        invalidatedBy: {type: integer, format: int64, nullable: true}
+        invalidatedByName: {type: string, nullable: true}
+        invalidatedAt: {type: string, format: date-time, nullable: true}
+    DocumentMutation:
+      type: object
+      required: [document, bookingVersion]
+      properties:
+        document: {$ref: '#/components/schemas/OceanBookingDocument'}
+        bookingVersion: {type: integer, minimum: 1}
+    DocumentInvalidation:
+      type: object
+      required: [documentId, bookingVersion]
+      properties:
+        documentId: {type: integer, format: int64}
+        bookingVersion: {type: integer, minimum: 1}
+    DocumentListResponse:
+      type: object
+      properties: {code: {type: string, example: '200'}, data: {type: array, items: {$ref: '#/components/schemas/OceanBookingDocument'}}}
+    DocumentMutationResponse:
+      type: object
+      properties: {code: {type: string, example: '200'}, data: {$ref: '#/components/schemas/DocumentMutation'}}
+    DocumentInvalidationResponse:
+      type: object
+      properties: {code: {type: string, example: '200'}, data: {$ref: '#/components/schemas/DocumentInvalidation'}}
     ChannelOption:
       type: object
       required: [priceBookVersionId, channelCode, channelName, priceModel, pricingTaxModes]
@@ -189,7 +308,7 @@ components:
           description: Sum of all container requirement quantities; independent of allocation, linking or unlinking.
     Detail:
       type: object
-      required: [oceanBooking, parties, containerRequirements, containers, histories]
+      required: [oceanBooking, parties, containerRequirements, containers, documents, histories]
       properties:
         oceanBooking:
           type: object
@@ -198,4 +317,5 @@ components:
         parties: {type: array}
         containerRequirements: {type: array}
         containers: {type: array, description: Existing containers allocated after port pickup linking}
+        documents: {type: array, items: {$ref: '#/components/schemas/OceanBookingDocument'}, description: Current and invalidated booking-owned file references}
         histories: {type: array}