Skip to Content
DecisionsADR-0016: 전용 어댑터가 없는 외부 기사는 Firecrawl LLM 추출로 크롤해 수동 주입 큐로 다음 배치에 합류시킨다

ADR-0016: 전용 어댑터가 없는 외부 기사는 Firecrawl LLM 추출로 크롤해 수동 주입 큐로 다음 배치에 합류시킨다

  • Status: Accepted
  • Date: 2026-09-29
  • 관련: HMH-9618 (이번 작업 티켓) · ADR-0006(크롤 파이프라인)·ADR-0009(후속 엔티티 인덱스)·ADR-0001(front-api BFF)

Context

크롤러는 사이트별 어댑터(도시정비뉴스·하우징헤럴드 등)가 있는 매체만 수집한다(ADR-0006). 운영자가 그 외 매체(예: edaily)의 기사를 “다음 브리프 잡에 강제로 포함”시키고 싶어도 방법이 없었다.

핵심 제약은 임의 사이트의 본문 추출이다. PoC 로 edaily 기사를 확인한 결과:

  • Firecrawl 의 metadata(og:*)는 임의 사이트에서도 제목·발행일·매체명·대표이미지를 정확히 준다.
  • 그러나 onlyMainContent:true markdown 본문은 사이트 크롬(언어선택·메뉴·배너·관련기사 목록)이 남았다 — 원본 35,654자, 정형 regex 정리 후에도 10,423자가 대부분 네비게이션이었다.
  • 같은 페이지를 Firecrawl json(LLM) 추출(schema {title, body, publishedAt, publisher})로 뽑으니 본문이 764자 순수 기사 텍스트로 깨끗하게 나왔다.

즉 regex 기반 본문 정리는 edaily 하나엔 맞출 수 있어도, 이 기능의 전제인 “우리가 지원하지 않는 임의 사이트”에는 일반화되지 않는다.

검토한 대안

대안채택 안 한 이유
매체마다 전용 어댑터 추가임의 사이트가 대상이라 어댑터를 미리 만들 수 없다. 수동 주입의 목적과 모순.
markdown + 범용 regex 본문 정리사이트별 크롬이 제각각이라 일반화 실패(PoC: 정리 후에도 네비가 대부분). regex 를 한 사이트에 맞추면 다음 사이트에서 또 깨진다.
우리 요약 LLM 이 노이즈 섞인 본문에서 알아서 추출수동 기사의 대용량 노이즈(관련기사 헤드라인 등)가 공용 배치 프롬프트에 섞여 클러스터링·비용을 오염시킨다.
crawled_article 을 큐로 재사용(어드민 필드 추가)ADR-0006 이 정한 crawled_article 의 단일 책임(멱등·중복방지)에 어드민 의도 필드가 섞인다.
어드민에서 GH workflow_dispatch 로 즉시 실행front-api 에 GH 토큰 도입 필요. 다음 크론 대기로 충분해 v1 범위 밖.

Decision

  1. 본문 추출 = Firecrawl json(LLM) 추출. 임의 사이트는 firecrawlExtract(url, {schema, prompt, checkPromptInjection:true}) 로 깨끗한 {title, body, publishedAt, publisher} 를 얻는다. 제목·발행일·매체명은 추출값 우선, 없으면 og:* 폴백. 신뢰 불가 사이트라 프롬프트 인젝션 방어를 켠다. 배선: packages/news-crawler/src/firecrawl.ts(firecrawlExtract), packages/news-crawler/src/adapters/manual.ts(fetchManualArticle).

  2. 어드민 의도는 별도 큐 테이블. news_brief_manual_source(packages/db/schema/newsBriefManualSource.ts)에 원본 URL·정규화 URL·메모만 담는다. 크롤 상태·결과는 기존 crawled_article(source='manual', source_uid=normalized_url) 을 조인해 파생한다(services listManualSourcesWithOutcome) — crawled_article 의 멱등 책임(ADR-0006)은 그대로 둔다.

  3. 정규 파이프라인 합류 + 큐레이션 선호 힌트. run.ts collectManualQueue() 가 큐를 로드→범용 크롤→claimArticles(source='manual')→일반 기사와 같은 claimed 로 합친다. 요약 프롬프트에 큐레이션 기사 id 를 표기해 “특별한 이유 없으면 브리프로 포함”하도록 편향하되, merge·후속 판정 기준은 일반 기사와 동일(강제 단독 브리프 아님).

  4. 쓰기는 front-api BFF 경유(ADR-0001). 어드민은 POST/GET/DELETE /admin/news-brief/manual-sources(verifyAdmin)로만 큐를 다룬다. 크롤러(백엔드 잡)는 Neon 을 직접 읽는다(crawled_article 과 동일 경계).

  5. 실행은 다음 크론 대기. 별도 즉시 실행 트리거를 두지 않는다.

Consequences

좋아지는 것

  • 전용 어댑터 없이 아무 뉴스 사이트 기사나 브리프 파이프라인에 넣을 수 있다.
  • 지저분한 범용 추출이 수동 경로에만 격리돼, 공용 배치 프롬프트는 깨끗하게 유지된다.
  • 결과 상태(대기·실패·게시됨·스킵)가 crawled_article 로 추적돼 어드민이 확인·재시도 가능.

감수하는 것

  • 수동 URL 당 Firecrawl LLM 추출 비용(일반 스크레이프보다 비쌈). 수동 건수가 소수라 무시할 수준.
  • LLM 추출이 본문을 놓칠 수 있다(페이월·anti-bot). 실패는 markFailed 로 기록하고 상한(MANUAL_MAX_ATTEMPTS)까지 다음 런에 재시도.
  • 큐레이션 기사도 merge/skip 될 수 있다(강제 단독 브리프 아님) — 일관성을 위해 감수.

이 결정을 다시 열어야 할 때

  • Firecrawl onlyMainContent 가 임의 사이트 본문을 충분히 깨끗하게 주게 되면(비용 절감), json 추출 대신 markdown 으로 되돌릴 수 있다.
  • 즉시 반영 요구가 커지면 workflow_dispatch 트리거(별도 인증)를 추가한다.
  • 수동 주입이 대량·상시화되면 별도 상태 컬럼을 큐 테이블에 두는 편이 조인보다 단순해질 수 있다.
Last updated on