feat(firstleg): close phase3 outbound customs and schedule gates

2026-08-08 22:36:41 +08:00
parent 789d97675b
commit 66d1aa0d3d
81 changed files with 5196 additions and 36 deletions
@@ -0,0 +1,114 @@
+openapi: 3.0.3
+info:
+  title: Platform Port Schedule API
+  version: 1.0.0
+  description: Independent port and vessel schedule observations linked to ocean bookings and allocated containers.
+paths:
+  /api/platform/v1/port-schedules:
+    get:
+      summary: Query schedules by customer, ocean booking, allocated container or expiry
+      parameters:
+        - {name: customerId, in: query, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: oceanBookingId, in: query, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: containerBookingId, in: query, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
+        - {name: expired, in: query, schema: {type: boolean}}
+        - {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: HTTP 200 business envelope containing a page of schedule views
+    post:
+      summary: Create a source observation linked to a real ocean booking
+      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/CreateRequest'}
+      responses:
+        '200': {description: Created detail in the standard business envelope}
+  /api/platform/v1/port-schedules/{portScheduleId}:
+    parameters: [{$ref: '#/components/parameters/PortScheduleId'}]
+    get:
+      summary: Get schedule and immutable history
+      responses:
+        '200': {description: Schedule detail with computed expired flag}
+    put:
+      summary: Update source observation with optimistic locking
+      parameters: [{$ref: '#/components/parameters/IdempotencyKey'}]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: {$ref: '#/components/schemas/UpdateRequest'}
+      responses:
+        '200': {description: Updated detail or A0409 conflict in the business envelope}
+  /api/platform/v1/port-schedules/{portScheduleId}/history:
+    parameters: [{$ref: '#/components/parameters/PortScheduleId'}]
+    get:
+      summary: Query immutable source observation history
+      responses:
+        '200': {description: Ordered CREATE and UPDATE history records}
+components:
+  parameters:
+    PortScheduleId:
+      name: portScheduleId
+      in: path
+      required: true
+      schema: {type: string, pattern: '^[1-9][0-9]*$'}
+    IdempotencyKey:
+      name: Idempotency-Key
+      in: header
+      required: true
+      schema: {type: string, minLength: 1, maxLength: 128}
+  schemas:
+    ScheduleData:
+      type: object
+      required:
+        - customerId
+        - oceanBookingId
+        - sourceType
+        - sourceName
+        - sourceRef
+        - vesselName
+        - voyageNo
+        - departurePortCode
+        - destinationPortCode
+        - observedAt
+        - expiresAt
+      properties:
+        customerId: {type: string, pattern: '^[1-9][0-9]*$'}
+        oceanBookingId: {type: string, pattern: '^[1-9][0-9]*$'}
+        containerBookingId: {type: string, nullable: true, pattern: '^[1-9][0-9]*$'}
+        sourceType: {type: string, enum: [MANUAL, CARRIER, TERMINAL, API]}
+        sourceName: {type: string, maxLength: 128}
+        sourceRef: {type: string, maxLength: 255}
+        vesselName: {type: string, maxLength: 128}
+        voyageNo: {type: string, maxLength: 64}
+        departurePortCode: {type: string, maxLength: 32}
+        departurePortName: {type: string, nullable: true, maxLength: 128}
+        destinationPortCode: {type: string, maxLength: 32}
+        destinationPortName: {type: string, nullable: true, maxLength: 128}
+        etdAt: {type: string, format: date-time, nullable: true}
+        etaAt: {type: string, format: date-time, nullable: true}
+        bookingCutoffAt: {type: string, format: date-time, nullable: true, description: Booking cutoff}
+        customsCutoffAt: {type: string, format: date-time, nullable: true, description: Customs cutoff}
+        portCutoffAt: {type: string, format: date-time, nullable: true, description: Port gate cutoff}
+        observedAt: {type: string, format: date-time}
+        expiresAt: {type: string, format: date-time}
+        remark: {type: string, nullable: true, maxLength: 1000}
+    CreateRequest:
+      type: object
+      required: [expectedVersion, data]
+      properties:
+        expectedVersion: {type: integer, minimum: 0, maximum: 0}
+        data: {$ref: '#/components/schemas/ScheduleData'}
+        reason: {type: string, nullable: true, maxLength: 1000}
+    UpdateRequest:
+      type: object
+      required: [expectedVersion, data]
+      properties:
+        expectedVersion: {type: integer, minimum: 0}
+        data: {$ref: '#/components/schemas/ScheduleData'}
+        reason: {type: string, nullable: true, maxLength: 1000}