ERP-node/docs/기상청_API키_발급가이드.md

# 기상청 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: 실시간 관측 데이터를 제공합니다 (매시간 업데이트).

---

✅ **설정 완료 후 대시보드에서 실시간 한국 날씨를 확인하세요!** 🌤️