UBLE BACK-END REPOSITORY

프로젝트 소개

🏆LG 유플러스 유레카 SW 아카데미 2기 융합프로젝트 우수상🏅

🌐 서비스 바로가기 : https://www.u-ble.com

📊 관리자 페이지 바로가기 : https://admin.u-ble.com

💡 UBLE 이란? : https://www.u-ble.com/intro

• 프로젝트명 : UBLE
• 프로젝트 주제 : LG U+ 멤버십 제휴처 안내 지도 서비스
• 프로젝트 기간 : 2025.06.30 - 2025.08.08

🧑🏻‍💻 팀원 소개

👑 양여은	변하영	한현우
@Yyang-YE	@hayong39	@Eric-HAN-01
통계 관리 기능 인프라 관리 검색 기능 즐겨찾기 기능 로깅 기능	인프라 관리 소셜 로그인 기능 제휴처 목록 조회 기능 제휴처 매장 추천 기능 로깅 기능	데이터 전처리 피드백 등록 및 조회 기능 나의 위치 관리 기능 지도 반경 필터링 기능 매장 마커 클러스터링

💡 주요 기능

1. 회원 기능

• 카카오 소셜 로그인 및 회원가입
• 로그아웃 및 탈퇴
• 회원 정보 (멤버십 등급/바코드, 생년월일, 성별, 관심 카테고리) 수정
• 제휴처 즐겨찾기 등록/삭제/조회
• (통계) 가장 많이 사용한 카테고리 및 제휴처 브랜드
• (통계) 가장 많이 사용한 날짜, 요일, 시간
• (통계) 비슷한 유저 평균 대비 사용량
• (통계) 월별 사용량 내역

2. 제휴처 조회 기능

• 제휴처 전체 조회 및 필터링
• 제휴처 상세 조회
• 제휴처 이름/카테고리 기반 검색 및 자동완성

3. 지도 기반 매장 조회 기능

• 현재 또는 지정 위치 기반 근처 제휴처 매장 조회 (클러스터링 적용)
• 제휴처 매장 상세 조회
• 제휴처 이름, 매장 이름, 카테고리 기반 검색 및 자동완성
• 자주 가는 곳 등록/삭제

4. 로깅 기능

• 유저별 검색 기록, 제휴처 조회 기록, 매장 조회 기록을 로깅
• 콘솔 로그 모니터링 및 에러 로그 감지 알림 시스템
• 오래된 로그를 정기적으로 S3에 업로드하여 관리

5. 추천 기능

• 사용자 정보(생년월일, 성별, 관심 카테고리), 로그(클릭/검색), 위치 정보 활용하여 제휴처 매장 추천
• 추천 결과 캐싱

6. 관리자 기능

• (통계) 제휴처/카테고리 클릭 순위
• (통계) 상위 10개 제휴처 대상 관심사 변화 추이
• (통계) 일별 인기 검색어 순위
• (통계) 결과 미포함 검색어 순위
• (통계) 서울 지역구 이용 순위
• (통계) 제휴처/카테고리 이용 순위

7. 피드백 기능

• 서비스에 대한 피드백 등록/조회

📚 스터디

• 📆 이용 내역 초기화를 위한 스케줄러 적용기
• ⛓️ 제휴처 추천 알고리즘 개발
• ⛓️ Redis 캐싱을 통한 추천 결과 응답 속도 개선
• 🗺️ 매장 탐색 기능 성능 개선
• 🔎 Elasticsearch를 활용한 검색 기능 구현

💾 DB

📸 ERD : https://www.erdcloud.com/d/C9vcCB4kCHXRWWczR

1. PostgreSQL

2. Elasticsearch

1) 검색용 INDEX

2) 통계용 INDEX

🛠️ 시스템 아키텍처

---

⚙️ 사용 기술

BE

	사용 기술	역할
	SpringBoot (ver. 3.5.3)	Backend FrameWork
	Spring Security (ver.6.5.1) OAuth2 JWT (ver. 0.12.6)	인증/인가 시스템 구축 소셜 로그인 stateless 인증 구현
	Spring Data JPA (ver. 3.5.1)	데이터 접근 계층을 단순화 및 유지보수성 향상
	QueryDSL (ver. 5.1.0)	타입 안정성을 보장하는 동적 쿼리 작성
	Spring Batch (ver. 3.5.3)	대량 데이터의 정기적 처리 로직 구현
	Springdoc Swagger (ver. 2.2.25)	API 명세 문서 자동 생성
	Mockito (ver. 5.2.0) JUnit5 (ver. 5.12.2)	테스트 프레임워크
	FastAPI (ver. 0.116.1)	추천 시스템 서버 구축

DataBase

	사용 기술	역할
	PostgreSQL (ver. 15.13)	전체 데이터 저장
	PGVector	추천 시스템의 임베딩 기반 유사도 계산 시 vector 정보 저장
	PostGIS	특정 거리 내 매장 정보 조회 시 사용
	Redis	스케줄러 분산 락 적용 및 세션 캐싱을 통한 응답 속도 개선

Logging

	사용 기술	역할
	Filebeat	컨테이너 내 JSON 로그 파일을 실시간으로 수집하여 Logstash로 전송
	Logstash	Filebeat로부터 전달된 로그를 파싱, 변환, 필터링하여 Elasticsearch에 적재
	Elasticsearch	검색 엔진 / 인덱스 기반으로 로그를 저장, 빠른 검색 지원
	Kibana	검색 결과 시각화 및 모니터링 지원 / 로그 시각화를 통해 용이한 로그 분석 가능

Infra

	사용 기술	역할
	AWS EC2	서비스 배포 서버
	AWS RDS	관계형 DB 호스팅
	AWS Route53 AWS Loadbalancer AWS Certificate Manager	도메인 및 HTTPS 적용
	AWS S3	제휴처 로고 및 로깅 내역 저장
	AWS CloudWatch AWS Lambda	서버 모니터링 시스템 구축
	Docker (ver. 28.0.1)	개발 및 배포 환경의 컨테이너 기반 구성
	GitHub Actions	CI/CD 자동화

⚙️ 기술 선택 근거

선택 기술	대안	비교 설명
PostgreSQL + PostGIS	MySQL	PostgreSQL은 PostGIS 확장을 통해 반경 내 매장 검색, 거리 계산 기능을 지원합니다. MySQL도 공간 쿼리를 제공하지만 정확도와 기능이 제한적이라 PostgreSQL을 선택하였습니다.
pgvector	Elasticsearch Vector / Faiss	pgvector는 벡터와 RDB 데이터를 하나의 DB에서 통합 관리할 수 있습니다. ElasticSearch는 텍스트 검색에는 강점이 있지만 벡터 정확도 측면에서 불리하며, Faiss는 별도의 인프라 관리가 필요하여 pgvector를 선택하였습니다.
ELK (Elasticsearch, Logstash, Kibana)	AWS CloudWatch Agent	ELK는 오픈소스 기반이고, Logstash을 활용한 커스텀 필드 정규화와 FastAPI와 Spring의 로그 통합이 가능합니다. CloudWatch Agent는 AWS 서비스에 종속적이며 커스텀 처리 유연성이 낮아 ELK를 선택하였습니다.

⚖️ 컨벤션

• 🗂️ 패키지 구조 컨벤션
• ⚙️ GIT 컨벤션
• 💻 CODE 컨벤션

💻 Screens

화면	기능
	✨ 사용자 정보 및 관심사 기반 제휴처 추천 사용자의 나이, 성별, 관심 카테고리 등 프로필 정보를 분석하여 맞춤형 LGU+ 멤버십 제휴처를 추천합니다.
	🎁 LGU+ 멤버십 제휴처 혜택 정보 각 제휴처의 상세한 혜택 정보를 조회하고, 할인 및 이벤트 등의 최신 정보를 제공합니다.
	🔥 실시간 인기 멤버십 제휴처 정보 현재 시간 기준으로 사용자들이 가장 많이 방문한 인기 제휴처 정보를 실시간으로 제공합니다.
	🔍 자동 완성 기능을 탑재한 검색 기능 (제휴처) 제휴처 및 키워드 검색 시, 사용자 입력에 따라 자동 완성 및 추천 검색어를 실시간으로 제공합니다.
	🗺 지도 기반 제휴처 탐색 사용자의 현재 위치 주변에 존재하는 LGU+ 제휴처를 지도상에서 확인할 수 있으며, 매장 클릭 시 상세 정보가 제공됩니다.
	📌 사용자 지정 위치 저장 사용자가 자주 방문하거나 관심 있는 위치를 지정하여 빠르게 탐색할 수 있도록 저장할 수 있습니다.
	⚡ 자동 완성 기능을 탑재한 제휴처 매장 검색 기능 (지도) 제휴처 이름이나 키워드를 입력할 때, 관련 매장을 자동 완성 형태로 실시간으로 제안하여 빠르게 탐색할 수 있습니다.
	⭐ 제휴처 즐겨찾기 관심 있는 제휴처를 즐겨찾기로 저장하여 언제든지 쉽게 다시 확인할 수 있도록 지원합니다.
	⚙️ 사용자 정보 및 관심 카테고리 등 설정 지원(마이페이지) 사용자 프로필 정보, 관심 카테고리, 멤버십 등급, 바코드 번호 등 다양한 설정을 마이페이지에서 관리할 수 있도록 지원합니다.
	🎫 바코드 기반 멤버십 혜택 사용 사용자가 등록한 바코드 번호를 기반으로 실제 사용할 수 있는 멤버십 바코드를 자동 생성하여 제휴처에서 혜택을 받을 수 있도록 지원합니다.
	📊 유저 개인 및 전체 사용자 평균 기준 혜택 사용 통계 조회 개인의 혜택 사용량과 전체 사용자 평균 사용량을 비교하여 시각적으로 제공합니다.
	📝 혜택 사용 내역 조회 사용자가 실제 사용한 제휴처 혜택의 사용 내역과 날짜, 사용처, 할인율 등의 상세 정보를 조회할 수 있도록 제공합니다.