baiyue-firstleg/lastleg-service/src/main/resources/openapi/fleet-transfer-pickup-v1.yaml

openapi: 3.0.3
info:
  title: 仓储转运上门取货与车辆排车
  version: 1.0.0
  description: |
    审核通过的 WAREHOUSE_PICKUP 外来转运单自动进入待取货候选；客户自送、库存转运、未审核及已完成测量单不进入。
    入仓取货和出库派送共用 ll_fleet_trip 及车辆司机占用，tripPurpose 分别为 PICKUP / DELIVERY，禁止混用库存出库命令、外接预订及余位发布。
    同车多单必须送往同一公共海外仓，原客户归属与转运单保留，不重复生成尾程单、不修改预报箱唛或库存。
    取货确认必须填写实提箱数并引用本票本车已上传的 PDF/JPG/PNG 凭证；送仓后开放 PDA 清点。
    司机实提箱数不替代仓库实收。全部送仓后结案运输，车辆和司机仍通过原 resources/release 分别结束任务。
    取消 PLANNED 车次原子释放资源和未执行取货关联，原单重新成为候选；已发车不可取消。
    写命令具备车次版本及请求键，同键同内容重放不重复写入，同键不同内容拒绝。普通业务返回 HTTP 200 + body.code。
security:
  - bearerAuth: []
paths:
  /api/platform/v1/last-leg/fleet/pickups:
    get:
      summary: 分页读取待取货需求
      description: 仅平台主体，权限 platform:fleet:trip:list。返回客户与原单、取货地址联系人、预报箱数、期望入仓时间及仓库名称编码。
      parameters:
        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
        - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 20}}
        - {name: keyword, in: query, schema: {type: string, maxLength: 128}}
      responses: {'200': {description: ApiResponse 分页候选}}
    post:
      summary: 选单创建同仓多点取货车次
      description: 仅平台主体，权限 platform:fleet:trip:create；创建后沿原 assignment 接口分配车辆司机，复用原 plan 接口调整时间，取货路线由原单地址确定。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [sources, plannedDepartureAt, expectedDriverEndAt, idempotencyKey]
              properties:
                sources:
                  type: array
                  minItems: 1
                  maxItems: 100
                  items:
                    type: object
                    required: [customerId, transferNo]
                    properties:
                      customerId: {type: string}
                      transferNo: {type: string}
                plannedDepartureAt: {type: string, format: date-time}
                expectedDriverEndAt: {type: string, format: date-time}
                remark: {type: string, maxLength: 1000}
                idempotencyKey: {type: string, minLength: 8, maxLength: 128}
      responses: {'200': {description: ApiResponse FleetTripModels.Detail，trip.tripPurpose=PICKUP}}
  /api/platform/v1/last-leg/fleet/pickups/{tripNo}/tasks:
    parameters: [{$ref: '#/components/parameters/tripNo'}]
    get:
      summary: 读取本车所有逐票取货任务
      description: 仅平台主体，权限 platform:fleet:trip:list。任务状态 WAITING / ASSIGNED / PICKED / ARRIVED；凭证按本票返回，不暴露文件公共直链。
      responses: {'200': {description: ApiResponse Task 数组}}
  /api/platform/v1/last-leg/fleet/pickups/{tripNo}/depart:
    parameters: [{$ref: '#/components/parameters/tripNo'}]
    post:
      summary: 确认取货发车
      description: 仅平台主体，权限 platform:fleet:trip:assign。复验车辆状态、司机资格、任务覆盖和两类资源占用。只推进车次 IN_TRANSIT，不触发出库。
      requestBody: {$ref: '#/components/requestBodies/command'}
      responses: {'200': {description: ApiResponse FleetTripModels.Detail}}
  /api/platform/v1/last-leg/fleet/pickups/{tripNo}/tasks/{customerId}/{transferNo}/files:
    parameters: [{$ref: '#/components/parameters/tripNo'}, {$ref: '#/components/parameters/customerId'}, {$ref: '#/components/parameters/transferNo'}]
    post:
      summary: 上传本票取货凭证
      description: 仅平台主体，权限 platform:fleet:trip:edit。最大10MiB，File沿 FLEET_TRIP_OPERATION_EVIDENCE / tenantId=0 / businessId=车次ID校验格式；Lastleg另存当前票上传归属。
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties: {file: {type: string, format: binary}}
      responses: {'200': {description: ApiResponse 文件ID、名称、类型和大小}}
  /api/platform/v1/last-leg/fleet/pickups/{tripNo}/tasks/{customerId}/{transferNo}/picked:
    parameters: [{$ref: '#/components/parameters/tripNo'}, {$ref: '#/components/parameters/customerId'}, {$ref: '#/components/parameters/transferNo'}]
    post:
      summary: 逐票确认取货
      description: 仅平台主体，权限 platform:fleet:trip:edit。车次已发车且任务 ASSIGNED，核对本票本车上传归属后转 PICKED，实提箱数不覆盖预报。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [recordVersion, idempotencyKey, actualPackages, evidenceFileIds]
              properties:
                recordVersion: {type: integer, format: int64, minimum: 0}
                idempotencyKey: {type: string, minLength: 8, maxLength: 128}
                actualPackages: {type: integer, minimum: 1, maximum: 5000}
                evidenceFileIds: {type: array, minItems: 1, maxItems: 10, items: {type: string, description: 正Long文件ID}}
                remark: {type: string, maxLength: 1000}
      responses: {'200': {description: ApiResponse 当前本车 Task 数组；车次版本已更新}}
  /api/platform/v1/last-leg/fleet/pickups/{tripNo}/tasks/{customerId}/{transferNo}/arrive:
    parameters: [{$ref: '#/components/parameters/tripNo'}, {$ref: '#/components/parameters/customerId'}, {$ref: '#/components/parameters/transferNo'}]
    post:
      summary: 确认本票送达海外仓
      description: 仅平台主体，权限 platform:fleet:trip:edit。仅 PICKED 可以转 ARRIVED；开放原 PDA 清点，不直接完成测量或入库。
      requestBody: {$ref: '#/components/requestBodies/command'}
      responses: {'200': {description: ApiResponse 当前本车 Task 数组；车次版本已更新}}
  /api/platform/v1/last-leg/fleet/pickups/{tripNo}/complete:
    parameters: [{$ref: '#/components/parameters/tripNo'}]
    post:
      summary: 全车送仓后结案取货运输
      description: 仅平台主体，权限 platform:fleet:trip:complete。全车非空且均 ARRIVED，车次转 COMPLETED；原单继续仓库作业，不自动释放车和司机。
      requestBody: {$ref: '#/components/requestBodies/command'}
      responses: {'200': {description: ApiResponse FleetTripModels.Detail}}
  /api/merchant/v1/last-leg/warehouse-transfers/{transferNo}/pickup-progress:
    parameters: [{$ref: '#/components/parameters/transferNo'}]
    get:
      summary: 客户读取本企业本票取货安排
      description: 权限 merchant:overseas-warehouse:transfer:list；客户ID从认证上下文取得，自送及库存来源返回null。仅返回本票运输与凭证，不授予整车读取。
      responses: {'200': {description: ApiResponse Task或null}}
  /api/platform/v1/last-leg/warehouse-transfers/{transferNo}/pickup-progress:
    parameters:
      - {$ref: '#/components/parameters/transferNo'}
      - {name: customerId, in: query, required: true, schema: {type: string}}
    get:
      summary: 平台尾程详情读取本票取货安排
      description: 仅平台主体，权限 platform:overseas-warehouse:last-mile-order:list。
      responses: {'200': {description: ApiResponse Task或null}}
  /api/merchant/v1/last-leg/warehouse-transfers/{transferNo}/pickup-evidence/{fileId}:
    parameters: [{$ref: '#/components/parameters/transferNo'}, {$ref: '#/components/parameters/fileId'}]
    get:
      summary: 客户下载本票已确认凭证
      description: 权限 merchant:overseas-warehouse:transfer:list；复验客户、原订单、文件引用及File归属，no-store。
      responses: {'200': {description: application/octet-stream 文件；业务错误仍为ApiResponse}}
  /api/platform/v1/last-leg/warehouse-transfers/{transferNo}/pickup-evidence/{fileId}:
    parameters:
      - {$ref: '#/components/parameters/transferNo'}
      - {$ref: '#/components/parameters/fileId'}
      - {name: customerId, in: query, required: true, schema: {type: string}}
    get:
      summary: 平台下载本票已确认凭证
      description: 仅平台主体，权限 platform:fleet:trip:list 或 platform:overseas-warehouse:last-mile-order:list；复验本票文件引用，不因共车授权其他客户文件。
      responses: {'200': {description: application/octet-stream 文件；业务错误仍为ApiResponse}}
components:
  securitySchemes:
    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
  parameters:
    tripNo: {name: tripNo, in: path, required: true, schema: {type: string}}
    customerId: {name: customerId, in: path, required: true, schema: {type: string}}
    transferNo: {name: transferNo, in: path, required: true, schema: {type: string}}
    fileId: {name: fileId, in: path, required: true, schema: {type: integer, format: int64}}
  requestBodies:
    command:
      required: true
      content:
        application/json:
          schema:
            type: object
            required: [recordVersion, idempotencyKey, reason]
            properties:
              recordVersion: {type: integer, format: int64, minimum: 0}
              idempotencyKey: {type: string, minLength: 8, maxLength: 128}
              reason: {type: string, maxLength: 1000}