Feat: [main] news-summary-bot 완성

2026-03-24 12:19:54 +09:00
commit dc4656e452
21 changed files with 1028 additions and 0 deletions
--- a/docs/development.md
+++ b/docs/development.md
@@ -0,0 +1,102 @@
+# 개발 가이드
+
+YouTube 뉴스 영상을 자동 요약하여 Discord로 전송하는 FastAPI 기반 봇의 개발 문서입니다.
+
+## 프로젝트 구조
+
+```
+news-summary-bot/
+├── app/
+│   ├── __init__.py
+│   ├── main.py          # FastAPI 엔드포인트 (/summarize, /health)
+│   ├── config.py        # pydantic-settings 환경변수
+│   ├── transcript.py    # youtube-transcript-api로 자막 추출
+│   ├── summarizer.py    # Claude Sonnet 4.6 요약
+│   └── discord.py       # Discord 웹훅 전송
+├── Dockerfile
+├── docker-compose.yml
+├── requirements.txt
+├── .env.example
+└── .gitignore
+```
+
+## 로컬 환경 설정
+
+**Python 3.12 이상** 필요.
+
+```bash
+# 의존성 설치
+pip install -r requirements.txt
+
+# 환경변수 파일 생성
+cp .env.example .env
+# .env 파일을 열어 API 키 등 설정
+
+# 개발 서버 실행
+uvicorn app.main:app --reload
+```
+
+서버가 정상 실행되면 `http://localhost:8000` 에서 접근 가능합니다.
+
+## API 엔드포인트
+
+### POST /summarize
+
+YouTube 영상 URL을 받아 자막을 추출하고, Claude로 요약한 뒤 Discord 웹훅으로 전송합니다.
+
+- **인증**: `X-Api-Secret` 헤더에 시크릿 값 전달 (API_SECRET 환경변수가 설정된 경우 필수)
+- **요청 본문**:
+  - `video_url` (string, 필수) — YouTube 영상 URL
+  - `title` (string, 필수) — 영상 제목
+
+### GET /health
+
+서버 상태 확인용 헬스체크 엔드포인트입니다. 별도 인증 없이 호출 가능합니다.
+
+## 로컬 테스트
+
+### 헬스체크 확인
+
+```bash
+curl http://localhost:8000/health
+```
+
+### 요약 요청
+
+```bash
+curl -X POST http://localhost:8000/summarize \
+  -H "Content-Type: application/json" \
+  -H "X-Api-Secret: your-secret-here" \
+  -d '{
+    "video_url": "https://www.youtube.com/watch?v=VIDEO_ID",
+    "title": "뉴스 영상 제목"
+  }'
+```
+
+정상 처리 시 Discord 채널에 요약 메시지가 전송됩니다.
+
+## 주요 모듈 설명
+
+### transcript.py
+
+YouTube URL에서 video ID를 추출하고 `youtube-transcript-api`를 사용하여 자막을 가져옵니다. 한국어(`ko`) 자막을 우선으로 시도하며, 없을 경우 영어 등 다른 언어 자막을 fallback으로 사용합니다.
+
+### summarizer.py
+
+Anthropic의 **Claude Sonnet 4.6** 모델을 사용하여 자막 텍스트를 요약합니다. 시스템 프롬프트에 뉴스/경제 요약에 최적화된 포맷을 지정하여 일관된 형식의 요약을 생성합니다.
+
+### discord.py
+
+요약 결과를 **Discord Embed** 형식으로 구성하여 웹훅 URL로 전송합니다. 영상 제목, 요약 내용, 원본 링크 등을 포함합니다.
+
+### config.py
+
+`pydantic-settings`를 사용하여 `.env` 파일 또는 시스템 환경변수에서 설정값을 로드합니다. 필수 값이 누락되면 서버 시작 시 에러가 발생합니다.
+
+## 환경변수
+
+| 변수 | 필수 | 설명 |
+|------|------|------|
+| `ANTHROPIC_API_KEY` | O | Anthropic API 키 |
+| `DISCORD_WEBHOOK_URL` | O | Discord 웹훅 URL |
+| `API_SECRET` | X | n8n → FastAPI 인증용 시크릿 (미설정 시 인증 생략) |
--- a/docs/n8n-setup.md
+++ b/docs/n8n-setup.md
@@ -0,0 +1,101 @@
+# n8n 워크플로우 구성 가이드
+
+## 워크플로우 개요
+
+이 워크플로우는 2개의 YouTube 채널(머니머니코믹스, 슈카월드)의 새 영상을 RSS Feed Trigger로 감지하고, FastAPI `/api/news/summarize` 엔드포인트를 호출하여 요약 후 Discord로 전송하는 자동화 파이프라인입니다.
+
+**전체 흐름:**
+
+```
+RSS Feed Trigger (채널A) ──┐
+                           ├→ Merge → HTTP Request (FastAPI) → 완료
+RSS Feed Trigger (채널B) ──┘                                ↘ Error Trigger → Discord 알림
+```
+
+## 노드 구성 상세
+
+### 1. RSS Feed Trigger 노드 (2개)
+
+RSS Feed Trigger는 **중복 방지가 내장**되어 있어 이전에 처리한 항목을 기억하고, 새 영상만 반환합니다. Poll Time으로 체크 주기를 설정합니다.
+
+**노드 A - 머니머니코믹스:**
+
+| 설정 항목 | 값 |
+|---|---|
+| Feed URL | `https://www.youtube.com/feeds/videos.xml?channel_id=UCJo6G1u0e_-wS-JQn3T-zEw` |
+| Poll Time | Every Day / Hour: 10, 14, 20 (하루 3회 권장) |
+
+**노드 B - 슈카월드:**
+
+| 설정 항목 | 값 |
+|---|---|
+| Feed URL | `https://www.youtube.com/feeds/videos.xml?channel_id=UCsJ6RuBiTVWRX156FVbeaGg` |
+| Poll Time | Every Day / Hour: 10, 14, 20 (하루 3회 권장) |
+
+> ⚠️ **첫 실행 주의:** RSS Feed Trigger를 처음 활성화하면 피드에 있는 모든 영상(최대 15개)을 새 영상으로 인식합니다. 워크플로우 활성화 전에 수동으로 한 번 테스트 실행하여 기존 항목을 처리 완료 상태로 만드세요.
+
+### 2. Merge 노드
+
+- **타입:** Merge
+- **모드:** Append
+- 두 RSS Feed Trigger의 출력을 하나의 리스트로 합칩니다.
+- 합쳐진 리스트의 각 항목마다 다음 노드(HTTP Request)가 실행됩니다.
+
+### 3. HTTP Request 노드
+
+FastAPI 서버의 `/api/news/summarize` 엔드포인트를 호출합니다.
+
+| 설정 항목 | 값 |
+|---|---|
+| Method | `POST` |
+| URL | `http://<서버IP>/api/news/summarize` |
+| Body Content Type | JSON |
+| Body | 아래 참조 |
+
+**Body (JSON):**
+
+```json
+{
+  "video_url": "{{ $json.link }}",
+  "title": "{{ $json.title }}"
+}
+```
+
+**Headers:**
+
+| 헤더 | 값 |
+|---|---|
+| `Content-Type` | `application/json` |
+| `X-Api-Secret` | 설정한 시크릿 값 (`.env`의 `API_SECRET`과 동일) |
+
+## 에러 처리
+
+### Error Trigger 워크플로우
+
+메인 워크플로우와 별도로 에러 처리 워크플로우를 생성합니다.
+
+1. **Error Trigger** 노드를 추가합니다.
+2. **HTTP Request** 노드로 Discord Webhook을 호출합니다:
+
+| 설정 항목 | 값 |
+|---|---|
+| Method | `POST` |
+| URL | Discord Webhook URL |
+| Body Content Type | JSON |
+
+**Body:**
+
+```json
+{
+  "content": "뉴스 요약 봇 에러 발생!\n워크플로우: {{ $json.workflow.name }}\n에러: {{ $json.execution.error.message }}"
+}
+```
+
+3. 메인 워크플로우의 **Settings → Error Workflow**에서 이 에러 워크플로우를 지정합니다.
+
+### HTTP Request 노드 자체 에러 처리
+
+HTTP Request 노드 설정에서:
+
+- **Continue On Fail:** `true`로 설정하면 하나의 영상 요약이 실패해도 나머지 영상은 계속 처리됩니다.
+- **Retry On Fail:** `true`, **Max Retries:** `2`, **Wait Between Retries (ms):** `3000`
--- a/docs/operations.md
+++ b/docs/operations.md
@@ -0,0 +1,84 @@
+# 운영 가이드
+
+YouTube 뉴스 요약 봇의 배포 및 운영 가이드.
+
+**아키텍처:** n8n (RSS 트리거) → FastAPI 앱 (Docker 컨테이너) → Claude API → Discord 웹훅
+
+---
+
+## 배포 절차
+
+### 1. Docker 이미지 빌드 & Push
+
+```bash
+docker build -t nkey/news-summary-bot:latest .
+docker push nkey/news-summary-bot:latest
+```
+
+### 2. OCI 서버 설정
+
+- `docker-compose.yml`과 `.env` 파일을 서버에 준비
+- `.env`에 아래 값 설정:
+  - `ANTHROPIC_API_KEY` — Claude API 키
+  - `DISCORD_WEBHOOK_URL` — Discord 웹훅 URL
+  - `API_SECRET` — n8n에서 호출 시 인증용 시크릿
+- 컨테이너 실행:
+
+```bash
+docker compose pull && docker compose up -d
+```
+
+### 3. 업데이트 시
+
+```bash
+# 로컬에서
+docker build -t nkey/news-summary-bot:latest .
+docker push nkey/news-summary-bot:latest
+
+# OCI 서버에서
+docker compose pull && docker compose up -d
+```
+
+---
+
+## 헬스체크
+
+```bash
+curl http://localhost:8000/health
+```
+
+---
+
+## 로그 확인
+
+```bash
+docker compose logs -f news-summary-bot
+```
+
+---
+
+## 트러블슈팅
+
+| 증상 | 원인 | 해결 |
+|------|------|------|
+| 자막 추출 실패 | 영상에 자막 없음 | 자동생성 자막이 없는 영상은 스킵됨 |
+| Discord 전송 실패 | 웹훅 URL 만료 | Discord에서 웹훅 재생성 후 `.env` 업데이트 |
+| 401 Unauthorized | API_SECRET 불일치 | n8n 헤더와 `.env` 값 확인 |
+| Claude API 오류 | API 키 만료 또는 잔액 부족 | Anthropic 콘솔에서 확인 |
+| Discord embed 글자 수 초과 | 요약이 4096자 초과 | `summarizer.py`의 `max_tokens` 줄이기 |
+
+---
+
+## 모니터링 포인트
+
+- `/health` 엔드포인트로 컨테이너 상태 확인
+- Discord 채널에 요약이 정상적으로 올라오는지 확인
+- `docker compose logs`로 에러 로그 모니터링
+
+---
+
+## 비용 관리
+
+- **Claude Sonnet 4.6:** Input $3/MTok, Output $15/MTok
+- 일 1~2건 기준 월 ~$3 이내
+- [Anthropic 콘솔](https://console.anthropic.com/)에서 usage 확인
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -0,0 +1,34 @@
+# 테스트 가이드
+
+## 의존성 설치
+
+```bash
+pip install pytest pytest-asyncio
+```
+
+## 테스트 실행
+
+```bash
+# 환경변수 더미값 설정 (config.py 로드용)
+ANTHROPIC_API_KEY=test DISCORD_WEBHOOK_URL=https://test pytest -v
+```
+
+## 테스트 구조
+
+### `tests/test_discord.py`
+
+Discord 메시지 전송 모듈(`app/discord.py`)에 대한 유닛 테스트.
+
+| 테스트 | 설명 |
+|--------|------|
+| `test_extract_video_id` | 다양한 YouTube URL 형식에서 비디오 ID를 올바르게 추출하는지 확인 (parametrize 5건) |
+| `test_parse_summary_bold_format` | `**한줄 요약**:` 볼드 형식의 요약 파싱 검증 |
+| `test_parse_summary_heading_format` | `## 한줄 요약` 헤딩 형식의 요약 파싱 검증 |
+| `test_parse_summary_empty` | 파싱 불가한 텍스트에 대해 빈 dict 반환 확인 |
+| `test_send_to_discord_embed_structure` | 임베드에 제목, URL, 썸네일, 필드, 푸터, 타임스탬프가 올바르게 구성되는지 확인 |
+| `test_send_to_discord_fallback_on_unparsable` | 파싱 실패 시 전체 텍스트가 description에 그대로 들어가는지 확인 |
+
+## 참고
+
+- 테스트는 외부 API를 호출하지 않습니다 (`httpx.AsyncClient`를 mock 처리).
+- `ANTHROPIC_API_KEY`, `DISCORD_WEBHOOK_URL`은 pydantic-settings가 필수로 요구하므로 더미값을 환경변수로 전달해야 합니다.