优化

2026-09-04 12:18:36 +08:00
parent 566b07be62
commit b697e4c9f0
51 changed files with 1898 additions and 623 deletions
@@ -0,0 +1,122 @@
+openapi: 3.0.3
+info:
+  title: Warehouse Internal Location Block API
+  version: 1.0.0
+paths:
+  /internal/warehouse/v1/pallet-locations/blocks/reservations:
+    post:
+      summary: 原子预占整票库位块
+      security: [{ internalServiceToken: [] }]
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema: { $ref: '#/components/schemas/ReserveRequest' }
+      responses:
+        '200': { $ref: '#/components/responses/BlockResponse' }
+  /internal/warehouse/v1/pallet-locations/blocks/confirm:
+    post:
+      summary: 整段确认占用
+      security: [{ internalServiceToken: [] }]
+      requestBody:
+        required: true
+        content: { application/json: { schema: { $ref: '#/components/schemas/ConfirmRequest' } } }
+      responses:
+        '200': { $ref: '#/components/responses/BlockResponse' }
+  /internal/warehouse/v1/pallet-locations/blocks/transfer:
+    post:
+      summary: 将整段资源归属转移给余量子入库单
+      security: [{ internalServiceToken: [] }]
+      requestBody:
+        required: true
+        content: { application/json: { schema: { $ref: '#/components/schemas/TransferRequest' } } }
+      responses:
+        '200': { $ref: '#/components/responses/BlockResponse' }
+  /internal/warehouse/v1/pallet-locations/blocks/release:
+    post:
+      summary: 整段释放
+      description: 仅整票剩余箱数为0、整票作废或显式人工调整可调用；不提供单槽释放接口。
+      security: [{ internalServiceToken: [] }]
+      requestBody:
+        required: true
+        content: { application/json: { schema: { $ref: '#/components/schemas/ReleaseRequest' } } }
+      responses:
+        '200': { $ref: '#/components/responses/BlockResponse' }
+components:
+  securitySchemes:
+    internalServiceToken:
+      type: apiKey
+      in: header
+      name: X-Internal-Service-Token
+  responses:
+    BlockResponse:
+      description: 统一 ApiResponse，data 为整票块快照
+      content:
+        application/json:
+          schema:
+            type: object
+            required: [code, message, data]
+            properties:
+              code: { type: string }
+              message: { type: string }
+              data: { $ref: '#/components/schemas/BlockResult' }
+  schemas:
+    ReserveRequest:
+      type: object
+      required: [warehouseId, sourceService, businessId, inboundCode, requiredSlotCount, idempotencyKey, operatorId, expiresAt]
+      properties:
+        warehouseId: { type: integer, format: int64, minimum: 1 }
+        sourceService: { type: string, maxLength: 40 }
+        businessId: { type: integer, format: int64, minimum: 1 }
+        inboundCode: { type: string, maxLength: 40 }
+        requiredSlotCount: { type: integer, minimum: 1, maximum: 200 }
+        idempotencyKey: { type: string, maxLength: 128 }
+        operatorId: { type: integer, format: int64, minimum: 1 }
+        expiresAt: { type: string, format: date-time }
+    ConfirmRequest:
+      type: object
+      required: [blockId, businessId, idempotencyKey, operatorId]
+      properties:
+        blockId: { type: integer, format: int64, minimum: 1 }
+        businessId: { type: integer, format: int64, minimum: 1 }
+        idempotencyKey: { type: string, maxLength: 128 }
+        operatorId: { type: integer, format: int64, minimum: 1 }
+    TransferRequest:
+      type: object
+      required: [blockId, sourceBusinessId, targetBusinessId, targetInboundCode, idempotencyKey, operatorId]
+      properties:
+        blockId: { type: integer, format: int64, minimum: 1 }
+        sourceBusinessId: { type: integer, format: int64, minimum: 1 }
+        targetBusinessId: { type: integer, format: int64, minimum: 1 }
+        targetInboundCode: { type: string, maxLength: 40 }
+        idempotencyKey: { type: string, maxLength: 128 }
+        operatorId: { type: integer, format: int64, minimum: 1 }
+    ReleaseRequest:
+      type: object
+      required: [blockId, businessId, idempotencyKey, operatorId, reason]
+      properties:
+        blockId: { type: integer, format: int64, minimum: 1 }
+        businessId: { type: integer, format: int64, minimum: 1 }
+        idempotencyKey: { type: string, maxLength: 128 }
+        operatorId: { type: integer, format: int64, minimum: 1 }
+        reason: { type: string, enum: [ALL_PACKAGES_PICKED, TICKET_VOID, MANUAL_ADJUSTMENT] }
+    BlockResult:
+      type: object
+      required: [blockId, blockStatus, resources]
+      properties:
+        blockId: { type: integer, format: int64 }
+        blockStatus: { type: string, enum: [RESERVED, OCCUPIED, RELEASED] }
+        resources:
+          type: array
+          items: { $ref: '#/components/schemas/Resource' }
+    Resource:
+      type: object
+      required: [blockId, reservationId, locationId, locationCode, slotNo, sharedOverflow, resourceStatus]
+      properties:
+        blockId: { type: integer, format: int64 }
+        reservationId: { type: integer, format: int64 }
+        locationId: { type: integer, format: int64 }
+        locationCode: { type: string }
+        slotNo: { type: integer, minimum: 1 }
+        sharedOverflow: { type: boolean }
+        resourceStatus: { type: string, enum: [RESERVED, OCCUPIED, RELEASED] }