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] }