SavvyETF

ETF·시황 리서치 플랫폼. 텔레그램 봇이 데이터를 모으고 브리프를 만들고, 웹 대시보드가 그 결과와 실시간 조회를 보여 줍니다.

• 대시보드: https://savvyetf.com (Vercel, webapp/)
• 봇·수집기: Render Web Service savvyetf-bot (Docker, 저장소 루트)
• 저장소: Cloudflare R2 버킷 savvyetf-briefs (브리프·스냅샷·시계열), Supabase (커뮤니티 로그인만)

          시세·뉴스 API (Yahoo · Naver · KRX · DART · FRED · OKX …)
                              │
                 ┌────────────┴────────────┐
                 ▼                         ▼
   Render: python bot.py            Vercel: webapp (Next.js)
   · 텔레그램 명령 / 브리프 발송      · 대시보드 탭 · /api/*
   · 스케줄러 (장마감 스냅샷 등)      · Yahoo 직접 조회 (히트맵·시뮬레이션)
   · /api/web/* (Vercel 전용)  ◀─────┤ BOT_WEB_API_SECRET
                 │                         │
                 └──────► Cloudflare R2 ◀──┘
                      (etf_db/, briefs/, nlp_history/, mp/ …)

저장소 구조

루트의 bot.py 는 실행기입니다. python bot.py 로 그대로 띄웁니다. 수집 코드는 종류별 번호 폴더에 있습니다.

경로	내용
bot.py	실행기. 번호 폴더를 경로에 넣고 01_봇/bot.py 를 띄움
01_봇/	HTTP 서버, 텔레그램, 스케줄 슬롯, 알림, ops_log.py
02_시황/	국내·미국·NXT 브리프, 뉴스, NLP, 레딧
03_ETF/	ETF DB, 편입비, 섹터, ETF CHECK
04_국내시장/	코스피200, 코스닥100, 종목 크롤러, KOFIA
05_매크로/	매크로, 계절성, 재무·컨센서스, 신용 모니터
06_ESG/	ESG, 이벤트 스터디, 기후
07_공시/	DART
08_ADR/	ADR
09_매매/	업비트·바이낸스, 김프, 리밸런싱 스케줄
10_공통/	R2, 차트 폰트, 시세 신선도, 미국 휴장 달력
11_받은자료/	받은 엑셀. 봇이 읽지 않음
webapp/	Vercel 대시보드 (Next.js 15). 자세한 내용은 webapp/README.md
data/	봇이 쓰는 시드·유니버스. webapp 사본의 원본 (아래 “공유 데이터”)
Claude_DB/, Claude_Work/	인수인계된 분석 코드. 폴더 이름이 import 경로라 그대로 둠
research/	오프라인 연구 하네스 (배포 안 됨)
obsidian/	결정 로그·데이터 정책 노트
colab/	원래 Colab 노트북과 티커 목록 (이미지에 포함됨)

로컬 실행

bash setup.sh                      # .env 생성, .venv 생성, 의존성 설치
# .env 에 TELEGRAM_BOT_TOKEN 등 입력 (.env.example 참고, 주석에 전체 목록)
source .venv/bin/activate
python bot.py

같은 토큰으로 봇을 두 곳에서 돌리면 텔레그램이 409를 반환합니다. 로컬에서 실행할 때는 Render 인스턴스와 토큰을 분리하세요.

웹앱:

cd webapp
npm install
npm run dev

배포

main 에 푸시하면 두 곳이 자동 배포됩니다.

대상	트리거	실패 시
Vercel (webapp/)	main 푸시	빌드 실패하면 직전 Production 유지
Render (savvyetf-bot)	main 푸시 (auto-deploy)	빌드 실패하면 직전 배포 유지

• Render 설정은 render.yaml (Blueprint, Web Service, Starter 플랜). 비밀값은 sync: false 로 두고 Render 대시보드에서만 입력합니다.
• Vercel 환경변수와 크론은 webapp/README.md, webapp/vercel.json.
• 푸시 전 확인: cd webapp && npm run build (import 검사 포함).

CI (GitHub Actions)

워크플로	하는 일
webapp-import-check.yml	웹앱 import 그래프 검사 + tsc --noEmit
python-check.yml	공유 데이터 동기화 확인, 의존성 설치, 모든 모듈 컴파일, import bot
python-deps-lock.yml	수동 실행. Python 3.12 기준으로 의존성을 해석해 constraints.txt 를 커밋

Python 의존성 고정

requirements.txt 는 허용 범위, constraints.txt 는 정확한 버전입니다. Docker 이미지는 constraints.txt 가 있으면 그 버전으로 설치합니다. 처음 한 번, 그리고 업그레이드하고 싶을 때 GitHub → Actions → python deps lock → Run workflow.

공유 데이터

봇과 웹앱이 같은 파일을 각자 사본으로 갖고 있습니다. data/ 가 원본입니다.

python scripts/sync_shared_data.py          # data/ → webapp/src/data/ 복사
python scripts/sync_shared_data.py --check  # 다르면 실패 (CI에서 실행)

관리자 전용 기능

대시보드의 관리자 전용 탭과 데이터는 서버에서 막습니다 (webapp/src/lib/adminGuard.ts). 새 관리자 전용 탭을 만들면 화면에서 숨기는 것과 별도로, 그 탭이 부르는 API 라우트에 requireSiteAdmin() 를 넣고 응답을 PRIVATE_NO_STORE 로 보내야 합니다 (CDN 이 Authorization 을 구분하지 않기 때문).

프로세스 역할 분리 (선택)

BOT_ROLE 로 한 프로세스가 맡을 일을 고릅니다. 기본값 all 은 지금까지와 동일합니다.

BOT_ROLE	웹 서버	스케줄러	텔레그램 폴링
all (기본)	✓	✓	✓
web	✓	–	✓
scheduler	✓ (/health)	✓	–

메모리가 부족할 때 web 과 scheduler 를 별도 Render 서비스로 나눌 수 있습니다. 나누기 전에 확인할 점:

• /summary*, /reddit, /event 페이지와 PDF 는 스케줄러가 로컬 디스크에 쓴 파일을 웹 서버가 읽습니다. 서비스를 나누면 디스크가 공유되지 않으므로 이 경로들을 R2 에서 읽도록 먼저 바꿔야 합니다.
• 텔레그램 폴링은 한 곳(web)에서만 돌아야 합니다. 발송(브로드캐스트)은 scheduler 에서도 됩니다.
• Render 서비스가 하나 늘면 요금도 늘어납니다 (Starter 기준 월 약 $7).

운영 확인

• GET /health (HEALTH_CHECK_SECRET 설정 시 토큰 필요): 스케줄러 스레드 상태, 마지막 슬롯·오류, role, suppressed_errors (무시된 예외의 호출 위치별 횟수).
• Render 로그의 [suppressed] 모듈.함수 (N회): 오류 줄은 호출 위치마다 10분에 한 번만 찍힙니다 (SUPPRESSED_LOG_WINDOW_SECONDS).
• 대시보드 관리자 탭 적재 현황: R2 데이터셋별 마지막 적재일과 지연 여부.

보안

• 토큰·키는 .env(로컬)와 Render/Vercel 대시보드에만 둡니다. 이 저장소는 공개 저장소입니다.
• 원래 Colab 노트북에 봇 토큰이 노출된 적이 있다면 @BotFather 에서 /revoke 후 새 토큰을 쓰세요.