README.md

# 정당 보도자료 크롤러

6개 정당 웹사이트에서 보도자료, 논평/브리핑, 모두발언을 자동으로 수집하고 허깅페이스에 업로드하는 크롤러입니다.

**지원 정당**: 더불어민주당, 국민의힘, 조국혁신당, 개혁신당, 기본소득당, 진보당

## 주요 특징

- **비동기 처리 (asyncio + aiohttp)**: 기존 대비 10-20배 빠른 속도
- **6개 정당 병렬 크롤링**: 동시에 실행하여 시간 단축
- **증분 업데이트**: 마지막 크롤링 이후 데이터만 수집
- **허깅페이스 자동 업로드**: 정당별 독립 저장소에 자동 병합

## 설치

```bash
pip install -r requirements.txt
```

또는 Windows:
```bash
setup.bat
```

## 환경 변수 설정

`.env` 파일 생성 후 아래 내용 입력:

```
HF_TOKEN=hf_xxxxxxxxxxxxxxxxxxxx

# 각 정당별 허깅페이스 데이터셋 저장소
HF_REPO_ID=your_username/minjoo-press-releases
HF_REPO_ID_PPP=your_username/ppp-press-releases
HF_REPO_ID_REBUILDING=your_username/rebuilding-press-releases
HF_REPO_ID_REFORM=your_username/reform-press-releases
HF_REPO_ID_BASIC_INCOME=your_username/basic-income-press-releases
HF_REPO_ID_JINBO=your_username/jinbo-press-releases
```

## 사용 방법

### main.py - 통합 진입점 (추천)

```bash
# 전체 정당 증분 업데이트 (기본)
python main.py

# 특정 정당만
python main.py --party minjoo        # 더불어민주당
python main.py --party ppp           # 국민의힘
python main.py --party rebuilding    # 조국혁신당
python main.py --party reform        # 개혁신당
python main.py --party basic_income  # 기본소득당
python main.py --party jinbo         # 진보당

# 날짜 범위 지정
python main.py --start-date 2024-01-01
python main.py --party reform --start-date 2024-01-01 --end-date 2024-06-30

# 도움말
python main.py --help
```

### 개별 크롤러 직접 실행

```bash
python minjoo_crawler_async.py
python ppp_crawler_async.py
python rebuilding_crawler_async.py
python reform_crawler_async.py
python basic_income_crawler_async.py
python jinbo_crawler_async.py
```

### 매일 자동 실행 (스케줄러)

```bash
python unified_scheduler.py   # 매일 오전 9시 전체 자동 실행
```

### Windows 배치 파일

| 파일 | 설명 |
|------|------|
| `run_unified.bat` | 전체 동시 크롤링 (한 번) |
| `run_unified_scheduler.bat` | 전체 매일 자동 크롤링 |
| `run_once.bat` | 민주당만 |
| `run_ppp.bat` | 국민의힘만 |

## 수집 데이터

| 정당 | 게시판 | 수집 시작일 |
|------|--------|------------|
| 더불어민주당 | 보도자료, 논평/브리핑, 모두발언 | 2003-11-11 |
| 국민의힘 | 대변인 논평보도자료, 원내 보도자료, 미디어특위 | 2000-03-10 |
| 조국혁신당 | 기자회견문, 논평브리핑, 보도자료 | 2024-03-04 |
| 개혁신당 | 보도자료, 논평브리핑 | 2024-02-13 |
| 기본소득당 | 논평·보도자료 (논평/발언/보도자료) | 2020-01-08 |
| 진보당 | 보도자료, 논평, 모두발언 | 2017-10-14 |

## 설정 (crawler_config.json)

각 정당별로 독립적으로 설정 가능:

```json
{
  "minjoo": { ... },
  "ppp": { ... },
  "rebuilding": { ... },
  "reform": { ... },
  "basic_income": { ... },
  "jinbo": { ... }
}
```

| 설정 | 설명 |
|------|------|
| `boards` | 수집할 게시판 목록 |
| `start_date` | 최초 크롤링 시작 날짜 |
| `max_pages` | 최대 페이지 수 |
| `concurrent_requests` | 동시 요청 수 (서버 부담 고려) |
| `request_delay` | 요청 간 대기 시간(초) |
| `output_path` | 로컬 저장 경로 |

## 파일 구조

```
정당크롤러/
├── main.py                        # 통합 진입점 (CLI 인자 지원)
├── unified_crawler.py             # 6개 정당 통합 크롤러
├── unified_scheduler.py           # 통합 스케줄러
├── minjoo_crawler_async.py        # 더불어민주당
├── ppp_crawler_async.py           # 국민의힘
├── rebuilding_crawler_async.py    # 조국혁신당
├── reform_crawler_async.py        # 개혁신당
├── basic_income_crawler_async.py  # 기본소득당
├── jinbo_crawler_async.py         # 진보당
├── scheduler.py                   # 민주당 전용 스케줄러 (레거시)
├── crawler_config.json            # 크롤링 설정 (6개 정당)
├── crawler_state.json             # 크롤링 상태 (자동 생성)
├── requirements.txt               # Python 의존성
└── .env                           # 환경 변수 (직접 생성)
```

## 데이터 컬럼 (공통)

| 컬럼 | 설명 |
|------|------|
| `board_name` | 게시판 이름 |
| `title` | 제목 |
| `category` | 카테고리/분류 |
| `date` | 게시 날짜 |
| `writer` | 작성자 |
| `text` | 본문 |
| `url` | 원문 URL |

> **참고**: 국민의힘은 `category` 대신 `section`, `no` 컬럼 추가 포함

## 성능

| 항목 | 비동기 버전 | 기존 동기 버전 |
|------|------------|--------------|
| 정당 1개 (1000개) | ~5분 | ~80분 |
| 6개 정당 동시 | ~5-10분 | ~480분 |

## 증분 업데이트 작동 방식

1. **첫 실행**: `start_date`부터 오늘까지 전체 수집
2. **이후 실행**: 마지막 크롤링 날짜 다음날부터만 수집
3. **허깅페이스 병합**: 기존 데이터셋과 자동 병합 + URL 기준 중복 제거
4. **상태 관리**: 정당별로 독립적으로 `crawler_state.json`에 기록

## 문제 해결

| 문제 | 해결 방법 |
|------|----------|
| `HF_TOKEN이 설정되지 않았습니다` | `.env` 파일의 `HF_TOKEN` 확인 |
| 크롤링이 느림 | `crawler_config.json`에서 `concurrent_requests` 증가 |
| 서버 연결 오류 | `crawler_config.json`에서 `request_delay` 증가 |
| 특정 정당만 실패 | `python main.py --party [정당코드]` 로 개별 실행하여 확인 |

## 로그 확인

```bash
type main.log              # main.py 실행 로그
type unified_crawler.log   # 통합 크롤러 로그
type unified_scheduler.log # 스케줄러 로그
```

## Windows 백그라운드 실행

```bash
# 배치 파일
start /B python main.py > main.log 2>&1

# 또는 Windows 작업 스케줄러
# 트리거: 매일 오전 9시 → 동작: python unified_scheduler.py
```

## 주의사항

1. `concurrent_requests`는 10-20 이하 권장 (서버 부담 최소화)
2. 수집 전 웹사이트 robots.txt 확인
3. 공개 시 개인정보 포함 여부 확인 및 출처 명시

## 라이선스

MIT License