document-management/backend/openapi/components/responses.yaml

HealthSuccess:
  description: DMS服务正常
  headers:
    X-Request-Id:
      description: 与响应体requestId相同
      schema:
        type: string
        format: uuid
  content:
    application/json:
      schema:
        $ref: './schemas.yaml#/HealthResponse'

InternalError:
  description: 未处理的服务器错误
  headers:
    X-Request-Id:
      description: 与响应体requestId相同
      schema:
        type: string
        format: uuid
  content:
    application/json:
      schema:
        $ref: './schemas.yaml#/ErrorResponse'

InvalidArgument:
  description: 请求参数错误
  content:
    application/json:
      schema:
        $ref: './schemas.yaml#/ErrorResponse'

AuthenticationError:
  description: 认证失败、Token过期、用户禁用或认证版本失效
  content:
    application/json:
      schema:
        $ref: './schemas.yaml#/ErrorResponse'

Forbidden:
  description: 当前用户无权执行该操作
  content:
    application/json:
      schema:
        $ref: './schemas.yaml#/ErrorResponse'

NotFound:
  description: 分类不存在或已逻辑删除
  content:
    application/json:
      schema:
        $ref: './schemas.yaml#/ErrorResponse'

Conflict:
  description: 数据版本冲突、方案名称冲突、分类编码重复或分类仍被占用
  content:
    application/json:
      schema:
        $ref: './schemas.yaml#/ErrorResponse'

PayloadTooLarge:
  description: 单文件、批量数量或请求总大小超过限制
  content:
    application/json:
      schema:
        $ref: './schemas.yaml#/ErrorResponse'

UnsupportedMedia:
  description: 文件类型不支持、文件结构损坏或Office不可预览
  content:
    application/json:
      schema:
        $ref: './schemas.yaml#/ErrorResponse'

PreviewConverterUnavailable:
  description: 预览转换器不可用
  content:
    application/json:
      schema: {$ref: './schemas.yaml#/ErrorResponse'}
      example:
        code: PREVIEW_CONVERTER_UNAVAILABLE
        message: 预览转换器未配置或LibreOffice不可用
        details: null
        requestId: 00000000-0000-0000-0000-000000000000

PreviewConversionTimeout:
  description: 预览转换超时
  content:
    application/json:
      schema: {$ref: './schemas.yaml#/ErrorResponse'}
      example:
        code: PREVIEW_CONVERSION_TIMEOUT
        message: 文档转换超时，请稍后重试
        details: null
        requestId: 00000000-0000-0000-0000-000000000000

PreviewConversionFailed:
  description: 预览转换失败
  content:
    application/json:
      schema: {$ref: './schemas.yaml#/ErrorResponse'}
      example:
        code: PREVIEW_CONVERSION_FAILED
        message: 文档转换为PDF失败
        details: null
        requestId: 00000000-0000-0000-0000-000000000000

BackupRunning:
  description: 已有备份任务正在运行（引擎单任务互斥）
  content:
    application/json:
      schema: {$ref: './schemas.yaml#/ErrorResponse'}
      example:
        code: BACKUP_RUNNING
        message: 已有备份任务正在运行，请等待完成后再试
        details: null
        requestId: 00000000-0000-0000-0000-000000000000

BackupTargetUnavailable:
  description: 备份目标不可达或不可写
  content:
    application/json:
      schema: {$ref: './schemas.yaml#/ErrorResponse'}
      example:
        code: BACKUP_TARGET_UNAVAILABLE
        message: 备份目标不可达或不可写
        details: null
        requestId: 00000000-0000-0000-0000-000000000000

BackupToolMissing:
  description: 备份所需外部工具不可用（rsync等）
  content:
    application/json:
      schema: {$ref: './schemas.yaml#/ErrorResponse'}
      example:
        code: BACKUP_TOOL_MISSING
        message: 备份所需外部工具不可用
        details: null
        requestId: 00000000-0000-0000-0000-000000000000

BackupFailed:
  description: 备份执行失败（详见服务端日志与进度快照error字段）
  content:
    application/json:
      schema: {$ref: './schemas.yaml#/ErrorResponse'}
      example:
        code: BACKUP_FAILED
        message: 备份执行失败，请查看服务端日志
        details: null
        requestId: 00000000-0000-0000-0000-000000000000

MetricUnavailable:
  description: 资源监控采集能力不可用（psutil 缺失或采样器未启动）
  content:
    application/json:
      schema: {$ref: './schemas.yaml#/ErrorResponse'}
      example:
        code: METRIC_UNAVAILABLE
        message: 资源监控采集能力不可用
        details: null
        requestId: 00000000-0000-0000-0000-000000000000