openapi: 3.0.3
info:
  title: 预约货物核实资料
  version: 1.0.0
  description: >-
    按原ORDER或BOOKING货源保存独立核实资料，不修改订单、登记、库存或预约确认状态。
    未取得预约确认也可保存箱数和各票货件号。核实记录逐版本追加，取消预约不删除资料。
security:
  - bearerAuth: []
paths:
  /api/platform/v1/last-leg/appointment-planning/sources/{sourceKey}/cargo-verification:
    parameters:
      - {name: sourceKey, in: path, required: true, schema: {type: string, maxLength: 160}, description: 原稳定货源键；外接货来货前后均使用BOOKING键}
      - {name: customerId, in: query, required: true, schema: {type: string, maxLength: 128}, description: 服务端核对的原客户归属}
    get:
      operationId: getAppointmentCargoVerification
      summary: 读取本票独立核实资料和分配总量
      description: >-
        仅平台，需platform:appointment:list与platform:overseas-warehouse:last-mile-order:list。
        source为权威原来源，verification为空表示尚无独立核实记录。
        原版本、目的地或原箱数变化后sourceChanged为true，可分配量返回null，重新核实前不得采用旧资料。
        allocatedPackages合计当前活动预约明细；未知分配单独计数，不当作零。
        availablePackages为当前有效总量减已分配量，未知、超量或待复核时为空，不虚构可用量。
        allowedActions表示业务资格；前端仍须与当前用户写权限取交集。
      parameters:
        - {name: destinationKey, in: query, schema: {type: string, maxLength: 160}, description: 可传选择时的目的地；与原来源不符则拒绝}
      responses:
        '200':
          description: 业务响应，data为核实上下文
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  data: {$ref: '#/components/schemas/CargoContext'}
        '400': {description: 来源格式或目的地不符}
        '403': {description: 非平台身份或权限不足}
        '404': {description: 原来源不存在或客户不匹配}
        '503': {description: 权威仓库目录不可用}
    post:
      operationId: saveAppointmentCargoVerification
      summary: 独立保存箱数和本票货件或追踪号
      description: >-
        仅平台，需两个读取权限及platform:overseas-warehouse:inbound-order:fba-appointment。
        操作人取登录身份。原货源锁与预约写命令共用，锁后重读来源和版本；expectedVersion首次为0。
        原来源已知箱数时，核实量不得超过原来源；任何情况下不得低于活动预约已分配量。
        原来源箱数未知时允许独立核实总量，原来源仍为空。
        可以暂缺箱数或货件，保存不会自动确认预约；正式确认仍需完整材料。
        同来源客户内的同幂等键、同操作人、同请求返回原核实版本，即使此后又有新版本。
        同键异内容、并发版本冲突或原来源变化返回409；记录与业务写入处于同一事务。
        后续预约写入采用核实版本及货件快照；单独再次核实不会改写已保存预约快照。
      requestBody:
        required: true
        content:
          application/json:
            schema: {$ref: '#/components/schemas/SaveCargoVerification'}
      responses:
        '200':
          description: 保存或重试原命令的核实资料快照
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  data: {$ref: '#/components/schemas/CargoVerification'}
        '400': {description: 请求字段无效}
        '403': {description: 非平台身份或缺少独立写权限}
        '404': {description: 原来源不存在或客户不匹配}
        '409': {description: 原来源或核实版本变化、幂等冲突、箱数越界或来源不可安排}
        '503': {description: 权威仓库目录不可用}
components:
  securitySchemes:
    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
  schemas:
    SaveCargoVerification:
      type: object
      required: [destinationKey, expectedVersion, shipmentReferences, idempotencyKey]
      properties:
        destinationKey: {type: string, minLength: 1, maxLength: 160}
        expectedSourceVersion: {type: string, maxLength: 160, nullable: true, description: 读取上下文中的原来源版本，空值也须一致}
        expectedVersion: {type: integer, minimum: 0}
        packageCount: {type: integer, minimum: 1, nullable: true}
        shipmentReferences: {type: array, maxItems: 100, items: {type: string, minLength: 1, maxLength: 128}, description: 本票货件号或追踪号，允许暂时空列表；保存时去首尾空格并去重}
        remark: {type: string, maxLength: 1000, nullable: true}
        idempotencyKey: {type: string, minLength: 1, maxLength: 64}
    CargoVerification:
      type: object
      required: [version, destinationKey, shipmentReferences, verifiedAt]
      properties:
        version: {type: integer, minimum: 1}
        sourceVersion: {type: string, nullable: true}
        destinationKey: {type: string}
        sourcePackages: {type: integer, nullable: true}
        packageCount: {type: integer, nullable: true}
        shipmentReferences: {type: array, items: {type: string}}
        remark: {type: string, nullable: true}
        operatorName: {type: string, nullable: true}
        verifiedAt: {type: string, format: date-time, description: UTC时间}
    CargoContext:
      type: object
      properties:
        source: {$ref: './appointment-planning-v1.yaml#/components/schemas/PlanningSource'}
        verification:
          allOf: [{$ref: '#/components/schemas/CargoVerification'}]
          nullable: true
        allocatedPackages: {type: integer, format: int64}
        unknownAllocationCount: {type: integer, format: int64}
        effectivePackages: {type: integer, nullable: true, description: 独立核实箱数；没有核实记录时采用原来源箱数}
        availablePackages: {type: integer, format: int64, nullable: true}
        sourceChanged: {type: boolean}
        allowedActions: {type: array, items: {type: string, enum: [VERIFY_CARGO]}}
        blockReasons: {type: array, items: {type: string}}