openapi: 3.0.3
info:
  title: 车辆与司机档案照片
  version: 1.0.0
  description: >-
    档案照片使用独立版本并保留历史。车辆读取沿vehicle:list、上传沿vehicle:edit；
    司机读取沿driver:list、上传沿driver:upload，均位于platform:overseas-master-data权限域。
    只接受非空JPG/PNG，最大10MiB。排车保存时仅对缺失的车辆/司机照片复制当趟附件；
    后续更换档案照片不覆盖已有排车照片，不创建临时外配主档，不改变驾驶证审核。
    驾驶证仍走既有license接口；排车审核与主档统一接受PDF/JPG/PNG。
security:
  - bearerAuth: []
paths:
  /api/platform/v1/last-leg/fleet/resource-photos/{kind}/{id}:
    parameters:
      - {$ref: '#/components/parameters/Kind'}
      - {$ref: '#/components/parameters/Id'}
    get:
      summary: 读取当前档案照片，未上传时版本为0且photo为空
      responses:
        '200': {$ref: '#/components/responses/Detail'}
        '403': {description: 缺少该类档案list权限}
    post:
      summary: 上传或替换档案照片，照片版本冲突时不覆盖
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [recordVersion, file]
              properties:
                recordVersion: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
                file: {type: string, format: binary}
      responses:
        '200': {$ref: '#/components/responses/Detail'}
        '403': {description: 缺少车辆edit或司机upload权限}
  /api/platform/v1/last-leg/fleet/resource-photos/{kind}/{id}/{fileId}/content:
    parameters:
      - {$ref: '#/components/parameters/Kind'}
      - {$ref: '#/components/parameters/Id'}
      - {name: fileId, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
    get:
      summary: 读取本档案已关联的当前或历史图片，no-store且无匿名URL
      responses:
        '200':
          description: 图片内容；业务错误为统一JSON响应，不可当成图片
          content:
            image/jpeg: {schema: {type: string, format: binary}}
            image/png: {schema: {type: string, format: binary}}
        '403': {description: 缺少该类档案list权限}
components:
  securitySchemes:
    bearerAuth: {type: http, scheme: bearer, bearerFormat: JWT}
  parameters:
    Kind: {name: kind, in: path, required: true, schema: {type: string, enum: [VEHICLE, DRIVER]}}
    Id: {name: id, in: path, required: true, schema: {type: string, pattern: '^[1-9][0-9]*$'}}
  responses:
    Detail:
      description: 业务成功code为200；版本冲突或归属无效通过业务错误返回
      content:
        application/json:
          schema:
            type: object
            required: [code, data]
            properties:
              code: {type: string}
              message: {type: string}
              data:
                type: object
                required: [recordVersion, photo]
                properties:
                  recordVersion: {type: string, pattern: '^(0|[1-9][0-9]*)$'}
                  photo:
                    type: object
                    nullable: true
                    required: [fileId, fileName, contentType, sizeBytes]
                    properties:
                      fileId: {type: string, pattern: '^[1-9][0-9]*$'}
                      fileName: {type: string}
                      contentType: {type: string, enum: [image/jpeg, image/png]}
                      sizeBytes: {type: string, pattern: '^[1-9][0-9]*$'}