openapi: 3.0.3
info:
  title: 平台车辆管理司机档案
  version: 1.0.0
  description: >-
    平台司机主数据，列表权限包含详情、资格预览、历史和已关联证照读取。
    写操作独立鉴权且要求当前recordVersion；创建版本0，后续每次成功写入递增。
    证照或身份关键字段变化、替换附件后重新待审；电话和备注更正不撤销既有审核。
    驾驶证是当前资格最低要求，其他资质不隐式必填。日期按licenseZone计算，
    30天内到期但仍有效允许并提醒，任务结束达到有效截止日次日当地零点或更晚则禁止。
    缺少预计结束时间时资格返回MISSING_TRIP_END；资格预览不预留司机，不代替发车事务复核。
    新档案允许缺证照保存为PENDING，通过审核必须补齐编号、类型、有效期和真实附件。
    所有业务错误遵循HTTP200加code，认证或基础设施错误可返回401/403/503。
security:
  - bearerAuth: []
paths:
  /api/platform/v1/last-leg/fleet/drivers:
    get:
      summary: 分页查询司机及资格
      description: '权限：platform:overseas-master-data:driver:list；无逐行文件请求。'
      parameters:
        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
        - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
        - {name: keyword, in: query, schema: {type: string, maxLength: 128}}
        - {name: active, in: query, schema: {type: boolean}}
        - {name: reviewStatus, in: query, schema: {type: string, enum: [PENDING, APPROVED, REJECTED]}}
        - {name: ownership, in: query, schema: {type: string, enum: [OWNED, DISPATCHED]}}
        - {name: region, in: query, schema: {type: string, enum: [DOMESTIC, OVERSEAS]}}
        - {name: licenseState, in: query, schema: {type: string, enum: [MISSING, VALID, EXPIRING, EXPIRED]}, description: 仅驾驶证日期状态，与审核和附件状态分别展示}
        - {name: expectedEnd, in: query, schema: {type: string, format: date-time}}
      responses:
        '200':
          description: 业务响应，分页数据
          content:
            application/json:
              schema:
                allOf:
                  - {$ref: '#/components/schemas/Envelope'}
                  - properties:
                      data:
                        type: object
                        properties:
                          records: {type: array, items: {$ref: '#/components/schemas/Driver'}}
                          page: {type: integer}
                          size: {type: integer}
                          total: {type: integer}
                          pages: {type: integer}
                          summary: {$ref: '#/components/schemas/Summary'}
    post:
      summary: 创建待审司机档案
      description: '权限：platform:overseas-master-data:driver:create'
      requestBody: {required: true, content: {application/json: {schema: {$ref: '#/components/schemas/Draft'}}}}
      responses: {'200': {$ref: '#/components/responses/Driver'}}
  /api/platform/v1/last-leg/fleet/drivers/warehouse-options:
    get:
      summary: 获取当前区域可关联的公共仓库
      description: '权限：platform:overseas-master-data:driver:list；复用Warehouse内部有效目录，国内DOMESTIC，海外OVERSEAS/OVERSEAS_PARTNER，排除FBA目的仓；保存时再次校验。'
      parameters:
        - {name: region, in: query, required: true, schema: {type: string, enum: [DOMESTIC, OVERSEAS]}}
      responses:
        '200':
          description: 业务响应，data为仓库候选
          content:
            application/json:
              schema:
                allOf:
                  - {$ref: '#/components/schemas/Envelope'}
                  - properties:
                      data: {type: array, items: {$ref: '#/components/schemas/WarehouseOption'}}
  /api/platform/v1/last-leg/fleet/drivers/{id}:
    parameters: [{$ref: '#/components/parameters/Id'}]
    get:
      summary: 司机详情
      description: '权限：platform:overseas-master-data:driver:list'
      parameters:
        - {name: expectedEnd, in: query, schema: {type: string, format: date-time}}
      responses: {'200': {$ref: '#/components/responses/Driver'}}
    put:
      summary: 编辑档案，关键字段变化后重新待审
      description: '权限：platform:overseas-master-data:driver:edit'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [recordVersion, details]
              properties:
                recordVersion: {type: integer, format: int64, minimum: 0}
                details: {$ref: '#/components/schemas/Draft'}
      responses: {'200': {$ref: '#/components/responses/Driver'}}
  /api/platform/v1/last-leg/fleet/drivers/{id}/status:
    parameters: [{$ref: '#/components/parameters/Id'}]
    patch:
      summary: 启停司机并记录原因
      description: '权限：platform:overseas-master-data:driver:status；停用后不可派车，历史保留。'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [recordVersion, active, reason]
              properties:
                recordVersion: {type: integer, format: int64, minimum: 0}
                active: {type: boolean}
                reason: {type: string, minLength: 1, maxLength: 1000}
      responses: {'200': {$ref: '#/components/responses/Driver'}}
  /api/platform/v1/last-leg/fleet/drivers/{id}/review:
    parameters: [{$ref: '#/components/parameters/Id'}]
    post:
      summary: 通过或打回司机证照
      description: '权限：platform:overseas-master-data:driver:review；仅PENDING允许审核；打回原因必填；通过前校验真实附件归属与证照有效性。'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [recordVersion, decision]
              properties:
                recordVersion: {type: integer, format: int64, minimum: 0}
                decision: {type: string, enum: [APPROVED, REJECTED]}
                reason: {type: string, maxLength: 1000}
      responses: {'200': {$ref: '#/components/responses/Driver'}}
  /api/platform/v1/last-leg/fleet/drivers/{id}/submit:
    parameters: [{$ref: '#/components/parameters/Id'}]
    post:
      summary: 已打回档案重新提交
      description: '权限：platform:overseas-master-data:driver:edit；仅REJECTED；先校验证照完整及文件归属。'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [recordVersion]
              properties:
                recordVersion: {type: integer, format: int64, minimum: 0}
      responses: {'200': {$ref: '#/components/responses/Driver'}}
  /api/platform/v1/last-leg/fleet/drivers/{id}/qualification:
    parameters: [{$ref: '#/components/parameters/Id'}]
    get:
      summary: 按预计任务结束时间预览派车资格
      description: '权限：platform:overseas-master-data:driver:list；预计结束应覆盖本司机承担的返程或转场。'
      parameters:
        - {name: expectedEnd, in: query, required: true, schema: {type: string, format: date-time}}
      responses:
        '200':
          description: 资格结果，canDispatch与expiringSoon独立
          content:
            application/json:
              schema:
                allOf:
                  - {$ref: '#/components/schemas/Envelope'}
                  - properties:
                      data: {$ref: '#/components/schemas/Qualification'}
  /api/platform/v1/last-leg/fleet/drivers/{id}/history:
    parameters: [{$ref: '#/components/parameters/Id'}]
    get:
      summary: 分页读取司机操作与审核历史
      description: '权限：platform:overseas-master-data:driver:list；按版本降序，snapshot是历史当时的档案及资格，不能用作当前派车门禁。'
      parameters:
        - {name: page, in: query, schema: {type: integer, minimum: 1, default: 1}}
        - {name: size, in: query, schema: {type: integer, minimum: 1, maximum: 200, default: 20}}
      responses:
        '200':
          description: 业务响应，data为含records/page/size/total/pages的分页
          content:
            application/json:
              schema:
                allOf:
                  - {$ref: '#/components/schemas/Envelope'}
                  - properties:
                      data:
                        type: object
                        properties:
                          records: {type: array, items: {$ref: '#/components/schemas/History'}}
                          page: {type: integer}
                          size: {type: integer}
                          total: {type: integer}
                          pages: {type: integer}
  /api/platform/v1/last-leg/fleet/drivers/{id}/license:
    parameters: [{$ref: '#/components/parameters/Id'}]
    post:
      summary: 上传并绑定驾驶证，重置为待审
      description: '权限：platform:overseas-master-data:driver:upload；复合归属固定平台0、FLEET_DRIVER_LICENSE、当前司机；非空PDF/JPG/PNG不超过10MiB，校验MIME和签名，旧版本附件保留在历史中。'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [recordVersion, file]
              properties:
                recordVersion: {type: integer, format: int64, minimum: 0}
                file: {type: string, format: binary}
      responses: {'200': {$ref: '#/components/responses/Driver'}}
  /api/platform/v1/last-leg/fleet/drivers/{id}/license/{fileId}:
    parameters:
      - {$ref: '#/components/parameters/Id'}
      - {name: fileId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
    get:
      summary: 下载当前或历史已关联驾驶证
      description: '权限：platform:overseas-master-data:driver:list；校验关联和File复合归属，attachment下载，Cache-Control no-store，拒绝未绑定文件。'
      responses:
        '200':
          description: 文件内容；业务错误仍需识别JSON响应
          content:
            application/pdf: {schema: {type: string, format: binary}}
            image/jpeg: {schema: {type: string, format: binary}}
            image/png: {schema: {type: string, format: binary}}
components:
  securitySchemes:
    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
  parameters:
    Id: {name: id, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
  responses:
    Driver:
      description: 业务响应，data为司机详情
      content:
        application/json:
          schema:
            allOf:
              - {$ref: '#/components/schemas/Envelope'}
              - properties:
                  data: {$ref: '#/components/schemas/Driver'}
  schemas:
    Envelope:
      type: object
      properties:
        code: {type: string}
        message: {type: string, nullable: true}
        data: {type: object, nullable: true}
    Draft:
      type: object
      required: [name, phone, ownership, region, licenseZone]
      properties:
        name: {type: string, minLength: 1, maxLength: 128}
        phone: {type: string, minLength: 1, maxLength: 64}
        ownership: {type: string, enum: [OWNED, DISPATCHED]}
        region: {type: string, enum: [DOMESTIC, OVERSEAS]}
        licenseNumber: {type: string, nullable: true, maxLength: 128}
        licenseType: {type: string, nullable: true, maxLength: 64}
        licenseIssuedOn: {type: string, format: date, nullable: true}
        licenseExpiresOn: {type: string, format: date, nullable: true}
        licenseZone: {type: string, maxLength: 64, description: IANA时区，如America/Los_Angeles}
        remark: {type: string, nullable: true, maxLength: 1000}
        profile: {$ref: '#/components/schemas/Profile'}
    Profile:
      type: object
      nullable: true
      description: 可选补充资料；当前其他资质日期不自动作为派车必需条件
      properties:
        warehouseId: {type: string, nullable: true, pattern: '^[1-9][0-9]*$'}
        vehicleModels: {type: string, nullable: true, maxLength: 128}
        languagesAndArea: {type: string, nullable: true, maxLength: 256}
        medicalExpiresOn: {type: string, format: date, nullable: true}
        trainingExpiresOn: {type: string, format: date, nullable: true}
        insuranceExpiresOn: {type: string, format: date, nullable: true}
    WarehouseOption:
      type: object
      properties:
        id: {type: string}
        code: {type: string}
        name: {type: string}
        region: {type: string, enum: [DOMESTIC, OVERSEAS]}
    Summary:
      type: object
      description: 与列表共用筛选范围，按各证照时区计算30天（含）提醒，不以浏览器时区计算
      properties:
        total: {type: integer, format: int64}
        owned: {type: integer, format: int64}
        dispatched: {type: integer, format: int64}
        expiringSoon: {type: integer, format: int64}
        expired: {type: integer, format: int64}
    Driver:
      type: object
      properties:
        id: {type: string}
        driverNo: {type: string, description: 独立生成的业务编号}
        details: {$ref: '#/components/schemas/Draft'}
        active: {type: boolean}
        reviewStatus: {type: string, enum: [PENDING, APPROVED, REJECTED]}
        licenseFileId: {type: string, nullable: true}
        recordVersion: {type: integer, format: int64}
        updatedBy: {type: string}
        updatedAt: {type: string, description: UTC本地日期时间}
        qualification: {$ref: '#/components/schemas/Qualification'}
        licenseState: {type: string, enum: [MISSING, VALID, EXPIRING, EXPIRED]}
        warehouseCode: {type: string, nullable: true}
        warehouseName: {type: string, nullable: true}
    Qualification:
      type: object
      properties:
        canDispatch: {type: boolean}
        expiringSoon: {type: boolean}
        reason:
          type: string
          enum: [ELIGIBLE, INACTIVE, MISSING_LICENSE, MISSING_EXPIRY, PENDING_REVIEW, REJECTED, EXPIRED, MISSING_TRIP_END, INVALID_TRIP_END, EXPIRES_DURING_TRIP]
        licenseExpiresOn: {type: string, format: date, nullable: true}
    History:
      type: object
      properties:
        recordVersion: {type: integer, format: int64}
        action: {type: string, enum: [CREATE, UPDATE, ACTIVATE, DEACTIVATE, UPLOAD_LICENSE, APPROVED, REJECTED, RESUBMIT]}
        reason: {type: string, nullable: true}
        operatorId: {type: string}
        occurredAt: {type: string, description: UTC本地日期时间}
        snapshot: {$ref: '#/components/schemas/Driver'}