ERP-node/docs/날씨위젯_API키_설정가이드.md

날씨 위젯 API 키 설정 가이드 🌤️

📌 개요

날씨 위젯을 사용하려면 OpenWeatherMap API 키가 필요합니다.

---

🔑 OpenWeatherMap API 키 발급

1. 회원가입

• 사이트: https://openweathermap.org/api
• 무료 플랜 선택 (Free Plan)
• 하루 60회 무료 호출 가능 (충분함)

2. API 키 확인

• 로그인 후 API keys 메뉴로 이동
• 자동 생성된 API 키 복사
• 또는 Create Key 버튼으로 새 키 생성

---

⚙️ 환경 변수 설정

백엔드 .env 파일 수정

# backend-node/.env 파일 열기
cd /Users/leeheejin/ERP-node/backend-node
vi .env

다음 내용 추가:

# OpenWeatherMap API 키
OPENWEATHER_API_KEY=your_actual_api_key_here

예시:

OPENWEATHER_API_KEY=a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

---

🔄 백엔드 재시작

docker restart pms-backend-mac

또는

cd /Users/leeheejin/ERP-node/backend-node
npm run dev

---

✅ 테스트

1. 브라우저에서 대시보드 설계 도구 접속

http://localhost:9771/admin/dashboard

2. 날씨 위젯 드래그 앤 드롭

• 오른쪽 사이드바에서 ☁️ 날씨 위젯 찾기
• 캔버스로 드래그 앤 드롭
• 실시간 날씨 정보 표시 확인

3. API 직접 테스트

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분 (기본값)

---

🎨 커스터마이징

날씨 위젯 도시 변경

// DashboardDesigner.tsx에서 요소 생성 시
const newElement = {
  ...
  content: "Tokyo", // 원하는 도시명으로 변경
};

새로고침 주기 변경

// WeatherWidget.tsx에서
<WeatherWidget 
  city="Seoul" 
  refreshInterval={300000} // 5분 (밀리초)
/>

---

📝 참고 링크

• OpenWeatherMap API 문서: https://openweathermap.org/current
• 무료 API 키 발급: https://openweathermap.org/price
• 지원 도시 검색: https://openweathermap.org/find

---

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