solorpower/docs/backfill_operation_guide.md

과거 데이터 역추적 백필 운용 및 검증 가이드

이 문서는 과거 발전 데이터 역추적 백필 스케줄러의 구동 현황을 모니터링하고, 내일 아침(또는 임의 시점)에 데이터 수집이 원본 사이트와 오차 없이 잘 수행되고 있는지 샘플링하여 교차 검증하기 위한 가이드라인입니다.

---

1. 백필 스케줄 및 인프라 현황

• 서버 이름: holdem-server
• 공인 IP: 140.245.73.212
• 접속 계정: ubuntu
• SSH 키 경로: C:\Users\haneu\.ssh\holdem_server.key
• 배포 위치: Oracle Cloud 서버 ~/solorpower/crawler/
• 실행 엔진: 시스템 파이썬 (/usr/bin/python3)
• 스케줄 설정 (Crontab): 매시간 30분 작동

  30 * * * * cd ~/solorpower/crawler && export PYTHONUTF8=1 && /usr/bin/python3 backward_backfill.py --days 5 --delay 2.0 >> backfill_cron.log 2>&1
  

• 1일 수집 속도: 24회 * 5일 = 하루 약 120일치(4개월 분량) 역추적 수집 진행

💻 서버 접속 명령어

ssh -i "C:\Users\haneu\.ssh\holdem_server.key" ubuntu@140.245.73.212

---

2. 향후 모니터링 및 체크 방법 (서버 터미널용)

2-1. 백필 로그 실시간 모니터링

백필 작업의 성공 여부 및 크롤링 결과(발전량 kWh 수집량)를 실시간으로 확인합니다.

tail -n 50 -f ~/solorpower/crawler/backfill_cron.log

2-2. SQLite 진행 상태(State) 조회

각 발전소의 마지막 백필 날짜와 연속 무발전 일수, 진행 상태(RUNNING 또는 COMPLETED)를 데이터베이스에서 덤프합니다.

• 리눅스(서버 터미널)에서 실행 시:

  /usr/bin/python3 -c "import sqlite3; conn = sqlite3.connect('/home/ubuntu/solorpower/crawler/crawler_manager.db'); cursor = conn.cursor(); cursor.execute('SELECT * FROM backfill_state'); [print(f'발전소: {r[0]:<12} | 마지막날짜: {r[1]} | 연속무발전: {r[2]}일 | 상태: {r[3]}') for r in cursor.fetchall()]; conn.close()"
  

• 윈도우(로컬 PowerShell)에서 원격으로 실행 시 (따옴표 에러 방지):

  ssh -i "C:\Users\haneu\.ssh\holdem_server.key" ubuntu@140.245.73.212 "export PYTHONUTF8=1 && /usr/bin/python3 -c \"import sqlite3; conn = sqlite3.connect('/home/ubuntu/solorpower/crawler/crawler_manager.db'); cursor = conn.cursor(); cursor.execute('SELECT * FROM backfill_state'); [print(f'발전소: {r[0]:<12} | 마지막날짜: {r[1]} | 연속무발전: {r[2]}일 | 상태: {r[3]}') for r in cursor.fetchall()]; conn.close()\""
  

---

3. 내일 아침 실데이터 교차 검증 (샘플링 비교)

내일 아침(배포 후 약 20~24시간 경과)이 되면, 방금 실행한 수동 10일치와 매시간 누적된 120일치를 포함하여 **약 130일치(약 4.3개월)**의 과거 데이터가 수집되어 있을 것입니다. 이에 따라 **2026년 2월 중순(예: 2026-02-15)**의 데이터를 샘플로 삼아 원본 사이트와 비교 검증합니다.

3-1. 검증 준비: SQLite에서 내일 아침 진행 날짜 확인

위의 2-2번 명령어를 실행해 발전소들의 마지막 백필 날짜가 2026년 2월 이전으로 도달했는지 확인합니다.

• 예: last_backfilled_date가 2026-02-10인 경우, 2026-02-15 데이터는 성공적으로 수집 완료된 상태입니다.

3-2. 검증 방법 1: Supabase DB에 적재된 데이터 조회

Supabase 테이블에서 특정 일자(2026-02-15)에 수집된 발전량이 들어와 있는지 확인합니다. (서버 터미널에서 아래의 파이썬 원라이너를 통해 Supabase 데이터를 터미널에 덤프할 수 있습니다.)

cd ~/solorpower/crawler && /usr/bin/python3 -c "from database import get_supabase_client; client = get_supabase_client(); res = client.table('daily_stats').select('plant_id, date, total_generation').eq('date', '2026-02-15').execute(); [print(f'Supabase -> 발전소: {r[\"plant_id\"]:<12} | 발전량: {r[\"total_generation\"]} kWh') for r in res.data]"

3-3. 검증 방법 2: 원본 사이트와 직접 교차 샘플링 비교

특정일(2026-02-15)을 대상으로 하이브리드 보정 집계기(daily_summary.py)를 수동 구동하여, 원본 사이트에서 직접 긁어오는 값과 Supabase 데이터를 터미널 화면에서 한눈에 비교합니다.

cd ~/solorpower/crawler && export PYTHONUTF8=1 && /usr/bin/python3 daily_summary.py 2026-02-15

🔍 모니터링 결과 해석법:

• 만약 출력창에 다음과 같이 보정 성공 메시지와 함께 값이 일치하거나 보정 완료된다면 정상 작동하는 것입니다:

  📡 [cmsolar-10] 원본 사이트 통계 크롤링 시도 (2026-02-15) ...
  ✓ 2026-02-15: 142.00kWh
  ➔ 🟢 보정 성공: 기존 집계 0.0 kWh ➔ 원본 142.0 kWh
  

• 만약 원본 값과 Supabase에 저장된 값이 서로 완전하게 일치한다면 과거 백필 및 보정이 완벽하게 진행되고 있음을 신뢰할 수 있습니다.

---

4. 트러블슈팅 및 특이 사항 관리

1. 연속 30일 무발전 마감 (COMPLETED):
   • 성공적으로 조회된 실제 0kWh만 연속 일수에 포함됩니다.
   • 정상 응답에 해당 날짜가 없거나 요청·로그인·파싱이 실패한 경우에는 30일 종료 조건에 포함되지 않습니다.
2. 백필 도중 IP 차단 또는 일시적 네트워크 에러:
   • 해당 발전소의 진행 커서와 무발전 횟수를 변경하지 않고 그 발전소의 이번 실행을 중단합니다.
   • 다른 발전소는 계속 처리하며, 다음 cron 실행에서 실패한 발전소의 같은 날짜부터 재시도합니다.
3. Supabase 조회 또는 저장 실패:
   • 진행 커서를 갱신하지 않으므로 다음 실행에서 같은 날짜가 다시 처리됩니다.
   • 기존 일간 통계보다 작거나 같은 값은 기존 값을 유지하고, 더 큰 값만 갱신합니다.

---

5. 2026-08-06 운영 검증 결과

• 9개 발전소의 backfill_state는 모두 COMPLETED이며 실행 중인 작업은 없습니다.
• KREMC 원본 첫 데이터는 2018-10-09 86kWh로 DB 최초 날짜와 일치합니다.
• CMSolar 원본 첫 데이터는 2020-09-22 50kWh로 DB 최초 날짜와 일치합니다.
• 2026-08-05 원본 값은 KREMC 160kWh, CMSolar 127kWh로 운영 DB 및 일일 마감 결과와 일치합니다.
• 운영 서버에서 백필·저장 보호·사이트 오류 계약을 포함한 테스트 23개가 통과했습니다.
• 완료된 백필 cron은 매시간 무작업 실행 중입니다. 비활성화는 운영 스케줄 변경이므로 별도 결정 후 수행합니다.