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

BackupConfig:
  get:
    operationId: getBackupConfig
    summary: 读取备份配置（密码永不回明文，仅回是否已设置）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 备份配置回显
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/BackupConfigResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'
  put:
    operationId: updateBackupConfig
    summary: 保存备份配置（全字段精确校验；rsync_password 空值保持不变）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/UpdateBackupConfigRequest'
    responses:
      '200':
        description: 保存成功后的配置回显
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/BackupConfigResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

BackupJobs:
  get:
    operationId: listBackupHistory
    summary: 备份历史列表（按备份ID升序，来自目标根 index.json 摘要）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 备份历史
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/BackupHistoryResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'
      '503':
        $ref: '../components/responses.yaml#/BackupTargetUnavailable'
  post:
    operationId: startBackupJob
    summary: 手动触发备份（记 BACKUP_CREATE 审计；已有任务运行中返回409）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    requestBody:
      required: true
      content:
        application/json:
          schema:
            $ref: '../components/schemas.yaml#/BackupJobStartRequest'
    responses:
      '202':
        description: 已受理（异步执行，返回初始进度快照）
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/BackupJobStartResponse'
      '400':
        $ref: '../components/responses.yaml#/InvalidArgument'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '409':
        $ref: '../components/responses.yaml#/BackupRunning'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

BackupJobCurrent:
  get:
    operationId: getBackupJobCurrent
    summary: 当前备份任务进度快照（含是否运行中）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 进度快照
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/BackupJobCurrentResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

BackupJobCancel:
  post:
    operationId: cancelBackupJob
    summary: 取消当前备份任务（中断传输并清理暂存目录）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 取消请求已受理（无运行任务时返回 canceled=false）
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/BackupCancelResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'

BackupTestTarget:
  post:
    operationId: testBackupTarget
    summary: 备份目标连通性测试（探测可写性；记 BACKUP_TEST_TARGET 审计）
    parameters:
      - $ref: '../components/parameters.yaml#/XRequestId'
    responses:
      '200':
        description: 探测结果（失败不报错，ok=false 携带原因）
        content:
          application/json:
            schema:
              $ref: '../components/schemas.yaml#/BackupTestTargetResponse'
      '401':
        $ref: '../components/responses.yaml#/AuthenticationError'
      '403':
        $ref: '../components/responses.yaml#/Forbidden'
      '500':
        $ref: '../components/responses.yaml#/InternalError'