Merge conflict 해결 - 로컬 변경사항 유지 (날씨 API)
This commit is contained in:
leeheejin
288
docs/기상청_API키_발급가이드.md
Normal file
288
docs/기상청_API키_발급가이드.md
Normal file
@@ -0,0 +1,288 @@
|
||||
# 기상청 Open API 키 발급 가이드 🇰🇷
|
||||
|
||||
## 📌 개요
|
||||
|
||||
날씨 위젯은 **공공데이터포털 기상청 API**를 사용합니다.
|
||||
- 🌐 **플랫폼**: https://www.data.go.kr
|
||||
- ✅ **완전 무료**
|
||||
- ✅ **일일 트래픽 제한 없음**
|
||||
- ✅ **실시간 한국 날씨 정보**
|
||||
|
||||
> **참고**: 기상청 API Hub (apihub.kma.go.kr)는 현재 접근 제한이 있어,
|
||||
> 공공데이터포털의 기상청 API를 사용합니다.
|
||||
|
||||
---
|
||||
|
||||
## 🔑 API 키 발급 (5분 소요)
|
||||
|
||||
### 1️⃣ 공공데이터포털 회원가입
|
||||
|
||||
```
|
||||
👉 https://www.data.go.kr
|
||||
```
|
||||
|
||||
1. 우측 상단 **회원가입** 클릭
|
||||
2. 이메일 입력 및 인증
|
||||
3. 약관 동의 후 가입 완료
|
||||
|
||||
---
|
||||
|
||||
### 2️⃣ API 활용신청
|
||||
|
||||
```
|
||||
👉 https://www.data.go.kr/data/15084084/openapi.do
|
||||
```
|
||||
|
||||
**"기상청_단기예보 ((구)_동네예보) 조회서비스"** 페이지에서:
|
||||
|
||||
1. **활용신청** 버튼 클릭
|
||||
2. 활용 목적: `기타`
|
||||
3. 상세 기능 설명: `대시보드 날씨 위젯`
|
||||
4. 신청 완료
|
||||
|
||||
⚠️ **승인까지 약 2-3시간 소요** (즉시 승인되는 경우도 있음)
|
||||
|
||||
---
|
||||
|
||||
### 3️⃣ 인증키 확인
|
||||
|
||||
```
|
||||
👉 https://www.data.go.kr/mypage/myPageOpenAPI.do
|
||||
```
|
||||
|
||||
**마이페이지 > 오픈API > 인증키**에서:
|
||||
|
||||
1. **일반 인증키(Encoding)** 복사
|
||||
2. 긴 문자열 전체를 복사하세요!
|
||||
|
||||
**예시:**
|
||||
```
|
||||
aBc1234dEf5678gHi9012jKl3456mNo7890pQr1234sTu5678vWx9012yZa3456bCd7890==
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 환경 변수 설정
|
||||
|
||||
### 방법 1: .env 파일 생성 (추천)
|
||||
|
||||
```bash
|
||||
# 1. .env 파일 생성
|
||||
cd /Users/leeheejin/ERP-node/backend-node
|
||||
nano .env
|
||||
```
|
||||
|
||||
### 2. 다음 내용 입력:
|
||||
|
||||
```bash
|
||||
# Node 환경
|
||||
NODE_ENV=development
|
||||
|
||||
# 서버 포트
|
||||
PORT=8080
|
||||
|
||||
# 기상청 API 키 (발급받은 인증키를 여기에 붙여넣기)
|
||||
KMA_API_KEY=여기에_발급받은_인증키를_붙여넣으세요
|
||||
```
|
||||
|
||||
### 3. 저장 및 종료
|
||||
- `Ctrl + O` (저장)
|
||||
- `Enter` (확인)
|
||||
- `Ctrl + X` (종료)
|
||||
|
||||
---
|
||||
|
||||
### 방법 2: 명령어로 추가
|
||||
|
||||
```bash
|
||||
cd /Users/leeheejin/ERP-node/backend-node
|
||||
|
||||
echo "KMA_API_KEY=여기에_발급받은_인증키_붙여넣기" >> .env
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 백엔드 재시작
|
||||
|
||||
```bash
|
||||
docker restart pms-backend-mac
|
||||
```
|
||||
|
||||
또는
|
||||
|
||||
```bash
|
||||
cd /Users/leeheejin/ERP-node/backend-node
|
||||
npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ 테스트
|
||||
|
||||
### 1. 브라우저에서 대시보드 접속
|
||||
```
|
||||
http://localhost:9771/admin/dashboard
|
||||
```
|
||||
|
||||
### 2. 날씨 위젯 드래그 앤 드롭
|
||||
- 오른쪽 사이드바에서 **☁️ 날씨 위젯** 드래그
|
||||
- 캔버스에 드롭
|
||||
- **실시간 한국 날씨** 표시 확인! 🎉
|
||||
|
||||
### 3. API 직접 테스트
|
||||
```bash
|
||||
curl "http://localhost:9771/api/open-api/weather?city=서울" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
```
|
||||
|
||||
**응답 예시:**
|
||||
```json
|
||||
{
|
||||
"success": true,
|
||||
"data": {
|
||||
"city": "서울",
|
||||
"country": "KR",
|
||||
"temperature": 18,
|
||||
"feelsLike": 16,
|
||||
"humidity": 65,
|
||||
"pressure": 1013,
|
||||
"weatherMain": "Clear",
|
||||
"weatherDescription": "맑음",
|
||||
"weatherIcon": "01d",
|
||||
"windSpeed": 3.5,
|
||||
"clouds": 10,
|
||||
"timestamp": "2025-10-13T07:30:00.000Z"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌍 지원 지역
|
||||
|
||||
### 한국 주요 도시
|
||||
- **서울** (Seoul)
|
||||
- **부산** (Busan)
|
||||
- **인천** (Incheon)
|
||||
- **대구** (Daegu)
|
||||
- **광주** (Gwangju)
|
||||
- **대전** (Daejeon)
|
||||
- **울산** (Ulsan)
|
||||
- **세종** (Sejong)
|
||||
- **수원** (Suwon)
|
||||
- **춘천** (Chuncheon)
|
||||
- **제주** (Jeju)
|
||||
|
||||
**영문/한글 모두 지원!**
|
||||
|
||||
---
|
||||
|
||||
## 🔧 트러블슈팅
|
||||
|
||||
### 1. "기상청 API 키가 설정되지 않았습니다" 오류
|
||||
|
||||
**원인**: `.env` 파일에 API 키가 없음
|
||||
|
||||
**해결방법**:
|
||||
```bash
|
||||
# .env 파일 확인
|
||||
cat /Users/leeheejin/ERP-node/backend-node/.env
|
||||
|
||||
# KMA_API_KEY가 있는지 확인
|
||||
# 없으면 위 "환경 변수 설정" 참고하여 추가
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 2. "기상청 API 오류: SERVICE_KEY_IS_NOT_REGISTERED_ERROR" 오류
|
||||
|
||||
**원인**: API 키가 아직 승인되지 않았거나 잘못된 키
|
||||
|
||||
**해결방법**:
|
||||
1. 공공데이터포털에서 승인 상태 확인
|
||||
2. **일반 인증키(Encoding)** 복사했는지 확인 (Decoding 아님!)
|
||||
3. 키 앞뒤에 공백 없는지 확인
|
||||
4. 백엔드 재시작
|
||||
|
||||
---
|
||||
|
||||
### 3. "지원하지 않는 지역입니다" 오류
|
||||
|
||||
**원인**: 등록되지 않은 도시명
|
||||
|
||||
**해결방법**:
|
||||
- 위 "지원 지역" 목록 참고
|
||||
- 영문 또는 한글 정확히 입력
|
||||
- 예: `서울`, `Seoul`, `부산`, `Busan`
|
||||
|
||||
---
|
||||
|
||||
### 4. API 키 재발급
|
||||
|
||||
공공데이터포털에서:
|
||||
1. **마이페이지 > 오픈API**
|
||||
2. 해당 API 찾기
|
||||
3. **상세보기 > 인증키 재발급**
|
||||
|
||||
---
|
||||
|
||||
## 📊 API 사용 현황 확인
|
||||
|
||||
```
|
||||
👉 https://www.data.go.kr/mypage/myPageOpenAPIStatView.do
|
||||
```
|
||||
|
||||
- 일일 트래픽: **무제한** ✅
|
||||
- 서비스 상태: 정상
|
||||
- 응답 속도: 평균 1초 이내
|
||||
|
||||
---
|
||||
|
||||
## 🎨 위젯 커스터마이징
|
||||
|
||||
### 기본 도시 변경
|
||||
|
||||
```typescript
|
||||
// DashboardDesigner.tsx
|
||||
case 'weather': return '부산'; // 원하는 도시로 변경
|
||||
```
|
||||
|
||||
### 새로고침 주기 변경
|
||||
|
||||
```typescript
|
||||
// WeatherWidget.tsx
|
||||
<WeatherWidget
|
||||
city="서울"
|
||||
refreshInterval={300000} // 5분 (밀리초)
|
||||
/>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 참고 링크
|
||||
|
||||
- **공공데이터포털**: https://www.data.go.kr
|
||||
- **기상청 API 신청**: https://www.data.go.kr/data/15084084/openapi.do
|
||||
- **마이페이지(인증키)**: https://www.data.go.kr/mypage/myPageOpenAPI.do
|
||||
- **기상청 공식 사이트**: https://www.weather.go.kr
|
||||
|
||||
---
|
||||
|
||||
## 💡 FAQ
|
||||
|
||||
**Q: 승인이 언제 되나요?**
|
||||
A: 보통 **2-3시간**, 빠르면 즉시 승인됩니다.
|
||||
|
||||
**Q: 유료인가요?**
|
||||
A: **완전 무료**입니다! 트래픽 제한도 없어요.
|
||||
|
||||
**Q: 해외 도시도 되나요?**
|
||||
A: 아니요, 기상청 API는 **한국 지역만** 지원합니다.
|
||||
|
||||
**Q: 실시간인가요?**
|
||||
A: 실시간 관측 데이터를 제공합니다 (매시간 업데이트).
|
||||
|
||||
---
|
||||
|
||||
✅ **설정 완료 후 대시보드에서 실시간 한국 날씨를 확인하세요!** 🌤️
|
||||
|
||||
168
docs/날씨위젯_API키_설정가이드.md
Normal file
168
docs/날씨위젯_API키_설정가이드.md
Normal file
@@ -0,0 +1,168 @@
|
||||
# 날씨 위젯 API 키 설정 가이드 🌤️
|
||||
|
||||
## 📌 개요
|
||||
|
||||
날씨 위젯을 사용하려면 **OpenWeatherMap API 키**가 필요합니다.
|
||||
|
||||
---
|
||||
|
||||
## 🔑 OpenWeatherMap API 키 발급
|
||||
|
||||
### 1. 회원가입
|
||||
- 사이트: https://openweathermap.org/api
|
||||
- 무료 플랜 선택 (Free Plan)
|
||||
- 하루 **60회** 무료 호출 가능 (충분함)
|
||||
|
||||
### 2. API 키 확인
|
||||
- 로그인 후 **API keys** 메뉴로 이동
|
||||
- 자동 생성된 API 키 복사
|
||||
- 또는 **Create Key** 버튼으로 새 키 생성
|
||||
|
||||
---
|
||||
|
||||
## ⚙️ 환경 변수 설정
|
||||
|
||||
### 백엔드 `.env` 파일 수정
|
||||
|
||||
```bash
|
||||
# backend-node/.env 파일 열기
|
||||
cd /Users/leeheejin/ERP-node/backend-node
|
||||
vi .env
|
||||
```
|
||||
|
||||
### 다음 내용 추가:
|
||||
|
||||
```bash
|
||||
# OpenWeatherMap API 키
|
||||
OPENWEATHER_API_KEY=your_actual_api_key_here
|
||||
```
|
||||
|
||||
**예시:**
|
||||
```bash
|
||||
OPENWEATHER_API_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🔄 백엔드 재시작
|
||||
|
||||
```bash
|
||||
docker restart pms-backend-mac
|
||||
```
|
||||
|
||||
또는
|
||||
|
||||
```bash
|
||||
cd /Users/leeheejin/ERP-node/backend-node
|
||||
npm run dev
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## ✅ 테스트
|
||||
|
||||
### 1. 브라우저에서 대시보드 설계 도구 접속
|
||||
```
|
||||
http://localhost:9771/admin/dashboard
|
||||
```
|
||||
|
||||
### 2. 날씨 위젯 드래그 앤 드롭
|
||||
- 오른쪽 사이드바에서 **☁️ 날씨 위젯** 찾기
|
||||
- 캔버스로 드래그 앤 드롭
|
||||
- 실시간 날씨 정보 표시 확인
|
||||
|
||||
### 3. API 직접 테스트
|
||||
```bash
|
||||
curl "http://localhost:9771/api/open-api/weather?city=Seoul" \
|
||||
-H "Authorization: Bearer YOUR_TOKEN"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🌍 지원 도시
|
||||
|
||||
### 한국 주요 도시
|
||||
- Seoul (서울)
|
||||
- Busan (부산)
|
||||
- Incheon (인천)
|
||||
- Daegu (대구)
|
||||
- Gwangju (광주)
|
||||
- Daejeon (대전)
|
||||
|
||||
### 해외 도시
|
||||
- Tokyo
|
||||
- New York
|
||||
- London
|
||||
- Paris
|
||||
- Singapore
|
||||
|
||||
---
|
||||
|
||||
## 🔧 트러블슈팅
|
||||
|
||||
### 1. "날씨 API 키가 유효하지 않습니다" 오류
|
||||
**원인**: API 키가 잘못되었거나 활성화되지 않음
|
||||
|
||||
**해결방법**:
|
||||
1. OpenWeatherMap 사이트에서 API 키 재확인
|
||||
2. 새로 발급한 키는 **2시간 후** 활성화됨 (대기 필요)
|
||||
3. `.env` 파일에 복사한 키가 정확한지 확인
|
||||
4. 백엔드 재시작
|
||||
|
||||
### 2. "도시를 찾을 수 없습니다" 오류
|
||||
**원인**: 도시명 철자 오류 또는 지원하지 않는 도시
|
||||
|
||||
**해결방법**:
|
||||
- 영문 도시명 사용 (Seoul, Busan 등)
|
||||
- OpenWeatherMap 도시 목록 확인: https://openweathermap.org/find
|
||||
|
||||
### 3. "CORS 오류" 발생
|
||||
**원인**: 프론트엔드-백엔드 통신 문제
|
||||
|
||||
**해결방법**:
|
||||
- 백엔드가 정상 실행 중인지 확인 (`docker ps`)
|
||||
- `backend-node/src/app.ts`의 CORS 설정 확인
|
||||
- 브라우저 개발자 도구에서 요청 URL 확인
|
||||
|
||||
---
|
||||
|
||||
## 📊 API 사용량 확인
|
||||
|
||||
- OpenWeatherMap 대시보드: https://home.openweathermap.org/api_keys
|
||||
- 무료 플랜: 하루 60회 (1분당 1회)
|
||||
- 위젯 새로고침 주기: **10분** (기본값)
|
||||
|
||||
---
|
||||
|
||||
## 🎨 커스터마이징
|
||||
|
||||
### 날씨 위젯 도시 변경
|
||||
```typescript
|
||||
// DashboardDesigner.tsx에서 요소 생성 시
|
||||
const newElement = {
|
||||
...
|
||||
content: "Tokyo", // 원하는 도시명으로 변경
|
||||
};
|
||||
```
|
||||
|
||||
### 새로고침 주기 변경
|
||||
```typescript
|
||||
// WeatherWidget.tsx에서
|
||||
<WeatherWidget
|
||||
city="Seoul"
|
||||
refreshInterval={300000} // 5분 (밀리초)
|
||||
/>
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📝 참고 링크
|
||||
|
||||
- OpenWeatherMap API 문서: https://openweathermap.org/current
|
||||
- 무료 API 키 발급: https://openweathermap.org/price
|
||||
- 지원 도시 검색: https://openweathermap.org/find
|
||||
|
||||
---
|
||||
|
||||
✅ **설정 완료 후 대시보드에서 실시간 날씨를 확인하세요!**
|
||||
|
||||
Reference in New Issue
Block a user