openapi: 3.0.3
info:
  title: 本土散板排车照片履约
  version: 1.0.0
  description: >-
    仅同客户权威关联的本土散板明细进入照片节点。全车为散板且尚无真实扫码时，审核通过后逐票保存取货照片，
    全部齐全才显示取货完成按钮；显式确认后从LOADING进入DELIVERING。不生成库存、PDA拣货或仓库出库事实。逐票保存送达照片后自动DELIVERED并结案释放车辆司机。
    混排从AFTER_LOADING或DELIVERING可逐票保存取货及送达照片；异地货同票须先取货再送达，不同票不限制取送顺序。
    仓内实托走原出库签收链，不要求散板节点照片；页面按pickupRequired仅展示本趟上门取货货物，送货到仓尚未入库则保留warehouseNotice提示。
    混排仓内真实装车确认后即发运仓内货，不等待异地取货或五类装车照片；剩余装车资料可以补传。
    仓内已发运而异地货尚未确认取齐时，同时展示在装车后和派送中，两页签计数允许重叠但总数不重复。
    取货照片齐全不自动完成取货；点击取货完成后仅在派送中展示，异地货量只在该确认动作计入。全部仓内货签收且散板确认取货并送达照片齐全才可整车完结。
    图片只接受10MiB以内JPG或PNG，每票每节点最多20张。保存提交该节点完整保留列表，支持追加和逐张删除；空列表代表删除最后一张。
    整车已完结的节点及已有送达照片的取货节点至少保留一张凭证，可先追加再删除；修改照片不撤销已执行的取货、发运或送达，不重复累计货量。
    上传不等于保存，保存用公共版本和幂等键，失败同事务回滚。历史照片列表保留审计，仅最新列表授权预览。
    本土散板号只用LB原单，不生成入仓码、柜号或虚构派送单号。分车运输按已保存送达照片的明细去重累计箱数，整票送达后才完成原单。
paths:
  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution/pickup-complete:
    parameters:
      - { name: number, in: path, required: true, schema: { type: string } }
    post:
      summary: 人工确认本车全部上门取货完成
      description: 需要platform:overseas-warehouse:dispatch:edit。逐票取货照片齐全、当前阶段允许且本轮尚未确认时才允许提交。公共版本及幂等键保护，失败回滚确认历史、数量及发运。返回Detail包含canCompletePickup及pickupCompleted。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [recordVersion, idempotencyKey]
              properties:
                recordVersion: { type: integer, format: int64, minimum: 0 }
                idempotencyKey: { type: string, minLength: 8, maxLength: 128 }
      responses: { '200': { description: 当前照片与人工取货确认状态 } }
  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution:
    parameters:
      - { name: number, in: path, required: true, schema: { type: string } }
    get:
      summary: 读取散板逐票照片与节点资格
      description: 需要platform:overseas-warehouse:dispatch:list。data包含dispatchNo、recordVersion、stage、direct和items；items包含itemId、customerId、orderNo、destination、packages、pickupPhotos、arrivalPhotos、canPickup、canArrive、warehouseNotice、pickupRequired。pickupRequired仅未入仓且选择上门取货的票为true。warehouseNotice仅送货到仓且尚无入仓实托时返回带原单号的待入仓提示，其他情况为null。
      responses: { '200': { description: 统一ApiResponse } }
  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution/{itemId}/{phase}/uploads:
    parameters:
      - { name: number, in: path, required: true, schema: { type: string } }
      - { name: itemId, in: path, required: true, schema: { type: string, pattern: '^[1-9][0-9]*$' } }
      - { name: phase, in: path, required: true, schema: { type: string, enum: [PICKUP, ARRIVAL] } }
    post:
      summary: 上传本车本节点照片，尚不作为保存或发运事实
      description: 需要platform:overseas-warehouse:dispatch:edit。文件业务归属为平台、本车ID、独立节点类别。
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties: { file: { type: string, format: binary } }
      responses: { '200': { description: data为fileId、fileName、contentType、sizeBytes } }
  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution/{itemId}/{phase}:
    parameters:
      - { name: number, in: path, required: true, schema: { type: string } }
      - { name: itemId, in: path, required: true, schema: { type: string } }
      - { name: phase, in: path, required: true, schema: { type: string, enum: [PICKUP, ARRIVAL] } }
    put:
      summary: 保存逐票节点照片并原子核对运输进度
      description: 需要platform:overseas-warehouse:dispatch:edit；不得跨车、跨节点或在不同票之间重复绑定照片。重审轮次变化后旧照片保留历史但不代替本轮履约。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [recordVersion, idempotencyKey, fileIds]
              properties:
                recordVersion: { type: integer, format: int64, minimum: 0 }
                idempotencyKey: { type: string, minLength: 8, maxLength: 128 }
                fileIds: { type: array, maxItems: 20, uniqueItems: true, description: 本节点完整保留照片列表，空列表用于删除最后一张且受已履约凭证约束, items: { type: string, pattern: '^[1-9][0-9]*$' } }
      responses: { '200': { description: 返回当前整车照片状态；重复原命令不重复推进运输或生成作业事实 } }
  /api/platform/v1/last-leg/dispatches/{number}/looseboard-execution/{itemId}/{phase}/files/{fileId}/content:
    parameters:
      - { name: number, in: path, required: true, schema: { type: string } }
      - { name: itemId, in: path, required: true, schema: { type: string } }
      - { name: phase, in: path, required: true, schema: { type: string, enum: [PICKUP, ARRIVAL] } }
      - { name: fileId, in: path, required: true, schema: { type: string } }
    get:
      summary: 读取当前明细节点已保存照片
      description: 需要platform:overseas-warehouse:dispatch:list；未保存上传和其他票照片不可读取。
      responses: { '200': { description: JPG或PNG，Cache-Control no-store } }