CouponLog (쿠폰로그)

Screenshots

고객 화면

점주 화면

1. 프로젝트 개요

종이 쿠폰의 불편함을 없애고, 데이터 기반의 고객 관리를 실현하는 디지털 적립 플랫폼

CouponLog는 소상공인과 고객을 연결하는 디지털 스탬프 솔루션입니다. 종이 쿠폰의 분실 위험과 관리의 비효율성을 해결하며, 사장님에게는 정교한 고객 방문 데이터를, 고객에게는 지갑 없이도 편리한 적립 경험을 제공합니다.

2. 주요 기능

🏪 점주 (Owner)

  • 대시보드 & 통계: 일별/주별 방문 추이, 쿠폰 발급/사용 현황을 시각적으로 분석
  • 정책 관리: 스탬프 적립 기준 및 리워드(무료 쿠폰 등) 정책 커스텀 설정
  • 직원 관리: 직원 초대 링크 생성 및 매장 관리 권한 부여
  • 이벤트/소식: 매장 이벤트 생성 및 고객 알림 발송
  • QR 관리: 매장 고유 QR 생성 및 관리

👨‍💼 직원 (Staff)

  • 적립/사용 스캔: 고객의 QR 코드를 스캔하여 즉시 스탬프 적립 또는 쿠폰 소진
  • 초대 수락: 점주의 초대를 받아 매장 스태프로 등록

🧑‍🦰 고객 (Customer)

  • 내 쿠폰함: 매장별 적립 현황과 보유 쿠폰 통합 관리
  • QR 체크인: 고유 QR 코드로 간편하게 스탬프 적립
  • 매장 탐색: 위치 기반(Google/Naver Map) 내 주변 적립 가능 매장 및 이벤트 찾기
  • 알림: 쿠폰 만료 및 혜택 알림 수신

3. 대상 사용자

  • 소상공인 (카페, 음식점 등): 단골 고객 관리와 재방문 유도가 필요한 사장님
  • 매장 직원: 빠르고 간편하게 계산대에서 적립을 처리해야 하는 근무자
  • 일반 소비자: 종이 쿠폰 휴대가 번거롭고 혜택을 놓치고 싶지 않은 알뜰 소비자

4. 기술 스택 (Tech Stack)

Frontend (Mobile)

  • Framework: Flutter (Dart)
  • State Management: Riverpod (riverpod_annotation)
  • Routing: GoRouter
  • Maps: google_maps_flutter, flutter_naver_map
  • UI/UX: Lottie (애니메이션), Google Fonts

Backend & Infrastructure

  • Platform: Supabase (BaaS)
  • Database: PostgreSQL
  • Authentication: Supabase Auth (Email, Kakao, Google, Apple)
  • Storage: Supabase Storage (이미지 등)
  • Notification: Firebase Cloud Messaging (FCM)

5. 아키텍처 개요

본 프로젝트는 유지보수성과 확장성을 위해 Feature-first Clean Architecture를 엄격히 따릅니다.

디렉터리 구조

lib/
 ├─ app/          # 진입점, 라우터, 테마, 로컬라이제이션
 ├─ core/         # 공통 유틸리티, 네트워크(Dio), 디자인 시스템, 보안
 └─ features/     # 도메인별 기능 모듈 (auth, customer, owner, store, event 등)
     ├─ data/         # API, DB, Repository 구현
     ├─ domain/       # Entity, UseCase, Repository 인터페이스
     └─ presentation/ # UI(Screen, Widget), ViewModel(Riverpod)

데이터 흐름

  1. Presentation: UI에서 User interaction 발생 → ViewModel로 이벤트 전달
  2. Domain: ViewModel이 Usecase 실행 (비즈니스 로직)
  3. Data: Repository 패턴을 통해 Remote(Supabase) 또는 Local 데이터 접근
  4. State: Riverpod를 통해 UI 상태(Loading/Success/Error) 전파 및 갱신

6. 설치 및 실행 방법

요구 사항

  • Flutter SDK (^3.10.0)
  • Android Studio / Xcode
  • Supabase Project Key

설치 절차

  1. 저장소 클론

    git clone https://github.com/your-repo/couponlog.git
cd couponlog

  2. 의존성 설치

    flutter pub get

  3. 환경 설정

    • android/key.properties 생성 및 키스토어 설정 (Android 빌드 시)
    • core/config 또는 .env 파일에 Supabase URL 및 Anon Key 설정 (구현 방식에 따라 확인 필요)

실행 방법

# 개발 모드로 실행
flutter run

# 릴리즈 모드 빌드 (Android)
flutter build apk --release

7. 설정 및 환경 변수

프로젝트 실행을 위해 다음의 주요 API 키 설정이 필요합니다.

  • Supabase Project URL & Anon Key
  • Kakao Native App Key (소셜 로그인용)
  • Google Maps API Key (Android/iOS)
  • Naver Map Client ID

8. 제한 사항 및 알려진 이슈

  • 지도 연동: 에뮬레이터 환경에서는 Google/Naver 지도 렌더링이 제한될 수 있습니다. 실물 기기 테스트를 권장합니다.
  • 소셜 로그인: 디버그 키해시 및 번들 ID가 각 플랫폼 개발자 센터에 등록되어 있어야 정상 작동합니다.

9. 향후 개선 방향

  • 비콘(Beacon) 연동: 매장 진입 시 자동 체크인 및 알림 기능
  • POS 연동: 결제와 동시에 적립이 이루어지는 POS 통합 모듈 개발
  • AI 추천: 고객 방문 패턴 분석을 통한 맞춤형 쿠폰 자동 발급 시스템 도입