baiyue-firstleg/lastleg-service/src/main/resources/openapi/inbound-reconciliation-v1.yaml

openapi: 3.0.3
info:
  title: 平台收货异常核对
  version: 1.0.0
paths:
  /api/platform/v1/last-leg/inbound-plans/{planNo}/receiving-reconciliation:
    parameters:
      - { name: planNo, in: path, required: true, schema: { type: string } }
    get:
      operationId: getInboundReceivingReconciliation
      summary: 查询收货异常核对
      description: 仅平台入库列表权限。按所选客户计划的来源柜次、柜号和实际接柜仓查询同柜计划。独立返回现场实盘与已分配数量，完成票据只读。普通FBA单票单SKU组可唯一确定归属时预填完整实盘，其余逐票逐SKU由平台显式核对。
      parameters:
        - { name: customerId, in: query, required: true, schema: { type: string } }
      responses:
        '200':
          description: 当前事实快照和确认资格
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  data: { $ref: '#/components/schemas/Snapshot' }
    post:
      operationId: confirmInboundReceivingReconciliation
      summary: 确认收货异常
      description: 仅平台入库编辑权限。必须提交当前snapshotHash、明确原因以及快照内全部逐托和逐票SKU明细。普通FBA可确认短少、超收、零实收或更正误录，每托归属合计须等于核实清点数，单托可编辑数量0至66。普通地址逐箱来源和已入库票据保持只读。原申报不变，按原现场时间生成实际库存及计租批次，逐SKU短少进入PARTIAL_INBOUND，其余进入COMPLETED。库存、托盘、原预排交接和审计同事务提交，保留原清点及归属事实，不重复发布卸柜事件。已完成一件代发来源独立分组，待核对一件代发仍须核实冻结整托身份。
      parameters:
        - { name: Idempotency-Key, in: header, required: true, schema: { type: string, maxLength: 128 } }
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/Confirm' }
      responses:
        '200':
          description: 确认结果，同键同操作人同载荷重放返回原结果
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: { type: string }
                  data:
                    type: object
                    properties:
                      planNo: { type: string }
                      status: { type: string }
                      confirmedPackageCount: { type: integer }
                      reconciledPlanNos: { type: array, items: { type: string } }
        '409': { description: 旧快照、归属不完整、逐托不平、已完成来源变化或证据缺失 }
components:
  schemas:
    Snapshot:
      type: object
      required: [planNo, containerNo, snapshotHash, expectedPackageCount, countedPackageCount, attributedPackageCount, canConfirm, plans, pallets, receipts]
      properties:
        planNo: { type: string }
        containerNo: { type: string }
        snapshotHash: { type: string }
        expectedPackageCount: { type: integer, description: 本柜原申报箱数 }
        countedPackageCount: { type: integer, description: 独立现场实盘箱数 }
        attributedPackageCount: { type: integer, description: 当前已归属货件的箱数 }
        canConfirm: { type: boolean }
        blockedReason: { type: string, nullable: true }
        plans:
          type: array
          items:
            type: object
            properties:
              customerId: { type: string }
              planNo: { type: string }
              customerName: { type: string, nullable: true }
              status: { type: string }
              expectedPackageCount: { type: integer }
              attributedPackageCount: { type: integer }
        pallets:
          type: array
          items:
            allOf:
              - { $ref: '#/components/schemas/Count' }
              - type: object
                properties:
                  palletNo: { type: string }
                  groupKey: { type: string }
                  attributedPackageCount: { type: integer }
                  editable: { type: boolean }
        receipts:
          type: array
          items:
            allOf:
              - { $ref: '#/components/schemas/Quantity' }
              - type: object
                properties:
                  inboundCode: { type: string, nullable: true }
                  palletNo: { type: string }
                  productName: { type: string, nullable: true }
                  expectedPackageCount: { type: integer, description: 该票SKU原申报合计，同SKU跨托显示重复值 }
                  editable: { type: boolean }
    Confirm:
      type: object
      required: [customerId, snapshotHash, reason, pallets, receipts]
      properties:
        customerId: { type: string }
        snapshotHash: { type: string }
        reason: { type: string, minLength: 1, maxLength: 200 }
        pallets: { type: array, items: { $ref: '#/components/schemas/Count' } }
        receipts: { type: array, items: { $ref: '#/components/schemas/Quantity' } }
    Count:
      type: object
      required: [palletId, countedPackageCount]
      properties:
        palletId: { type: string }
        countedPackageCount: { type: integer, minimum: 0 }
    Quantity:
      type: object
      required: [customerId, planNo, lineId, palletId, skuCode, receivedPackageCount]
      properties:
        customerId: { type: string }
        planNo: { type: string }
        lineId: { type: string }
        palletId: { type: string }
        skuCode: { type: string }
        receivedPackageCount: { type: integer, minimum: 0 }