优化

2026-08-17 13:24:48 +08:00
parent ac6cf9c904
commit 6739c83467
43 changed files with 1049 additions and 315 deletions
@@ -21,10 +21,10 @@ paths:
      responses: {'200': {description: Operational real booking page}}
    post:
      summary: Register an offline-confirmed ocean booking with complete transport snapshots
-      description: 'Requires platform:firstleg:ocean-booking:create. The booking has already been completed offline, so registration persists it directly as CONFIRMED. RELEASED remains a separate later action.'
+      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.'
      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateRequest'}}}}
-      responses: {'200': {description: CONFIRMED real booking detail}}
+      responses: {'200': {description: CONFIRMED real booking detail, content: {application/json: {schema: {$ref: '#/components/schemas/Detail'}}}}}
  /api/platform/v1/ocean-bookings/{oceanBookingId}/release:
    post:
      summary: Release an already registered booking and synchronize associated cabinet transport snapshots
@@ -32,6 +32,33 @@ paths:
      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}:
+    get:
+      summary: Get an ocean booking with its real container units
+      description: Requires platform:firstleg:ocean-booking:list.
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}]
+      responses: {'200': {description: Booking detail, content: {application/json: {schema: {$ref: '#/components/schemas/Detail'}}}}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/cancel:
+    post:
+      summary: Cancel a confirmed or change-pending real booking
+      description: Requires platform:firstleg:ocean-booking:cancel. A non-blank reason is required; RELEASED bookings are irreversible.
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ActionRequest'}}}}
+      responses: {'200': {description: CANCELLED detail}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/change-request:
+    post:
+      summary: Request a voyage change for a confirmed booking
+      description: Requires platform:firstleg:ocean-booking:change. Current transport snapshots remain active until change-confirm succeeds.
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ChangeRequest'}}}}
+      responses: {'200': {description: CHANGE_PENDING detail}}
+  /api/platform/v1/ocean-bookings/{oceanBookingId}/change-confirm:
+    post:
+      summary: Confirm a pending voyage change
+      description: Requires platform:firstleg:ocean-booking:change.
+      parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ActionRequest'}}}}
+      responses: {'200': {description: CONFIRMED detail with the pending voyage snapshots applied}}
 components:
  parameters:
    OceanBookingId: {name: oceanBookingId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
@@ -45,13 +72,14 @@ components:
        data: {$ref: '#/components/schemas/DraftData'}
    DraftData:
      type: object
-      required: [channelCode, warehouseId, warehouseName, billOfLadingNo, vesselName, voyageNo, serviceTerm, freightTerm, estimatedSailingAt, estimatedArrivalAt, parties, containerRequirements]
+      required: [channelCode, warehouseId, billOfLadingNo, vesselName, voyageNo, serviceTerm, freightTerm, estimatedSailingAt, estimatedArrivalAt, parties, containers]
      properties:
        customerId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional customer snapshot; must be supplied together with customerName.}
        customerName: {type: string, maxLength: 128, nullable: true, description: Optional customer snapshot; must be supplied together with customerId.}
        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}
+        warehouseId: {type: integer, format: int64, minimum: 1, description: ACTIVE domestic transit warehouse ID; warehouseName is resolved and frozen server-side.}
+        shippingCompanyId: {type: integer, format: int64, minimum: 1, nullable: true, description: Optional shipping-company master-data ID; the carrier is independent from the logistics channel and booking-agent Supplier.}
+        shippingCompanyName: {type: string, maxLength: 128, nullable: true, description: Optional shipping-company name snapshot.}
        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.}
@@ -59,19 +87,62 @@ components:
        billOfLadingNo: {type: string, maxLength: 128, description: Required offline-confirmed bill of lading snapshot.}
        vesselName: {type: string, maxLength: 128, description: Required offline-confirmed vessel snapshot.}
        voyageNo: {type: string, maxLength: 64, description: Required offline-confirmed voyage snapshot.}
+        departurePortCode: {type: string, maxLength: 32, nullable: true}
+        departurePortName: {type: string, maxLength: 128, nullable: true}
+        destinationPortCode: {type: string, maxLength: 32, nullable: true}
+        destinationPortName: {type: string, maxLength: 128, nullable: true}
+        placeOfDelivery: {type: string, maxLength: 128, nullable: true}
        estimatedSailingAt: {type: string, format: date-time, description: Required offline-confirmed ETD snapshot.}
        estimatedArrivalAt: {type: string, format: date-time, description: Required offline-confirmed ETA snapshot; cannot be earlier than ETD.}
-        parties: {type: array, minItems: 3, items: {type: object}}
-        containerRequirements: {type: array, minItems: 1, maxItems: 20, items: {$ref: '#/components/schemas/ContainerRequirement'}}
-    ContainerRequirement:
+        remark: {type: string, maxLength: 1000, nullable: true}
+        parties: {type: array, minItems: 3, maxItems: 3, items: {$ref: '#/components/schemas/PartyRequest'}}
+        containers: {type: array, minItems: 1, maxItems: 20, items: {$ref: '#/components/schemas/ContainerRequest'}}
+    PartyRequest:
      type: object
-      required: [containerType, containerKind, capacityCbm, maxWeightKg, quantity]
+      required: [partyType, partyName]
      properties:
+        partyType: {type: string, enum: [SHIPPER, CONSIGNEE, NOTIFY_PARTY]}
+        partyName: {type: string, maxLength: 255}
+        address: {type: string, maxLength: 1000, nullable: true}
+        contactName: {type: string, maxLength: 128, nullable: true}
+        contactPhone: {type: string, maxLength: 64, nullable: true}
+    ContainerRequest:
+      type: object
+      required: [containerNo, containerType, containerKind, capacityCbm, maxWeightKg]
+      additionalProperties: false
+      properties:
+        containerNo: {type: string, minLength: 1, maxLength: 64, description: Required real container number; unique across all ACTIVE and unmerged container records.}
        containerType: {type: string, enum: [20GP, 40GP, 40HC, 40NR, 45HC], description: Platform-controlled container type}
        containerKind: {type: string, maxLength: 32}
        capacityCbm: {type: number, exclusiveMinimum: true, minimum: 0, description: Must match the fixed platform specification for containerType}
        maxWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, description: Must match the fixed platform specification for containerType}
-        quantity: {type: integer, minimum: 1}
+    Detail:
+      type: object
+      required: [oceanBooking, parties, containers, histories]
+      properties:
+        oceanBooking: {type: object, description: Ocean booking aggregate and frozen transport snapshots.}
+        parties: {type: array, items: {type: object}}
+        containers: {type: array, items: {$ref: '#/components/schemas/RealContainer'}}
+        histories: {type: array, items: {type: object}}
+    RealContainer:
+      type: object
+      required: [containerBookingId, cabinetNo, containerNo, requirementId, allocationId, containerType, containerKind, capacityCbm, maxWeightKg, warehouseId, warehouseName, channelCode, channelName]
+      properties:
+        containerBookingId: {type: integer, format: int64, minimum: 1, description: Current ACTIVE operational container identity.}
+        cabinetNo: {type: string, maxLength: 64, description: Stable server-generated internal cabinet number.}
+        containerNo: {type: string, maxLength: 64, description: Unique real container number.}
+        requirementId: {type: integer, format: int64, minimum: 1}
+        allocationId: {type: integer, format: int64, minimum: 1}
+        containerType: {type: string, enum: [20GP, 40GP, 40HC, 40NR, 45HC]}
+        containerKind: {type: string, maxLength: 32}
+        capacityCbm: {type: number}
+        maxWeightKg: {type: number}
+        warehouseId: {type: integer, format: int64, minimum: 1}
+        warehouseName: {type: string, maxLength: 128}
+        channelCode: {type: string, maxLength: 64}
+        channelName: {type: string, maxLength: 128}
+        customerId: {type: integer, format: int64, minimum: 1, nullable: true}
+        customerName: {type: string, maxLength: 128, nullable: true}
    ChannelOption:
      type: object
      required: [priceBookVersionId, channelCode, channelName, priceModel, pricingTaxModes]
@@ -84,7 +155,17 @@ components:
    ActionRequest:
      type: object
      required: [expectedVersion]
-      properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, maxLength: 1000}}
+      properties: {expectedVersion: {type: integer, minimum: 0}, reason: {type: string, maxLength: 1000, nullable: true}}
+    ChangeRequest:
+      type: object
+      required: [expectedVersion, vesselName, voyageNo, reason]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        vesselName: {type: string, maxLength: 128}
+        voyageNo: {type: string, maxLength: 64}
+        estimatedSailingAt: {type: string, format: date-time, nullable: true}
+        estimatedArrivalAt: {type: string, format: date-time, nullable: true}
+        reason: {type: string, maxLength: 1000}
    ReleaseRequest:
      type: object
      required: [expectedVersion, billOfLadingNo, vesselName, voyageNo, estimatedSailingAt, estimatedArrivalAt]