优化

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

@@ -18,7 +18,18 @@ paths:
         - {name: keyword, in: query, schema: {type: string, maxLength: 128}}
         - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
         - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
-      responses: {'200': {description: Operational real booking page}}
+      responses:
+        '200':
+          description: Operational real booking page; each record follows OceanBookingSummary
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  data:
+                    type: object
+                    properties:
+                      records: {type: array, items: {$ref: '#/components/schemas/OceanBookingSummary'}}
     post:
       summary: Register an offline-confirmed ocean booking with complete transport snapshots
       description: 'Requires platform:firstleg:ocean-booking:create. Registers every real container unit atomically, creates one stable fl_container_booking plus one requirement/allocation per container, and persists the booking directly as CONFIRMED. RELEASED remains a separate later action.'
@@ -64,6 +75,34 @@ components:
     OceanBookingId: {name: oceanBookingId, 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:
+    OceanBookingSummary:
+      type: object
+      required: [id, bookingNo, status, billOfLadingNo, vesselName, voyageNo, estimatedSailingAt, estimatedArrivalAt, containerCount, version]
+      properties:
+        id: {type: integer, format: int64}
+        bookingNo: {type: string}
+        status: {type: string, enum: [CONFIRMED, CHANGE_PENDING, RELEASED, CANCELLED]}
+        customerId: {type: integer, format: int64, nullable: true}
+        customerName: {type: string, nullable: true}
+        billOfLadingNo: {type: string}
+        shipperName: {type: string, nullable: true, description: SHIPPER party snapshot}
+        consigneeName: {type: string, nullable: true, description: CONSIGNEE party snapshot}
+        shippingCompanyId: {type: integer, format: int64, nullable: true}
+        shippingCompanyName: {type: string, nullable: true}
+        bookingAgentId: {type: integer, format: int64, nullable: true}
+        bookingAgentName: {type: string, nullable: true}
+        vesselName: {type: string}
+        voyageNo: {type: string}
+        departurePortCode: {type: string, nullable: true}
+        departurePortName: {type: string, nullable: true}
+        destinationPortCode: {type: string, nullable: true}
+        destinationPortName: {type: string, nullable: true}
+        estimatedSailingAt: {type: string, format: date-time}
+        estimatedArrivalAt: {type: string, format: date-time}
+        containerCount: {type: integer, format: int64, minimum: 0, description: ACTIVE real container units allocated to the booking}
+        createdByName: {type: string, nullable: true}
+        updatedAt: {type: string, format: date-time}
+        version: {type: integer, minimum: 0}
     CreateRequest:
       type: object
       required: [expectedVersion, data]