🎰 여행가챠 (Travel Gacha)

랜덤으로 뽑은 여행지에서, 랜덤으로 뽑은 미션을 친구들과 함께 수행하는 여행 앱

주요 기능 • 기술 스택 • 시작하기 • 프로젝트 구조 • 문서

---

📸 스크린샷

홈 · 미션 선택 · 미션로그

여행지 뽑기 · 여행 일기장 · 도감

---

✨ 주요 기능

🎲 랜덤 여행지 뽑기

• 여행지 가챠: 랜덤으로 추천된 여행 지역 3곳 중 하나를 선택
• 리롤: 마음에 들지 않는 후보는 개별로 다시 뽑기
• 여행방 생성 & 초대: 초대 코드로 친구들을 여행에 초대

🎯 오늘의 랜덤 미션

• 미션 후보 캐러셀: 매일 제공되는 미션 후보 중 하나를 선택 (후보별 리롤 가능)
• 위치 인증: 미션 장소 근처에 있어야 미션 완료 가능 (expo-location)
• 진행도 트래킹: 오늘의 미션 진행도와 멤버별 인증 상태를 한눈에 확인
• 미션 포기: 너무 어려운 미션은 포기하고 다음 미션으로

🎬 미션로그 (셋로그)

• 멤버별 촬영: 모든 멤버가 미션로그 영상을 촬영해야 미션 완료
• 카메라: 후면 카메라 기본, 화면 회전 지원 (expo-camera)
• 영상 미리보기 & 다운로드: 촬영한 미션로그를 다시 보고 저장 (expo-video)

📔 여행 기록

• 여행 일기장: 하루의 추억을 일기로 기록
• 미션 목록 / 여행 기록: 여행 동안 수행한 미션 이력과 요약 확인
• 도감: 미션 보상으로 획득한 아이템 모아보기

👥 여행 관리

• 멤버 관리: 방장 위임, 멤버 강퇴, 여행 나가기
• 여행 조기 종료: 방장이 진행 중인 여행을 조기 종료(취소)
• 여행 정보 수정: 여행 이름/일정 편집

🔐 계정 & 알림

• Apple 로그인: expo-apple-authentication 기반 소셜 로그인 + 온보딩
• 푸시 알림 / 알림함: expo-notifications 기반 알림 수신 및 읽음 처리
• 권한 동기화: OS 권한(카메라·위치·알림) 변경을 앱 상태와 실시간 동기화

---

🛠 기술 스택

Mobile (주 개발 대상)

기술	버전	설명
Expo	57	앱 런타임 / 네이티브 모듈
React Native	0.86	UI 프레임워크
React	19.2	UI 라이브러리
expo-router	57	파일 기반 라우팅
Reanimated	4.5	애니메이션 (캐러셀 등)
TypeScript	6.0	타입 안정성

Web

기술	버전	설명
Next.js	14	App Router, 공유 패키지용 최소 뼈대

상태 관리 & API

기술	설명
TanStack Query	서버 상태 관리
Jotai	로컬/UI 상태 관리
Axios	HTTP 클라이언트

스타일링

기술	설명
@travel-gacha/ui	공통 디자인 토큰 (colors / spacing / radius)
RN StyleSheet	컴포넌트별 index.css.ts 로 분리 (스타일은 TSX에 두지 않음)

빌드 & 개발 도구

기술	설명
Turborepo	모노레포 태스크 러너
pnpm (catalog)	워크스페이스 + 의존성 버전 중앙 관리
EAS Build / Submit	iOS 빌드 및 TestFlight 제출
ESLint / Prettier	린팅 / 포맷팅
Husky + lint-staged	커밋 전 Prettier 자동 적용

---

🚀 시작하기

필수 요구사항

• Node.js >= 18.x
• pnpm 9.x (packageManager 필드 기준)

설치

pnpm install

환경 변수 설정

cp apps/mobile/.env.example apps/mobile/.env

# API 서버
EXPO_PUBLIC_API_BASE_URL=https://your-api.example.com

# (선택) 로컬 개발용 값
EXPO_PUBLIC_DEV_JWT=
EXPO_PUBLIC_DEV_MEMBER_ID=
EXPO_PUBLIC_DEV_TRIP_ID=

개발 서버 실행

# 모바일 (Expo) — 주 개발 대상
pnpm dev:mobile

# Metro 캐시 초기화 후 실행 (설정 변경 후)
pnpm --filter mobile dev:clear

# 웹 (Next.js)
pnpm dev:web

Expo 실행 후 터미널에서 i(iOS), a(Android), w(web)로 플랫폼을 선택합니다.

기타 스크립트

명령	설명
pnpm build	전 워크스페이스 빌드
pnpm typecheck	TypeScript 검사
pnpm lint	ESLint
pnpm format	Prettier 포맷 (.prettierrc.json)
pnpm format:check	Prettier 검사만

iOS 배포

EAS Build로 빌드 후 TestFlight에 제출합니다. 인증서·API Key 세팅은 EAS iOS 빌드 세팅을 참고하세요.

cd apps/mobile
eas build --platform ios --profile production
eas submit --platform ios --latest

---

📁 프로젝트 구조

apps/
├── mobile/                    # Expo 앱 (주 개발 대상)
│   ├── app/                   # expo-router 라우트 (폴더 = URL)
│   │   ├── (auth)/            # 로그인 / 회원가입
│   │   ├── (tabs)/            # 하단 탭 5개
│   │   │   ├── index/         # 홈 (여행지 뽑기, 여행 생성)
│   │   │   ├── travel/        # 여행 목록
│   │   │   ├── mission-select/# 미션 선택 (중앙 탭)
│   │   │   ├── collection/    # 도감 목록
│   │   │   └── mission-log/   # 미션 로그
│   │   └── (stack)/           # 탭이 아닌 하위 화면
│   │       ├── diary/                 # 여행 일기장
│   │       ├── mission-list/          # 미션 목록
│   │       ├── mission-log-capture/   # 미션로그 촬영
│   │       ├── notification/          # 알림함
│   │       ├── settings/              # 설정
│   │       ├── travel-join/           # 여행 참여
│   │       └── travel-record/         # 여행 기록 / 멤버 관리
│   ├── components/            # 공통 UI 컴포넌트
│   ├── constants/             # 탭 정의 등 상수 (tabs.ts)
│   ├── hooks/                 # 커스텀 훅
│   ├── services/              # 인증 · 세션 · 권한 · 푸시 알림
│   ├── stores/                # 앱 전용 Jotai atom
│   └── plugins/               # Expo config plugin
└── web/                       # Next.js (최소 뼈대)

packages/
├── api/                       # Axios 클라이언트, queryOptions (queries/*.ts)
├── store/                     # Jotai, AppProviders, QueryClient
├── ui/                        # 디자인 토큰 (theme.ts)
├── types/                     # 공유 타입
├── utils/                     # 공유 유틸
├── eslint-config/             # ESLint 공유 설정
└── typescript-config/         # tsconfig 공유 설정

docs/                          # 아키텍처 / API / 빌드 문서

워크스페이스 패키지 import

import { theme, colors } from '@travel-gacha/ui';
import { AppProviders } from '@travel-gacha/store';
import { getApiClient } from '@travel-gacha/api';

모바일 앱 내부는 @/* → apps/mobile 루트 (tsconfig paths).

---

📋 주요 플로우

1. 여행 생성 플로우

여행지 후보 뽑기 → (리롤) → 여행지 선택 → 여행 정보 입력 → 여행 생성 → 초대 코드로 멤버 초대

2. 미션 수행 플로우

미션 후보 확인 → (리롤) → 미션 선택 → 멤버별 미션로그 촬영 → 위치 인증 → 미션 완료 → 아이템 획득

---

🧭 탭 구성

탭 경로	라벨
/	홈
/travel	여행 목록
/mission-select	미션 선택
/collection	도감 목록
/mission-log	미션 로그

탭은 apps/mobile/constants/tabs.ts에 등록합니다. 탭이 아닌 상세·모달 화면은 app/(stack)/ 아래에 두고 여기에 등록하지 않습니다.

---

📚 문서

• 모노레포 구조
• 모바일 앱 (라우팅, 스타일, 탭 vs 하위 화면)
• API 연동 예시
• EAS iOS 빌드 세팅

---

👥 팀

이름	역할	GitHub
김동현	Frontend	@Kimd0ng
이정선	Frontend	@leejs0823

---

Made with 🎰 by 가챠즈