feat: initial commit - unified FGTools from static, weather, mattermost-noti

README.md

@@ -0,0 +1,176 @@
+# ===================================================================
+# 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. 환경 설정
+
+```bash
+# 저장소 클론
+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. 설정 파일 생성
+
+```bash
+# .env 파일 생성
+cp .env.sample .env
+
+# .env 파일을 편집하여 실제 값 입력
+# - 데이터베이스 접속 정보
+# - API 키
+# - 알림 설정 등
+```
+
+### 3. 애플리케이션 실행
+
+```bash
+# 대시보드 서버 실행
+python -m apps.dashboard.app
+
+# 날씨 API 서버 실행
+python -m apps.weather_api.app
+
+# 웹훅 수신 서버 실행
+python -m apps.webhook.app
+```
+
+### 4. Docker로 실행
+
+```bash
+# 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 포매터 권장
+
+### 테스트
+
+```bash
+# 테스트 실행
+pytest tests/
+
+# 커버리지 포함
+pytest --cov=. tests/
+```
+
+## 📝 라이선스
+
+Private - First Garden Internal Use Only
+
+## 📞 연락처
+
+기술 지원: dev@firstgarden.kr