From 91cd2ad7b2be601cedf7e0fbe223733c1b652ed9 Mon Sep 17 00:00:00 2001 From: KWON Date: Fri, 19 Dec 2025 10:56:38 +0900 Subject: [PATCH] =?UTF-8?q?=EC=9B=B9=ED=9B=85=20API=20=EC=82=AC=EC=9A=A9?= =?UTF-8?q?=EB=B2=95=EA=B3=BC=20=EC=9D=91=EB=8B=B5=20=EB=82=B4=EC=9A=A9=20?= =?UTF-8?q?=EC=88=98=EC=A0=95?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 211 +++++++++++++++++++++++++++++++++++++++++++++- app/api_server.py | 2 +- 2 files changed, 208 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index ca83ec6..2e2c81b 100644 --- a/README.md +++ b/README.md @@ -67,15 +67,19 @@ project-root/ - 10:00 ~ 22:00 영업시간 강수 데이터 HTML 테이블 생성 - SQLite DB에 저장 -### `webhook/webhook.py` ⭐ (개선) -- **Flask 기반 카카오 챇봇 응답 서버** +### `app/api_server.py` ⭐ (Flask 웹훅 서버) +- **Flask 기반 카카오 챗봇 응답 서버** +- **포트**: 5000 (docker-compose에서 5151로 노출) - **주요 기능**: - **당일 조회**: 09:00 캡처된 **실제 강우량 데이터** 응답 - **미래 날짜 조회**: 기상청 API 기반 **예보 강우량** 응답 - 예보 시 "변동될 수 있음" 경고 문구 표시 - 10mm 초과 시 이벤트 적용 안내 - 날씨 캡처 이미지 함께 전송 -- **통합**: 현재 `app/api_server.py`로 통합되어 동일 컨테이너에서 실행 +- **주요 엔드포인트**: + - `POST /webhook` - Kakaotalk 챗봇 웹훅 + - `GET /health` - 헬스 체크 + - `GET /data/` - 캡처 이미지 조회 ### `app/config.py` - 환경 변수 로드 (`.env` 또는 컨테이너 환경 변수) @@ -215,7 +219,206 @@ CREATE TABLE rainfall_summary ( --- -## 💬 카카오 챗봇 응답 예시 +## � 웹훅 API 사용법 + +### 웹훅 엔드포인트 + +**URL**: `https://webhook.firstgarden.co.kr/webhook` (또는 `DOMAIN/webhook`) + +**요청 방식**: `POST` + +### 1. 카카오 챗봇 연동 (자동) + +#### 요청 형식 (카카오로부터) +```json +{ + "userRequest": { + "text": "12월 19일 강우량은?", + "user": { + "id": "user_123", + "properties": {} + } + } +} +``` + +#### 응답 형식 (카카오에게) +```json +{ + "version": "2.0", + "template": { + "outputs": [ + { + "simpleText": { + "text": "📅 12월 19일(금)...(응답 내용)..." + } + }, + { + "simpleImage": { + "imageUrl": "https://webhook.firstgarden.co.kr/data/weather_capture_20251219.png", + "altText": "날씨 이미지" + } + } + ] + } +} +``` + +### 2. 직접 API 호출 (수동 테스트) + +#### cURL로 테스트 +```bash +# 당일 조회 +curl -X POST https://webhook.firstgarden.co.kr/webhook \ + -H "Content-Type: application/json" \ + -d '{"userRequest": {"text": "오늘 레이니데이 적용?"}}' + +# 특정 날짜 조회 +curl -X POST https://webhook.firstgarden.co.kr/webhook \ + -H "Content-Type: application/json" \ + -d '{"userRequest": {"text": "12월 20일 레이니데이"}}' + +# 헬스 체크 +curl https://webhook.firstgarden.co.kr/health +``` + +#### Python으로 테스트 +```python +import requests + +webhook_url = "https://webhook.firstgarden.co.kr/webhook" + +payload = { + "userRequest": { + "text": "내일 레이니데이?" + } +} + +response = requests.post(webhook_url, json=payload) +print(response.json()) +``` + +### 3. 응답 분석 규칙 + +챗봇은 사용자 입력에서 **날짜 패턴**을 자동으로 감지합니다: + +| 입력 예시 | 인식 날짜 | 데이터 출처 | +|---------|---------|----------| +| "오늘 강우량" | 당일 | SQLite (09:00 캡처) ✅ 실제값 | +| "12월 19일" | 2025-12-19 | 당일이면 SQLite, 미래면 API ⚠️ | +| "내일" | 내일 | API 예보 | +| "모레" | 모레 | API 예보 | +| "12월 25일" | 2025-12-25 | API 예보 | +| "날짜 지정 없음" | 당일 | SQLite (09:00 캡처) | + +### 4. 웹훅 응답 예시 + +#### 당일 실제 데이터 (SQLite) +``` +📅 12월 19일(금) +📊 실제 강수량 (09:00 캡처 기준) + +10:00 → ☀️ 강수 없음 +11:00 → ☀️ 강수 없음 +12:00 → 0.5mm +13:00 → 0.5mm +14:00 → 1.2mm +... +21:00 → 2.3mm + +💧 총 강수량: 5.2mm +❌ 이벤트 기준(10mm 초과)을 충족하지 않음 + +🔗 게시글 링크: https://firstgarden.co.kr/news/123 +``` + +#### 미래 날짜 예보 (API) +``` +📅 12월 20일(토) +📊 예보 강수량 (08:00 발표 기준) + +10:00 → 1.2mm +11:00 → 2.1mm +12:00 → 3.5mm +... +21:00 → 0.8mm + +💧 총 강수량: 12.5mm +✅ 레이니데이 적용 가능 + +⚠️ 이는 기상청 08:00 발표 예보입니다. 실제 이벤트 적용 기준은 당일 09:00 캡처 데이터입니다. +``` + +#### 이미지 첨부 (자동) +``` +응답에 자동으로 캡처된 날씨 이미지가 함께 전송됩니다. +``` + +### 5. 헬스 체크 + +```bash +# 엔드포인트 상태 확인 +curl https://webhook.firstgarden.co.kr/health + +# 응답 +{ + "status": "healthy", + "timestamp": "2025-12-19 10:30:45" +} +``` + +### 6. 이미지 직접 조회 + +```bash +# 캡처 이미지 조회 (브라우저에서도 열기 가능) +https://webhook.firstgarden.co.kr/data/weather_capture_20251219.png +``` + +--- +## 🎯 카카오 챗봇 설정 + +### 1. 카카오 디벨로퍼 콘솔에서 + +1. [카카오 디벨로퍼 콘솔](https://developers.kakao.com/) 접속 +2. 앱 생성 → "채팅" 선택 +3. **구성 > 채팅 설정** 이동 +4. **스킬 추가** 클릭 + - 스킬명: `레이니데이 이벤트` + - URL: `https://webhook.firstgarden.co.kr/webhook` + - HTTP 메서드: `POST` +5. **인텐트** 설정 (예시) + - "강우량은?", "날씨는?", "이벤트 조건?", "무료 입장?", "강수량", "강우" 등 + +### 2. 테스트 채널에서 확인 +- 카카오톡 채팅 → 챗봇에 메시지 전송 → 웹훅이 자동으로 응답 + +--- + +## 📊 게시글 등록 완료 알림 + +`gnu_autoupload.py`가 성공적으로 게시글을 등록할 때, Mattermost 알림이 발송됩니다: + +``` +✅ **게시글 등록 완료** + +📅 날짜: 2025-12-19 09:05:30 +📋 게시판: `news` +📝 제목: 2025-12-19 날씨정보 +📎 첨부파일: 2개 +🖼️ 캡처파일: `weather_capture_20251219.png` (1024.5KB) +🔗 게시글 링크: https://firstgarden.co.kr/news/123 +``` + +**포함 정보**: +- 등록 일시 +- 게시판 ID +- 게시글 제목 +- 첨부파일 개수 +- 캡처 이미지 정보 +- **게시글 직접 링크** (`URL/BOARD_ID/wr_id` 형식) + +--- +## �💬 카카오 챗봇 응답 예시 ### 당일 조회 (실제 데이터) ``` diff --git a/app/api_server.py b/app/api_server.py index aaaee9a..be3c1b9 100644 --- a/app/api_server.py +++ b/app/api_server.py @@ -220,7 +220,7 @@ def webhook(): # 이벤트 적용 여부 if rainfall_info['total'] > 10: - lines.append("✅ 식음료 2만원 이상 결제 시 무료입장권 제공") + lines.append("✅ 레이니데이 이벤트 기준(10mm 초과) 충족") else: lines.append("❌ 이벤트 기준(10mm 초과)을 충족하지 않음") else: