baiyue-firstleg/lastleg-service/src/main/resources/openapi/warehouse-transfer-quantities-v1.yaml

openapi: 3.0.3
info:
  title: 仓储转运与混箱库存数量
  version: 1.0.0
  description: 件、箱、托分开记录。所有Long数量序列化为十进制字符串；未知件数保持null，空筛选返回零。同托部分出库可同时属于历史实收、剩余、出库集合，禁止托数相减。
paths:
  /api/platform/v1/last-leg/orders/warehouse-transfer-quantities:
    get:
      operationId: platformWarehouseTransferQuantityTotals
      description: 权限platform:overseas-warehouse:last-mile-order:list，平台访问域与主订单列表一致。复用主订单全部Query筛选及relabelNo，额外限定WAREHOUSE_TRANSFER；page/size不参与汇总。
      responses:
        '200':
          description: ApiResponse.data为TransferQuantityTotals。
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TotalsEnvelope' }
  /api/merchant/v1/last-leg/warehouse-transfers/quantities:
    get:
      operationId: merchantWarehouseTransferQuantityTotals
      description: 权限merchant:overseas-warehouse:transfer:list，客户范围只从会话获取。复用转运列表完整筛选，包括transferNo/inboundCode/operatingWarehouseId/fbaWarehouseCode/status/needRelabel和创建、审核、清点完成、出库日期区间；日期区间上界包含端点。page/size不参与汇总。
      responses:
        '200':
          description: ApiResponse.data为TransferQuantityTotals。
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TotalsEnvelope' }
  /api/platform/v1/last-leg/inventory/piece-projection:
    get:
      operationId: platformInventoryPieceProjection
      description: 权限platform:overseas-warehouse:inventory:list，与库存列表相同平台客户访问域及BalanceQuery完整筛选，不分页。按原箱清点及正式目的仓签收凭据投影当前未占用可用库存。每仓位精确箱映射数量须等于available_packages，箱内SKU件数须等于箱总清点件数；缺失、不一致、无法追溯的非转运库存均为未知，不按箱规或首SKU推算。通用余额MIXED也逐箱读取全部SKU。SKU查询可命中混箱第二SKU。
      responses:
        '200':
          description: ApiResponse.data为InventoryPieceProjection。
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  data: { $ref: '#/components/schemas/InventoryPieceProjection' }
components:
  schemas:
    Count:
      type: string
      pattern: '^[0-9]+$'
    NullableCount:
      type: string
      nullable: true
      pattern: '^[0-9]+$'
    TransferQuantityView:
      type: object
      description: 主订单列表与详情summary.warehouseTransferQuantity，仅转运订单提供。新到仓历史实收取counted_at非空且COUNTED/DISCARD_PENDING/DISCARDED/SHIPPED原箱；库存转运实收取正式目的仓签收凭据，件数取精确原箱清点。
      properties:
        lastlegOrderId: { $ref: '#/components/schemas/Count' }
        declaredPieceCount: { $ref: '#/components/schemas/NullableCount' }
        receivedPieceCount: { $ref: '#/components/schemas/NullableCount' }
        declaredCartonCount: { $ref: '#/components/schemas/Count' }
        receivedCartonCount: { $ref: '#/components/schemas/Count' }
        receivedPalletCount: { $ref: '#/components/schemas/Count' }
        availableCartonCount: { type: string, description: 原箱当前COUNTED数，非扣除其他业务预留后的可用库存。真实可用数读取库存投影。 }
        shippedCartonCount: { $ref: '#/components/schemas/Count' }
        remainingPalletCount: { $ref: '#/components/schemas/Count' }
        shippedPalletCount: { $ref: '#/components/schemas/Count' }
    TransferQuantityTotals:
      allOf:
        - { $ref: '#/components/schemas/TransferQuantityView' }
        - type: object
          properties:
            orderCount: { $ref: '#/components/schemas/Count' }
            knownDeclaredPieceCount: { $ref: '#/components/schemas/Count' }
            unknownDeclaredOrderCount: { $ref: '#/components/schemas/Count' }
            knownReceivedPieceCount: { $ref: '#/components/schemas/Count' }
            unknownReceivedOrderCount: { $ref: '#/components/schemas/Count' }
    TotalsEnvelope:
      type: object
      properties:
        code: { type: string }
        data: { $ref: '#/components/schemas/TransferQuantityTotals' }
    Sku:
      type: object
      properties:
        skuCode: { type: string }
        quantity: { $ref: '#/components/schemas/Count' }
    InventoryPieceProjection:
      type: object
      properties:
        availablePieceCount: { $ref: '#/components/schemas/NullableCount' }
        knownAvailablePieceCount: { $ref: '#/components/schemas/Count' }
        unknownCartonCount: { $ref: '#/components/schemas/Count' }
        availableCartonCount: { $ref: '#/components/schemas/Count' }
        availablePalletCount: { $ref: '#/components/schemas/Count' }
        groups:
          type: array
          items:
            type: object
            properties:
              customerId: { type: string }
              warehouseId: { type: string }
              destinationCode: { type: string, nullable: true }
              anchorSkuCode: { type: string, nullable: true, description: 原余额记账SKU，可能为MIXED。完整SKU在skuContents中。 }
              availablePieceCount: { $ref: '#/components/schemas/NullableCount' }
              knownAvailablePieceCount: { $ref: '#/components/schemas/Count' }
              unknownCartonCount: { $ref: '#/components/schemas/Count' }
              availableCartonCount: { $ref: '#/components/schemas/Count' }
              availablePalletCount: { $ref: '#/components/schemas/Count' }
              skuContents:
                type: array
                items: { $ref: '#/components/schemas/Sku' }
              cartons:
                type: array
                items:
                  type: object
                  properties:
                    cartonMark: { type: string }
                    inventoryPositionId: { type: string }
                    palletId: { type: string, nullable: true }
                    quantity: { $ref: '#/components/schemas/NullableCount' }
                    items:
                      type: array
                      items: { $ref: '#/components/schemas/Sku' }