baiyue-firstleg/file/src/main/resources/openapi/dispatch-evidence-v1.yaml

openapi: 3.0.3
info:
  title: 平台排车车辆与司机证据内部文件契约
  version: 1.0.0
  description: >-
    复用 InternalBusinessFileController 的现有通用内部入口，不新增公开文件路由。
    两类证据均固定平台 tenantId=0，businessId 为排车内部正数 Long ID 的十进制表示，
    不使用车辆 ID、司机 ID、车牌或客户 ID。车辆与司机证据分别使用
    OVERSEAS_DISPATCH_VEHICLE_EVIDENCE、OVERSEAS_DISPATCH_DRIVER_EVIDENCE，不可互换。
    File 校验内部服务令牌、平台归属、正数业务 ID、文件非空、最大 10MiB（10485760 字节，包含边界）、
    PDF/JPG/PNG MIME 及对应内容签名。元数据和下载按 tenantId、businessType、businessId、fileId
    联合查询 ACTIVE 且未删除文件，错车或错类别均视为归属不匹配，下载前完成归属校验。
    上传生成不可变文件和真实元数据，不自动绑定证据或通过审核，不返回公开 URL 或存储路径。
    Lastleg 负责排车存在性、仓库与角色权限、当前及历史附件引用和审核状态；File 不查询 Lastleg 业务表。
    本文只描述排车网关实际消费的上传、元数据和内容三个操作，不改变通用文件接口的其他用途。
    统一异常处理使用 HTTP 200 JSON 业务错误，调用方必须检查 code；内容接口错误也返回 JSON，不能当作文件。
security:
  - InternalServiceToken: []
paths:
  /internal/file/v1/business-files/{tenantId}/{businessType}/{businessId}:
    parameters:
      - {$ref: '#/components/parameters/TenantId'}
      - {$ref: '#/components/parameters/BusinessType'}
      - {$ref: '#/components/parameters/BusinessId'}
    post:
      operationId: uploadDispatchEvidence
      summary: 上传本排车的车辆或司机证据
      parameters:
        - name: X-Operator-Id
          in: header
          required: true
          description: Lastleg 已认证操作者的正数 Long ID
          schema: {$ref: '#/components/schemas/PositiveLongString'}
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [file]
              properties:
                file:
                  type: string
                  format: binary
                  description: 非空且不超过10485760字节；application/pdf、image/jpeg或image/png，并校验对应内容签名
      responses:
        '200': {$ref: '#/components/responses/MetadataOrError'}
  /internal/file/v1/business-files/{tenantId}/{businessType}/{businessId}/{fileId}:
    parameters:
      - {$ref: '#/components/parameters/TenantId'}
      - {$ref: '#/components/parameters/BusinessType'}
      - {$ref: '#/components/parameters/BusinessId'}
      - {$ref: '#/components/parameters/FileId'}
    get:
      operationId: readDispatchEvidenceMetadata
      summary: 按本排车与证据类别联合校验并读取元数据
      responses:
        '200': {$ref: '#/components/responses/MetadataOrError'}
  /internal/file/v1/business-files/{tenantId}/{businessType}/{businessId}/{fileId}/content:
    parameters:
      - {$ref: '#/components/parameters/TenantId'}
      - {$ref: '#/components/parameters/BusinessType'}
      - {$ref: '#/components/parameters/BusinessId'}
      - {$ref: '#/components/parameters/FileId'}
    get:
      operationId: downloadDispatchEvidence
      summary: 按完整复合归属读取文件内容
      responses:
        '200':
          description: >-
            成功返回真实文件；错误返回 application/json 统一业务错误。
            A0400 表示作用域、ID或文件格式无效，A0403 表示内部令牌无效，
            A0404 表示文件不存在、非有效文件或复合归属不匹配。
          headers:
            Cache-Control: {schema: {type: string, enum: [no-store]}}
            Content-Disposition: {schema: {type: string}, description: 成功时为attachment及UTF-8文件名}
            Content-Length: {schema: {type: integer, format: int64}, description: 成功时为真实文件字节数}
          content:
            application/pdf: {schema: {type: string, format: binary}}
            image/jpeg: {schema: {type: string, format: binary}}
            image/png: {schema: {type: string, format: binary}}
            application/json: {schema: {$ref: '#/components/schemas/ErrorEnvelope'}}
components:
  securitySchemes:
    InternalServiceToken: {type: apiKey, in: header, name: X-Internal-Service-Token}
  parameters:
    TenantId:
      name: tenantId
      in: path
      required: true
      description: 两类排车证据只属于平台，客户作用域一律拒绝
      schema: {type: string, enum: ['0']}
    BusinessType:
      name: businessType
      in: path
      required: true
      schema: {$ref: '#/components/schemas/DispatchEvidenceType'}
    BusinessId:
      name: businessId
      in: path
      required: true
      description: 排车内部正数Long ID，上限9223372036854775807；Lastleg以标准十进制字符串传入
      schema: {$ref: '#/components/schemas/PositiveLongString'}
    FileId:
      name: fileId
      in: path
      required: true
      schema: {$ref: '#/components/schemas/PositiveLongString'}
  responses:
    MetadataOrError:
      description: >-
        统一JSON响应，业务成功code为200。A0400为无效平台作用域、ID、操作者或文件；
        A0403为内部服务令牌无效；A0404为文件不存在、非ACTIVE、已删除或复合归属不匹配；
        S0503为存储不可用，S0500为元数据保存失败等内部异常。
      content:
        application/json:
          schema:
            oneOf:
              - {$ref: '#/components/schemas/MetadataEnvelope'}
              - {$ref: '#/components/schemas/ErrorEnvelope'}
  schemas:
    PositiveLongString:
      type: string
      pattern: '^[1-9][0-9]*$'
      maxLength: 19
      description: 正数Long的十进制字符串，值不得超过9223372036854775807
    DispatchEvidenceType:
      type: string
      enum: [OVERSEAS_DISPATCH_VEHICLE_EVIDENCE, OVERSEAS_DISPATCH_DRIVER_EVIDENCE]
    MetadataEnvelope:
      type: object
      required: [code, data]
      properties:
        code: {type: string, enum: ['200']}
        message: {type: string}
        data: {$ref: '#/components/schemas/Metadata'}
        requestId: {type: string, nullable: true}
        traceId: {type: string, nullable: true}
        timestamp: {type: string, format: date-time}
    Metadata:
      type: object
      required: [fileId, ownerScope, tenantId, businessType, businessId, fileName, sha256, contentType, sizeBytes, createdAt]
      properties:
        fileId: {$ref: '#/components/schemas/PositiveLongString'}
        ownerScope: {type: string, enum: [PLATFORM]}
        tenantId: {type: string, enum: ['0']}
        businessType: {$ref: '#/components/schemas/DispatchEvidenceType'}
        businessId: {$ref: '#/components/schemas/PositiveLongString'}
        fileName: {type: string, minLength: 1, description: 清理路径和控制字符后的原始文件名}
        sha256: {type: string, pattern: '^[0-9a-f]{64}$'}
        contentType: {type: string, enum: [application/pdf, image/jpeg, image/png]}
        sizeBytes:
          type: string
          pattern: '^[1-9][0-9]*$'
          description: 实际字节数，范围1到10485760；公共Jackson配置将Long输出为字符串
          example: '1024'
        createdAt: {type: string, description: File真实上传时间，LocalDateTime的ISO本地时间表示，无时区偏移}
    ErrorEnvelope:
      type: object
      required: [code, data]
      properties:
        code: {type: string, enum: [A0400, A0403, A0404, A0422, S0500, S0503]}
        message: {type: string}
        data: {type: object, nullable: true, description: 业务错误为null；参数校验错误可携带字段信息}
        requestId: {type: string, nullable: true}
        traceId: {type: string, nullable: true}
        timestamp: {type: string, format: date-time}