본 프로젝트는 LG U+ 연계 팝업 스토어 중심의 지역 기반 이벤트에 사용자가 참여하며, 인근 제휴처(소상공인 포함)를 추천받고 이벤트 매장 결제를 통해 스탬프를 적립하는 참여형 혜택 플랫폼입니다. 사용자는 지도 기반으로 주변 제휴처의 멤버십 혜택 및 할인 정보를 확인하며, 이벤트 정보를 통해 멤버십 바코드 제출 및 결제 인증을 통해 참여하는 것을 목표로 합니다.
- 🗺️ 위치 기반 이벤트 참여: LG U+ 팝업 스토어와 연계한 지역 맞춤형 이벤트 제공
- 🏆 스탬프 적립 시스템: 방문 인증을 통한 스탬프 적립 및 보상 시스템
- 🤝 소상공인 상생: 지역 소상공인 제휴처 추천을 통한 상생 생태계 구축
- 📱 실시간 위치 알림: 제휴처 진입 시 자동 팝업을 통한 이벤트 안내
- 💳 통합 멤버십 관리: 멤버십 바코드 제출 및 결제 인증을 통한 간편한 혜택 이용
Unear는 LG U+ 연계 팝업 스토어를 중심으로 한 지역 기반 참여형 혜택 플랫폼입니다. 사용자의 위치 정보를 활용하여 주변 제휴처의 이벤트 정보를 제공하고, 방문 인증을 통한 스탬프 적립 시스템으로 지역 상권 활성화를 도모합니다.
| 기능 | 설명 |
|---|---|
| 🏪 LG U+ 팝업 스토어 연계 | LG U+ 팝업 스토어 중심의 지역 이벤트 참여 |
| 📍 위치 기반 알림 | 제휴처 진입 시 자동 팝업을 통한 실시간 이벤트 안내 |
| ⭐ 스탬프 적립 시스템 | 방문 인증 및 결제 인증을 통한 스탬프 적립 및 보상 |
| 🏬 소상공인 제휴 | 지역 소상공인 매장 추천 및 상생 혜택 제공 |
| 📱 멤버십 바코드 통합 | 간편한 바코드 제출을 통한 혜택 이용 |
| 🔐 소셜 로그인 | Google, Kakao, Naver 간편 로그인 지원 |
| 서비스 | 링크 |
|---|---|
| 🖥️ Frontend | 프론트엔드 저장소 |
| 🔧 Backend | 백엔드 저장소 |
| 📝 Documentation | 프로젝트 노션 |
| 🎨 Design | Figma 디자인 |
| 📷 Video Link | 시연영상 링크 |
📂 프로젝트 구조 보기
unear-frontend/
├── 📁 public/ # 정적 파일
│ ├── 📁 images/ # 이미지 파일
│ └── 📁 icons/ # 아이콘 파일
├── 📁 src/
│ ├── 📁 apis/ # API 호출 관련 파일
│ │ ├── ⚙️ axiosInstance.ts # Axios 인스턴스 설정
│ │ ├── 🔐 auth.ts # 인증 관련 API
│ │ ├── 🎫 getUserCoupons.ts # 쿠폰 관련 API
│ │ ├── 📍 getPlaces.ts # 장소 관련 API
│ │ └── 📄 ... # 기타 API 파일들
│ ├── 📁 assets/ # 정적 자원
│ │ ├── 📁 common/ # 공통 아이콘/이미지
│ │ ├── 📁 main/ # 메인 페이지 자원
│ │ ├── 📁 map/ # 지도 관련 자원
│ │ ├── 📁 story/ # 스토리 관련 자원
│ │ └── 📁 my/ # 마이페이지 자원
│ ├── 📁 components/ # 재사용 가능한 컴포넌트
│ │ ├── 📁 common/ # 공통 컴포넌트
│ │ │ ├── 🔘 ActionButton.tsx # 액션 버튼
│ │ │ ├── 📱 BottomNavigator.tsx # 하단 네비게이션
│ │ │ ├── 🎫 CouponCard.tsx # 쿠폰 카드
│ │ │ ├── 📋 Header.tsx # 헤더
│ │ │ └── 📄 ... # 기타 공통 컴포넌트들
│ │ ├── 📁 junior/ # 주니어 기능 컴포넌트
│ │ ├── 📁 map/ # 지도 기능 컴포넌트
│ │ ├── 📁 my/ # 마이페이지 컴포넌트
│ │ └── 📁 story/ # 스토리 컴포넌트
│ ├── 📁 hooks/ # 커스텀 훅
│ │ ├── 📁 my/ # 마이페이지 관련 훅
│ │ ├── 🔔 useNotifications.ts # 알림 관련 훅
│ │ └── ⬆️ useScrollToTop.ts # 스크롤 제어 훅
│ ├── 📁 pages/ # 페이지 컴포넌트
│ │ ├── 📁 auth/ # 인증 관련 페이지
│ │ ├── 🏠 MainPage.tsx # 메인 페이지
│ │ ├── 🗺️ MapPage.tsx # 지도 페이지
│ │ ├── 📖 StoryPage.tsx # 스토리 페이지
│ │ ├── 🎯 JuniorPage.tsx # 주니어 페이지
│ │ └── 👤 MyPage.tsx # 마이페이지
│ ├── 📁 providers/ # Context Provider
│ │ └── 🔐 AuthProvider.tsx # 인증 Provider
│ ├── 📁 router/ # 라우팅 설정
│ │ └── 🛣️ index.tsx # 라우터 설정
│ ├── 📁 store/ # 상태 관리 (Zustand)
│ │ └── 🔐 auth.ts # 인증 상태 관리
│ ├── 📁 types/ # TypeScript 타입 정의
│ │ ├── 🎫 coupon.ts # 쿠폰 타입
│ │ ├── 🗺️ map.ts # 지도 타입
│ │ ├── 🏪 store.ts # 매장 타입
│ │ └── 📄 ... # 기타 타입들
│ ├── 📁 utils/ # 유틸리티 함수
│ │ ├── 📅 formatDate.ts # 날짜 포맷팅
│ │ ├── 🍞 toast.ts # 토스트 알림
│ │ └── 🎫 tokenUtils.ts # 토큰 관련 유틸
│ ├── 🎨 index.css # 전역 스타일
│ ├── 🚀 main.tsx # 애플리케이션 진입점
│ └── 📱 default.tsx # 기본 레이아웃
├── 🔧 .env # 환경 변수
├── 📦 package.json # 의존성 관리
├── 🎨 tailwind.config.js # Tailwind CSS 설정
├── ⚙️ tsconfig.json # TypeScript 설정
├── ⚡ vite.config.ts # Vite 빌드 도구 설정
└── 📖 README.md # 프로젝트 문서
| 단계 | 명령어 / 파일 | 설명 |
|---|---|---|
| 1️⃣ Node.js 버전 확인 | node --version |
Node.js 18.0.0 이상 필요 |
| 2️⃣ 의존성 설치 | npm install |
프로젝트 의존성 설치 |
| 3️⃣ 환경 변수 설정 | .env 파일 생성 후 아래 내용 추가VITE_API_BASE_URL=백엔드 서버 URL VITE_KAKAO_MAP_API_KEY=카카오 지도 API 키 VITE_GOOGLE_CLIENT_ID=구글 클라이언트 ID |
환경 변수 등록 |
| 4️⃣ 개발 서버 실행 | npm run dev |
개발 서버 실행 🌐 http://localhost:4000 |
| 5️⃣ 프로덕션 빌드 | npm run build |
프로덕션 빌드 생성 |
| 6️⃣ 빌드 미리보기 | npm run preview |
빌드 결과물 미리보기 |
| 7️⃣ 코드 포맷팅 | npm run format |
코드 포맷팅 |
| 8️⃣ 코드 검사 | npm run lint |
코드 린트(검사) |
| 명령어 | 설명 |
|---|---|
npm run build |
프로덕션 빌드 |
npm run preview |
빌드 결과물 미리보기 |
npm run format |
코드 포맷팅 |
npm run lint |
코드 검사 |
📊 주요 기능: 개인화된 대시보드 및 추천 혜택 표시
🔧 핵심 컴포넌트:
- 🎯 멤버십 혜택 배너
- 🏪 추천 매장 리스트
- 📈 개인 통계 요약
- 📖 스토리 추천 섹션
✨ 특징: 개인화된 콘텐츠, 반응형 디자인, 실시간 데이터 업데이트
📍 주요 기능: 위치 기반 제휴처 검색 및 LG U+ 팝업 스토어 정보 표시
🔧 핵심 컴포넌트:
MapContainer.tsx: 카카오맵 통합 컴포넌트BottomSheetLocationDetail.tsx: 제휴처 상세 정보 바텀시트MapActionButtons.tsx: 지도 액션 버튼들BottomSheetFilter.tsx: 필터링 바텀시트
✨ 특징: 실시간 위치 추적, 제휴처 진입 시 자동 팝업 알림, 카테고리별 필터링, 즐겨찾기 기능
🎨 주요 기능: 개인 맞춤형 할인 혜택 스토리 제공
🔧 핵심 컴포넌트:
StoryCard.tsx: 스토리 카드 컴포넌트StoryLayout.tsx: 스토리 레이아웃StoryDetailLayout.tsx: 스토리 상세 레이아웃
✨ 특징: 월별 개인화 스토리, AI 기반 추천, 인터랙티브 카드, 진단 시스템 연계
🎲 주요 기능: 방문 인증을 통한 스탬프 적립 및 룰렛 이벤트 시스템
🔧 핵심 컴포넌트:
Roulette.tsx: 룰렛 게임 컴포넌트ProbabilityRoulette.tsx: 확률 기반 룰렛StampRouletteCard.tsx: 스탬프 룰렛 카드TodayCouponSection.tsx: 오늘의 쿠폰 섹션
✨ 특징: 방문 인증 스탬프 시스템, 확률 기반 보상, 일일 한정 이벤트, 애니메이션 효과
⚙️ 주요 기능: 개인정보 관리, 쿠폰/북마크 관리, 통계 확인
🔧 핵심 컴포넌트:
UserProfileSection.tsx: 사용자 프로필 섹션StatisticsSection.tsx: 통계 요약 섹션MembershipBenefitSection.tsx: 멤버십 혜택 섹션RecentUsageSection.tsx: 최근 이용 내역 섹션
📋 하위 페이지:
- 🎫 쿠폰 관리 (
/my/coupons) - ⭐ 북마크 관리 (
/my/bookmarks) - 📊 통계 상세 (
/my/statistics) - 📝 이용 내역 (
/my/usage-history)
✨ 특징: 실시간 통계 차트, 쿠폰 상태 관리, 즐겨찾기 매장 관리
🏪 주요 기능: 브랜드별 멤버십 혜택 조회 및 관리
✨ 특징: 브랜드별 할인율 정보, 카테고리 필터링, 혜택 상세 정보
🔑 주요 기능: 소셜 로그인 및 회원 관리, 방문/결제 인증 시스템
🌐 지원 플랫폼: Kakao, Google, Naver
✨ 특징: JWT 기반 인증, 보호된 라우트 관리, 멤버십 바코드 통합 관리
| 컴포넌트 | 설명 |
|---|---|
BottomNavigator.tsx |
하단 탭 네비게이션 |
Header.tsx |
페이지별 헤더 |
CouponCard.tsx |
쿠폰 카드 컴포넌트 |
LoadingSpinner.tsx |
로딩 표시 |
✨ 특징: 일관된 디자인 시스템, 접근성 및 반응형 지원
 |
 |
 |
 |
 |
 |
 |
|---|---|---|---|---|---|---|
| 한세영 | 이본규 | 정성빈 | 김현우 | 김준서 | 임재찬 | 홍석준 |
| @1seyoung | @lbk00 | @tjdqls3607 | @khwww | @KimJunSeo289 | @alex8396 | @Hongjunior |
 |
 |
 |
 |
 |
|
|
| 팀 | 이름 | 역할 | 담당 업무 |
|---|---|---|---|
| 🔧 Backend | 한세영 (BE 팀장) | DevOps & Backend Lead | • DevOps, 포스기 기능 개발 • 알림 시스템 구축, Airflow • 포스기 프론트 개발, 데이터 샘플링 • RAG 추천 |
| 🔧 Backend | 이본규 (테크리더) | Tech Lead & Database | • ERD 설계, DB 관리 • OAuth 연동, 유저 서버 개발 • Log-consumer 구축, Airflow 설계 • 관리자 대시보드 시각화 |
| 🔧 Backend | 정성빈 | QA & API Development | • QA 담당, 어드민 서버 개발 • 이번주니어 API 개발 • 대시보드 프론트 개발, 커뮤니케이션 • 소비스토리 및 제휴처 추천 API 개발 |
| 💻 Frontend | 김현우 (FE 팀장) | Frontend Lead & Architecture | • 공통 컴포넌트 개발 • 지도 페이지 개발 • PWA 구축, 검색 엔진 최적화 |
| 💻 Frontend | 김준서 | Frontend Developer | • 공통 컴포넌트 개발 • 메인 페이지 개발, 마이 페이지 개발 • 알림 시스템 연동 |
| 💻 Frontend | 임재찬 | Frontend Developer | • 공통 컴포넌트 개발 • 로그인/회원가입 페이지 개발 • 이번주니어 페이지 개발 |
| 💻 Frontend | 홍석준 | Frontend Developer | • 공통 컴포넌트 개발 • 스토리 페이지 개발 • 온보딩/혜택 안내 페이지 개발 |
| 특징 | 설명 |
|---|---|
| 📱 반응형 디자인 | 모바일 퍼스트 접근 방식 (최대 너비 600px), 사용자 친화적 UI/UX 설계 |
| 🎯 사용자 경험 | 직관적인 인터페이스, 큰 버튼과 명확한 텍스트로 접근성 향상 |
| ⚡ 성능 최적화 | Vite 기반 빠른 개발 환경 |
| 🔧 개발 환경 | TypeScript로 타입 안전성 확보, ESLint + Prettier 코드 품질 관리 |
| 🔐 보안 & 인증 | JWT 기반 토큰 인증, 소셜 로그인 지원, 보호된 라우트 관리 |