baiyue-firstleg/lastleg-service/src/main/resources/openapi/dispatch-vehicle-documents-v1.yaml

openapi: 3.0.3
info:
  title: 排车车辆资料
  version: 1.0.0
  description: 仅平台有效排车DELIVERING/DELIVERED可用；兼容有无拼车货物，沿装车归属证据校验。共享原车队照片、版本、命令与历史，不新建附件存储。派送文件仍使用delivery-orders
    documents；不把车队RECEIPT照片当签收。列表权限只读，排车edit独立写；恢复还需list。
security:
- bearerAuth: []
paths:
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/vehicle-documents:
    get:
      operationId: getDispatchVehicleDocuments
      summary: 读取本车油耗图片；复用车队附加记录
      x-permission-code: platform:overseas-warehouse:dispatch:list
      parameters:
      - $ref: '#/components/parameters/dispatchNo'
      responses:
        '200':
          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Documents'
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/vehicle-documents/{slot}/uploads:
    post:
      operationId: uploadDispatchVehiclePhoto
      summary: 准备本车油耗图片；尚未绑定保存
      x-permission-code: platform:overseas-warehouse:dispatch:edit
      parameters:
      - $ref: '#/components/parameters/dispatchNo'
      - $ref: '#/components/parameters/slot'
      responses:
        '200':
          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Photo'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
              - file
              - idempotencyKey
              properties:
                file:
                  type: string
                  format: binary
                  description: 非空JPG/PNG，最大10MiB
                idempotencyKey:
                  type: string
                  minLength: 8
                  maxLength: 128
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/vehicle-documents/{slot}:
    put:
      operationId: bindDispatchVehiclePhoto
      summary: 按附加版本绑定原上传文件，不改变排车或签收状态
      x-permission-code: platform:overseas-warehouse:dispatch:edit
      parameters:
      - $ref: '#/components/parameters/dispatchNo'
      - $ref: '#/components/parameters/slot'
      responses:
        '200':
          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Documents'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BindPhoto'
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/vehicle-documents/{slot}/files/{fileId}/content:
    get:
      operationId: readDispatchVehiclePhoto
      summary: 只读取本车当前绑定图片
      x-permission-code: platform:overseas-warehouse:dispatch:list
      parameters:
      - $ref: '#/components/parameters/dispatchNo'
      - $ref: '#/components/parameters/slot'
      - $ref: '#/components/parameters/fileId'
      responses:
        '200':
          description: no-store图片内容
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/vehicle-documents/uploads/{idempotencyKey}:
    get:
      operationId: recoverDispatchVehiclePhoto
      summary: 只恢复当前操作者原油耗上传成功结果，未知结果拒绝重传
      x-permission-code: platform:overseas-warehouse:dispatch:edit
      parameters:
      - $ref: '#/components/parameters/dispatchNo'
      - $ref: '#/components/parameters/idempotencyKey'
      responses:
        '200':
          description: 成功；业务错误沿ApiResponse返回A0400/A0403/A0404/A0409及诊断编号
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  data:
                    $ref: '#/components/schemas/Photo'
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
  parameters:
    dispatchNo:
      name: dispatchNo
      in: path
      required: true
      schema:
        type: string
    slot:
      name: slot
      in: path
      required: true
      schema:
        type: string
        enum:
        - FUEL_START
        - FUEL_END
    fileId:
      name: fileId
      in: path
      required: true
      schema:
        type: string
    idempotencyKey:
      name: idempotencyKey
      in: path
      required: true
      schema:
        type: string
  schemas:
    Photo:
      type: object
      required:
      - slot
      - fileId
      - fileName
      - contentType
      - sizeBytes
      - uploadedAt
      properties:
        slot:
          type: string
          enum:
          - FUEL_START
          - FUEL_END
        category:
          type: string
          enum:
          - FUEL
        fileId:
          type: string
        fileName:
          type: string
        contentType:
          type: string
        sizeBytes:
          type: string
        uploadedAt:
          type: string
        savedAt:
          type: string
          nullable: true
    Documents:
      type: object
      required:
      - dispatchNo
      - recordVersion
      - editable
      - photos
      properties:
        dispatchNo:
          type: string
        recordVersion:
          type: string
        editable:
          type: boolean
        photos:
          type: array
          items:
            $ref: '#/components/schemas/Photo'
    BindPhoto:
      type: object
      required:
      - recordVersion
      - idempotencyKey
      - fileId
      properties:
        recordVersion:
          type: string
          pattern: ^(0|[1-9][0-9]*)$
        idempotencyKey:
          type: string
          minLength: 8
          maxLength: 128
        fileId:
          type: string
        replaceFileId:
          type: string
          nullable: true
          pattern: "^[1-9][0-9]*$"
          description: 待替换的当前同类文件ID；省略时装车照片追加，每类最多5张，油耗沿单张替换。