优化

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

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