5.2 KiB
5.2 KiB
===================================================================
FGTools - First Garden 통합 도구
===================================================================
퍼스트가든 운영을 위한 통합 도구 모음입니다.
기상 데이터, 방문객 분석, 알림 등의 기능을 제공합니다.
===================================================================
📌 개요
FGTools는 퍼스트가든 운영에 필요한 다양한 도구들을 통합한 프로젝트입니다.
주요 기능
- 날씨 서비스: 기상청 API를 통한 날씨 예보 및 ASOS 종관기상 데이터 수집
- 분석 서비스: Google Analytics 4, 대기질 데이터 수집 및 방문객 예측
- 알림 서비스: Notion 웹훅 처리 및 Mattermost/Telegram 알림 발송
- 대시보드: 수집된 데이터를 조회하고 시각화하는 웹 인터페이스
📁 프로젝트 구조
fgtools/
├── core/ # 핵심 공통 모듈
│ ├── config.py # 통합 설정 관리
│ ├── database.py # 데이터베이스 연결 관리
│ ├── logging_utils.py # 로깅 유틸리티
│ ├── http_client.py # HTTP 클라이언트 (재시도 지원)
│ └── message_sender.py # 다중 플랫폼 메시지 발송
│
├── services/ # 도메인 서비스
│ ├── weather/ # 기상 데이터 서비스
│ │ ├── forecast.py # 예보 API (초단기/단기/중기)
│ │ ├── asos.py # ASOS 종관기상 데이터
│ │ └── precipitation.py # 강수량 서비스
│ │
│ ├── analytics/ # 분석 서비스
│ │ ├── ga4.py # Google Analytics 4
│ │ ├── air_quality.py # 대기질 데이터
│ │ └── visitor_forecast.py # 방문객 예측
│ │
│ └── notification/ # 알림 서비스
│ ├── notion.py # Notion 웹훅 처리
│ └── mattermost.py # Mattermost 알림
│
├── apps/ # 웹 애플리케이션
│ ├── dashboard/ # 대시보드 API
│ ├── weather_api/ # 날씨 API 서버
│ └── webhook/ # 웹훅 수신 서버
│
├── .env.sample # 환경변수 샘플
├── requirements.txt # Python 의존성
└── docker-compose.yml # Docker 구성
🚀 시작하기
1. 환경 설정
# 저장소 클론
git clone https://git.siane.kr/firstgarden/fgtools.git
cd fgtools
# 가상환경 생성 및 활성화
python -m venv venv
source venv/bin/activate # Linux/Mac
# 또는
.\venv\Scripts\activate # Windows
# 의존성 설치
pip install -r requirements.txt
2. 설정 파일 생성
# .env 파일 생성
cp .env.sample .env
# .env 파일을 편집하여 실제 값 입력
# - 데이터베이스 접속 정보
# - API 키
# - 알림 설정 등
3. 애플리케이션 실행
# 대시보드 서버 실행
python -m apps.dashboard.app
# 날씨 API 서버 실행
python -m apps.weather_api.app
# 웹훅 수신 서버 실행
python -m apps.webhook.app
4. Docker로 실행
# Docker Compose로 모든 서비스 실행
docker-compose up -d
# 로그 확인
docker-compose logs -f
📖 API 문서
Dashboard API (포트 5000)
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/api/dashboard/health |
GET | 헬스 체크 |
/api/dashboard/stats |
GET | 통계 조회 |
/api/dashboard/weather/forecast |
GET | 날씨 예보 |
/api/dashboard/weather/precipitation |
GET | 강수량 예보 |
Weather API (포트 5001)
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/api/weather/health |
GET | 헬스 체크 |
/api/weather/precipitation |
GET | 시간별 강수량 |
/api/weather/forecast/ultra |
GET | 초단기예보 |
/api/weather/forecast/vilage |
GET | 단기예보 |
/api/weather/forecast/midterm |
GET | 중기예보 |
Webhook API (포트 5002)
| 엔드포인트 | 메서드 | 설명 |
|---|---|---|
/webhook/health |
GET | 헬스 체크 |
/webhook/notion |
POST | Notion 웹훅 수신 |
/webhook/notify |
POST | 알림 발송 |
⚙️ 환경변수 설명
주요 환경변수는 .env.sample 파일을 참고하세요.
| 변수명 | 설명 | 필수 |
|---|---|---|
DB_HOST |
데이터베이스 호스트 | ✅ |
DB_USER |
데이터베이스 사용자 | ✅ |
DB_PASSWORD |
데이터베이스 비밀번호 | ✅ |
DATA_API_SERVICE_KEY |
공공데이터포털 API 키 | ✅ |
MATTERMOST_URL |
Mattermost 서버 URL | ❌ |
NOTION_API_SECRET |
Notion API 시크릿 | ❌ |
🔧 개발
코드 스타일
- Python 3.10 이상
- Type hints 사용
- Docstring 필수
- Black 포매터 권장
테스트
# 테스트 실행
pytest tests/
# 커버리지 포함
pytest --cov=. tests/
📝 라이선스
Private - First Garden Internal Use Only
📞 연락처
기술 지원: dev@firstgarden.kr