优化

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

@@ -24,7 +24,7 @@ paths:
     get:
       summary: Query a truck appointment
       responses:
-        '200': {description: Appointment detail}
+        '200': {description: Appointment detail, content: {application/json: {schema: {$ref: '#/components/schemas/DetailStableReferences'}}}}
     put:
       summary: Update an editable truck appointment with optimistic locking
       requestBody:
@@ -78,16 +78,20 @@ paths:
     parameters: [{$ref: '#/components/parameters/AppointmentId'}]
     get:
       summary: Query attachment references owned by the appointment
+      description: 'Requires platform:firstleg:truck-appointment:list.'
       responses:
-        '200': {description: Attachment references}
+        '200': {description: Attachment references, content: {application/json: {schema: {type: array, items: {$ref: '#/components/schemas/Attachment'}}}}}
     post:
       summary: Reference a file already owned by the appointment customer and business scope
+      description: 'Requires platform:firstleg:truck-appointment:edit. The file must belong to customerId + TRUCK_APPOINTMENT_ATTACHMENT + appointmentId.'
+      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/AttachmentRequest'}}}}
       responses:
-        '200': {description: Created attachment reference}
+        '200': {description: Created attachment reference, content: {application/json: {schema: {$ref: '#/components/schemas/Attachment'}}}}
   /api/platform/v1/truck-appointments/{id}/attachments/upload:
     parameters: [{$ref: '#/components/parameters/AppointmentId'}]
     post:
       summary: Upload and reference a truck appointment attachment
+      description: 'Requires platform:firstleg:truck-appointment:edit.'
       requestBody:
         required: true
         content:
@@ -96,7 +100,7 @@ paths:
               type: object
               required: [file]
               properties:
-                attachmentType: {type: string, maxLength: 32}
+                attachmentType: {type: string, maxLength: 64}
                 file: {type: string, format: binary}
       responses:
         '200': {description: Uploaded attachment reference}
@@ -106,6 +110,7 @@ paths:
       - {$ref: '#/components/parameters/AttachmentId'}
     delete:
       summary: Delete an attachment reference owned by the appointment
+      description: 'Requires platform:firstleg:truck-appointment:edit. Deletes the appointment reference only; the File object is retained.'
       responses:
         '200': {description: Reference deleted}
 components:
@@ -122,6 +127,26 @@ components:
     IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, maxLength: 128}}
     RequestHash: {name: X-Request-Hash, in: header, required: false, schema: {type: string, pattern: '^[0-9a-fA-F]{64}$'}}
   schemas:
+    AttachmentRequest:
+      type: object
+      required: [fileId]
+      properties:
+        fileId: {type: integer, format: int64, minimum: 1}
+        attachmentType: {type: string, maxLength: 64}
+        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:
+      type: object
+      properties:
+        id: {type: integer, format: int64}
+        appointmentId: {type: integer, format: int64}
+        fileId: {type: integer, format: int64}
+        attachmentType: {type: string}
+        fileName: {type: string}
+        fileHash: {type: string}
+        visibility: {type: string, enum: [PLATFORM]}
+        uploadedBy: {type: integer, format: int64}
+        uploadedAt: {type: string, format: date-time}
     ActionRequest:
       type: object
       required: [expectedVersion]
@@ -137,3 +162,23 @@ components:
         loadingPlanId: {type: integer, format: int64, minimum: 1}
         plannedLoadingAt: {type: string, format: date-time}
         expectedVersion: {type: integer, minimum: 0}
+    DetailStableReferences:
+      type: object
+      description: Stable IDs plus server-resolved saved resource names returned by appointment detail.
+      properties:
+        oceanBookingId: {type: integer, format: int64}
+        oceanBookingNo: {type: string}
+        containerBookingId: {type: integer, format: int64}
+        cabinetNo: {type: string}
+        containerNo: {type: string, nullable: true}
+        loadingPlanId: {type: integer, format: int64}
+        warehouseId: {type: integer, format: int64}
+        warehouseName: {type: string}
+        customerId: {type: integer, format: int64}
+        customerName: {type: string, description: Frozen from the associated ocean booking; request input cannot override it}
+        shippingCompanyId: {type: integer, format: int64}
+        shippingCompanyName: {type: string}
+        bookingAgentId: {type: integer, format: int64}
+        bookingAgentName: {type: string}
+        carrierId: {type: integer, format: int64}
+        carrierName: {type: string}