# task-571: Scrapling 기반 크롤링 시스템 고도화 구현 (한정승인)

## 한정승인 (Scoped Delegation)
제이회장님이 **전체 Phase를 2팀에 한정승인**하셨다.
- 각 Phase 완료 → .done → 즉시 다음 Phase 진행 (아누 승인 대기 없음)
- Phase 간 산출물은 파일로 연결
- 중간보고: 각 Phase 완료 시 간결 3줄 보고
- 마지막 Phase 완료 시 전체 통합 보고
- **chain_manager.py를 사용하지 말 것** — 직접 다음 Phase dispatch 호출로 이어갈 것

## 참조 문서 (반드시 읽을 것)
1. `memory/research/scrapling-analysis.md` — Scrapling 심층분석 보고서 (35개 도입 항목, 비교표, 로드맵)
2. `memory/reports/task-570.1.md` — 분석 완료 보고서

## 전체 범위
task-570.1에서 도출한 5 Phase 로드맵을 실행한다.

---

## Phase 1: browser.py 스텔스 강화 (task-571.1)

### 작업 항목
1. **A-1: STEALTH_ARGS 적용** — Scrapling의 constants.py에서 38개 Chrome 스텔스 플래그를 가져와 browser.py에 적용
2. **A-2: HARMFUL_ARGS 제거** — Playwright 기본 플래그 중 탐지 유발 플래그 제거 (ignore_default_args 설정)
3. **A-3: browserforge 헤더 생성** — OS별 실제 Chrome User-Agent + Accept-Language 생성
   - `pip install browserforge` 필요
4. **A-4: Google Referer 자동 주입** — 검색 엔진에서 온 것처럼 위장
5. **R-1: 리소스 차단** — 이미지/폰트/미디어/CSS 선택적 로딩 차단 (page.route 인터셉트)
6. **R-4: viewport/screen 최적화** — 1920x1080 + device_scale_factor=2

### 수정 파일
- `/home/jay/workspace/scripts/browser.py` — 스텔스 모드 추가 (--stealth 옵션 또는 기본 적용)

### 완료 기준
- browser.py에 스텔스 플래그 적용
- 리소스 차단 옵션 추가
- 테스트: `scripts/tests/test_browser_stealth.py`
- 기존 browser.py 기능 회귀 없음

### 보고서
`memory/reports/task-571.1.md`

---

## Phase 2: Scrapling 설치 + 크롤링 스킬 구축 (task-571.2)

### 작업 항목
1. **Scrapling 설치**: `pip install scrapling[all]` + `scrapling install`
2. **크롤링 유틸리티 모듈**: `/home/jay/workspace/scripts/crawl_utils.py`
   - Scrapling Fetcher/StealthyFetcher 래핑
   - 프록시 로테이션 (N-1) + 자동 재시도 (N-2) + 프록시 에러 판별 (N-3)
   - 리소스 차단 설정 헬퍼
3. **크롤링 스킬 SKILL.md**: `/home/jay/workspace/skills/advanced-crawling/SKILL.md`
   - 3단계 Fetcher 사용 가이드
   - Smart Matching 활용법
   - CSS/XPath 셀렉터 가이드
4. **P-5: 마크다운 변환** — HTML→Markdown 변환 유틸 (LLM 입력 최적화)

### 완료 기준
- Scrapling 설치 확인 (import 테스트)
- crawl_utils.py + 테스트
- SKILL.md 작성

### 보고서
`memory/reports/task-571.2.md`

---

## Phase 3: Smart Matching 활용 크롤러 프로토타입 (task-571.3)

### 작업 항목
1. **S-1~S-4: Smart Matching 적용** — 요소 fingerprinting + SQLite 저장 + 유사도 재탐색
2. **보험사 공개 데이터 크롤러 프로토타입**: `/home/jay/workspace/scripts/insurance-crawler.py`
   - 보험사 공시 페이지 데이터 추출 (테스트 대상 사이트 선정)
   - Smart Matching으로 구조 변경 대응
   - CSS 셀렉터 기반 데이터 추출
3. **P-1~P-4, P-6 파싱 기능 통합** — lxml 파서, TextHandler, find_similar()

### 주의사항
- ⚠️ **실제 크롤링 테스트 결과물은 제이회장님 확인 후에만 삭제** (외부 서비스 테스트 규칙)
- 합법적 공개 데이터만 대상

### 완료 기준
- insurance-crawler.py + 테스트
- Smart Matching 동작 확인
- 프로토타입 실행 결과 (데이터 샘플)

### 보고서
`memory/reports/task-571.3.md`

---

## Phase 4: Spider 기반 정기 크롤링 시스템 (task-571.4)

### 작업 항목
1. **SP-1~SP-6: Spider 프레임워크 활용**
   - Spider ABC 상속 크롤러 구현
   - PriorityQueue + SHA-1 중복 필터 (SP-2)
   - Checkpoint/재시작 (SP-3)
   - 병렬 크롤링 (SP-4)
   - 도메인별 동시성 제어 (SP-5, 예의 바른 크롤링)
   - JSON/JSONL 결과 내보내기 (SP-6)
2. **정기 크롤링 스케줄러**: cokacdir --cron 연동 설계 (등록은 프로젝트 시작 시)
3. **N-4: Response 이력 추적** — 리다이렉트 체인 보존

### 완료 기준
- Spider 기반 크롤러 구현 + 테스트
- Checkpoint 저장/복원 확인
- 병렬 크롤링 동작 확인

### 보고서
`memory/reports/task-571.4.md`

---

## Phase 5: MCP 서버 통합 + 전체 통합 보고 (task-571.5)

### 작업 항목
1. **D-1: MCP 서버 활용** — Scrapling MCP를 우리 시스템에서 활용할 수 있는 설정
2. **D-2: curl 파서** — DevTools curl 명령어 → Fetcher 인자 변환 유틸
3. **전체 통합 테스트** — browser.py + crawl_utils + insurance-crawler + Spider 연동
4. **전체 통합 보고서**: `memory/reports/task-571-final.md`
   - 35개 항목 중 구현 완료/미구현 현황
   - 시스템 개선 전/후 비교
   - 향후 과제 (Cloudflare 솔버 등 조건부 항목)

### 완료 기준
- MCP 설정 + 통합 테스트
- 전체 통합 보고서

### 보고서
`memory/reports/task-571.5.md`
`memory/reports/task-571-final.md`

---

## 공통 규칙
- 코딩은 팀원(Sonnet)에게 위임. 팀장(Opus)은 설계/검토만.
- pyright 에러 0건 유지
- 기존 테스트 회귀 금지
- 보안: Cloudflare 솔버 등 법적 리스크 기능은 합법적 용도에만 사용. 경고 주석 필수.
- CODING-STANDARDS.md 준수
- task-timer로 작업 기록 필수
- 각 Phase 보고서: `memory/reports/task-571.{phase번호}.md`