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:truemarkdown 본문은 사이트 크롬(언어선택·메뉴·배너·관련기사 목록)이 남았다 — 원본 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
-
본문 추출 = 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). -
어드민 의도는 별도 큐 테이블.
news_brief_manual_source(packages/db/schema/newsBriefManualSource.ts)에 원본 URL·정규화 URL·메모만 담는다. 크롤 상태·결과는 기존crawled_article(source='manual', source_uid=normalized_url)을 조인해 파생한다(serviceslistManualSourcesWithOutcome) — crawled_article 의 멱등 책임(ADR-0006)은 그대로 둔다. -
정규 파이프라인 합류 + 큐레이션 선호 힌트. run.ts
collectManualQueue()가 큐를 로드→범용 크롤→claimArticles(source='manual')→일반 기사와 같은claimed로 합친다. 요약 프롬프트에 큐레이션 기사 id 를 표기해 “특별한 이유 없으면 브리프로 포함”하도록 편향하되, merge·후속 판정 기준은 일반 기사와 동일(강제 단독 브리프 아님). -
쓰기는 front-api BFF 경유(ADR-0001). 어드민은
POST/GET/DELETE /admin/news-brief/manual-sources(verifyAdmin)로만 큐를 다룬다. 크롤러(백엔드 잡)는 Neon 을 직접 읽는다(crawled_article 과 동일 경계). -
실행은 다음 크론 대기. 별도 즉시 실행 트리거를 두지 않는다.
Consequences
좋아지는 것
- 전용 어댑터 없이 아무 뉴스 사이트 기사나 브리프 파이프라인에 넣을 수 있다.
- 지저분한 범용 추출이 수동 경로에만 격리돼, 공용 배치 프롬프트는 깨끗하게 유지된다.
- 결과 상태(대기·실패·게시됨·스킵)가 crawled_article 로 추적돼 어드민이 확인·재시도 가능.
감수하는 것
- 수동 URL 당 Firecrawl LLM 추출 비용(일반 스크레이프보다 비쌈). 수동 건수가 소수라 무시할 수준.
- LLM 추출이 본문을 놓칠 수 있다(페이월·anti-bot). 실패는
markFailed로 기록하고 상한(MANUAL_MAX_ATTEMPTS)까지 다음 런에 재시도. - 큐레이션 기사도 merge/skip 될 수 있다(강제 단독 브리프 아님) — 일관성을 위해 감수.
이 결정을 다시 열어야 할 때
- Firecrawl
onlyMainContent가 임의 사이트 본문을 충분히 깨끗하게 주게 되면(비용 절감), json 추출 대신 markdown 으로 되돌릴 수 있다. - 즉시 반영 요구가 커지면 workflow_dispatch 트리거(별도 인증)를 추가한다.
- 수동 주입이 대량·상시화되면 별도 상태 컬럼을 큐 테이블에 두는 편이 조인보다 단순해질 수 있다.