优化

2026-08-18 15:43:58 +08:00
parent 4e4d047862
commit 4b0b3e9172
71 changed files with 523 additions and 724 deletions
@@ -462,7 +462,6 @@ paths:
                length: {type: number, format: decimal, minimum: 0.001}
                width: {type: number, format: decimal, minimum: 0.001}
                height: {type: number, format: decimal, minimum: 0.001}
-                weight: {type: number, format: decimal, minimum: 0.001, nullable: true}
                machineNo: {type: string, maxLength: 64}
                measuredAt: {type: string, format: date-time, nullable: true}
                picture: {type: string, description: 'data:image/jpeg;base64,...'}
@@ -621,7 +620,6 @@ paths:
                    length: {type: number, format: double, minimum: 0.001}
                    width: {type: number, format: double, minimum: 0.001}
                    height: {type: number, format: double, minimum: 0.001}
-                    weight: {type: number, format: double, minimum: 0.001, nullable: true}
                    machineNo: {type: string, maxLength: 64}
                    measuredAt: {type: string, format: date-time}
                image: {type: string, format: binary}
@@ -653,7 +651,6 @@ paths:
                    length: {type: number, format: double, minimum: 0.001}
                    width: {type: number, format: double, minimum: 0.001}
                    height: {type: number, format: double, minimum: 0.001}
-                    weight: {type: number, format: double, minimum: 0.001, nullable: true}
                    machineNo: {type: string, maxLength: 64}
                    measuredAt: {type: string, format: date-time}
                image: {type: string, format: binary}
@@ -1245,9 +1242,7 @@ components:
        widthCm: {type: number, format: double, nullable: true}
        heightCm: {type: number, format: double, nullable: true}
        girthCm: {type: number, format: double, nullable: true}
-        unitWeightKg: {type: number, format: double, nullable: true}
        unitVolumeCbm: {type: number, format: double, nullable: true}
-        totalWeightKg: {type: number, format: double, nullable: true}
        totalVolumeCbm: {type: number, format: double, nullable: true}
        volumeWeightKg: {type: number, format: double, nullable: true}
        intelligentImageFileId:
@@ -1331,7 +1326,7 @@ components:
          items: {$ref: '#/components/schemas/InboundMeasurementItemRequest'}
    InboundMeasurementItemRequest:
      type: object
-      required: [inboundDetailId, itemNo, boxSpecification, packageCount, lengthCm, widthCm, heightCm, unitWeightKg]
+      required: [inboundDetailId, itemNo, boxSpecification, packageCount, lengthCm, widthCm, heightCm]
      additionalProperties: false
      properties:
        inboundDetailId: {type: string, pattern: '^[1-9][0-9]*$'}
@@ -1341,7 +1336,6 @@ components:
        lengthCm: {type: number, minimum: 0.001}
        widthCm: {type: number, minimum: 0.001}
        heightCm: {type: number, minimum: 0.001}
-        unitWeightKg: {type: number, minimum: 0.001}
        intelligentImageFileId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
        overLimitWarning: {type: string, maxLength: 500, nullable: true}
        outerLengthCm: {type: number, minimum: 0, nullable: true}
@@ -1729,7 +1723,6 @@ components:
        widthCm: {type: number, exclusiveMinimum: true, minimum: 0, example: 40.10}
        heightCm: {type: number, exclusiveMinimum: true, minimum: 0, example: 30.00}
        packageCount: {type: integer, minimum: 1, maximum: 1000000, example: 50}
-        unitWeightKg: {type: number, exclusiveMinimum: true, minimum: 0, nullable: true, example: 20}
        remark: {type: string, maxLength: 500, nullable: true}
    InboundMeasurementEventResponse:
      type: object
@@ -1761,9 +1754,11 @@ components:
        maxWeightKg: {type: number, minimum: 0, exclusiveMinimum: true, description: 必须等于柜型固定限重}
    ContainerOceanBookingLinkRequest:
      type: object
-      required: [realContainerBookingId, expectedVersion]
+      required: [oceanBookingId, requirementId, containerNo, expectedVersion]
      properties:
-        realContainerBookingId: {type: integer, format: int64, minimum: 1, description: 订舱创建的 OCEAN_BOOKING/ACTIVE 真实柜ID；成功合并后该来源记录转为 MERGED}
+        oceanBookingId: {type: integer, format: int64, minimum: 1, description: RELEASED订舱ID}
+        requirementId: {type: integer, format: int64, minimum: 1, description: 未满配的订舱柜型需求ID}
+        containerNo: {type: string, maxLength: 64, description: 港口提柜后取得的全局唯一真实集装箱号}
        expectedVersion: {type: integer, minimum: 0}
    ContainerOceanBookingUnlinkRequest:
      type: object
@@ -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}}}
@@ -2,7 +2,7 @@ openapi: 3.0.3
 info:
  title: Truck Appointment API
  version: 1.2.0
-  description: Truck appointments are independent operational records. Ocean booking, container booking and loading plan are optional links. 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: Truck appointments are independent operational records. Ocean booking, container booking and loading plan are optional links. Draft creation/editing does not require a bill of lading or attachment; DISPATCH requires a nonblank billOfLadingNo and at least one active BILL_OF_LADING attachment owned by the appointment customer. When linked to a RELEASED booking, the server freezes and validates the booking bill of lading snapshot. 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:
@@ -109,9 +109,9 @@ paths:
          multipart/form-data:
            schema:
              type: object
-              required: [file]
+              required: [attachmentType, file]
              properties:
-                attachmentType: {type: string, maxLength: 64}
+                attachmentType: {type: string, enum: [BILL_OF_LADING, DISPATCH_ORDER, DRIVER_DOCUMENT, VEHICLE_DOCUMENT, OTHER], description: Attachment classification; BILL_OF_LADING is required before DISPATCH}
                file: {type: string, format: binary}
      responses:
        '200': {description: Uploaded attachment reference}
@@ -140,10 +140,10 @@ components:
  schemas:
    AttachmentRequest:
      type: object
-      required: [fileId]
+      required: [fileId, attachmentType]
      properties:
        fileId: {type: integer, format: int64, minimum: 1}
-        attachmentType: {type: string, maxLength: 64}
+        attachmentType: {type: string, enum: [BILL_OF_LADING, DISPATCH_ORDER, DRIVER_DOCUMENT, VEHICLE_DOCUMENT, OTHER], description: Attachment classification; BILL_OF_LADING is required before DISPATCH}
        fileName: {type: string, maxLength: 255, description: Ignored; authoritative metadata comes from File service}
        fileHash: {type: string, maxLength: 128, description: Ignored; authoritative metadata comes from File service}
    Attachment:
@@ -152,7 +152,7 @@ components:
        id: {type: integer, format: int64}
        appointmentId: {type: integer, format: int64}
        fileId: {type: integer, format: int64}
-        attachmentType: {type: string}
+        attachmentType: {type: string, enum: [BILL_OF_LADING, DISPATCH_ORDER, DRIVER_DOCUMENT, VEHICLE_DOCUMENT, OTHER]}
        fileName: {type: string}
        fileHash: {type: string}
        visibility: {type: string, enum: [PLATFORM]}
@@ -177,6 +177,7 @@ components:
        customerName: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint only; persisted value is resolved from IAM customer master data.}
        carrierId: {type: integer, format: int64, minimum: 1, description: Required ACTIVE Warehouse supplier ID validated as TRUCKING.}
        carrierName: {type: string, maxLength: 128, nullable: true, description: Optional consistency hint only; the persisted snapshot comes from Warehouse supplier master data.}
+        billOfLadingNo: {type: string, maxLength: 128, nullable: true, description: Optional on draft; required before DISPATCH and server-frozen from a linked RELEASED booking when present.}
        plannedLoadingAt: {type: string, format: date-time}
        expectedVersion: {type: integer, minimum: 0, description: Must be 0 on create; current version on edit.}
    DetailStableReferences:
@@ -200,4 +201,5 @@ components:
        bookingAgentName: {type: string, nullable: true}
        carrierId: {type: integer, format: int64}
        carrierName: {type: string}
+        billOfLadingNo: {type: string, maxLength: 128, nullable: true, description: Frozen bill of lading snapshot used by dispatch readiness.}
        attachmentCount: {type: integer, format: int64, minimum: 0, description: Number of attachment references owned by this appointment}