feat(firstleg): capture container number at pickup

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

@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
   title: Truck Appointment API
   version: 1.3.0
-  description: Every truck appointment must select one RELEASED ocean booking and one ACTIVE real-numbered container already allocated to that booking. The bill-of-lading number is frozen from the booking, and the booking must own at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file under OCEAN_BOOKING_DOCUMENT. Booking and bill files are not owned by truck appointments. After a PDA loading transaction commits, the server best-effort completes the unique active appointment explicitly linked to that container in an isolated transaction; absence, duplicates or concurrent truck edits never roll back loading completion.
+  description: Every truck appointment must select one RELEASED ocean booking and its allocated ACTIVE internal container identity. A real ISO 6346 container number is not required for create, edit, submit or dispatch. PICKUP may omit it and still advances normally; when supplied, PICKUP atomically records it if still missing or reuses the existing valid number. The bill-of-lading number is frozen from the booking, and the booking must own at least one active BOOKING_CONFIRMATION or BILL_OF_LADING file under OCEAN_BOOKING_DOCUMENT. Booking and bill files are not owned by truck appointments. After a PDA loading transaction commits, the server best-effort completes the unique active appointment explicitly linked to that container in an isolated transaction; absence, duplicates or concurrent truck edits never roll back loading completion.
 paths:
   /api/platform/v1/truck-appointments:
     get:
@@ -20,7 +20,7 @@ paths:
                     properties:
                       records: {type: array, items: {$ref: '#/components/schemas/DetailStableReferences'}}
     post:
-      summary: Create a truck appointment for a released booking and its allocated real container
+      summary: Create a truck appointment for a released booking and its allocated internal container
       description: If the real container already has a non-terminal appointment, the server returns A0409 with the existing appointment number and instructs the operator to continue editing. This duplicate guard runs before booking-document validation; the database unique key provides the same response for concurrent creates.
       requestBody:
         required: true
@@ -53,7 +53,7 @@ paths:
       - {$ref: '#/components/parameters/RequestHash'}
     post:
       summary: Apply an idempotent appointment lifecycle action
-      description: ARRIVE, LOAD and DEPART persist their actual event timestamps atomically with the status transition.
+      description: PICKUP accepts optional containerNo. Omitting it never blocks the transition to PICKUP_IN_PROGRESS; when supplied, the server atomically records it on the linked internal container if missing. An existing valid ISO 6346 number may be omitted or resubmitted unchanged; a different value is rejected and must use the preload correction flow. Other actions reject containerNo. ARRIVE, LOAD and DEPART persist their actual event timestamps atomically with the status transition.
       requestBody:
         required: true
         content:
@@ -176,13 +176,14 @@ components:
       properties:
         expectedVersion: {type: integer, minimum: 0}
         reason: {type: string, maxLength: 500}
+        containerNo: {type: string, maxLength: 32, nullable: true, description: Optional and only valid for PICKUP. Omission does not block PICKUP; when supplied it is normalized and validated as unique ISO 6346 before being written atomically. A different value from an existing number is rejected and must use preload correction.}
     SaveRequest:
       type: object
       required: [oceanBookingId, containerBookingId, carrierId, plannedLoadingAt, expectedVersion]
       properties:
         outboundOrderId: {type: integer, format: int64, minimum: 1, nullable: true}
         oceanBookingId: {type: integer, format: int64, minimum: 1, description: Required RELEASED booking; must own an active BOOKING_CONFIRMATION or BILL_OF_LADING file.}
-        containerBookingId: {type: integer, format: int64, minimum: 1, description: Required ACTIVE container already allocated to oceanBookingId and carrying a valid unique ISO 6346 container number.}
+        containerBookingId: {type: integer, format: int64, minimum: 1, description: Required ACTIVE internal container already allocated to oceanBookingId. Its real ISO 6346 number may remain empty until PICKUP.}
         loadingPlanId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional loading-plan association. It may be supplied only with containerBookingId and must be that container's current plan.}
         warehouseId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional warehouse scope. Linked booking/container warehouse facts must agree; when omitted the linked fact is frozen if available.}
         carrierId: {type: integer, format: int64, minimum: 1, description: Required ACTIVE Warehouse supplier ID validated as TRUCKING.}