openapi: 3.1.0
info:
  title: biliup-next Control API
  version: 0.1.0
  summary: 本地 worker、任务和控制台 API
servers:
  - url: http://127.0.0.1:8787
paths:
  /:
    get:
      summary: 控制台首页
      responses:
        "200":
          description: HTML dashboard
  /health:
    get:
      summary: 健康检查
      responses:
        "200":
          description: OK
  /settings:
    get:
      summary: 获取当前设置
      responses:
        "200":
          description: 当前配置，敏感字段已掩码
    put:
      summary: 更新设置
      responses:
        "200":
          description: 保存成功
  /settings/schema:
    get:
      summary: 获取 settings schema
      responses:
        "200":
          description: schema-first UI 元数据
  /doctor:
    get:
      summary: 运行时依赖检查
      responses:
        "200":
          description: doctor result
  /modules:
    get:
      summary: 查询已注册模块与 manifest
      responses:
        "200":
          description: module list
  /runtime/services:
    get:
      summary: 查询 systemd 服务状态
      responses:
        "200":
          description: service list
  /runtime/services/{serviceId}/{action}:
    post:
      summary: 执行 service start/stop/restart
      parameters:
        - in: path
          name: serviceId
          required: true
          schema:
            type: string
        - in: path
          name: action
          required: true
          schema:
            type: string
            enum: [start, stop, restart]
      responses:
        "202":
          description: action accepted
  /logs:
    get:
      summary: 查询日志列表或日志内容
      parameters:
        - in: query
          name: name
          schema:
            type: string
        - in: query
          name: lines
          schema:
            type: integer
        - in: query
          name: contains
          schema:
            type: string
      responses:
        "200":
          description: log list or log content
  /history:
    get:
      summary: 查询全局动作流
      parameters:
        - in: query
          name: task_id
          schema:
            type: string
        - in: query
          name: action_name
          schema:
            type: string
        - in: query
          name: status
          schema:
            type: string
        - in: query
          name: limit
          schema:
            type: integer
      responses:
        "200":
          description: action records
  /tasks:
    get:
      summary: 查询任务列表
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
      responses:
        "200":
          description: task list
    post:
      summary: 从 source_path 手动创建任务
      responses:
        "201":
          description: task created
  /webhooks/full-video-uploaded:
    post:
      summary: 接收原视频上传成功后的完整版 BV webhook
      responses:
        "202":
          description: accepted
  /tasks/{taskId}:
    get:
      summary: 查询任务详情
      parameters:
        - in: path
          name: taskId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: task detail
  /tasks/{taskId}/steps:
    get:
      summary: 查询任务步骤
      parameters:
        - in: path
          name: taskId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: task steps
  /tasks/{taskId}/artifacts:
    get:
      summary: 查询任务产物
      parameters:
        - in: path
          name: taskId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: task artifacts
  /tasks/{taskId}/history:
    get:
      summary: 查询单任务动作历史
      parameters:
        - in: path
          name: taskId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: task action history
  /tasks/{taskId}/timeline:
    get:
      summary: 查询单任务时间线
      parameters:
        - in: path
          name: taskId
          required: true
          schema:
            type: string
      responses:
        "200":
          description: task timeline
  /tasks/{taskId}/actions/run:
    post:
      summary: 推进单个任务
      parameters:
        - in: path
          name: taskId
          required: true
          schema:
            type: string
      responses:
        "202":
          description: accepted
  /tasks/{taskId}/actions/retry-step:
    post:
      summary: 从指定 step 重试
      parameters:
        - in: path
          name: taskId
          required: true
          schema:
            type: string
      responses:
        "202":
          description: accepted
  /tasks/{taskId}/actions/reset-to-step:
    post:
      summary: 重置到指定 step 并重跑
      parameters:
        - in: path
          name: taskId
          required: true
          schema:
            type: string
      responses:
        "202":
          description: accepted
  /worker/run-once:
    post:
      summary: 执行一轮 worker
      responses:
        "202":
          description: accepted
  /stage/import:
    post:
      summary: 从本机已有绝对路径复制到隔离 stage
      responses:
        "201":
          description: imported
  /stage/upload:
    post:
      summary: 上传文件到隔离 stage
      responses:
        "201":
          description: uploaded