Services

Services

Fetchers (src/fetchers/)

각 fetcher는 특정 뉴스 소스에서 기사를 수집하여 Article 객체 리스트로 반환합니다.

Tech Fetcher (src/fetchers/tech.py)

Hacker News API에서 상위 기술 뉴스를 수집합니다.

데이터 소스: hacker-news.firebaseio.com/v0

동작 흐름:

1. /topstories 엔드포인트에서 상위 스토리 ID 목록 가져오기
2. 상위 50개 스토리의 상세 정보 fetch (병렬 아님, 순차 + 재시도)
3. 비기술 키워드 필터링 (정치, 스포츠, 유명인 등)
4. 점수순 정렬 후 상위 5개 반환

필터링 규칙:

NON_TECH_PATTERNS = re.compile(
    r"\b(politics|election|president|congress|senate|democrat|republican|"
    r"nfl|nba|mlb|fifa|olympics|weight loss|diet pill|celebrity|...)\\b",
    re.IGNORECASE,
)

Stocks Fetcher (src/fetchers/stocks.py)

주식 시장 뉴스를 언어별로 다른 소스에서 수집합니다.

영어 소스: Yahoo Finance RSS (finance.yahoo.com/news/rssurl) 한국어 소스: Google News Korea RSS (news.google.com/rss/search?q=주식+코스피)

키워드 필터링:

• 영어: stock, market, S&P, NASDAQ, earnings, dividend, IPO, bitcoin 등
• 한국어: 주식, 코스피, 코스닥, 증시, 주가, 상장, 배당, ETF 등

Real Estate Fetcher (src/fetchers/realestate.py)

부동산 뉴스를 언어별로 다른 소스에서 수집합니다.

영어 소스:

• Zillow Research (zillow.com/research/feed/)
• HousingWire (housingwire.com/feed/)
• CNBC Real Estate (search.cnbc.com/rs/...)

한국어 소스: Google News Korea RSS

Summarizer (src/summarizer.py)

기사 본문을 추출하고 AI로 요약합니다.

본문 추출:

1. trafilatura.extract() — 메인 콘텐츠 추출
2. Hacker News text 필드 — HN 자체 게시글인 경우
3. HN 댓글 본문 — URL 없는 Ask HN/Show HN 등

요약 엔진:

• 주 엔진: Groq API (qwen/qwen3.8-27b)
• 폴백: Google Translate (무료 API)

언어별 프롬프트:

한국어: "한국 테크 블로거가 개발자 친구에게 설명하는 느낌으로 3문장 요약.
        딱딱한 '~했습니다' 대신 '~했어요', '~인 셈이죠' 등 사용."
영어:   "Summarize in 3 sentences in English. Casual, friendly tone."

재시도 로직:

• Rate limit 시 지수 백오프: 5초 → 10초 → 20초
• 최대 3회 재시도
• 실패 시 빈 문자열 반환 (요약 없이 기사 제목만 발송)

Notifier (src/notifier.py)

HTML 이메일을 생성하여 Gmail SMTP로 발송합니다.

이메일 구성:

• 모바일 친화적 HTML 템플릿
• 기사별: 순번, 제목 (링크), AI 요약, HN 댓글 링크
• 하단: 구독 해지 링크
• 토픽별 이모지 헤더 (💻 Tech, 📈 Stocks, 🏠 Real Estate)

보안:

• URL sanitization: http://, https:// 스킴만 허용
• HTML escape: 모든 사용자 입력값
• 이메일 주소 HTML escape

발송 방식:

• 단일 SMTP SSL 연결로 모든 이메일 처리
• SMTP_SSL (465) 시도 → 실패 시 STARTTLS (587) 폴백
• 발송 실패 시 로그 후 다음 구독자로 계속

Subscriber Management (src/subscribers.py)

subscribers.json 파일 기반의 구독자 CRUD 관리입니다.

데이터 모델:

[
  {
    "email": "user@example.com",
    "language": "ko",
    "topics": ["tech", "stocks"]
  }
]

제공 함수:

함수	설명
load_subscribers()	JSON에서 구독자 목록 로드
save_subscribers()	구독자 목록을 JSON으로 저장
add_subscriber()	새 구독자 추가 (중복 검사, 최대 500명)
remove_subscriber()	이메일로 구독자 제거
update_subscriber()	언어/토픽 변경

Cloudflare Worker (worker/src/index.js)

구독 페이지에서의 요청을 GitHub Actions repository_dispatch로 프록시합니다.

역할:

• GitHub PAT 토큰을 서버 사이드에 안전하게 보관
• CORS origin 검증 (프로덕션 도메인만 허용)
• Rate limiting (IP별 분당 5건, 시간당 20건)
• 입력 검증 및 필터링

보안 조치:

✅ CORS: https://minjungsung.github.io만 허용
✅ 필드 화이트리스트: email, language, topics, action만
✅ 언어/토픽 값 검증: 허용된 값만
✅ Request body 크기 제한: 1KB
✅ 이메일 길이 제한: 254자
✅ IP 기반 Rate limiting

Cache (src/cache.py)

GitHub Actions Cache를 활용한 일간 캐싱 시스템입니다.

캐시 파일:

• data/cache/articles_{topic}.json — 토픽별 기사 캐시
• data/cache/summaries_{language}.json — 언어별 요약 캐시

캐시 전략:

• 같은 기사를 여러 구독자에게 발송할 때 중복 Groq API 호출 방지
• 기사 URL을 키로 사용하여 요약 결과 저장
• 실행마다 새 캐시 생성, 이전 실행의 캐시에서 복원 (hackdigest-v2- prefix)