# 리스크/알림 위젯 API 키 발급 가이드 🚨

## 📌 개요

리스크/알림 위젯은 **공공데이터포털 API**를 사용합니다:

1. ✅ **기상청 API** (날씨 특보) - **이미 설정됨!**
2. 🔧 **국토교통부 도로교통 API** (교통사고, 도로공사) - **신규 발급 필요**

---

## 🔑 1. 기상청 특보 API (이미 설정됨 ✅)

현재 `.env`에 설정된 키:
```bash
KMA_API_KEY=ogdXr2e9T4iHV69nvV-IwA
```

**사용 API:**
- 기상특보조회서비스 (기상청)
- URL: https://www.data.go.kr/data/15000415/openapi.do

**제공 정보:**
- ☁️ 대설특보
- 🌀 태풍특보
- 💨 강풍특보
- 🌊 호우특보

---

## 🚗 2. 국토교통부 도로교통 API (신규 발급)

### 2️⃣-1. 공공데이터포털 회원가입

```
👉 https://www.data.go.kr
```

1. 우측 상단 **회원가입** 클릭
2. 이메일 입력 및 인증
3. 약관 동의 후 가입 완료

---

### 2️⃣-2. API 활용신청

#### A. 실시간 교통사고 정보

```
👉 https://www.data.go.kr/data/15098913/openapi.do
```

**"실시간 교통사고 정보제공 서비스"** 페이지에서:

1. **활용신청** 버튼 클릭
2. 활용 목적: `기타`
3. 상세 기능 설명: `물류 대시보드 리스크 알림`
4. 신청 완료

#### B. 도로공사 및 통제 정보

```
👉 https://www.data.go.kr/data/15071004/openapi.do
```

**"도로공사 및 통제정보 제공 서비스"** 페이지에서:

1. **활용신청** 버튼 클릭
2. 활용 목적: `기타`
3. 상세 기능 설명: `물류 대시보드 리스크 알림`
4. 신청 완료

⚠️ **승인까지 약 2-3시간 소요** (즉시 승인되는 경우도 있음)

---

### 2️⃣-3. 인증키 확인

```
👉 https://www.data.go.kr/mypage/myPageOpenAPI.do
```

**마이페이지 > 오픈API > 인증키**에서:

1. **일반 인증키(Encoding)** 복사
2. 긴 문자열 전체를 복사하세요!

**예시:**
```
aBc1234dEf5678gHi9012jKl3456mNo7890pQr1234sTu5678vWx9012yZa3456bCd7890==
```

---

## ⚙️ 환경 변수 설정

### .env 파일 수정

```bash
cd /Users/leeheejin/ERP-node/backend-node
nano .env
```

### 다음 내용 **추가**:

```bash
# 기상청 API Hub 키 (기존 - 예특보 활용신청 완료 시 사용)
KMA_API_KEY=ogdXr2e9T4iHV69nvV-IwA

# 국토교통부 도로교통 API 키 (활용신청 완료 시 추가)
MOLIT_TRAFFIC_API_KEY=여기에_발급받은_교통사고_API_인증키_붙여넣기
MOLIT_ROADWORK_API_KEY=여기에_발급받은_도로공사_API_인증키_붙여넣기
```

⚠️ **주의사항:**
- API 활용신청이 **승인되기 전**에는 더미 데이터를 사용합니다
- **승인 후** API 키만 추가하면 **자동으로 실제 데이터로 전환**됩니다
- 승인 여부는 각 포털의 마이페이지에서 확인 가능합니다

### 저장 및 종료
- `Ctrl + O` (저장)
- `Enter` (확인)
- `Ctrl + X` (종료)

---

## 🔄 백엔드 재시작

```bash
docker restart pms-backend-mac
```

---

## 📊 사용 가능한 API 정보

### 1️⃣ 기상청 특보 (KMA_API_KEY)

**엔드포인트:**
```
GET /api/risk-alerts/weather
```

**응답 예시:**
```json
{
  "success": true,
  "data": [
    {
      "id": "weather-001",
      "type": "weather",
      "severity": "high",
      "title": "대설특보",
      "location": "강원 영동지역",
      "description": "시간당 2cm 이상 폭설 예상",
      "timestamp": "2024-10-14T10:00:00Z"
    }
  ]
}
```

---

### 2️⃣ 교통사고 (MOLIT_TRAFFIC_API_KEY)

**엔드포인트:**
```
GET /api/risk-alerts/accidents
```

**응답 예시:**
```json
{
  "success": true,
  "data": [
    {
      "id": "accident-001",
      "type": "accident",
      "severity": "high",
      "title": "교통사고 발생",
      "location": "경부고속도로 서울방향 189km",
      "description": "3중 추돌사고로 2차로 통제 중",
      "timestamp": "2024-10-14T10:00:00Z"
    }
  ]
}
```

---

### 3️⃣ 도로공사 (MOLIT_ROADWORK_API_KEY)

**엔드포인트:**
```
GET /api/risk-alerts/roadworks
```

**응답 예시:**
```json
{
  "success": true,
  "data": [
    {
      "id": "construction-001",
      "type": "construction",
      "severity": "medium",
      "title": "도로 공사",
      "location": "서울외곽순환 목동IC~화곡IC",
      "description": "야간 공사로 1차로 통제 (22:00~06:00)",
      "timestamp": "2024-10-14T10:00:00Z"
    }
  ]
}
```

---

## ✅ 테스트

### 1. API 키 발급 확인
```bash
curl "https://www.data.go.kr/mypage/myPageOpenAPI.do"
```

### 2. 백엔드 API 테스트
```bash
# 날씨 특보
curl "http://localhost:9771/api/risk-alerts/weather" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 교통사고
curl "http://localhost:9771/api/risk-alerts/accidents" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 도로공사
curl "http://localhost:9771/api/risk-alerts/roadworks" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

### 3. 대시보드에서 위젯 확인
1. `http://localhost:9771/admin/dashboard` 접속
2. 우측 사이드바 → **🚨 리스크 / 알림** 드래그
3. 실시간 정보 확인!

---

## 🔧 트러블슈팅

### 1. "API 키가 유효하지 않습니다" 오류

**원인**: API 키가 잘못되었거나 활성화되지 않음

**해결방법**:
1. 공공데이터포털에서 API 키 재확인
2. 신청 후 **승인 대기** 상태인지 확인 (2-3시간 소요)
3. `.env` 파일에 복사한 키가 정확한지 확인
4. 백엔드 재시작 (`docker restart pms-backend-mac`)

---

### 2. "서비스가 허용되지 않습니다" 오류

**원인**: 신청한 API와 요청한 서비스가 다름

**해결방법**:
1. 공공데이터포털 마이페이지에서 **신청한 서비스 목록** 확인
2. 필요한 서비스를 **모두 신청**했는지 확인
3. 승인 완료 상태인지 확인

---

### 3. 데이터가 표시되지 않음

**원인**: API 응답 형식 변경 또는 서비스 중단

**해결방법**:
1. 공공데이터포털 **공지사항** 확인
2. API 문서에서 **응답 형식** 확인
3. 백엔드 로그 확인 (`docker logs pms-backend-mac`)

---

## 💡 참고 링크

- 공공데이터포털: https://www.data.go.kr
- 기상청 Open API: https://data.kma.go.kr
- 국토교통부 Open API: https://www.its.go.kr
- API 활용 가이드: https://www.data.go.kr/tcs/dss/selectApiDataDetailView.do

---

**완료되면 브라우저 새로고침 (Cmd + R) 하세요!** 🚨✨