# FGTools 모듈 테스트 가이드

프로젝트의 각 모듈을 개별적으로 테스트 실행할 수 있습니다.

## 준비 사항

```powershell
# 프로젝트 디렉토리로 이동
cd c:\DEV\python\fgtools

# PYTHONPATH 설정 (선택사항: 명시적 경로 설정)
$env:PYTHONPATH='c:\DEV\python\fgtools'

# 가상환경 활성화
.\venv\Scripts\Activate.ps1
```

## 서비스 모듈 테스트

### Weather (기상청) 서비스

#### ASOS 모듈 (종관기상 데이터)
```powershell
python services/weather/asos.py
```
**기능:**
- 기상청 ASOS 종관기상 데이터 조회
- 일별 기상 데이터 수집 (기온, 강수량, 습도 등)
- DB 저장 기능

#### Forecast 모듈 (기상청 예보)
```powershell
python services/weather/forecast.py
```
**기능:**
- 초단기 예보 (향후 6시간)
- 단기 예보 (향후 3일)
- 중기 예보 (3~10일 후)

#### Precipitation 모듈 (강수량)
```powershell
python services/weather/precipitation.py
```
**기능:**
- 시간별 강수량 예보
- HTML 테이블 생성
- 다양한 출력 형식 (JSON, HTML, 텍스트)

### Analytics (분석) 서비스

#### Air Quality 모듈 (대기질)
```powershell
python services/analytics/air_quality.py
```
**기능:**
- 한국환경공단 API를 통한 대기질 데이터 수집
- PM2.5, PM10, SO2, CO, NO2, O3 측정
- 측정소별 데이터 저장

#### GA4 모듈 (Google Analytics)
```powershell
python services/analytics/ga4.py
```
**기능:**
- GA4 API를 통한 웹사이트 분석 데이터 수집
- 일별 세션, 사용자, 이벤트 수 조회
- 병렬 처리를 통한 성능 최적화

#### Visitor Forecast 모듈 (방문객 예측)
```powershell
python services/analytics/visitor_forecast.py
```
**기능:**
- 날씨, 휴일, 과거 데이터를 기반한 방문객 예측
- 일별 및 주별 예측
- 날씨 영향도 분석

### Notification (알림) 서비스

#### Mattermost 모듈
```powershell
python services/notification/mattermost.py
```
**기능:**
- Mattermost로 알림 메시지 발송
- 웹훅 및 Bot API 방식 지원
- 다양한 메시지 타입 (날씨, 보고서 등)

#### Notion 모듈
```powershell
python services/notification/notion.py
```
**기능:**
- Notion 웹훅 이벤트 처리
- 페이지 생성/수정/삭제 감지
- 알림 메시지 생성 및 발송

## Flask 애플리케이션 테스트

### Dashboard (대시보드)
```powershell
# 서버 실행
python apps/dashboard/app.py

# 또는 직접 실행
$env:PYTHONPATH='c:\DEV\python\fgtools'
python -c "from apps.dashboard.app import create_app; app = create_app(); app.run()"
```
**포트:** 5000 (기본값)  
**엔드포인트:**
- `GET /api/dashboard/health` - 헬스 체크
- `GET /api/dashboard/stats` - 통계 조회

### Weather API (날씨 API 서버)
```powershell
python apps/weather_api/app.py
```
**포트:** 5001  
**엔드포인트:**
- `GET /api/weather/health` - 헬스 체크
- `GET /api/weather/precipitation` - 강수량 예보

### Webhook (웹훅 수신 서버)
```powershell
python apps/webhook/app.py
```
**포트:** 5002  
**엔드포인트:**
- `GET /webhook/health` - 헬스 체크
- `POST /webhook/notion` - Notion 웹훅 수신

## 통합 테스트

### 모든 애플리케이션 동시 실행
```powershell
# Docker Compose 사용 (권장)
docker compose up -d

# 또는 개별 터미널에서 각각 실행
# 터미널 1
python apps/dashboard/app.py

# 터미널 2
python apps/weather_api/app.py

# 터미널 3
python apps/webhook/app.py
```

## 디버깅 및 로깅

### 디버그 모드 활성화
```powershell
$env:DEBUG='true'
$env:LOG_LEVEL='DEBUG'
python services/weather/asos.py
```

### 로그 레벨 설정
```powershell
$env:LOG_LEVEL='DEBUG'    # 가장 상세
$env:LOG_LEVEL='INFO'     # 일반 정보
$env:LOG_LEVEL='WARNING'  # 경고
$env:LOG_LEVEL='ERROR'    # 에러만
```

## 환경변수 설정

`.env` 파일에 다음 변수를 설정하세요:

```
# API 키
DATA_API_SERVICE_KEY=your_service_key

# 데이터베이스
DB_HOST=localhost
DB_USER=firstgarden
DB_PASSWORD=your_password
DB_NAME=firstgarden

# GA4
GA4_ENABLED=true
GA4_PROPERTY_ID=your_property_id

# Mattermost
MATTERMOST_ENABLED=true
MATTERMOST_WEBHOOK_URL=your_webhook_url

# Notion
NOTION_ENABLED=true
NOTION_API_SECRET=your_api_secret

# 로깅
LOG_LEVEL=INFO
DEBUG=false
```

## 성능 최적화 팁

### 병렬 처리
```powershell
# 최대 워커 수 설정 (기본: 4)
$env:MAX_WORKERS='8'
python services/analytics/ga4.py
```

### 타임아웃 설정
각 서비스는 적절한 타임아웃을 기본 설정으로 포함하고 있습니다.

## 트러블슈팅

### ModuleNotFoundError
```powershell
# PYTHONPATH 설정
$env:PYTHONPATH='c:\DEV\python\fgtools'
```

### 환경변수 누락
필요한 `.env` 파일이 있는지 확인하세요:
```powershell
# .env 파일 확인
Test-Path .env
```

### 데이터베이스 연결 오류
```powershell
# 데이터베이스 설정 확인
$env:DB_HOST
$env:DB_USER
$env:DB_NAME
```

### Docker 빌드 오류 ("image already exists")
```powershell
# WSL2 Ubuntu 환경에서 발생하는 오류 해결:

# 방법 1: BuildKit 비활성화 (권장)
$env:DOCKER_BUILDKIT=0
docker compose build

# 방법 2: 캐시 무시하고 빌드
docker compose build --no-cache

# 방법 3: 이전 이미지 삭제
docker rmi reg.firstgarden.co.kr/fgtools:latest
docker compose build

# 방법 4: BuildKit 캐시 정리
docker buildx prune -a

# 방법 5: 완전 초기화 후 빌드
docker compose down
docker rmi reg.firstgarden.co.kr/fgtools:latest
docker buildx prune -a
docker compose build
```

## 추가 정보

- [전체 프로젝트 구조](README.md)
- [설정 관리](core/config.py)
- [로깅 설정](core/logging_utils.py)