데이터 수집 시스템 아키텍처

<aside> 📋

이 문서는 scripts/ 디렉토리의 데이터 수집 스크립트 구조와 리팩토링 전략을 정리합니다.

로컬 파일: docs/crawling-architecture-strategy.md

</aside>

1. 스크립트 분류

구분 스크립트 실행 빈도 환경
데이터 임포트 import-csv, import-kakao, import-naver-local 비정기 (데이터 갱신 시) 로컬 CLI
크롤링 (API) crawl-naver-blogs, crawl-youtube 비정기 (데이터 보강 시) 로컬 CLI
크롤링 (브라우저) crawl-naver-place 비정기 로컬 CLI / GitHub Actions
큐레이션 curate-hell-parking, collect-1010-channel 비정기 (수동) 로컬 CLI
아카이브 merge-duplicates, seed-reviews, backfill-summaries, register-1010-unmatched 일회성 (완료) scripts/archive/

2. 활성 스크립트 역할

스크립트 역할 실행 시점 사용 lib
import-csv.ts 공공데이터 CSV → D1 임포트 월 1회 (데이터 갱신 시) d1, sql-flush
import-kakao.ts 카카오 PK6 주차장 수집 비정기 d1, sql-flush, progress, geo
import-naver-local.ts 네이버 지역검색 주차장 수집 비정기 d1, sql-flush, progress, naver-api, geo
crawl-naver-blogs.ts 네이버 블로그/카페 리뷰 수집 비정기 (리뷰 보강) d1, sql-flush, progress, naver-api, geo
crawl-youtube.ts YouTube 영상/댓글 수집 비정기 (리뷰 보강) d1, sql-flush, progress, youtube-api, geo
crawl-naver-place.ts 네이버 플레이스 방문자 리뷰 비정기 (리뷰 보강) d1, sql-flush, progress, geo, playwright
curate-hell-parking.ts 헬/이지 큐레이션 태그 적용 큐레이션 추가 시 d1, sql-flush
collect-1010-channel.ts 10시10분 채널 영상 분석 비정기 (수동) d1, youtube-api

3. 공통 라이브러리 (scripts/lib/)

파일 역할 상태
d1.ts D1 쿼리/실행 유틸, --remote 플래그 지원 ✅ 기존
naver-api.ts 네이버 검색 API 래퍼 (블로그/카페) ✅ 기존
youtube-api.ts YouTube Data API 래퍼 ✅ 기존
progress.ts JSON 기반 진행 상태 관리 (중단/재개) 📋 추출 예정
sql-flush.ts SQL escape, INSERT 생성, 배치 flush 📋 추출 예정
geo.ts 주소→지역 추출, 제네릭 이름 판별 📋 추출 예정

4. 리팩토링 전략

원칙

<aside> 🎯

  1. YAGNI — 현재 필요한 것만 만든다. Worker Cron, Repository 패턴은 실제로 필요해질 때 도입.
  2. 공통 코드 추출 — 반복되는 패턴을 scripts/lib/로 모은다.
  3. 로컬 CLI 우선 — 비정기 실행이므로 스크립트 유지. 자동화가 필요하면 GitHub Actions. </aside>

중복 코드 현황

중복 코드 발견 위치 추출 대상
loadProgress() / saveProgress() crawl-naver-blogs, crawl-youtube, crawl-naver-place progress.ts
esc() • SQL flush 패턴 3곳 동일 sql-flush.ts
extractRegion() / extractDistrict() 3곳 각기 다른 구현 geo.ts (최선 버전으로 통합)
isGenericName() crawl-naver-blogs에만 있지만 다른 곳에도 필요 geo.ts
sleep() 2곳 동일 progress.ts 또는 인라인

리팩토링 효과

항목 Before After
크롤러 스크립트 평균 줄 수 ~310줄 ~200줄
esc() 함수 정의 3곳 1곳
loadProgress/saveProgress 3곳 1곳
extractRegion 변종 3곳 (각기 다른 구현) 1곳 (최선 버전)
버그 수정 시 수정 파일 수 N개 1개