优化
This commit is contained in:
@@ -1,218 +1,71 @@
|
||||
openapi: 3.0.3
|
||||
info: {title: Phase 3 Ocean Booking API, version: 1.1.0}
|
||||
info: {title: Ocean Booking API, version: 2.0.0}
|
||||
paths:
|
||||
/api/platform/v1/ocean-bookings/channels:
|
||||
get:
|
||||
summary: List logistics channels from the current ACTIVE price book for an origin warehouse
|
||||
description: 'Requires platform:firstleg:ocean-booking:list. Returns only channels with an ACTIVE price row; the selected channel name is frozen server-side when the offline-confirmed booking is registered.'
|
||||
parameters:
|
||||
- {name: originWarehouseId, in: query, required: true, schema: {type: integer, format: int64, minimum: 1}}
|
||||
responses: {'200': {description: Available channel options, content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/ChannelOption'}}}}}}
|
||||
/api/platform/v1/ocean-bookings:
|
||||
get:
|
||||
summary: List only real confirmed booking records
|
||||
description: 'Requires platform:firstleg:ocean-booking:list. The operational list exposes only CONFIRMED, CHANGE_PENDING, RELEASED and CANCELLED bookings; DRAFT is internal to the create transaction and legacy SUBMITTED/FAILED values are invalid.'
|
||||
parameters:
|
||||
- {name: customerId, in: query, schema: {type: integer, format: int64, minimum: 1}}
|
||||
- {name: status, in: query, schema: {type: string, enum: [CONFIRMED, CHANGE_PENDING, RELEASED, CANCELLED]}}
|
||||
- {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; each record follows OceanBookingSummary
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
type: object
|
||||
properties:
|
||||
data:
|
||||
type: object
|
||||
properties:
|
||||
records: {type: array, items: {$ref: '#/components/schemas/OceanBookingSummary'}}
|
||||
get: {summary: List DRAFT and RELEASED bookings, responses: {'200': {description: Booking page}}}
|
||||
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.'
|
||||
summary: Create an editable DRAFT
|
||||
description: Creates only the booking aggregate and container requirements; no containerNo, container row, or allocation is created.
|
||||
parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
|
||||
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/CreateRequest'}}}}
|
||||
responses: {'200': {description: CONFIRMED real booking detail, content: {application/json: {schema: {$ref: '#/components/schemas/Detail'}}}}}
|
||||
responses: {'200': {description: DRAFT detail}}
|
||||
/api/platform/v1/ocean-bookings/{oceanBookingId}:
|
||||
get: {summary: Get booking detail, parameters: [{$ref: '#/components/parameters/OceanBookingId'}], responses: {'200': {description: Detail}}}
|
||||
put:
|
||||
summary: Replace a DRAFT
|
||||
parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
|
||||
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/UpdateRequest'}}}}
|
||||
responses: {'200': {description: Updated DRAFT}}
|
||||
delete:
|
||||
summary: Delete a DRAFT; RELEASED is immutable
|
||||
parameters: [{$ref: '#/components/parameters/OceanBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
|
||||
requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ActionRequest'}}}}
|
||||
responses: {'200': {description: Deleted}}
|
||||
/api/platform/v1/ocean-bookings/{oceanBookingId}/release:
|
||||
post:
|
||||
summary: Release an already registered booking and synchronize associated cabinet transport snapshots
|
||||
description: 'The transport fields were registered at create time. The request must repeat the same bill of lading, vessel, voyage, ETD and ETA values; mismatches are rejected. This action does not create cabinets, change channels, replace cabinetNo, or recreate loading plans.'
|
||||
summary: Validate and permanently release a DRAFT
|
||||
description: Release validates the persisted aggregate and 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}:
|
||||
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}}
|
||||
/api/platform/v1/ocean-bookings/channels:
|
||||
get: {summary: List ACTIVE channels for an origin warehouse, responses: {'200': {description: Channel options}}}
|
||||
components:
|
||||
parameters:
|
||||
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:
|
||||
CreateRequest: {type: object, required: [expectedVersion, data], properties: {expectedVersion: {type: integer, enum: [0]}, data: {$ref: '#/components/schemas/DraftData'}}}
|
||||
UpdateRequest: {type: object, required: [expectedVersion, data], properties: {expectedVersion: {type: integer, minimum: 0}, data: {$ref: '#/components/schemas/DraftData'}}}
|
||||
DraftData:
|
||||
type: object
|
||||
required: [id, bookingNo, status, billOfLadingNo, vesselName, voyageNo, estimatedSailingAt, estimatedArrivalAt, containerCount, version]
|
||||
description: Fields may be incomplete in DRAFT. RELEASE validates the complete persisted aggregate.
|
||||
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}
|
||||
channelCode: {type: string, nullable: true}
|
||||
warehouseId: {type: integer, format: int64, nullable: true}
|
||||
billOfLadingNo: {type: string, nullable: true}
|
||||
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}
|
||||
vesselName: {type: string, nullable: true}
|
||||
voyageNo: {type: string, nullable: true}
|
||||
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]
|
||||
properties:
|
||||
expectedVersion: {type: integer, enum: [0]}
|
||||
data: {$ref: '#/components/schemas/DraftData'}
|
||||
DraftData:
|
||||
type: object
|
||||
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, 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 only as category BOOKING; booking suppliers do not use domestic/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.}
|
||||
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.}
|
||||
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: [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}
|
||||
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]
|
||||
properties:
|
||||
priceBookVersionId: {type: integer, format: int64}
|
||||
channelCode: {type: string, maxLength: 64}
|
||||
channelName: {type: string, maxLength: 128}
|
||||
priceModel: {type: string}
|
||||
pricingTaxModes: {type: array, items: {type: string}}
|
||||
ActionRequest:
|
||||
type: object
|
||||
required: [expectedVersion]
|
||||
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}
|
||||
placeOfDelivery: {type: string, nullable: true}
|
||||
serviceTerm: {type: string, nullable: true}
|
||||
freightTerm: {type: string, nullable: true}
|
||||
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]
|
||||
properties:
|
||||
expectedVersion: {type: integer, minimum: 0}
|
||||
billOfLadingNo: {type: string, maxLength: 128}
|
||||
vesselName: {type: string, maxLength: 128}
|
||||
voyageNo: {type: string, maxLength: 64}
|
||||
estimatedSailingAt: {type: string, format: date-time}
|
||||
estimatedArrivalAt: {type: string, format: date-time}
|
||||
reason: {type: string, maxLength: 1000}
|
||||
remark: {type: string, nullable: true}
|
||||
parties: {type: array, nullable: true, items: {$ref: '#/components/schemas/PartyRequest'}}
|
||||
containerRequirements: {type: array, nullable: true, items: {$ref: '#/components/schemas/ContainerRequirementRequest'}}
|
||||
PartyRequest: {type: object, required: [partyType, partyName], properties: {partyType: {type: string, enum: [SHIPPER, CONSIGNEE, NOTIFY_PARTY]}, partyName: {type: string}, address: {type: string, nullable: true}, contactName: {type: string, nullable: true}, contactPhone: {type: string, nullable: true}}}
|
||||
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}}}
|
||||
Detail: {type: object, required: [oceanBooking, parties, containerRequirements, containers, histories], properties: {oceanBooking: {type: object}, parties: {type: array}, containerRequirements: {type: array}, containers: {type: array, description: Existing containers allocated after port pickup linking}, histories: {type: array}}}
|
||||
|
||||
Reference in New Issue
Block a user