baiyue-firstleg/lastleg-service/src/main/resources/openapi/dispatch-transport-tasks-v1.yaml

openapi: 3.0.3
info:
  title: 现有排车运输任务
  version: 1.0.0
  description: >-
    平台主体（tenantId=0）在现有排车列表内安排到仓取货、本土卡车，使用真实PC排车号。
    请求经统一Gateway与Bearer认证；JSON响应HTTP200，业务code=200成功，A0400参数错误、A0403权限不足、A0404不存在、A0409版本或状态冲突。
    list读取、create安排、edit分配/执行/释放、depart发车、cancel取消权限前缀均为platform:overseas-warehouse:dispatch:。
    创建及执行使用稳定idempotencyKey；重试保留完整原载荷。取消仅限未发车；完成后分别释放司机、车辆。
    到仓取货逐原单确认实提和送仓，送仓只开放仓库收货门禁；本土卡车同步原单运输状态，完成须本任务凭证。
    仓储转运上门取货入仓单审核通过时自动生成待发车排车并绑定原转运单；重复审核不重复建单，主动取消排车时对应转运、尾程、入仓单和待收货计划一并取消。
    PICKUP 维护车辆后复用 dispatches/{dispatchNo}/submit-review、dispatch-review、loading-review 两级审核入口及版本化命令。
    调度通过后待理货审核，任一级驳回返回车辆信息修改重提；两级通过后进入装货中；逐票上传取货照片并确认后自动进入派送中，逐票上传到仓照片并确认后自动完成取货派送，再走原仓库收货流程，不走仓内拣货扣库存。
    车辆、司机或计划时刻变化作废本轮审核；运输版本与排车审核版本各自递增，命令使用对应详情的当前版本。
servers:
  - url: /api/platform/v1/last-leg/dispatches/transport-tasks
security:
  - bearerAuth: []
paths:
  /pickup-candidates:
    get:
      summary: 同仓上门取货候选（list，page/size/keyword/warehouseId）
      responses: &response
        '200':
          description: 业务响应信封；data为对应详情、候选或操作结果
  /truck-candidates:
    get:
      summary: 待派车且未被运输或拼车占用的本土卡车候选（list）
      responses: *response
  /pickup:
    post:
      summary: 同一海外仓多客户取货安排（create）
      description: sources为customerId/transferNo数组，plannedDepartureAt和expectedDriverEndAt为ISO时刻；idempotencyKey必填，remark可选。返回Detail。
      responses: *response
  /truck:
    post:
      summary: 本土卡车原单接入排车（create）
      description: customerId、orderNo、warehouseId、plannedDepartureAt、expectedDriverEndAt、idempotencyKey必填；原单须PENDING_DISPATCH且未被占用。返回Detail。
      responses: *response
  /{number}:
    parameters: &number
      - { name: number, in: path, required: true, schema: { type: string }, description: 真实PC排车业务号 }
    get:
      summary: 排车运输详情（list）
      description: data包含dispatchNo、taskType（PICKUP/LOCAL_TRUCK）、execution（现有资源与执行详情）、customerId、orderNo、pickups、completionEvidence（已确认凭证）、dispatchRecordVersion（排车审核版本）、resources（取货车辆司机照片快照；其他类型为null）。resources.driver.evidence.masterLicenseFileId仅表示司机主档驾驶证来源，包含在fileIds内；其他fileIds属于本车补传。
      responses: *response
  /{number}/{action}:
    parameters:
      - { name: number, in: path, required: true, schema: { type: string } }
      - { name: action, in: path, required: true, schema: { type: string, enum: [assign, cancel, resource-occupancy, release] } }
    post:
      summary: 分配、取消、资源可用性查询与实际任务释放
      description: >-
        assign(edit)：recordVersion、vehicleId、driverId、reason；cancel(cancel)：recordVersion、reason。
        PICKUP分配还必须提交dispatchRecordVersion和reviewPhotos（vehicleFileIds、driverPhotoFileIds、licenseFileIds），每类最多20个唯一正整数ID。
        车辆图片和司机照片各至少一张，驾驶证须有本车licenseFileIds或masterLicenseFileId；后者仅可引用所选司机当前有效主档驾驶证，不放入请求的licenseFileIds。
        所有补传经dispatches/{number}/evidence/{VEHICLE|DRIVER_PHOTO|DRIVER}上传并校验本车类别归属；主档预览复用司机档案受权下载。
        资源、照片与审核失效同事务，双版本过期或任一照片不合法则不分配资源。重新换车/司机不得沿用对应旧照片，照片修改必须重新两级审核，运输状态同步保留同一资源的照片。
        resource-occupancy(list)：kind=VEHICLE/DRIVER、resourceIds数组。
        release(edit)：recordVersion、resourceKind、actualEndAt、endLocation、vehicleStatus（车辆必填）、idempotencyKey、reason。
      responses: *response
  /{number}/{kind}/{action}:
    parameters:
      - { name: number, in: path, required: true, schema: { type: string } }
      - { name: kind, in: path, required: true, schema: { type: string, enum: [pickup, truck] } }
      - { name: action, in: path, required: true, schema: { type: string, enum: [depart, complete] } }
    post:
      summary: 运输发车（depart）或完成（edit）
      description: recordVersion、idempotencyKey、reason必填。本土卡车complete还须至少一份evidenceFileIds，文件归属本任务。取货complete要求所有原单已送仓。
      responses: *response
  /{number}/pickup/{customer}/{source}/{action}:
    parameters:
      - { name: number, in: path, required: true, schema: { type: string } }
      - { name: customer, in: path, required: true, schema: { type: string } }
      - { name: source, in: path, required: true, schema: { type: string }, description: 仓储转运单号 }
      - { name: action, in: path, required: true, schema: { type: string, enum: [picked, arrive, files] } }
    post:
      summary: 按原单上传凭证、确认实提或送仓（edit）
      description: files使用multipart字段file；picked使用recordVersion、idempotencyKey、actualPackages、evidenceFileIds、remark；arrive使用recordVersion、idempotencyKey、reason。凭证不能跨客户原单使用。
      responses: *response
  /{number}/truck/files:
    parameters: *number
    post:
      summary: 本土卡车凭证上传（edit）
      description: multipart字段file，非空且不超过10MB，只能在计划或运输中上传。上传不等于完成，须通过complete命令确认文件引用。
      responses: *response
  /{number}/truck/files/{fileId}:
    parameters:
      - { name: number, in: path, required: true, schema: { type: string } }
      - { name: fileId, in: path, required: true, schema: { type: integer, format: int64 } }
    get:
      summary: 已确认本土卡车完成凭证鉴权下载（list）
      responses:
        '200': { description: application/octet-stream文件；失败返回业务响应信封 }
  /{number}/pickup/{customer}/{source}/files/{fileId}:
    parameters:
      - { name: number, in: path, required: true, schema: { type: string } }
      - { name: customer, in: path, required: true, schema: { type: string } }
      - { name: source, in: path, required: true, schema: { type: string } }
      - { name: fileId, in: path, required: true, schema: { type: integer, format: int64 } }
    get:
      summary: 当前排车原单已确认取货凭证鉴权下载（list）
      responses:
        '200': { description: application/octet-stream文件；当前排车及原单归属不符时拒绝 }
components:
  securitySchemes:
    bearerAuth: { type: http, scheme: bearer, bearerFormat: JWT }