openapi: 3.0.3
info: {title: Firstleg Terminal Drayage API, version: 1.0.0}
paths:
  /api/platform/v1/terminal-drayages:
    get:
      summary: 批量查询货柜码头拖车及服务端报空预警
      x-permission: platform:firstleg:terminal-drayage:list
      parameters:
        - name: containerBookingIds
          in: query
          required: true
          schema: {type: array, minItems: 1, maxItems: 200, items: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses: {'200': {$ref: '#/components/responses/ViewsResponse'}}
  /api/platform/v1/terminal-drayages/{containerBookingId}:
    get:
      summary: 查询单柜码头拖车详情
      description: 已确认国内离仓的货柜即使船节点跟踪任务尚未建立也返回WAITING_FOR_ARRIVAL空详情；实际操作仍按到港、清关和卸柜节点校验
      x-permission: platform:firstleg:terminal-drayage:list
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
      responses: {'200': {$ref: '#/components/responses/ViewResponse'}}
  /api/platform/v1/terminal-drayages/{containerBookingId}/history:
    get:
      summary: 查询单柜码头拖车操作历史
      x-permission: platform:firstleg:terminal-drayage:list
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
      responses: {'200': {$ref: '#/components/responses/HistoryResponse'}}
  /api/platform/v1/terminal-drayages/{containerBookingId}/fleet:
    post:
      summary: 到港后选择或更换码头车队
      x-permission: platform:firstleg:terminal-drayage:fleet:edit
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/FleetSelectionRequest'}}}}
      responses: {'200': {$ref: '#/components/responses/ViewResponse'}}
  /api/platform/v1/terminal-drayages/{containerBookingId}/pickup-appointment:
    post:
      summary: 预约目的港提柜时间
      x-permission: platform:firstleg:terminal-drayage:pickup-appointment:edit
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/PickupAppointmentRequest'}}}}
      responses: {'200': {$ref: '#/components/responses/ViewResponse'}}
  /api/platform/v1/terminal-drayages/{containerBookingId}/empty-return:
    post:
      summary: 海外卸柜收货完成后确认实际还柜并推进EMPTY_RETURNED节点
      description: 以海外卸柜完成事实开放还柜；无需已有车队、预约或实际提柜记录。无拖车记录时提交 expectedVersion=0，由命令创建记录，不补造提柜时间。实际还柜时间不得早于卸柜完成时间及已有实际提柜时间。
      x-permission: platform:firstleg:terminal-drayage:empty-return:confirm
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/ActualTimeRequest'}}}}
      responses: {'200': {$ref: '#/components/responses/ViewResponse'}}
  /api/platform/v1/terminal-drayages/{containerBookingId}/pickup-email:
    post:
      summary: 将当前车队提柜邮件加入发送队列
      description: 初次选择车队不发信；此命令携带版本和幂等键，发送成功是任务已入队，不表示已送达。人工可使用最新版本重复发送提柜请求。更换车队时，原车队存在提柜请求邮件记录才原子入队取消邮件，并始终为新车队入队提柜请求；原车队从未下发时不发送取消邮件。同一车队重复选择不发信。
      x-permission: platform:firstleg:terminal-drayage:fleet:edit
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}, {$ref: '#/components/parameters/IdempotencyKey'}]
      requestBody: {required: true, content: {application/json: {schema: {type: object, required: [expectedVersion], properties: {expectedVersion: {type: integer, minimum: 0}}}}}}
      responses: {'200': {$ref: '#/components/responses/ViewResponse'}}
  /api/platform/v1/terminal-drayages/{containerBookingId}/emails:
    get:
      summary: 查询最近100封车队邮件及发信开关
      description: 已确认国内离仓的货柜允许读取空邮件列表，不以船节点跟踪任务是否已经建立作为货柜存在性条件
      x-permission: platform:firstleg:terminal-drayage:list
      parameters: [{$ref: '#/components/parameters/ContainerBookingId'}]
      responses:
        '200':
          description: 邮件记录；SENT表示SMTP已接受，不表示收件人已阅读
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  data:
                    type: object
                    properties:
                      deliveryEnabled: {type: boolean}
                      records: {type: array, items: {$ref: '#/components/schemas/EmailTask'}}
  /api/platform/v1/terminal-drayages/{containerBookingId}/emails/{mailId}/retry:
    post:
      summary: 核对失败邮件未收到后手动重试
      description: 仅FAILED状态可重试，服务端校验mailId归属本柜；失败可能已经送达，须人工核对。同柜邮件依次发送，失败阻断后续邮件。
      x-permission: platform:firstleg:terminal-drayage:fleet:edit
      parameters:
        - {$ref: '#/components/parameters/ContainerBookingId'}
        - {name: mailId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
      responses: {'200': {description: 已重新入队}}
components:
  parameters:
    ContainerBookingId: {name: containerBookingId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
    IdempotencyKey: {name: Idempotency-Key, in: header, required: true, schema: {type: string, minLength: 1, maxLength: 255}}
  schemas:
    EmailTask:
      type: object
      properties:
        id: {type: string}
        containerBookingId: {type: string}
        fleetSupplierId: {type: string}
        fleetName: {type: string}
        recipient: {type: string, format: email}
        kind: {type: string, enum: [REQUEST_PICKUP, CANCEL_PICKUP]}
        subject: {type: string}
        body: {type: string}
        status: {type: string, enum: [PENDING, SENDING, SENT, FAILED]}
        attempts: {type: integer}
        failureReason: {type: string, nullable: true}
        createdAt: {type: string, format: date-time}
        sentAt: {type: string, format: date-time, nullable: true}
    FleetSelectionRequest:
      type: object
      required: [expectedVersion, fleetSupplierId]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        fleetSupplierId: {type: string, pattern: '^[1-9][0-9]*$', description: Warehouse ACTIVE/TRUCKING且truckingScope=OVERSEAS的海外车队供应商ID}
        fleetSupplierName: {type: string, maxLength: 128, nullable: true, description: 可选一致性提示，持久化名称以服务端快照为准}
        reason: {type: string, maxLength: 500, nullable: true}
    PickupAppointmentRequest:
      type: object
      required: [expectedVersion, pickupAppointmentAt]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        pickupAppointmentAt: {type: string, format: date-time}
        reason: {type: string, maxLength: 500, nullable: true}
    ActualTimeRequest:
      type: object
      required: [expectedVersion, actualAt]
      properties:
        expectedVersion: {type: integer, minimum: 0}
        actualAt: {type: string, format: date-time}
        remark: {type: string, maxLength: 500, nullable: true}
    Warning:
      type: object
      required: [status, overdueHours, overdueDays]
      properties:
        status: {type: string, enum: [NOT_APPLICABLE, PENDING, OVERDUE, RESOLVED]}
        deadlineAt: {type: string, format: date-time, nullable: true, description: 卸柜完成时间加72小时}
        overdueHours: {type: integer, format: int64, minimum: 0}
        overdueDays: {type: integer, format: int64, minimum: 0}
    TerminalDrayageView:
      type: object
      required: [containerBookingId, status, version, emptyReturnWarning, allowedActions, actualFacts]
      properties:
        containerBookingId: {type: string, pattern: '^[1-9][0-9]*$'}
        containerNo: {type: string, nullable: true}
        oceanBookingId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
        status: {type: string, enum: [WAITING_FOR_ARRIVAL, ARRIVED, PICKUP_SCHEDULED, PICKED_UP, UNLOADED, EMPTY_RETURNED]}
        version: {type: integer, minimum: 0}
        fleetSupplierId: {type: string, pattern: '^[1-9][0-9]*$', nullable: true}
        fleetSupplierName: {type: string, nullable: true}
        pickupAppointmentAt: {type: string, format: date-time, nullable: true}
        actualPickupAt: {type: string, format: date-time, nullable: true, description: 优先使用实际船节点提柜时间；缺失时在海外PDA确认整柜拆柜完成后使用卸柜完成时间}
        estimatedEmptyReturnAt: {type: string, format: date-time, nullable: true, description: 服务端权威值，卸柜完成时间加72小时}
        actualEmptyReturnAt: {type: string, format: date-time, nullable: true}
        unloadingCompletedAt: {type: string, format: date-time, nullable: true}
        emptyReturnWarning: {$ref: '#/components/schemas/Warning'}
        allowedActions: {type: array, items: {type: string, enum: [SELECT_FLEET, SCHEDULE_PICKUP, RECORD_EMPTY_RETURN, SEND_PICKUP_EMAIL]}}
        actualFacts: {$ref: '#/components/schemas/ContainerActualFacts'}
        updatedAt: {type: string, format: date-time, nullable: true}
    ContainerActualFacts:
      type: object
      required: [containerBookingId, queryId, queryVersion, queryStatus]
      properties:
        containerBookingId: {type: string, pattern: '^[1-9][0-9]*$'}
        queryId: {type: string, pattern: '^[1-9][0-9]*$'}
        queryVersion: {type: integer, minimum: 0}
        queryStatus: {type: string}
        latestActualNode: {type: string, nullable: true}
        latestActualAt: {type: string, format: date-time, nullable: true}
        departedWarehouseAt: {type: string, format: date-time, nullable: true}
        departedOriginPortAt: {type: string, format: date-time, nullable: true}
        arrivedDestinationPortAt: {type: string, format: date-time, nullable: true}
        pickupReadyAt: {type: string, format: date-time, nullable: true}
        pickedUpAt: {type: string, format: date-time, nullable: true}
        emptyReturnedAt: {type: string, format: date-time, nullable: true}
    History:
      type: object
      required: [action, fromStatus, toStatus, fromVersion, toVersion, operatorId, createdAt]
      properties:
        action: {type: string, enum: [SELECT_FLEET, SCHEDULE_PICKUP, RECORD_EMPTY_RETURN, SEND_PICKUP_EMAIL]}
        fromStatus: {type: string}
        toStatus: {type: string}
        fromVersion: {type: integer, minimum: 0}
        toVersion: {type: integer, minimum: 1}
        reason: {type: string, nullable: true}
        operatorId: {type: string, pattern: '^[1-9][0-9]*$'}
        operatorName: {type: string, nullable: true}
        createdAt: {type: string, format: date-time}
    ApiView: {type: object, required: [code, data], properties: {code: {type: string}, message: {type: string}, data: {$ref: '#/components/schemas/TerminalDrayageView'}}}
    ApiViews: {type: object, required: [code, data], properties: {code: {type: string}, message: {type: string}, data: {type: array, items: {$ref: '#/components/schemas/TerminalDrayageView'}}}}
    ApiHistory: {type: object, required: [code, data], properties: {code: {type: string}, message: {type: string}, data: {type: array, items: {$ref: '#/components/schemas/History'}}}}
  responses:
    ViewResponse: {description: 成功, content: {application/json: {schema: {$ref: '#/components/schemas/ApiView'}}}}
    ViewsResponse: {description: 成功, content: {application/json: {schema: {$ref: '#/components/schemas/ApiViews'}}}}
    HistoryResponse: {description: 成功, content: {application/json: {schema: {$ref: '#/components/schemas/ApiHistory'}}}}