fgtools/README.md

===================================================================

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 시크릿	❌

🔑 API 키 발급 가이드

1. 공공데이터포털 API 키 (DATA_API_SERVICE_KEY, SERVICE_KEY)

기상청 API, 대기질 API 등 공공데이터 사용에 필요합니다.

1. 공공데이터포털 접속 및 회원가입
2. 로그인 후 필요한 API 검색:
   • 기상청_단기예보 조회서비스: 초단기/단기 예보
   • 기상청_중기예보 조회서비스: 중기 예보
   • 기상청_지상(종관, ASOS) 일자료 조회서비스: ASOS 데이터
   • 한국환경공단_에어코리아_대기오염정보: 대기질 정보
3. 각 API의 "활용신청" 클릭
4. 신청 승인 후 마이페이지 → 인증키 발급현황에서 일반 인코딩 키 복사
5. .env 파일의 DATA_API_SERVICE_KEY 및 SERVICE_KEY에 동일한 키 입력

2. Google Analytics 4 (GA4_*)

웹사이트 방문자 데이터 수집에 필요합니다.

GA4 Property ID 확인

1. Google Analytics 접속
2. 관리(⚙️) → 속성 설정 → 속성 ID 확인
3. .env 파일의 GA4_PROPERTY_ID에 입력

서비스 계정 생성 (API 접근용)

1. Google Cloud Console 접속
2. 새 프로젝트 생성 또는 기존 프로젝트 선택
3. API 및 서비스 → 라이브러리 → "Google Analytics Data API" 검색 후 사용 설정
4. API 및 서비스 → 사용자 인증 정보 → + 사용자 인증 정보 만들기 → 서비스 계정
5. 서비스 계정 생성 후 키 탭 → 키 추가 → 새 키 만들기 → JSON 선택
6. 다운로드된 JSON 파일을 conf/service-account-credentials.json으로 저장
7. .env 파일의 GA4_SERVICE_ACCOUNT_FILE에 경로 입력

GA4에 서비스 계정 권한 부여

1. Google Analytics → 관리(⚙️) → 속성 액세스 관리
2. + 클릭 → 사용자 추가
3. 서비스 계정 이메일 (예: xxx@project-id.iam.gserviceaccount.com) 입력
4. 뷰어 권한 부여 후 저장

3. Mattermost (MATTERMOST_*)

Mattermost 알림 발송에 필요합니다.

Bot 토큰 방식 (권장)

1. Mattermost 서버 → 통합 → 봇 계정
2. 봇 계정 추가 클릭
3. 봇 이름, 설명 입력 후 생성
4. 생성된 액세스 토큰을 MATTERMOST_TOKEN에 입력
5. 봇을 사용할 채널에 봇 추가
6. 채널 설정 → URL에서 채널 ID 확인 또는 API로 조회
7. MATTERMOST_CHANNEL_ID에 채널 ID 입력

웹훅 방식 (대안)

1. Mattermost 서버 → 통합 → 수신 웹훅
2. 수신 웹훅 추가 클릭
3. 채널 선택 후 생성
4. 생성된 웹훅 URL을 MATTERMOST_WEBHOOK_URL에 입력

4. Telegram Bot (TELEGRAM_*)

Telegram 알림 발송에 필요합니다.

1. Telegram에서 @BotFather 검색
2. /newbot 명령어 입력
3. 봇 이름과 사용자명 입력
4. 발급된 HTTP API 토큰을 TELEGRAM_BOT_TOKEN에 입력
5. 봇과 대화 시작 (또는 그룹에 봇 추가)
6. https://api.telegram.org/bot<TOKEN>/getUpdates 접속
7. 응답에서 chat.id 값을 TELEGRAM_CHAT_ID에 입력

5. Notion API (NOTION_*)

Notion 웹훅 처리에 필요합니다.

1. Notion Developers 접속
2. + New integration 클릭
3. 이름 입력, 워크스페이스 선택 후 생성
4. Internal Integration Secret을 NOTION_API_SECRET에 입력
5. Notion에서 연동할 페이지/DB 열기
6. ··· → 커넥션 → 생성한 통합 추가

6. Synology Chat (SYNOLOGY_*)

Synology Chat 알림 발송에 필요합니다.

1. Synology Chat 앱 실행
2. 채널 설정 → 통합 → 봇
3. + 추가 → 수신 웹훅 선택
4. 봇 이름 입력 후 생성
5. 생성된 웹훅 URL을 SYNOLOGY_CHAT_URL에 입력
6. URL에 포함된 토큰을 SYNOLOGY_CHAT_TOKEN에 입력

🔧 개발

코드 스타일

• Python 3.10 이상
• Type hints 사용
• Docstring 필수
• Black 포매터 권장

테스트

# 테스트 실행
pytest tests/

# 커버리지 포함
pytest --cov=. tests/

📝 라이선스

Private - First Garden Internal Use Only

📞 연락처

기술 지원: dev@firstgarden.kr