solorpower_crawler/crawler_structure.md

Crawler 시스템 파일 구조 및 역할 정의

이 문서는 crawler 폴더 내의 각 파일과 모듈의 역할, 기능, 그리고 상호 작용 방식에 대해 자세히 설명합니다.

📁 디렉토리 구조 및 핵심 파일 요약

파일명	분류	핵심 역할
main.py	Core	크롤러 시스템의 메인 진입점. 전체 수집 프로세스 조율
config.py	Config	발전소 정보, 비밀번호, 시스템 상수 등 설정 관리
database.py	Data	Supabase 데이터베이스 연결 및 CRUD 처리
crawler_manager.py	Logic	지능형 스케줄링 관리 (업데이트 패턴 학습 및 최적화)
crawler_gui.py	UI	관리자용 대시보드 (윈도우 GUI), 모니터링 및 수동 제어
daily_summary.py	Batch	일일 발전 통계 집계 및 요약 테이블 저장
fetch_history.py	Tool	과거 데이터(Hourly, Daily) 수집 도구
sync_plants.py	Tool	발전소 메타 정보를 DB와 동기화
verify_data.py	Test	수집된 데이터의 무결성 검증 및 테스트 스크립트

---

📄 파일별 상세 역할 분석

1. 핵심 시스템 (Core System)

main.py

• 역할: 전체 크롤링 시스템의 오케스트레이터(Orchestrator).
• 주요 기능:
  • integrated_monitoring() 함수를 통해 정의된 모든 발전소를 순회합니다.
  • CrawlerManager를 통해 현재 시점에 실행해야 할 크롤러를 선별합니다.
  • 각 발전소 타입에 맞는 크롤러 함수(crawlers 패키지)를 동적으로 호출합니다.
  • 수집된 실시간 데이터를 콘솔에 출력하고, database.py를 통해 DB에 저장합니다.
  • 발전량이 0인 경우 등 간단한 이상 감지 로직을 수행합니다.
• 실행 방식: 스케줄러(Cron 등)에 의해 주기적으로 실행되거나, GUI에서 호출됩니다. --force 옵션으로 강제 실행 가능합니다.

config.py

• 역할: 시스템 설정 및 발전소 정보의 단일 진실 공급원(Single Source of Truth).
• 주요 기능:
  • SYSTEM_CONSTANTS: 각 크롤러 시스템(NREMS, KREMC 등)의 URL 및 API 엔드포인트 정의.
  • COMPANIES: 업체 및 산하 발전소들의 계층 구조, 인증 정보(ID/PW), 용량(Customer ID) 등을 JSON 구조로 관리.
  • get_all_plants(): 계층화된 데이터를 크롤러가 사용하기 쉬운 평탄화(Flat)된 리스트로 변환하여 제공.
  • 특이 사항: 보안이 필요한 인증 정보가 포함되어 있어 관리에 주의가 필요합니다. 1, 2호기와 같이 하나의 계정으로 분리되는 발전소(is_split) 설정도 이곳에서 관리됩니다.

crawler_manager.py (Smart Scheduler)

• 역할: 비효율적인 반복 호출을 줄이고 NAS 리소스를 절약하기 위한 미들웨어.
• 주요 기능:
  • SQLite 기반 상태 관리: crawler_manager.db 로컬 파일에 각 발전소의 상태 저장.
  • 학습 모드(LEARNING): 초기에는 자주 실행하며 발전소 서버의 데이터 업데이트 주기 패턴을 학습.
  • 최적화 모드(OPTIMIZED): 학습된 업데이트 시점(예: 매시 15분) 전후의 윈도우(Window)에만 크롤링을 허용.
  • 야간(21시~05시) 크롤링 자동 차단 로직 포함.

2. 데이터 관리 (Data Management)

database.py

• 역할: Supabase 클라우드 데이터베이스와의 인터페이스.
• 주요 기능:
  • Supabase 클라이언트 싱글턴 연결 관리.
  • save_to_supabase(): 실시간 발전 데이터(solar_logs) 저장. 일일 통계(daily_stats) 단순 Upsert 처리.
  • save_history(): 과거 내역 저장 시 사용되며, solar_logs(Hourly), daily_stats(Daily), monthly_stats(Monthly) 등 데이터 타입에 따라 적절한 테이블에 저장하고, 월별 통계 자동 갱신 트리거 로직을 포함합니다.

daily_summary.py

• 역할: 수집된 로그 데이터를 기반으로 일일 최종 통계를 확정 짓는 배치 스크립트.
• 주요 기능:
  • 특정 날짜의 solar_logs를 모두 조회하여 발전소별 총 발전량, 피크 출력, 발전 시간(이용률)을 계산.
  • 계산된 확정 데이터를 daily_stats 테이블에 저장.
  • 주로 하루가 끝나는 시점이나 다음 날 새벽에 실행하여 데이터 정확도를 보정합니다.

3. 사용자 인터페이스 (User Interface)

crawler_gui.py

• 역할: 윈도우 환경에서 크롤러 상태를 시각적으로 모니터링하고 제어하는 관리자 도구.
• 주요 기능:
  • tkinter 기반의 GUI 제공.
  • 발전소별 현재 상태(대기, 실행중, 최적화 여부), 마지막 실행 시간 등을 트리 뷰(Tree View)로 표시.
  • 개별/전체 크롤링 강제 실행, 히스토리 수집 명령, 학습 모드 리셋 등의 제어 기능 제공.
  • 실시간 로그 창을 통해 백그라운드 프로세스(subprocess)의 실행 결과를 출력.

4. 도구 및 유틸리티 (Tools & Utilities)

fetch_history.py

• 역할: 누락된 데이터나 초기 구축 시 과거 데이터를 수집하기 위한 스크립트.
• 주요 기능:
  • 특정 발전소 ID를 인자로 받아 과거 데이터를 조회.
  • 각 크롤러 모듈(crawlers/)에 구현된 fetch_history_hourly, fetch_history_daily 등을 호출.
  • 시간별(Hourly), 일별(Daily) 데이터를 수집하여 DB에 적재.

sync_plants.py

• 역할: 로컬 코드(config.py)와 원격 DB(plants 테이블) 간의 메타 데이터 동기화.
• 주요 기능:
  • 새로운 발전소가 추가되거나 이름/용량이 변경되었을 때, config.py의 내용을 DB의 마스터 테이블에 반영(Upsert).
  • NREMS 1, 2호기와 같이 논리적으로 분리해야 하는 발전소를 별도 레코드로 DB에 생성.

verify_data.py

• 역할: 크롤링 로직 검증 및 데이터 무결성 테스트.
• 주요 기능:
  • 각 발전소별로 샘플 날짜(과거/현재)를 지정하여 실제 데이터를 가져와 봅니다.
  • 시간별, 일별, 월별 합계가 논리적으로 맞는지 검증 포맷을 출력하여 개발자가 확인하기 쉽게 돕습니다.

5. 하위 폴더

crawlers/ (폴더)

• 역할: 실제 사이트별 크롤링 로직이 구현된 모듈들의 집합.
• 구성:
  • nrems.py, kremc.py, hyundai.py, sun_wms.py, cmsolar.py 등 사이트 타입별로 파일이 존재.
  • 각 모듈은 공통적으로 get_current_status() (실시간), fetch_history_* (과거 내역) 등의 인터페이스를 구현해야 함.

venv/, temp_env/ (폴더)

• 역할: Python 가상 환경 폴더. 프로젝트 실행에 필요한 라이브러리(requests, pandas, supabase 등)가 설치됨.

---

작성일: 2026-01-28