-- 2026-06-14 PR-Background-Jobs-Observability: 큐 밖 관리 스크립트(백필 등) 진행 가시화.
-- processing_queue 는 파이프라인 stage 전용 — hier_overnight_backfill / section_summary_pilot
-- 같은 off-queue 관리 스크립트는 여기에 진행상황을 남겨 대시보드 보드가 노출한다.
-- worker_jobs(user_id NOT NULL, worker-pool 전용)와 별개 — 이건 owner 없는 관리 작업 heartbeat.
-- 단일 statement (asyncpg multi-statement 불허 컨벤션). 인덱스는 소량 테이블이라 생략.
CREATE TABLE IF NOT EXISTS background_jobs (
    id           BIGSERIAL PRIMARY KEY,
    kind         TEXT NOT NULL,                 -- 'hier_redecompose' | 'section_summary' | ...
    label        TEXT,                          -- 사람이 읽는 대상 표기 (예: 'doc 5210 (Sec VIII)')
    state        TEXT NOT NULL DEFAULT 'running'
                    CHECK (state IN ('running', 'done', 'failed')),
    processed    INTEGER NOT NULL DEFAULT 0,    -- 처리한 단위 수 (절/leaf 등)
    total        INTEGER,                       -- 전체 단위 수 (미상이면 NULL)
    detail       JSONB NOT NULL DEFAULT '{}'::jsonb,
    error        TEXT,
    started_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    updated_at   TIMESTAMPTZ NOT NULL DEFAULT now(),
    finished_at  TIMESTAMPTZ
);