优化

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

@@ -250,11 +250,11 @@ paths:
         '403': {description: 无新增按钮权限}
   /api/platform/v1/containers/{id}/ocean-booking-link:
     post:
-      summary: 将内部模拟柜关联到真实已确认订舱柜
-      description: 需要 platform:firstleg:container:edit；首次关联允许 WAIT_LOADING 或已有预排货的 EDITING 柜，保留原 containerBookingId/cabinetNo/loadingPlanId/items；存在 PDA、有效装柜证据、业务单证或已进入 LOADING/COMPLETED 等不可逆事实时拒绝。
+      summary: 将内部模拟柜原地合并为指定真实订舱柜
+      description: 需要 platform:firstleg:container:edit；请求指定未消费且尚无装柜计划/PDA/证据/单证的 realContainerBookingId。首次关联允许 WAIT_LOADING 或已有预排货的 EDITING 模拟柜，保留原 containerBookingId/cabinetNo/loadingPlanId/items，将真实柜 containerNo、订舱、运输和范围快照原子复制到模拟柜并把 allocation 改指模拟柜；原真实柜置 MERGED 且不再出现在正常货柜列表。存在跨仓、跨渠道、柜型规格不一致、PDA、有效装柜证据、业务单证或 LOADING/COMPLETED 等事实时拒绝。
       parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
       requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ContainerOceanBookingLinkRequest'}}}}
-      responses: {'200': {description: 关联后的同一 containerBookingId/cabinetNo}}
+      responses: {'200': {description: 合并后的同一模拟柜 containerBookingId/cabinetNo；列表仅保留这一条 ACTIVE 操作身份}}
     delete:
       summary: 解除内部模拟柜的真实订舱关联
       description: 需要 platform:firstleg:container:edit；解绑或换绑仅允许完全空的 WAIT_LOADING 模拟柜；任何排货、PDA、有效装柜证据或业务单证事实均拒绝。
@@ -1212,13 +1212,16 @@ components:
             pages: {type: string, pattern: '^[0-9]+$'}
     ContainerBooking:
       type: object
-      required: [id, bookingNo, cabinetNo, warehouseId, warehouseName, containerType, capacityCbm, maxWeightKg, planStatus, version]
+      required: [id, bookingNo, cabinetNo, sourceType, recordStatus, warehouseId, warehouseName, containerType, capacityCbm, maxWeightKg, planStatus, version]
       properties:
         id: {type: string, pattern: '^[1-9][0-9]*$'}
         planId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: 关联智能装柜计划ID；未创建计划时为空}
         bookingNo: {type: string, maxLength: 40}
         containerNo: {type: string, maxLength: 64, nullable: true}
         cabinetNo: {type: string, maxLength: 64}
+        sourceType: {type: string, enum: [SIMULATION, OCEAN_BOOKING], description: SIMULATION 为内部模拟柜；OCEAN_BOOKING 为订舱登记直接生成的真实柜}
+        recordStatus: {type: string, enum: [ACTIVE, MERGED], description: 正常列表和详情仅返回 ACTIVE；真实订舱柜被模拟柜消费后变为 MERGED 且不再作为可操作柜返回}
+        mergedIntoContainerBookingId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true, description: MERGED 源真实柜指向保留的模拟柜稳定 containerBookingId；ACTIVE 时为空}
         channelCode: {type: string, maxLength: 64, nullable: true, description: Missing legacy snapshots are blocked from loading until explicitly backfilled}
         channelName: {type: string, maxLength: 128, nullable: true}
         oceanBookingId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
@@ -1456,10 +1459,9 @@ components:
         maxWeightKg: {type: number, minimum: 0, exclusiveMinimum: true, description: 必须等于柜型固定限重}
     ContainerOceanBookingLinkRequest:
       type: object
-      required: [oceanBookingId, requirementId, expectedVersion]
+      required: [realContainerBookingId, expectedVersion]
       properties:
-        oceanBookingId: {type: integer, format: int64, minimum: 1}
-        requirementId: {type: integer, format: int64, minimum: 1}
+        realContainerBookingId: {type: integer, format: int64, minimum: 1, description: 订舱创建的 OCEAN_BOOKING/ACTIVE 真实柜ID；成功合并后该来源记录转为 MERGED}
         expectedVersion: {type: integer, minimum: 0}
     ContainerOceanBookingUnlinkRequest:
       type: object

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

@@ -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]