优化

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

@@ -1,8 +1,71 @@
 openapi: 3.0.3
 info:
-  title: Truck Appointment Attachments and History API
-  version: 1.0.0
+  title: Truck Appointment API
+  version: 1.1.0
 paths:
+  /api/platform/v1/truck-appointments:
+    get:
+      summary: Query truck appointments
+      responses:
+        '200': {description: Paged truck appointments}
+    post:
+      summary: Create a truck appointment linked to a released ocean booking
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/SaveRequest'}
+      responses:
+        '200': {description: Created appointment}
+  /api/platform/v1/truck-appointments/{id}:
+    parameters: [{$ref: '#/components/parameters/AppointmentId'}]
+    get:
+      summary: Query a truck appointment
+      responses:
+        '200': {description: Appointment detail}
+    put:
+      summary: Update an editable truck appointment with optimistic locking
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/SaveRequest'}
+      responses:
+        '200': {description: Updated appointment}
+  /api/platform/v1/truck-appointments/{id}/{action}:
+    parameters:
+      - {$ref: '#/components/parameters/AppointmentId'}
+      - {$ref: '#/components/parameters/Action'}
+      - {$ref: '#/components/parameters/IdempotencyKey'}
+      - {$ref: '#/components/parameters/RequestHash'}
+    post:
+      summary: Apply an idempotent appointment lifecycle action
+      description: ARRIVE, LOAD and DEPART persist their actual event timestamps atomically with the status transition.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/ActionRequest'}
+      responses:
+        '200': {description: Updated or replayed appointment}
+  /api/platform/v1/truck-appointments/{id}/reschedule:
+    parameters:
+      - {$ref: '#/components/parameters/AppointmentId'}
+      - {$ref: '#/components/parameters/IdempotencyKey'}
+      - {$ref: '#/components/parameters/RequestHash'}
+      - name: plannedLoadingAt
+        in: query
+        required: true
+        schema: {type: string, format: date-time}
+    post:
+      summary: Idempotently reschedule an appointment
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/ActionRequest'}
+      responses:
+        '200': {description: Rescheduled or replayed appointment}
   /api/platform/v1/truck-appointments/{id}/history:
     parameters: [{$ref: '#/components/parameters/AppointmentId'}]
     get:
@@ -47,3 +110,28 @@ components:
   parameters:
     AppointmentId: {name: id, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
     AttachmentId: {name: attachmentId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+    Action:
+      name: action
+      in: path
+      required: true
+      schema:
+        type: string
+        enum: [SUBMIT, DISPATCH, PICKUP, ARRIVE, LOAD, DEPART, COMPLETE, EXCEPTION, CANCEL]
+    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:
+    ActionRequest:
+      type: object
+      required: [expectedVersion]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        reason: {type: string, maxLength: 500}
+    SaveRequest:
+      type: object
+      required: [oceanBookingId, plannedLoadingAt, expectedVersion]
+      properties:
+        oceanBookingId: {type: integer, format: int64, minimum: 1}
+        containerBookingId: {type: integer, format: int64, minimum: 1}
+        loadingPlanId: {type: integer, format: int64, minimum: 1}
+        plannedLoadingAt: {type: string, format: date-time}
+        expectedVersion: {type: integer, minimum: 0}