서울시 공공 데이터를 활용한 실시간 도시 정보 알림 시스템
Seoul Fit은 서울시의 다양한 공공 데이터를 실시간으로 모니터링하여 사용자에게 맞춤형 알림을 제공하는 오픈소스 프로젝트입니다.
- 🌡️ 날씨 기반 알림: 폭염, 한파, 대기질 악화 시 실시간 알림
- 🚲 따릉이 현황: 대여소별 자전거 부족/포화 상태 알림
- 🏛️ 문화행사 정보: 관심 있는 문화행사 및 공연 정보 알림
- 👥 인구 혼잡도: 지역별 실시간 혼잡도 정보 제공
- 📍 위치 기반 서비스: 사용자 위치 반경 2km 내 맞춤 정보
- ⚙️ 확장 가능한 아키텍처: 플러그인 형태의 새로운 기능 추가 지원
- 서울시민 및 방문객
- 실시간 도시 정보가 필요한 모든 사용자
- 공공 데이터 활용 개발자
- 오픈소스 기여자
- Java 21 이상
- Maven 3.8 이상
- 서울시 공공데이터 API 키
# 1. 저장소 클론
git clone https://github.com/seoul-fit/backend.git
cd seoul-fit
# 2. 의존성 설치
mvn clean install
# 3. 애플리케이션 실행
mvn spring-boot:run
# 4. 브라우저에서 확인
open http://localhost:8080/swagger-ui.htmlSeoul Fit의 모든 기능을 사용하려면 서울시 공공데이터 포탈에서 API 키를 발급받아야 합니다.
- 서울시 공공데이터 포탈 접속
- 우상단 "회원가입" 클릭하여 계정 생성
- 이메일 인증 완료 후 로그인
- 로그인 후 인증키 신청
- 일반 인증키 신청
- 실시간 지하철 인증키 신청
- "API 키 신청" 버튼 클릭
- 다음 정보 입력:
- 사용URL: 도메인 입력
- 관리용 대표 이메일: 대표자 이메일
- 활용용도: 서울시 도시 정보 알림 서비스
- 내용: 서울시 도시 정보 알림 서비스
위 내용 입력 후 약관 동의 후 인증키 신청 버튼 클릭시 인증키 발급 완료
- 승인 완료 후 "API 키 관리"에서 발급된 키 확인
- 키는 영문자와 숫자로 구성된 32자리 문자열
보안: 실제 운영에서는 환경변수를 사용하세요. 환경 설정 가이드 참조
src/main/resources/application.yml 파일 수정:
# 서울시 공공데이터 API 설정
seoul:
api:
key: ${SEOUL_API_KEY:your-seoul-api-key-here}
base-url: http://openapi.seoul.go.kr:8088
endpoints:
air-quality: /api/RealtimeCityAir/json/1/25/
bike-status: /api/bikeList/json/1/1000/
cultural-events: /api/culturalEventInfo/json/1/100/
population: /api/SPOP_LOCAL_RESD_DONG/json/1/100/- API 키 노출 금지: GitHub 등 공개 저장소에 API 키 업로드 금지
- 환경 변수 사용: 코드에 직접 하드코딩하지 말고 환경 변수 활용
- 키 순환: 정기적으로 API 키 재발급 권장
- .gitignore 확인:
application-local.yml등 로컬 설정 파일 제외
# application.yml 또는 환경 변수로 설정
export SEOUL_API_KEY=your-seoul-api-key
export JWT_SECRET=your-jwt-secret애플리케이션 실행 후 다음 URL에서 API 문서를 확인할 수 있습니다:
- Swagger UI: http://localhost:8080/swagger-ui.html
- API Docs: http://localhost:8080/api-docs
# 사용자 관심사 관리
GET /api/users/interests
PUT /api/users/interests
# 알림 히스토리
GET /api/notifications
POST /api/notifications
PATCH /api/notifications/{id}/read
# OAuth 인증
POST /api/auth/oauth/signup
POST /api/auth/oauth/login┌─────────────────────────────────────────────────────────────┐
│ Presentation Layer │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Controllers │ │ Event Listeners│ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Application Layer │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Use Cases │ │ Services │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Domain Layer │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Entities │ │ Domain Events │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────┐
│ Infrastructure Layer │
│ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Repositories │ │ External APIs │ │
│ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────┘
- Hexagonal Architecture: 도메인 중심 설계
- Strategy Pattern: 확장 가능한 트리거 시스템
- Observer Pattern: 이벤트 기반 알림 처리
- Factory Pattern: 유연한 객체 생성
- Template Method Pattern: 공통 로직 재사용
- Java 21: 최신 LTS 버전
- Spring Boot 3.x: 웹 애플리케이션 프레임워크
- Spring Security: 인증 및 보안
- Spring Data JPA: 데이터 액세스
- H2 Database: 개발용 인메모리 데이터베이스
- 서울시 실시간 도시 데이터 API
- 따릉이 현황 API
- 대기환경 현황 API
- 문화행사 정보 API
- Maven: 빌드 도구
- Swagger/OpenAPI: API 문서화
- Lombok: 코드 간소화
- Jackson: JSON 처리
- WebClient: 비동기 HTTP 클라이언트
UrbanPing은 오픈소스 프로젝트입니다. 여러분의 기여를 환영합니다!
- 이슈 확인: GitHub Issues에서 해결할 문제를 찾아보세요
- 포크 & 클론: 저장소를 포크하고 로컬에 클론하세요
- 브랜치 생성:
git checkout -b feature/your-feature-name - 개발 & 테스트: 기능을 개발하고 테스트를 작성하세요
- 커밋 & 푸시: 변경사항을 커밋하고 푸시하세요
- Pull Request: PR을 생성하고 리뷰를 요청하세요
- 🆕 새로운 트리거 전략 추가: 강수량, 지하철 혼잡도 등
- 🔧 설정 개선: 새로운 임계값이나 옵션 추가
- 📝 문서 개선: README, 주석, 가이드 문서 개선
- 🧪 테스트 추가: 기존 기능의 테스트 커버리지 향상
- 🐛 버그 수정: 발견된 버그 수정
자세한 내용은 기여 가이드를 참조하세요.
- OAuth 회원가입 시스템
- 사용자 관심사 관리
- 알림 히스토리 시스템
- 트리거 시스템 (온도, 대기질, 따릉이)
- 공공 데이터 API 연동
- 이벤트 기반 알림 처리
- 실시간 푸시 알림
- 위치 기반 서비스 고도화
- 관리자 대시보드
- 모바일 앱 연동
애플리케이션 실행 후 다음 엔드포인트에서 시스템 상태를 확인할 수 있습니다:
- Health Check: http://localhost:8080/actuator/health
- Metrics: http://localhost:8080/actuator/metrics
- Scheduled Tasks: http://localhost:8080/actuator/scheduledtasks
- JWT 기반 인증
- OAuth 2.0 소셜 로그인
- API 요청 제한
- 입력 데이터 검증
중요: 기존 코드에 민감정보가 노출되어 있었습니다. 보안 해결 가이드를 참조하여 즉시 조치하세요.
보안 이슈 발견 시 보안 정책을 참조하여 신고해주세요.
이 프로젝트는 MIT 라이선스 하에 배포됩니다.
MIT License
Copyright (c) 2025 Seoul Fit
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
이 프로젝트는 서울시 공공데이터 포탈의 데이터를 활용합니다:
- 데이터 제공: 서울특별시
- 출처: 서울시 공공데이터 포탈
- 이용 조건: 서울시 공공데이터 포탈 이용약관 준수
- 출처 표시: "서울특별시에서 제공하는 데이터를 활용하였습니다"
사용 데이터:
- 실시간 대기환경 현황 (대기질 알림)
- 서울자전거 따릉이 실시간 대여정보 (따릉이 현황 알림)
- 문화행사 정보 (문화행사 알림)
- 문화공간 정보 (문화공간 알림)
- 문화행사예약 정보 (문화행사예약 알림)
- 공공도서관 정보 (공공도서관 알림)
- 무더위쉼터 정보 (무더위 쉼터 알림)
- 실시간 인구 데이터 (혼잡도 알림)
자세한 데이터 이용 조건은 데이터 출처 문서를 참조하세요.
중요: 이 프로젝트를 사용할 때는 서울시 공공데이터 포탈의 이용약관을 반드시 준수해야 합니다.
- OAuth 설정 가이드 - 카카오 OAuth 연동 설정
- 보안 정책 - 보안 및 데이터 정책
- cURL 예제 - 명령줄에서 API 호출 예제
- Postman 컬렉션 - API 테스트용 Postman 컬렉션
- 서울시: 공공 데이터 제공
- Spring Team: 훌륭한 프레임워크 제공
- 오픈소스 커뮤니티: 지속적인 기여와 피드백
- GitHub Issues: 이슈 등록
- GitHub Discussions: 토론 참여
- Email: [email protected]
함께 만들어가는 스마트 시티! 🌆
Seoul Fit과 함께 더 나은 도시 생활을 경험하세요.