site11/docs/PIPELINE_SCHEDULER_GUIDE.md

# Pipeline Scheduler Guide

## 개요
Pipeline Scheduler는 등록된 키워드를 주기적으로 실행하여 자동으로 뉴스를 수집하고 AI 기사를 생성하는 시스템입니다.

## 아키텍처

### 1. 구성 요소

#### 1.1 Multi-Thread Scheduler (pipeline-scheduler)
- **역할**: 키워드별 스레드 관리 및 주기적 실행
- **특징**:
  - 단일 Docker 컨테이너에서 여러 스레드 동시 실행
  - 각 키워드당 하나의 독립 스레드
  - 30초마다 새 키워드 체크 및 스레드 관리
- **위치**: `services/pipeline/scheduler/multi_thread_scheduler.py`

#### 1.2 Keyword Manager API (keyword-manager)
- **역할**: 키워드 CRUD 및 스레드 모니터링
- **포트**: 8100
- **주요 엔드포인트**:
  - `GET /threads/status` - 모든 스레드 상태 조회
  - `GET /keywords` - 모든 키워드 목록
  - `POST /keywords` - 새 키워드 추가
  - `PUT /keywords/{keyword}` - 키워드 수정
  - `DELETE /keywords/{keyword}` - 키워드 삭제
  - `POST /keywords/{keyword}/activate` - 키워드 활성화
  - `POST /keywords/{keyword}/deactivate` - 키워드 비활성화
  - `POST /keywords/{keyword}/trigger` - 즉시 실행
- **위치**: `services/pipeline/scheduler/keyword_manager.py`

### 2. 데이터 모델

```python
class Keyword:
    keyword_id: str           # UUID
    keyword: str              # 검색 키워드
    interval_minutes: int     # 실행 주기 (분)
    is_active: bool          # 활성 상태
    priority: int            # 우선순위 (높을수록 우선)
    rss_feeds: List[str]     # RSS 피드 URL 목록
    max_articles_per_run: int # 실행당 최대 기사 수
    last_run: datetime       # 마지막 실행 시간
    next_run: datetime       # 다음 실행 예정 시간
```

## 사용 방법

### 1. 서비스 시작

```bash
# 스케줄러와 매니저 시작
docker-compose up -d pipeline-scheduler keyword-manager

# 로그 확인
docker-compose logs -f pipeline-scheduler
```

### 2. 키워드 관리

#### 2.1 키워드 추가
```bash
curl -X POST http://localhost:8100/keywords \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "딥러닝",
    "interval_minutes": 60,
    "priority": 1,
    "rss_feeds": [],
    "max_articles_per_run": 100,
    "is_active": true
  }'
```

#### 2.2 키워드 수정
```bash
curl -X PUT http://localhost:8100/keywords/딥러닝 \
  -H "Content-Type: application/json" \
  -d '{
    "interval_minutes": 30,
    "priority": 2
  }'
```

#### 2.3 키워드 활성화/비활성화
```bash
# 활성화
curl -X POST http://localhost:8100/keywords/딥러닝/activate

# 비활성화
curl -X POST http://localhost:8100/keywords/딥러닝/deactivate
```

#### 2.4 즉시 실행
```bash
curl -X POST http://localhost:8100/keywords/딥러닝/trigger
```

#### 2.5 키워드 삭제
```bash
curl -X DELETE http://localhost:8100/keywords/딥러닝
```

### 3. 모니터링

#### 3.1 스레드 상태 확인
```bash
curl http://localhost:8100/threads/status | python3 -m json.tool
```

응답 예시:
```json
{
  "total_threads": 4,
  "active_threads": 4,
  "threads": [
    {
      "keyword": "블록체인",
      "keyword_id": "5c7ac9a9-c56f-4878-94ec-adb13f105c8a",
      "is_active": true,
      "interval_minutes": 30,
      "priority": 2,
      "last_run": "2025-09-15T08:05:58.807000",
      "next_run": "2025-09-15T08:35:58.807000",
      "thread_status": "active",
      "minutes_until_next_run": 25.3
    }
  ]
}
```

#### 3.2 키워드 목록 조회
```bash
curl http://localhost:8100/keywords | python3 -m json.tool
```

## 작동 방식

### 1. 실행 흐름

1. **키워드 스레드 시작**
   - 스케줄러 시작 시 활성 키워드 로드
   - 각 키워드별 독립 스레드 생성

2. **주기적 실행**
   - 각 스레드는 설정된 주기마다 실행
   - 실행 시 PipelineJob 생성 후 Redis 큐에 추가
   - RSS 수집 → Google 검색 → AI 기사 생성 → 번역 파이프라인 자동 진행

3. **동적 스레드 관리**
   - 30초마다 새 키워드 확인
   - 새 키워드 추가 시 자동으로 스레드 생성
   - 비활성화/삭제 시 스레드 자동 중지

### 2. 우선순위 처리

- 높은 우선순위(priority) 키워드가 먼저 처리
- Redis 큐에서 우선순위별 정렬

### 3. 오류 처리

- 각 스레드는 독립적으로 오류 처리
- 오류 발생 시 1분 대기 후 재시도
- 스레드별 error_count, last_error 추적

## 현재 설정된 키워드

| 키워드 | 실행 주기 | 우선순위 | 상태 |
|--------|-----------|----------|------|
| 블록체인 | 30분 | 2 | 활성 |
| AI | 60분 | 1 | 활성 |
| 테크놀로지 | 60분 | 1 | 활성 |
| 경제 | 60분 | 0 | 활성 |

## 주의사항

1. **스레드 관리**
   - 키워드 추가/삭제는 30초 이내 자동 반영
   - 스레드 상태는 keyword-manager API로 실시간 확인 가능

2. **실행 주기**
   - 최소 실행 주기: 제한 없음 (권장: 30분 이상)
   - interval_minutes 변경 시 다음 실행 시간 자동 재계산

3. **중복 방지**
   - 동일 키워드 중복 등록 불가
   - RSS 수집 시 중복 URL 자동 필터링

## 트러블슈팅

### 스레드가 시작되지 않을 때
```bash
# 스케줄러 재시작
docker-compose restart pipeline-scheduler

# 로그 확인
docker-compose logs --tail=50 pipeline-scheduler
```

### 키워드가 실행되지 않을 때
```bash
# 키워드 상태 확인
curl http://localhost:8100/keywords/키워드명 | python3 -m json.tool

# 즉시 실행 트리거
curl -X POST http://localhost:8100/keywords/키워드명/trigger
```

### MongoDB 연결 오류
```bash
# MongoDB 상태 확인
docker-compose ps mongodb

# MongoDB 재시작
docker-compose restart mongodb
```

## 파일 구조

```
services/pipeline/scheduler/
├── multi_thread_scheduler.py  # 멀티스레드 스케줄러
├── keyword_manager.py         # 키워드 관리 API
├── single_keyword_scheduler.py # (deprecated) 단일 키워드 스케줄러
├── requirements.txt           # Python 의존성
└── Dockerfile                # Docker 이미지 정의

services/pipeline/shared/
└── models.py                 # Keyword, PipelineJob 모델 정의
```

## 향후 개선사항

1. **웹 대시보드**: 실시간 모니터링 UI
2. **알림 시스템**: 오류 발생 시 이메일/Slack 알림
3. **통계 기능**: 키워드별 수집 통계 및 분석
4. **스케줄 템플릿**: 자주 사용하는 설정 저장/불러오기
5. **백업/복구**: 키워드 설정 백업 및 복구 기능