ZEROST

제로웨이스트 실천을 미션, 재료 수집, 레시피, 스프 제작, 가챠 보상으로 연결한 게이미피케이션 프론트엔드입니다.
앱인토스 미니앱으로 Granite · React Native · TDS 기반으로 구현했으며, 인증·미션·제작·보상 화면을 BE API 계약에 맞춰 연결합니다.

• 콘솔 appName: 0st (granite.config.ts)
• 표시명: 제로스트 (app.config.ts APP_DISPLAY_NAME)
• 백엔드: team-0st/BE

프로젝트 구조

FE/
├── pages/                         # Granite 라우트 진입
│   ├── index.tsx                  # 홈
│   ├── login.tsx
│   ├── onboarding/                # 인트로 · 프로필 · 단골 샵
│   ├── missions/                  # 목록 · 상세 · 인증 · 결과
│   ├── ingredients/               # 제작(재료 슬롯)
│   ├── soup/                      # 스프 제작 결과
│   ├── gacha/                     # 에코잼 가챠
│   ├── recipes/                   # 레시피
│   ├── profile/                   # 마이
│   ├── shop/                      # 상점 · 파트너 · 선택
│   └── admin/                     # 미션 검수
├── src/
│   ├── app/                       # 스키마 정규화 등 앱 부트
│   ├── api/                       # BE 클라이언트 · mock 폴백
│   │   ├── notion/                # API_PATHS · 계약 타입
│   │   └── mock/                  # API 비활성 시 로컬 스텁
│   ├── features/                  # 화면·도메인 UI
│   │   ├── auth/
│   │   ├── home/
│   │   ├── missions/
│   │   ├── craft/
│   │   ├── soup/
│   │   ├── gacha/
│   │   ├── recipes/
│   │   ├── ingredients/
│   │   ├── profile/
│   │   ├── shop/
│   │   ├── onboarding/
│   │   ├── user/
│   │   ├── legal/
│   │   └── about/
│   └── shared/                    # UI · 네비 · 테마 · 스토리지 · 피드백
├── assets/brand/                  # 브랜드·미션·스프·가챠 에셋
├── docs/
│   ├── assets/                    # README 서비스 화면 캡처
│   ├── CONVENTIONS.md             # API·에러·PR·용어 (BE 정렬)
│   ├── USER_FLOW.md
│   ├── PRODUCT_SPEC.md
│   ├── SECURITY.md
│   └── BE_HANDOFF.md
├── scripts/                       # sandbox · API base URL sync
├── granite.config.ts
└── app.config.ts

주요 기능

• 온보딩(닉네임·전화번호·단골 샵) 및 로그인
• 홈 출석 체크 → 랜덤 재료
• 오늘의 미션 / 공동 미션 · 사진 인증 · 결과 · 보상 탭
• 재료 슬롯 기반 스프 제작 · 결과 · 리롤 UX
• 에코잼 가챠
• 주간 / 히든 / 전설 레시피 탐색
• 상점·파트너 안내, 마이(재화·이력)
• 관리자 미션 검수
• EXPO_PUBLIC_API_BASE_URL 비우면 mock 모드로 동일 UX 유지

서비스 화면

오늘의 미션	공동 미션	레시피
일일 미션 편성, 상태 확인, 보상 탭 흐름 상태 화면 · 보상 탭	단계형 인증과 완료 상태 중심의 공동 미션 구조 목록 화면	일반 / 히든 레시피를 구분해 탐색하는 화면 히든 레시피
스프 제작 / 리롤	에코잼 가챠	보상 탭
재료 조합, 제작 결과, 리롤까지 이어지는 흐름 소개 화면 · 재료 선택	에코잼 사용 후 포인트 / 재료 / 보상을 획득하는 가챠 흐름 소개 화면 · 재료 보상	미수령 보상 조회와 수령 흐름 미션 상태

스프 제작 데모	스프 리롤 데모	에코잼 가챠 데모
soup-brew-demo.mp4	soup-reroll-update.mp4	gacha-demo.mp4

주요 설계와 구현

API 계약과 mock 폴백

BE 정렬 컨벤션
경로·에러 코드·도메인 용어는 BE와 공유하고, 화면은 src/api 계약에 맞춰 붙입니다. EXPO_PUBLIC_API_BASE_URL이 비어 있으면 mock으로 같은 UX를 유지해 샌드박스·데모에서도 흐름이 끊기지 않게 했습니다.

FE / BE 역할 분리
확률·1일 1회·검수·지급 같은 비즈니스 규칙은 BE가 결정하고, FE는 요청·응답 반영과 상태 UI에 집중합니다.

제품 루프와 네비게이션

일일 / 주간 유저 플로우
출석·미션(일일)과 재료→스프→가챠(주간)를 홈·5탭 구조로 이었습니다. 앱인토스 appName/scheme은 콘솔과 맞추고, legacy intoss://zerost는 normalizeSchemeUrl에서 0st로 정규화합니다.

연동·보안

BE 핸드오프 · SECURITY
파일럿 연동에 필요한 API 갭과 클라이언트 보안 체크를 문서로 남겨 BE/운영과 맞춥니다.

기술 스택

구분	내용
Platform	Apps in Toss 미니앱
Framework	Granite (@granite-js/react-native)
UI	React 19, React Native 0.84, TDS (@toss/tds-react-native)
Language	TypeScript
Lint / Format	Biome (indent 4, BE 정렬)
Test	Jest, Testing Library
Build	ait build → 0st.ait

실행 방법

환경 변수

기본 예시는 .env.example를 참고하면 됩니다.

키	설명
EXPO_PUBLIC_API_BASE_URL	BE base URL (trailing slash 없이). 비우면 mock 모드

애플리케이션 실행

npm install
npm run dev:sandbox   # Metro → 샌드박스에 IP:8081, intoss://0st
npm run build         # 0st.ait
npm run typecheck
npm test

• 콘솔 appName = granite.config.ts appName
• 표기명 = app.config.ts APP_DISPLAY_NAME (제로스트)

관련 문서

• CONVENTIONS.md — API·에러·PR·용어 (BE 정렬, rename 제외)
• USER_FLOW.md
• PRODUCT_SPEC.md
• SECURITY.md
• BE_HANDOFF.md
• team-0st/BE