openapi: 3.0.3
info:
  title: Lastleg Internal Dropship API
  version: 1.0.0
  description: 国内头程事件落地后向海外 Lastleg 冻结一件代发托盘、SKU 与箱唛快照的内部同步契约。
paths:
  /internal/v1/lastleg/dropship/receive:
    post:
      summary: 接收一件代发托盘与 SKU 快照
      description: 仅服务间调用；必须携带内部服务令牌。相同 customerId、orderId 与 idempotencyKey 重放返回既有结果。
      security:
        - internalServiceToken: []
      parameters:
        - name: X-Internal-Service-Token
          in: header
          required: true
          schema: { type: string, minLength: 1 }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/DropshipReceiveRequest' }
      responses:
        '200':
          description: 统一 ApiResponse，data 为接收的箱唛数量
          content:
            application/json:
              schema: { $ref: '#/components/schemas/IntegerApiResponse' }
        '401': { description: 内部服务令牌缺失或无效 }
components:
  securitySchemes:
    internalServiceToken:
      type: apiKey
      in: header
      name: X-Internal-Service-Token
  schemas:
    DropshipReceiveRequest:
      type: object
      required: [customerId, orderId, warehouseId, idempotencyKey, pallets]
      properties:
        customerId: { type: string, minLength: 1, description: 客户数据隔离键 }
        orderId: { type: integer, format: int64, description: Lastleg 尾程订单 ID }
        warehouseId: { type: integer, format: int64, description: 海外仓 ID 快照 }
        idempotencyKey: { type: string, minLength: 1, description: 跨区域调用幂等键 }
        pallets:
          type: array
          minItems: 1
          items: { $ref: '#/components/schemas/DropshipPallet' }
    DropshipPallet:
      type: object
      required: [palletNo, skuPackages]
      properties:
        palletNo: { type: string, minLength: 1, description: 来源头程托盘号快照 }
        skuPackages:
          type: array
          minItems: 1
          items: { $ref: '#/components/schemas/DropshipSkuPackages' }
    DropshipSkuPackages:
      type: object
      required: [skuCode, packageCount, productQuantity, cartonMarks, cartonQuantities]
      properties:
        skuCode: { type: string, minLength: 1 }
        productName: { type: string, nullable: true }
        packageCount: { type: integer, format: int64, minimum: 1 }
        productQuantity: { type: integer, format: int64, minimum: 1 }
        cartonQuantities:
          type: object
          description: 箱唛到逐箱实收商品件数的完整映射，键必须与 cartonMarks 一致，值合计必须等于 productQuantity
          additionalProperties: { type: integer, format: int64, minimum: 1 }
        cartonMarks:
          type: array
          minItems: 1
          items: { type: string, minLength: 1 }
    IntegerApiResponse:
      type: object
      required: [code, message, data, timestamp]
      properties:
        code: { type: string, example: '200' }
        message: { type: string }
        data: { type: integer, format: int32, minimum: 0 }
        requestId: { type: string, nullable: true }
        traceId: { type: string, nullable: true }
        timestamp: { type: string, format: date-time }