document-management/backend/openapi/paths/system.yaml

SystemMetricsCurrent:
  get:
    operationId: getSystemMetricsCurrent
    summary: 实时资源快照（CPU/内存/交换分区/磁盘分区/开机时间；psutil 缺失返回503）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 实时资源快照
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/SystemMetricsCurrentResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'
      '503':
        $ref: '../components/responses.yaml#/MetricUnavailable'

SystemMetricsHistory:
  get:
    operationId: getSystemMetricsHistory
    summary: 近 N 小时资源采样序列（升序，供趋势图；30 秒采样保留 7 天）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
      - name: hours
        in: query
        required: false
        schema: {type: integer, minimum: 1, maximum: 720, default: 24}
        description: 查询窗口小时数（默认24）
    responses:
      '200':
        description: 采样序列
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/SystemMetricHistoryResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'
      '503':
        $ref: '../components/responses.yaml#/MetricUnavailable'

SystemProcess:
  get:
    operationId: getSystemProcess
    summary: 应用进程监控（CPU/内存/线程数/运行时长/运行时版本）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 进程监控数据
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/SystemProcessResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'
      '503':
        $ref: '../components/responses.yaml#/MetricUnavailable'

SystemStorageUsage:
  get:
    operationId: getSystemStorageUsage
    summary: 存储目录占用统计（七个存储子目录实时遍历）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 存储占用列表
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/SystemStorageUsageResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

SystemConverter:
  get:
    operationId: getSystemConverterStatus
    summary: LibreOffice 转换器状态（存活/并发占用/累计成功失败计数）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 转换器状态
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/SystemConverterResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

SystemHealth:
  get:
    operationId: runSystemHealthCheck
    summary: 一键体检（数据库/存储可写/转换器/备份目标/信封加密逐项探测）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 体检结果（逐项 ok/detail，失败项不报错仅标记）
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/SystemHealthResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

SystemInfo:
  get:
    operationId: getSystemInfo
    summary: 系统信息卡片（契约版本/后端类型/运行环境/数据库/启动时间/关键路径）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 系统信息
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/SystemInfoResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

SystemRuntimeConfig:
  get:
    operationId: getSystemRuntimeConfig
    summary: 运行参数只读总览（脱敏：密钥类仅显示是否已配置）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 分类运行参数列表
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/SystemRuntimeConfigResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

SystemLogs:
  get:
    operationId: getSystemLogs
    summary: 运行日志尾部 N 行（按 [LEVEL] 标记级别过滤；日志未启用返回空列表）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
      - name: lines
        in: query
        required: false
        schema: {type: integer, minimum: 1, maximum: 5000, default: 500}
        description: 返回行数上限（默认500）
      - name: level
        in: query
        required: false
        schema: {type: string, enum: [DEBUG, INFO, WARNING, ERROR, CRITICAL]}
        description: 级别过滤（可选）
    responses:
      '200':
        description: 日志尾部
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/SystemLogsResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

SystemLogsDownload:
  get:
    operationId: downloadSystemLog
    summary: 原始运行日志文件下载（日志审计页签单开窗口查看；日志审计权限）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 日志文件流（text/plain 附件）
        content:
          text/plain:
            schema: {type: string, format: binary}
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

SystemMaintenancePreviewCache:
  post:
    operationId: clearPreviewCache
    summary: 清空预览缓存目录（可重建；记 PREVIEW_CACHE_CLEAR 审计）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 清理结果（删除文件数与释放字节数）
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/SystemPreviewCacheClearResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

SystemForceOffline:
  post:
    operationId: forceUserOffline
    summary: 强制下线（auth_version+1 使目标用户全部访问令牌立即失效；记 FORCE_OFFLINE 审计）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
      - name: user_id
        in: path
        required: true
        schema: {type: integer, minimum: 1}
    responses:
      '200':
        description: 强制下线结果
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/SystemForceOfflineResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '404':
        $ref: '../components/responses.yaml#/NotFound'
      '500':
        $ref: '../components/responses.yaml#/InternalError'