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

openapi: 3.0.3
info:
  title: 排车装车资料（Admin/PDA共用）
  version: 1.0.0
  description: 理货审核通过时，将本趟已核验驾驶证和车辆照片复制到空的司机驾驶证、车牌照片类别（每类最多5份），来源未变的已有照片保持不变；保存车辆、司机或证照来源变更时，对应类别旧资料与资源保存同事务失效并保留历史；换车另失效装车完成及封车照片，换司机另失效BOL签字，重审通过后只带入驾驶证与车牌资料；PDF驾驶证保留原件并计为一份。GET只读，不对存量记录补写。LOADING阶段即可同步上传并保存五个整车照片框；照片齐全不会提前发车。装车确认时资料已齐则直接进入DELIVERING，否则进入AFTER_LOADING，最后一次绑定自动生成派送并进入DELIVERING。触发推进的装车确认或照片绑定与派送同事务，失败保留先前已保存资料。复用车队照片记录，技术槽位沿用原文件归属，按顺序对应司机驾驶证、车牌照片、装车完成、封车照片、BOL司机签字；每类1至5张，允许追加或指定replaceFileId精确替换，不代表驾驶证审核或真实签收。PDA每次核验Token冻结仓，平台list只读、edit写；原键仅原操作者恢复。上传须携当前reviewRound并将轮次写入上传账本；绑定须携uploadKey核对原上传文件、分类、操作者及当前审核轮次，不允许用最新资料版本重绑旧轮次上传。
security:
- bearerAuth: []
paths:
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-documents:
    get:
      operationId: getDispatchLoadingDocuments
      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/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents:
    get:
      operationId: getDispatchLoadingDocumentsPda
      summary: 读取本车装车资料或原上传结果
      x-permission-code: lastleg:pda:operate
      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'
      x-required-role: OVERSEAS_WAREHOUSE_PDA_OPERATOR
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-documents/{slot}/uploads:
    post:
      operationId: uploadDispatchLoadingPhoto
      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
              - reviewRound
              properties:
                file:
                  type: string
                  format: binary
                  description: 非空JPG/PNG，司机驾驶证（LOADING_SCENE）也支持PDF，最大10MiB
                reviewRound:
                  type: string
                  pattern: "^[1-9][0-9]*$"
                  description: 选择照片时看到的审核轮次；不得在上传后改用新轮次。
                idempotencyKey:
                  type: string
                  minLength: 8
                  maxLength: 128
  /api/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents/{slot}/uploads:
    post:
      operationId: uploadDispatchLoadingPhotoPda
      summary: 上传整车装车照片，尚未绑定
      x-permission-code: lastleg:pda:operate
      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
              - reviewRound
              properties:
                file:
                  type: string
                  format: binary
                  description: 非空JPG/PNG，司机驾驶证（LOADING_SCENE）也支持PDF，最大10MiB
                reviewRound:
                  type: string
                  pattern: "^[1-9][0-9]*$"
                  description: 选择照片时看到的审核轮次；不得在上传后改用新轮次。
                idempotencyKey:
                  type: string
                  minLength: 8
                  maxLength: 128
      x-required-role: OVERSEAS_WAREHOUSE_PDA_OPERATOR
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-documents/{slot}:
    put:
      operationId: bindDispatchLoadingPhoto
      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/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents/{slot}:
    put:
      operationId: bindDispatchLoadingPhotoPda
      summary: 保存装车照片；五框齐全时自动进入派送中
      x-permission-code: lastleg:pda:operate
      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'
      x-required-role: OVERSEAS_WAREHOUSE_PDA_OPERATOR
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-documents/{slot}/files/{fileId}/content:
    get:
      operationId: readDispatchLoadingPhoto
      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
            application/pdf:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
  /api/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents/{slot}/files/{fileId}/content:
    get:
      operationId: readDispatchLoadingPhotoPda
      summary: 读取本车装车资料或原上传结果
      x-permission-code: lastleg:pda:operate
      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
            application/pdf:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
      x-required-role: OVERSEAS_WAREHOUSE_PDA_OPERATOR
  /api/platform/v1/last-leg/dispatches/{dispatchNo}/loading-documents/uploads/{idempotencyKey}:
    get:
      operationId: recoverDispatchLoadingPhoto
      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'
  /api/pda/v1/last-leg/dispatches/{dispatchNo}/loading-documents/uploads/{idempotencyKey}:
    get:
      operationId: recoverDispatchLoadingPhotoPda
      summary: 读取本车装车资料或原上传结果
      x-permission-code: lastleg:pda:operate
      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'
      x-required-role: OVERSEAS_WAREHOUSE_PDA_OPERATOR
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: &id001
        - LOADING_SCENE
        - LOADING_LIST
        - PRE_DEPARTURE_CHECK
        - DRIVER_LICENSE
        - RECEIPT
    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: *id001
        category:
          type: string
          enum:
          - LOADING
        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
      - dispatchRecordVersion
      - reviewRound
      - stage
      - complete
      properties:
        dispatchNo:
          type: string
        recordVersion:
          type: string
        editable:
          type: boolean
        photos:
          type: array
          items:
            $ref: '#/components/schemas/Photo'
        dispatchRecordVersion:
          type: string
        reviewRound:
          type: string
          pattern: "^[1-9][0-9]*$"
        stage:
          type: string
          enum:
          - LOADING
          - AFTER_LOADING
          - DELIVERING
          - DELIVERED
        complete:
          type: boolean
          description: 五类各至少一张已保存照片，不能用总张数代替类别齐全
    BindPhoto:
      type: object
      required:
      - recordVersion
      - idempotencyKey
      - uploadKey
      - fileId
      properties:
        recordVersion:
          type: string
          pattern: ^(0|[1-9][0-9]*)$
        uploadKey:
          type: string
          minLength: 8
          maxLength: 128
          description: 本文件原上传请求的幂等键；与当前审核轮次及操作者一致。
        idempotencyKey:
          type: string
          minLength: 8
          maxLength: 128
        fileId:
          type: string
        replaceFileId:
          type: string
          nullable: true
          pattern: "^[1-9][0-9]*$"
          description: 待替换的当前同类文件ID；省略时装车照片追加，每类最多5张，油耗沿单张替换。