강원환급패스 (GWPass)

혜택 달성 코스를 추천하고, 환급받은 강원상품권까지 바로 쓰게 만드는 강원 여행 실행 앱. 관광 데이터 · 환급 정책 · 지역화폐 가맹점을 하나의 사용자 흐름(코스 → 소비 인증 → 환급 달성 → 재소비)으로 묶었다.

2026 관광데이터 공모전 출품작. Android 앱 + Spring Boot 서버 + PostgreSQL.

주요 기능

• 혜택 달성 코스 추천 — 관광지·가맹점·숙박을 묶어 환급 조건을 달성할 수 있는 코스 제안(테마·지역·예산 필터, 환급 쉬운 순 정렬)
• 환급 가능 소비처 지도 — 강원상품권 가맹점·관광지를 한 화면에서 확인하고, 반경 500m 사용처 안내
• 환급 챌린지 — 영수증 인증 → 게이지 달성 → 상품권 지급 예정 안내(정책 자동 판정)
• QR 즉시 할인 + 스탬프 — 가맹점 방문 인증 시 즉시 할인·스탬프, 5곳 완주 시 특산물 쿠폰
• 도민증/생활도민증 — 거주지 자기신고를 통한 발급과 유형별 혜택 정책
• 재방문 유도 — 시즌 패스, 다음 여행 쿠폰, SNS 공유 카드

기술 스택

모바일

Framework: Expo · React Native · TypeScript · Expo Router

State & Data: TanStack Query · Zustand · React Hook Form · Zod

UI & Platform: react-native-svg · React Native Naver Map · Android

서버

Runtime & Build: Java 17 · Spring Boot 3.4 · Gradle

Web, Security & Batch: Spring Web · Spring Security · Spring Batch · Bean Validation · Spring Data JPA · JWT

Database & Migration: PostgreSQL · Flyway

개발·검증 환경

Tooling: Docker Compose · Testcontainers · OpenAPI · Port-Adapter 기반 Fake/Real Provider

디렉터리 구조

AI·문서

├── AGENTS.md                         # 프로젝트 작업 규칙과 개발 가이드
├── .claude/                          # AI 작업 환경 설정·스킬·작업 트리
├── .codex/                           # Codex 에이전트 설정
├── docs/                             # 프로젝트 단일 문서 저장소
│   ├── analysis/                     # 분석, 누락 정보, 원본 대조 자료
│   ├── architecture/                 # 시스템·도메인·데이터 모델과 ADR 성격의 설계
│   ├── audit/                        # 구현 완성도 및 UI·명세 감사 결과
│   ├── automation/                   # 작업 상태, 의사결정, 작업 보드, 검증 로그
│   ├── decisions/                    # 가정과 주요 의사결정 기록
│   ├── design/                       # 브랜드, 디자인 시스템, 리디자인 명세
│   ├── product/                      # 제품 정의, 요구사항, 사용자 흐름, 정책
│   ├── release/                      # Android 빌드와 배포 관련 문서
│   ├── tasks/                        # 기능 단위 작업 명세
│   └── testing/                      # 독립 검토 및 시각 QA 결과
├── 기획/                             # 공모전 원본 기획·와이어프레임 자료
└── 디자인/                           # 디자인 기준 문서

서버

├── server/                           # Spring Boot 모듈러 모놀리스
│   ├── src/main/java/kr/gwpass/
│   │   ├── auth/                     # 인증·인가와 소셜 로그인
│   │   ├── user/                     # 사용자·도민증
│   │   ├── catalog/                  # 관광지·가맹점·코스 데이터
│   │   ├── map/                      # 지도 조회·마커·클러스터
│   │   ├── challenge/                # 환급 챌린지와 진행 상태
│   │   ├── receipt/                  # 영수증 제출·심사
│   │   ├── benefit/                  # 환급·쿠폰·상품권 혜택
│   │   ├── share/                    # 공유 카드
│   │   ├── notification/             # 알림
│   │   ├── provider/                 # 외부 연동 Port 및 Fake/Real Adapter
│   │   ├── common/                   # 공통 보안·예외·응답·설정
│   │   └── demo/                     # 개발·데모 전용 API와 시드 데이터
│   ├── src/main/resources/
│   │   ├── application.yml           # 애플리케이션·정책 설정
│   │   └── db/migration/             # Flyway 데이터베이스 마이그레이션
│   ├── data/                         # 개발 환경 영수증 파일 저장소
│   └── build.gradle                  # 서버 의존성·빌드 설정

모바일

├── mobile/                           # Expo 기반 React Native 앱
│   ├── app/                          # Expo Router 파일 기반 라우트
│   │   ├── (auth)/                   # 로그인·온보딩 흐름
│   │   └── (tabs)/                   # 홈·코스·지도·챌린지·마이 탭
│   ├── src/
│   │   ├── api/                      # 서버 API 클라이언트와 요청 정의
│   │   ├── design-system/            # 색상·간격·타이포그래피 등 디자인 토큰
│   │   ├── features/                 # 도메인별 화면·상태·비즈니스 로직
│   │   ├── providers/                # 앱 전역 Provider
│   │   ├── platform/                 # Android 등 플랫폼 특화 구현
│   │   └── lib/                      # 공통 유틸리티
│   ├── assets/                       # 브랜드 이미지·폰트·아이콘
│   ├── android/                      # Expo prebuild Android 네이티브 프로젝트
│   ├── app.config.js                 # Expo 앱·공개 환경변수 설정
│   └── package.json                  # 앱 의존성·스크립트

공통

├── contracts/openapi.yaml            # 모바일과 서버가 공유하는 API 계약
├── tests/e2e/                        # 핵심 사용자 여정 E2E 스모크 테스트
└── scripts/                          # 개발 서버·테스트·Android 빌드 스크립트

사전 요구사항

• Docker (PostgreSQL 컨테이너)
• Java 17+ (서버; Gradle wrapper 포함)
• Node 20+ (모바일)
• Android SDK + 에뮬레이터 (앱 실행)

환경 변수

서버 환경변수는 server/.env, 모바일 환경변수는 mobile/.env.local에 설정한다. 실제 비밀값과 공개 앱 설정값은 저장소에 커밋하지 않는다.

서버 (server/.env)

DB_URL=
DB_USER=
DB_PASSWORD=
SERVER_PORT=
JWT_SECRET=
RECEIPT_DIR=
R2_ENABLED=
R2_ENDPOINT=
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_BUCKET=
R2_SIGNED_URL_MINUTES=
TOUR_API_KEY=
MERCHANT_API_KEY=
KAKAO_CLIENT_ID=
VOUCHER_API_KEY=
REVIEW_WEBHOOK_SECRET=
FCM_SERVICE_ACCOUNT=

모바일 (mobile/.env.local)

EXPO_PUBLIC_API_BASE_URL=
EXPO_PUBLIC_NAVER_MAP_CLIENT_ID=
EXPO_PUBLIC_SENTRY_DSN=

CI·Android Release 빌드

SENTRY_AUTH_TOKEN=
GWPASS_RELEASE_STORE_FILE=
GWPASS_RELEASE_STORE_PASSWORD=
GWPASS_RELEASE_KEY_ALIAS=
GWPASS_RELEASE_KEY_PASSWORD=

최초 실행

scripts/setup.sh            # DB 기동 + 의존성 설치

Docker로 전체 실행 (서버 + DB)

docker compose --profile full up -d --build
curl http://localhost:8080/actuator/health

• DB만 실행: docker compose up -d db (호스트 포트 5433)

서버 실행 (개발)

scripts/dev.sh

• API 계약: contracts/openapi.yaml
• 데모 계정: demo@gwpass.local / demo1234

Android 실행 (에뮬레이터)

# 1) 에뮬레이터 부팅
emulator -avd <AVD이름>
# 2) 앱 실행 (Metro 개발 서버)
cd mobile && npx expo start --dev-client
# 3) 개발 빌드가 없다면 Debug APK 빌드·설치
scripts/build-android.sh
adb install -r mobile/android/app/build/outputs/apk/debug/app-debug.apk
adb reverse tcp:8081 tcp:8081 && adb reverse tcp:8080 tcp:8080
adb shell am start -n kr.gwpass.app/.MainActivity

Android APK 생성

scripts/build-android.sh
# → mobile/android/app/build/outputs/apk/debug/app-debug.apk

Release 빌드·서명은 docs/release/android-build-guide.md를 참고한다.

자세한 결과는 docs/release/final-report.md.