docs: add historical backfill operation and verification guide

docs/backfill_operation_guide.md

@@ -0,0 +1,75 @@
+# 과거 데이터 역추적 백필 운용 및 검증 가이드
+
+이 문서는 과거 발전 데이터 역추적 백필 스케줄러의 구동 현황을 모니터링하고, 내일 아침(또는 임의 시점)에 데이터 수집이 원본 사이트와 오차 없이 잘 수행되고 있는지 샘플링하여 교차 검증하기 위한 가이드라인입니다.
+
+---
+
+## 1. 백필 스케줄 및 인프라 현황
+
+*   **배포 위치:** Oracle Cloud 서버 `~/solorpower/crawler/`
+*   **실행 엔진:** 시스템 파이썬 (`/usr/bin/python3`)
+*   **스케줄 설정 (Crontab):** 매시간 30분 작동
+    ```text
+    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개월 분량)** 역추적 수집 진행
+
+---
+
+## 2. 향후 모니터링 및 체크 방법 (서버 터미널용)
+
+### 2-1. 백필 로그 실시간 모니터링
+백필 작업의 성공 여부 및 크롤링 결과(발전량 kWh 수집량)를 실시간으로 확인합니다.
+```bash
+tail -n 50 -f ~/solorpower/crawler/backfill_cron.log
+```
+
+### 2-2. SQLite 진행 상태(State) 조회
+각 발전소의 마지막 백필 날짜와 연속 무발전 일수, 진행 상태(`RUNNING` 또는 `COMPLETED`)를 데이터베이스에서 덤프합니다.
+```bash
+/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 데이터를 터미널에 덤프할 수 있습니다.)
+```bash
+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 데이터**를 터미널 화면에서 한눈에 비교합니다.
+```bash
+cd ~/solorpower/crawler && export PYTHONUTF8=1 && /usr/bin/python3 daily_summary.py 2026-02-15
+```
+
+#### 🔍 모니터링 결과 해석법:
+- 만약 출력창에 다음과 같이 `보정 성공` 메시지와 함께 값이 일치하거나 보정 완료된다면 정상 작동하는 것입니다:
+  ```text
+  📡 [cmsolar-10] 원본 사이트 통계 크롤링 시도 (2026-02-15) ...
+  ✓ 2026-02-15: 142.00kWh
+  ➔ 🟢 보정 성공: 기존 집계 0.0 kWh ➔ 원본 142.0 kWh
+  ```
+- 만약 원본 값과 Supabase에 저장된 값이 서로 완전하게 일치한다면 과거 백필 및 보정이 완벽하게 진행되고 있음을 신뢰할 수 있습니다.
+
+---
+
+## 4. 트러블슈팅 및 특이 사항 관리
+
+1.  **연속 30일 무발전 마감 (`COMPLETED`)**:
+    - 만약 특정 발전소의 상태가 너무 빨리 `COMPLETED`로 변경되었다면, 원본 사이트에서 제공하는 과거 이력 조회 가능 일수가 30일 미만으로 제한되어 수집이 마감된 것일 수 있습니다.
+    - 이때는 수동으로 복구할 수 없으며, 해당 사이트 정책상의 한계입니다.
+2.  **백필 도중 IP 차단 또는 일시적 네트워크 에러**:
+    - 크롤러 모듈 실행 에러가 일시적으로 나더라도 스크립트는 해당 일자에 대한 상태를 `RUNNING`으로 유지하며 넘어가거나 에러를 기록합니다.
+    - 크론 스케줄에 의해 다음 시간에 다시 시도되므로 일시적인 순단 현상은 자동으로 치유됩니다.