feat(warehouse-overseas): reserve inbound pallet batches

2026-09-08 23:52:36 +08:00
parent 4c1e9aa714
commit a88a04fd24
22 changed files with 1227 additions and 6 deletions
@@ -0,0 +1,93 @@
+openapi: 3.0.3
+info:
+  title: Warehouse Overseas Internal Pallet Batch API
+  version: 1.0.0
+paths:
+  /internal/v1/warehouse-pallet-batches/ensure-reserved:
+    post:
+      summary: 按柜级入库计划稳定业务键批量确保并预留公共托盘
+      description: 仅内部服务令牌；同柜批次可跨客户。物理托盘固定customer_id=0，每个item资源锁使用其真实customerId。同warehouseId+batchKey同请求重放不重复造码，异请求返回A0409；COMPENSATED批次同请求复用原托盘并开启新attempt。
+      security: [{ internalServiceToken: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/EnsureReservedRequest' } } } }
+      responses:
+        '200': { description: 批量预留结果；业务冲突仍为HTTP 200且响应体code=A0409, content: { application/json: { schema: { $ref: '#/components/schemas/BatchApiResponse' } } } }
+        '401': { description: 内部服务令牌无效 }
+  /internal/v1/warehouse-pallet-batches/confirm:
+    post:
+      summary: 确认Lastleg已持久化托盘快照并建立业务绑定
+      description: 仅RESERVED可确认；重复确认返回同一结果，不生成新托盘或资源锁。
+      security: [{ internalServiceToken: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/ConfirmRequest' } } } }
+      responses:
+        '200': { description: 已确认批次；业务冲突仍为HTTP 200且响应体code=A0409, content: { application/json: { schema: { $ref: '#/components/schemas/BatchApiResponse' } } } }
+  /internal/v1/warehouse-pallet-batches/compensate:
+    post:
+      summary: 补偿释放Lastleg本地失败对应的本批未确认资源
+      description: 仅RESERVED且尚未建立业务绑定的本批资源可补偿；CONFIRMED或已被后续占用时返回A0409。
+      security: [{ internalServiceToken: [] }]
+      requestBody: { required: true, content: { application/json: { schema: { $ref: '#/components/schemas/CompensateRequest' } } } }
+      responses:
+        '200': { description: 已补偿批次；业务冲突仍为HTTP 200且响应体code=A0409, content: { application/json: { schema: { $ref: '#/components/schemas/BatchApiResponse' } } } }
+components:
+  securitySchemes:
+    internalServiceToken: { type: apiKey, in: header, name: X-Internal-Service-Token }
+  schemas:
+    BatchItemRequest:
+      type: object
+      required: [customerId, businessKey, inboundPlanNo, sequenceNo, palletType]
+      properties:
+        customerId: { type: string, pattern: '^[1-9][0-9]*$' }
+        businessKey: { type: string, minLength: 1, maxLength: 100 }
+        inboundPlanNo: { type: string, minLength: 1, maxLength: 128 }
+        sequenceNo: { type: integer, minimum: 1 }
+        palletType: { type: string, minLength: 1, maxLength: 32 }
+        fbaWarehouseCode: { type: string, nullable: true, maxLength: 128 }
+    EnsureReservedRequest:
+      type: object
+      required: [warehouseId, batchKey, items]
+      properties:
+        warehouseId: { type: string, pattern: '^[1-9][0-9]*$' }
+        batchKey: { type: string, minLength: 1, maxLength: 160 }
+        items: { type: array, minItems: 1, maxItems: 200, items: { $ref: '#/components/schemas/BatchItemRequest' } }
+    ConfirmRequest:
+      type: object
+      required: [warehouseId, batchKey, commandKey]
+      properties:
+        warehouseId: { type: string, pattern: '^[1-9][0-9]*$' }
+        batchKey: { type: string, minLength: 1, maxLength: 160 }
+        commandKey: { type: string, minLength: 1, maxLength: 160 }
+    CompensateRequest:
+      allOf:
+        - { $ref: '#/components/schemas/ConfirmRequest' }
+        - type: object
+          required: [reason]
+          properties: { reason: { type: string, minLength: 1, maxLength: 500 } }
+    BatchItemResponse:
+      type: object
+      required: [customerId, businessKey, inboundPlanNo, sequenceNo, palletId, palletCode, locationId, resourceLockId, status]
+      properties:
+        customerId: { type: string, pattern: '^[1-9][0-9]*$' }
+        businessKey: { type: string }
+        inboundPlanNo: { type: string }
+        sequenceNo: { type: integer, minimum: 1 }
+        palletId: { type: string, pattern: '^[1-9][0-9]*$' }
+        palletCode: { type: string, maxLength: 64 }
+        locationId: { type: string, pattern: '^[1-9][0-9]*$' }
+        resourceLockId: { type: string, pattern: '^[1-9][0-9]*$' }
+        status: { type: string, enum: [RESERVED, CONFIRMED, RELEASED] }
+    BatchResponse:
+      type: object
+      required: [batchId, batchKey, status, attemptNo, replayed, items]
+      properties:
+        batchId: { type: string, pattern: '^[1-9][0-9]*$' }
+        batchKey: { type: string }
+        status: { type: string, enum: [RESERVED, CONFIRMED, COMPENSATED] }
+        attemptNo: { type: integer, minimum: 1 }
+        replayed: { type: boolean }
+        items: { type: array, items: { $ref: '#/components/schemas/BatchItemResponse' } }
+    BatchApiResponse:
+      type: object
+      properties:
+        code: { type: string, example: '200' }
+        message: { type: string }
+        data: { $ref: '#/components/schemas/BatchResponse' }