fgtools/MODULES.md

FGTools 모듈 테스트 가이드

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

준비 사항

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

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

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

서비스 모듈 테스트

Weather (기상청) 서비스

ASOS 모듈 (종관기상 데이터)

python services/weather/asos.py

기능:

• 기상청 ASOS 종관기상 데이터 조회
• 일별 기상 데이터 수집 (기온, 강수량, 습도 등)
• DB 저장 기능

Forecast 모듈 (기상청 예보)

python services/weather/forecast.py

기능:

• 초단기 예보 (향후 6시간)
• 단기 예보 (향후 3일)
• 중기 예보 (3~10일 후)

Precipitation 모듈 (강수량)

python services/weather/precipitation.py

기능:

• 시간별 강수량 예보
• HTML 테이블 생성
• 다양한 출력 형식 (JSON, HTML, 텍스트)

Analytics (분석) 서비스

Air Quality 모듈 (대기질)

python services/analytics/air_quality.py

기능:

• 한국환경공단 API를 통한 대기질 데이터 수집
• PM2.5, PM10, SO2, CO, NO2, O3 측정
• 측정소별 데이터 저장

GA4 모듈 (Google Analytics)

python services/analytics/ga4.py

기능:

• GA4 API를 통한 웹사이트 분석 데이터 수집
• 일별 세션, 사용자, 이벤트 수 조회
• 병렬 처리를 통한 성능 최적화

Visitor Forecast 모듈 (방문객 예측)

python services/analytics/visitor_forecast.py

기능:

• 날씨, 휴일, 과거 데이터를 기반한 방문객 예측
• 일별 및 주별 예측
• 날씨 영향도 분석

Notification (알림) 서비스

Mattermost 모듈

python services/notification/mattermost.py

기능:

• Mattermost로 알림 메시지 발송
• 웹훅 및 Bot API 방식 지원
• 다양한 메시지 타입 (날씨, 보고서 등)

Notion 모듈

python services/notification/notion.py

기능:

• Notion 웹훅 이벤트 처리
• 페이지 생성/수정/삭제 감지
• 알림 메시지 생성 및 발송

Flask 애플리케이션 테스트

Dashboard (대시보드)

# 서버 실행
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 서버)

python apps/weather_api/app.py

포트: 5001
엔드포인트:

• GET /api/weather/health - 헬스 체크
• GET /api/weather/precipitation - 강수량 예보

Webhook (웹훅 수신 서버)

python apps/webhook/app.py

포트: 5002
엔드포인트:

• GET /webhook/health - 헬스 체크
• POST /webhook/notion - Notion 웹훅 수신

통합 테스트

모든 애플리케이션 동시 실행

# 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

디버깅 및 로깅

디버그 모드 활성화

$env:DEBUG='true'
$env:LOG_LEVEL='DEBUG'
python services/weather/asos.py

로그 레벨 설정

$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

성능 최적화 팁

병렬 처리

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

타임아웃 설정

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

트러블슈팅

ModuleNotFoundError

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

환경변수 누락

필요한 .env 파일이 있는지 확인하세요:

# .env 파일 확인
Test-Path .env

데이터베이스 연결 오류

# 데이터베이스 설정 확인
$env:DB_HOST
$env:DB_USER
$env:DB_NAME

Docker 빌드 오류 ("image already exists")

# 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

추가 정보

• 전체 프로젝트 구조
• 설정 관리
• 로깅 설정