优化提交

2026-09-14 09:58:30 +08:00
parent 5ffd6c0118
commit 8cf7c4b9c9
93 changed files with 2945 additions and 188 deletions
@@ -0,0 +1,132 @@
+openapi: 3.0.3
+info:
+  title: Overseas warehouse PDA pallet transition internal API
+  version: 1.0.0
+paths:
+  /internal/v1/warehouse-pallets/resolve/{palletCode}:
+    get:
+      summary: Resolve a public pallet for PDA operations
+      description: Location fields are nullable because overseas tail-leg operations may work by pallet only.
+      security: [{ internalServiceToken: [] }]
+      parameters:
+        - in: path
+          name: palletCode
+          required: true
+          schema: { type: string }
+      responses:
+        '200':
+          description: Pallet resolution result
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/PalletResolveApiResponse' }
+  /internal/v1/pda-pallet-transitions/{palletId}:
+    post:
+      summary: Apply an idempotent PDA pallet state transition
+      security: [{ internalServiceToken: [] }]
+      parameters:
+        - in: path
+          name: palletId
+          required: true
+          schema: { type: integer, format: int64, minimum: 1 }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/PalletTransitionApply' }
+      responses:
+        '200':
+          description: Transition result
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/PalletTransitionApiResponse' }
+  /internal/v1/pda-pallet-transitions/{palletId}/{operationKey}/compensate:
+    post:
+      summary: Compensate an applied PDA pallet transition
+      security: [{ internalServiceToken: [] }]
+      parameters:
+        - in: path
+          name: palletId
+          required: true
+          schema: { type: integer, format: int64, minimum: 1 }
+        - in: path
+          name: operationKey
+          required: true
+          schema: { type: string, maxLength: 128 }
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/PalletTransitionCompensate' }
+      responses:
+        '200':
+          description: Compensation result
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/PalletTransitionApiResponse' }
+components:
+  securitySchemes:
+    internalServiceToken: { type: apiKey, in: header, name: X-Internal-Service-Token }
+  schemas:
+    PalletTransitionApply:
+      type: object
+      required: [warehouseId, expectedVersion, targetStatus, operationKey]
+      properties:
+        warehouseId: { type: string, pattern: '^[1-9][0-9]*$' }
+        expectedVersion: { type: integer, minimum: 0 }
+        targetStatus: { type: string, enum: [IDLE, OCCUPIED] }
+        targetLocationId:
+          type: string
+          pattern: '^[1-9][0-9]*$'
+          nullable: true
+          description: Optional; omitted for pallet-only operations without location management
+        operationKey: { type: string, maxLength: 128 }
+        reason: { type: string, maxLength: 500, nullable: true }
+    PalletTransitionCompensate:
+      type: object
+      required: [warehouseId]
+      properties:
+        warehouseId: { type: string, pattern: '^[1-9][0-9]*$' }
+    PalletResolveResult:
+      type: object
+      required: [palletId, palletCode, warehouseId, status, unitPrice, version, reservable]
+      properties:
+        palletId: { type: string, pattern: '^[1-9][0-9]*$' }
+        palletCode: { type: string }
+        warehouseId: { type: string, pattern: '^[1-9][0-9]*$' }
+        locationId: { type: string, pattern: '^[1-9][0-9]*$', nullable: true }
+        status: { type: string }
+        fbaWarehouseCode: { type: string, nullable: true }
+        unitPrice: { type: number }
+        version: { type: integer, minimum: 0 }
+        locationType: { type: string, nullable: true }
+        locationStatus: { type: string, nullable: true }
+        reservable: { type: boolean }
+        reservationBlockReason: { type: string, nullable: true }
+    PalletTransitionResult:
+      type: object
+      required: [operationKey, palletId, palletCode, warehouseId, beforeStatus, afterStatus, beforeVersion, afterVersion, operationStatus, replayed]
+      properties:
+        operationKey: { type: string }
+        palletId: { type: string, pattern: '^[1-9][0-9]*$' }
+        palletCode: { type: string }
+        warehouseId: { type: string, pattern: '^[1-9][0-9]*$' }
+        beforeStatus: { type: string }
+        afterStatus: { type: string }
+        beforeLocationId: { type: string, pattern: '^[1-9][0-9]*$', nullable: true }
+        afterLocationId: { type: string, pattern: '^[1-9][0-9]*$', nullable: true }
+        beforeVersion: { type: integer }
+        afterVersion: { type: integer }
+        operationStatus: { type: string }
+        replayed: { type: boolean }
+    PalletTransitionApiResponse:
+      type: object
+      properties:
+        code: { type: string, example: '200' }
+        message: { type: string }
+        data: { $ref: '#/components/schemas/PalletTransitionResult' }
+    PalletResolveApiResponse:
+      type: object
+      properties:
+        code: { type: string, example: '200' }
+        message: { type: string }
+        data: { $ref: '#/components/schemas/PalletResolveResult' }