Initial commit - cleaned repository

2025-09-28 20:41:57 +09:00
commit e3c28f796a
188 changed files with 28102 additions and 0 deletions
--- a/docs/PIPELINE_SCHEDULER_GUIDE.md
+++ b/docs/PIPELINE_SCHEDULER_GUIDE.md
@ -0,0 +1,238 @@
+# 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. **백업/복구**: 키워드 설정 백업 및 복구 기능