GearMatch AI v2.0 — 모바일 웹 MVP
목표: 2026-10-16(금)까지 내부 테스트 가능한 MVP
흐름: Landing → Runner Test → Identity Reveal → Profile → RUNNING Main → Run 기록 → Stats → ITEMS
스택: Next.js 15 (App Router) · TypeScript · Tailwind CSS 4 · Supabase(STEP 3에서 연결) · Vercel(배포 단계)
1. 내 컴퓨터에서 실행하기 (Windows 기준)
필요한 것: Node.js 20.9 이상 (https://nodejs.org 의 LTS 버전)
PowerShell 또는 명령 프롬프트에서:
node -v # v20.9 이상인지 확인
git clone https://github.com/chorockai-lab/GearMatch-AI-MVP.git
cd GearMatch-AI-MVP
npm install # 처음 한 번만 (몇 분 걸릴 수 있음)
npm run dev # 개발 서버 실행
브라우저에서 열기:
휴대폰 크기로 보려면 브라우저 개발자 도구(F12) → 기기 툴바에서 390 × 844를 선택하세요.
검사 명령:
npm run test:identity # 동물 판정 로직: 명세 §4·§7과 일치하는지 (3,125개 조합 전부)
npm run check:assets # 캐릭터 PNG 23개가 있고 64×48인지
npm run test:onboarding # 온보딩 화면 이동 규칙
npm run test:stats # 통계 계산 정의
npm run test:items # 비슷한 러너 집계 규칙·가져오기 검증
npm run test:analytics # PostHog 전송 정책(허용 속성·주소 정리·켜짐 조건)
npm run verify:sql # 마이그레이션·RLS·분석 SQL (로컬 Postgres, 네트워크 없음)
npm run check:supabase # 실제 Supabase 연결·테이블 확인 (.env.local 필요)
npm run test:rls # 실제 Supabase RLS 격리 확인 (.env.local 필요)
npm run typecheck # 타입 검사
npm run lint # ESLint
npm run build # 배포용 빌드
처음 npm run dev 할 때 Google Fonts(Barlow, Barlow Condensed, Noto Sans KR)를 내려받으므로 인터넷 연결이 필요합니다.
2. 폴더 구조
public/assets/ 캐릭터 · 효과 PNG (gearmatch-running-assets v1.1 원본 그대로)
char/ human/ fx/
src/app/ 화면(라우트)
page.tsx Landing
test/[n]/ Runner Test Q1~Q5
reveal/ Identity Reveal (runner-type/ = RUNNING "?" 결과 다시 보기)
onboarding/ habits(프로필 1) · runner(프로필 2) · shoe(지금 신는 러닝화)
running/ RUNNING Main
dev/ dev/states/ 개발 미리보기 · 8종 × 상태 QA 화면
runs/ runs/new/ runs/[id]/(edit/) 러닝 기록 History · 입력 · 상세 · 수정/삭제
stats/ stats/detail/ Stats Card · 상세 통계
items/ items/[id]/ items/saved/ Runners Like You · 제품 상세 · 저장한 신발
profile/ privacy/ 다음 STEP에서 구현할 자리(임시 화면)
src/components/
onboarding/ Landing 장면 · Runner Test · Reveal · Profile · Current Shoe · 공통 Flow 부품
running/ RunnerScene(사람+동물 장면) · RunnerCard · RecentRuns · RunningMainView
ui/ 하단 탭 · 헤더 · 아이콘 · 임시 화면
src/lib/
identity/ 동물 8종 · 5문항 · 판정(점수 · 정규화 · 동점 규칙) · 결과 문구 · WHY
onboarding/ 온보딩 데이터 저장 계층 (STEP 2: 이 브라우저 임시 저장 → STEP 3: Supabase로 교체)
running/ 카드 상태 정책(잠정) · 페이스/표시 형식 · 마일스톤(확정 전, 꺼둠)
assets/sprites.ts PNG 기준점(bbox) 데이터
demo/ DEMO 데이터 (실제 데이터와 구분, 화면에 DEMO DATA 표시)
supabase/ Supabase 연결 (환경변수가 없으면 DEMO 모드)
supabase/migrations/ DB 스키마 (2026-10-13 SQL Editor로 적용 — docs/SUPABASE.md)
scripts/ 판정 테스트 · 에셋 검사
docs/asset-source/ 스프라이트 원본 데이터 · 내보내기 검사 기록
3. 지금 상태 (STEP 3)
- 저장 위치는
NEXT_PUBLIC_DATA_MODE로 정해집니다(빌드 시 고정).
demo(기본): 온보딩·러닝 기록을 이 브라우저에만 임시 저장(localStorage). 서버 저장 아님.real + Supabase 값: 익명 사용자로 Supabase에 저장(RLS로 본인 데이터만 접근). 사용자 행동 이벤트도 기록.- 두 모드의 데이터는 섞이지 않습니다(DEMO 기록은 서버로 옮기지 않음).
- 익명 사용자는 같은 브라우저에서만 이어집니다. 다른 브라우저·시크릿 창·사이트 데이터 삭제 시 복구할 수 없습니다.
?state= 미리보기 화면의 기록 값은 모두 DEMO입니다.- PostHog 분석 연동·대시보드:
docs/POSTHOG.md
- ITEMS 데이터·가져오기·로컬 DEMO:
docs/ITEMS_DATA.md
- Supabase 운영·마이그레이션 이력:
docs/SUPABASE.md · 분석 쿼리: docs/ANALYTICS_QUERIES.md
- 카드 상태 규칙은
src/lib/running/state-policy.ts 한 곳에 모아 두었습니다(잠정 정책).
- 캐릭터 배치 규칙(정수 ×3 확대 · 기준점 고정 · 동물 속도선이 사람을 가리지 않음)은
src/components/running/RunnerScene.tsx에 있습니다.
4. 개발 현황
진행 상황·테스트 결과·남은 일은 docs/DEVELOPMENT_STATUS.md를 봅니다.
5. 확인이 필요한 항목
| 항목 | 현재 처리 |
|---|
| CURRENT MODE 산출 규칙 | 규칙 문서 없음 → 실제 데이터에서는 “—” 표시. DEMO만 시안 값(BUILDING SPEED) |
| FIRST 10K 판정 조건 | 명세에 없음 → 자리만 만들고 꺼 둠(milestones.ts) |
| 성취 기록 수정 · 삭제 시 처리 | 미정 |
| Runner Code 화면 | v1.8 문서에는 있으나 v2.0 기획 · 킥오프 흐름에서 제외 → 넣지 않음(익명 로그인 예정) |
| 브라우저 변경 · 데이터 삭제 후 복구 | MVP에서 지원하지 않음(같은 브라우저만). 복구 기능이 있는 것처럼 표시하지 않음 |
