웹 대시보드 백필 제어(딸깍) — supervisor·Job Object·잔여 카운터

[wjdtjddns98]

배경

백필(A=이메일 채우기, C=도메인 해석→승격)을 현재 bat 러너로 수동 운영 중 — 인코딩(cp949/LF)·재부팅 유실·세션 종속 등 함정 다수. 운영자가 웹 대시보드에서 "딸깍" 한 번으로 제어하도록 백엔드를 만든다. (Codex·Claude 독립 설계 후 종합 확정안, 2026-08-18)

사용자 관점 (딸깍 원칙 — 트랙 개념 비노출)

• 상시 잔여 패널: GET /admin/backfill/overview — 조건(국가·제외업종·상장) 변경 시 즉시 재계산되는 깔때기(도메인해석 대기→이메일 대기→큐 pending)
• 버튼 하나: POST /admin/backfill/start {조건} — 내부에서 C·A 자동 병행 가동. stop으로 중지
• 진행 카드 하나: GET /admin/backfill/status — 처리/해석/승격/이메일 누적·잔여·오류·예산소진

내부 구조 확정안

• 서버는 supervisor 스레드만 — 자식 CLI 프로세스(--max-batches N)를 세대(generation) 단위 재기동(메모리 리셋 유지, OOM 이력). Playwright 는 서버 프로세스에 안 올림
• Windows Job Object(KILL_ON_JOB_CLOSE)로 서버 종료 시 자식+Chromium 트리 자동 정리
• PG advisory lock으로 웹·bat·crawl companion 전 경로 트랙 중복 방지
• backfill_job 테이블 1개(필터 스냅샷·누적 카운터·세대·취소플래그) + CLI --job-id 자기보고(로그 파싱 금지)
• 서버 재시작 시 자동 재개(취소플래그 재확인 후 — 과거 워치독 취소사고 방어), 예산 소진 시 budget_exhausted 명시 종료
• review_queue.created_at 마이그레이션 — 신규 승격이 전체큐 상단에 노출(적재시각 LIFO)

PR 분해

• PR① 필터 정식 편입 — fill/resolve --exclude-industry·--exclude-listed (worktree 구현분)
• PR② backfill_job 테이블 + review_queue.created_at 마이그레이션
• PR③ CLI --job-id(진행 자기보고·취소 폴링) + 트랙 advisory lock
• PR④ supervisor + Job Object 프로세스 관리
• PR⑤ admin API(overview/start/stop/status) + FE 계약 공유

[wjdtjddns98]

PR④(supervisor) 인수조건 — PR②·③ 리뷰에서 도출 (2026-08-18)

• 모든 종료 경로(정상 recycle / 취소 / 락실패 / 크래시 / 서버 shutdown)에서 finish_backfill_job 호출 책임은 supervisor — CLI 는 호출하지 않는다(구세대의 오종료 위험)
• 세대(generation) 교체 전 구자식 프로세스의 실제 종료 확인 필수 — 확인 없이 교체하면 유령 세대가 남는다(자식의 보고-거부 자체종료는 최후 방어선일 뿐)
• finish_backfill_job 에 generation 가드 추가 검토(늦은 종료 호출의 오격발 방지)
• Windows Job Object(KILL_ON_JOB_CLOSE) — 서버 종료 시 자식+Chromium 트리 자동 정리, PID 기반 kill 금지(재사용 위험)
• 취소 = 플래그 기록 후 Job Object 닫기(회사 단위 커밋이라 강제종료 안전) + 자식의 협조적 폴링은 보조
• 서버 재시작 시 자동 재개하되 cancel_requested 재확인 후(과거 크롤 워치독 취소사고 방어)
• 예산 소진 시 budget_exhausted 종료(배치 경계에서 DB 월합계 재조회 — 프로세스 로컬 캐시 금지)
• 컷오버: 배포 후 기존 bat 러너 재시작해야 잠금 계약 참여(run-backfill-loop.bat 주석 참조)

[wjdtjddns98]

BE 체인 완료 — PR① #353, PR② #354, PR③ #355, PR④ #356, PR⑤ #357 전부 dev 머지. 남은 것: FE 대시보드(프론트 영역, PR⑤ 본문의 계약 표 참조) + prod 승격(마이그레이션 적용·bat 러너 재시작 컷오버·MINOR bump).