openapi: 3.0.3
info:
  title: 车辆履约与更换历史
  version: 1.0.0
  description: >-
    平台按稳定车辆ID读取Lastleg本库履约事实，不按当前车牌文本反查，不修改单据或历史。
    计划中的派送归当前分配车辆；实际发车后按不可变DEPART及在途交接快照中的车辆身份归属。接替车辆仅关联交接时未完成且属于原客户的派送。
    关联排车和派送时同时匹配客户归属，不返回财务、附件、联系人或内部数据库主键。
    更换记录依据相邻车次版本的ASSIGN或HANDOVER快照；在途交接仅列实际剩余货物涉及的排车单，首次分配和资源未变化的操作不算更换。
    旧车和新车均能读取同一更换事实；仅换司机也保留。返回历史车牌/姓名，不用当前主档覆盖。
    不生成原型示例记录；没有正式车次关联的旧派送不通过车牌猜测归属。
security: [{bearerAuth: []}]
paths:
  /api/platform/v1/last-leg/fleet/vehicles/{vehicleId}/deliveries:
    parameters:
      - {$ref: '#/components/parameters/Vehicle'}
      - {$ref: '#/components/parameters/Page'}
      - {$ref: '#/components/parameters/Size'}
    get:
      summary: 当前车辆关联派送记录
      description: '同时要求 platform:overseas-master-data:vehicle:list 与 platform:overseas-warehouse:delivery:list。按派送创建时间、内部排序键倒序分页；排序键不返回。'
      responses:
        '200':
          description: '统一ApiResponse，成功code为200，data为分页；车辆不存在返回业务404语义。'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  data:
                    allOf:
                      - {$ref: '#/components/schemas/Page'}
                      - type: object
                        properties:
                          records: {type: array, items: {$ref: '#/components/schemas/Delivery'}}
  /api/platform/v1/last-leg/fleet/vehicles/{vehicleId}/assignment-history:
    parameters:
      - {$ref: '#/components/parameters/Vehicle'}
      - {$ref: '#/components/parameters/Page'}
      - {$ref: '#/components/parameters/Size'}
    get:
      summary: 当前车辆相关的换车与换司机事实
      description: '同时要求 platform:overseas-master-data:vehicle:list 与 platform:fleet:trip:list。按事件时间、历史排序键倒序分页，一行一个变更事件；关联排车使用该事件快照，不使用当前关联覆盖历史。'
      responses:
        '200':
          description: '统一ApiResponse，data为分页。历史记录只含稳定业务编号及更换事实，不公开整份客户快照或操作人内部ID。'
          content:
            application/json:
              schema:
                type: object
                properties:
                  code: {type: string}
                  data:
                    allOf:
                      - {$ref: '#/components/schemas/Page'}
                      - type: object
                        properties:
                          records: {type: array, items: {$ref: '#/components/schemas/Change'}}
components:
  securitySchemes:
    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
  parameters:
    Vehicle: {name: vehicleId, in: path, required: true, schema: {type: integer, format: int64, minimum: 1}}
    Page: {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
    Size: {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 100, default: 10}}
  schemas:
    Page:
      type: object
      required: [records, page, size, total, pages]
      properties:
        page: {type: integer, minimum: 1}
        size: {type: integer, minimum: 1, maximum: 100}
        total: {type: integer, format: int64, minimum: 0}
        pages: {type: integer, format: int64, minimum: 0}
    Delivery:
      type: object
      required: [deliveryNo, dispatchNo, tripNo, status, relationship]
      properties:
        deliveryNo: {type: string}
        dispatchNo: {type: string}
        tripNo: {type: string}
        bolNo: {type: string, nullable: true}
        customerName: {type: string, nullable: true}
        destinationType: {type: string}
        destinationWarehouseCode: {type: string, nullable: true}
        destinationWarehouseName: {type: string, nullable: true}
        deliveryAddress: {type: string, nullable: true}
        plannedDeliveryAt: {type: string, nullable: true, description: 服务端作业时区的本地日期时间}
        status: {type: string}
        relationship: {type: string, enum: [PLANNED, DEPARTED]}
    Change:
      type: object
      required: [tripNo, recordVersion, occurredAt, relationship, dispatchNos]
      properties:
        tripNo: {type: string}
        recordVersion: {type: string, pattern: '^[0-9]+$', description: 车次版本字符串，与车次号组成事件标识}
        occurredAt: {type: string, format: date-time}
        reason: {type: string, nullable: true}
        previousVehiclePlate: {type: string, nullable: true}
        vehiclePlate: {type: string, nullable: true}
        previousDriverName: {type: string, nullable: true}
        driverName: {type: string, nullable: true}
        relationship: {type: string, enum: [REPLACED_OUT, REPLACED_IN, DRIVER_CHANGED]}
        dispatchNos: {type: array, items: {type: string}}