해율 자연의 흐름 전자여권

자연의 흐름을 맛으로 전합니다.

해율만두전골에서 운영하는 전자여권형 멤버십 웹앱입니다.
매장 전체에서 동일한 QR코드 하나를 사용하며, 고객이 방문할 때마다 QR코드를 촬영하여 방문을 기록하고,
누적 방문 횟수에 따라 방문 등급이 오르며, 3·5·10·20·30회 방문 시마다
해율이 준비한 선물을 받을 수 있습니다.

---

기술 스택

항목	기술
프레임워크	Next.js 15 (App Router)
언어	TypeScript
스타일	Tailwind CSS v4
데이터베이스	Supabase (PostgreSQL)
배포	Vercel
시간대	Asia/Seoul

---

로컬 실행 방법

1. 저장소 복제

git clone https://github.com/your-username/haeyul-passport.git
cd haeyul-passport

2. 패키지 설치

npm install

3. 환경변수 설정

.env.example을 복사하여 .env.local 파일을 만들고, Supabase 정보를 입력하세요.

cp .env.example .env.local

필요한 환경변수:

변수명	설명	확인 위치
NEXT_PUBLIC_SUPABASE_URL	Supabase 프로젝트 URL	Supabase 대시보드 > Settings > API
NEXT_PUBLIC_SUPABASE_ANON_KEY	Supabase anon key	같은 위치
SUPABASE_SERVICE_ROLE_KEY	Supabase service role key	같은 위치 (비공개)
NEXT_PUBLIC_APP_URL	매장 QR 생성 시 사용할 절대주소	배포 후에는 실제 운영 도메인으로 설정

4. Supabase 데이터베이스 설정

1. supabase.com에서 무료 프로젝트를 생성합니다.
2. 프로젝트 대시보드 > SQL Editor를 엽니다.
3. supabase/migrations/001_initial_schema.sql 파일 내용을 복사하여 실행합니다.
4. 이어서 supabase/migrations/003_verify_admin_password.sql 파일 내용을 복사하여 실행합니다. (관리자 비밀번호 확인용 함수)
5. 이어서 supabase/migrations/004_reward_tiers.sql 파일 내용을 복사하여 실행합니다. (3/5/10/20/30회 선물 + 자동 발급 트리거)
6. 시험 데이터가 자동으로 생성됩니다.

002_verify_employee_pin.sql은 예전에 있었던 직원 PIN 확인 화면(/staff, 현재는 제거됨)을 위한 함수라 신규 설치 시에는 실행하지 않아도 됩니다.

5. 개발 서버 실행

npm run dev

브라우저에서 http://localhost:3000을 열어 확인하세요.

---

Supabase 프로젝트 생성 방법

1. supabase.com에 접속하여 회원가입/로그인합니다.
2. New Project 버튼을 클릭합니다.
3. 프로젝트 이름: haeyul-passport
4. 데이터베이스 비밀번호: 안전한 비밀번호를 설정하세요.
5. 지역(Region): Northeast Asia (Tokyo) 또는 가장 가까운 지역을 선택하세요.
6. Create new project를 클릭하면 1~2분 내에 생성됩니다.
7. 프로젝트가 생성되면 Settings > API에서 URL과 키를 확인합니다.

---

매장 QR

매장 QR은 더 이상 환경변수로 관리하지 않습니다. 토큰이 Supabase app_settings 테이블에 저장되고, 관리자 화면(/admin/settings > QR 관리)에서 발급·재발급·다운로드·인쇄를 모두 처리합니다.

https://haeyul-passport.vercel.app/visit?key=현재_발급된_토큰

• key가 맞으면(src/proxy.ts가 확인) 10분짜리 쿠키를 남기고, 전자여권 홈에 "해율 매장 방문이 확인되었습니다 / 오늘의 방문을 기록하시겠습니까?"와 함께 "해율 방문 기록하기" 버튼이 나타납니다. 이 버튼을 눌러야 방문이 기록됩니다. 신규 가입도 이 확인이 있어야 가능합니다.
• key가 없거나 유효하지 않으면(예: QR 없이 예전 링크로 직접 접속, 재발급되어 무효화된 옛 QR) 버튼 대신 "매장의 QR코드를 다시 스캔해 주세요" 안내만 표시되고, 방문 기록/가입 자체가 서버에서 거부됩니다.
• 관리자가 "QR 재발급"을 누르면 새 토큰이 즉시 발급되고 기존 QR은 그 순간부터 작동하지 않습니다. 재발급 직후에는 반드시 새 QR을 다운로드하거나 인쇄해서 매장에 붙은 실물을 교체하세요.
• 이건 완벽한 보안 장치는 아니라 "그냥 URL을 검색해서 들어오는 경우"를 걸러주는 정도입니다 — QR을 사진 찍어간 사람은 여전히 우회할 수 있습니다.

---

방문 등급 & 방문 선물

방문 등급은 누적 방문 횟수로부터 그때그때 계산되는 값이라 별도로 저장하지 않습니다(src/lib/tiers.ts). 방문 횟수가 바뀔 때마다 자동으로 다시 계산됩니다.

등급	누적 방문 횟수
새싹	1회 이상 5회 미만
푸른잎	5회 이상 10회 미만
나무	10회 이상 20회 미만
숲	20회 이상 30회 미만
해율 VIP	30회 이상

해율 VIP 등급 고객에게는 "다음 등급까지 남은 횟수" 대신 아래 문구가 표시됩니다.

해율 VIP가 되셨습니다. 오랜 시간 자연의 흐름을 함께해 주셔서 감사합니다.

방문 선물은 등급과 별도로, 아래 방문 횟수에 도달할 때마다 한 번씩만 자동 발급됩니다(DB 트리거 + customer_rewards(customer_id, reward_id) UNIQUE 제약으로 중복 발급을 막습니다). 발급된 선물은 사용하지 않으면 선물함에 계속 남아 있다가, 고객이 매장에서 선물함 화면을 직원에게 보여주고 "직원확인" 버튼을 누르면 그 자리에서 바로 사용 처리됩니다. 별도의 직원 로그인이나 PIN은 필요 없습니다.

방문 횟수	선물
3회	음료수 또는 만두 2알
5회	해율술빵 1개
10회	동충하초 또는 노루궁뎅이 버섯
20회	새싹인삼 + 전복 2미
30회	해율 VIP 특별 감사 선물

이 내용을 한 장으로 정리한 안내 화면이 /guide(로그인 불필요)에 있으며, 신규 가입 완료 화면(/welcome) 하단의 "여권 설명서 보기"에서 바로 볼 수 있습니다.

---

Vercel 배포 방법

현재 운영 주소: haeyul-passport.vercel.app

1. GitHub에 이 저장소를 푸시합니다.
2. vercel.com에서 New Project를 클릭합니다.
3. GitHub 저장소를 연결합니다.
4. 환경변수를 설정합니다 (.env.example 참고).
5. Deploy를 클릭합니다.

vercel.json에 "framework": "nextjs"를 명시해뒀습니다. Vercel 프로젝트를 새로 만들 때 프레임워크가 자동으로 "Next.js"로 인식되지 않으면(예: "Other"로 잡히면) 정적 파일로만 서빙되어 모든 페이지가 404가 나므로, 대시보드의 Project Settings > General > Framework Preset이 "Next.js"인지 꼭 확인하세요.

---

테스트 계정

관리자

/admin 접속 시 로그인이 안 되어 있으면 /admin/login으로 이동합니다. 로그인하면 대시보드, 고객관리, 방문관리, 선물관리, VIP관리, 설정(QR 관리·통계) 6개 메뉴를 이용할 수 있습니다.

항목	값
주소	/admin
아이디	admin
비밀번호	haeyul8000

테스트 고객

고객명	전화번호	방문 횟수	등급	비고
김신규	010-1111-0001	1회	새싹	신규
이중간	010-2222-0002	4회	새싹	다음 등급까지 1회
박아홉	010-3333-0003	10회	나무	3·5·10회 선물 보유
최열번	010-4444-0004	10회	나무	3·5회 선물 보유, 10회 선물 사용 완료
정완료	010-5555-0005	12회	나무	3·5회 선물 보유, 10회 선물 사용 완료
황금별	010-9999-0009	32회	해율 VIP	3·5·10·20·30회 선물 전부 보유 (VIP 화면 확인용)

---

프로젝트 구조

haeyul-passport/
├── src/
│   ├── app/                    # Next.js App Router
│   │   ├── layout.tsx          # 루트 레이아웃
│   │   ├── page.tsx            # 홈 화면
│   │   ├── actions.ts          # 고객용 Server Actions (가입/로그인/방문/선물함)
│   │   ├── visit/               # QR 접속 (가입/로그인)
│   │   ├── welcome/              # 가입 완료 안내 (여권 설명서 링크 포함)
│   │   ├── guide/                # 해율 여권 설명서 (등급/방문 선물 안내, 로그인 불필요)
│   │   ├── passport/            # 전자여권 홈 / 방문기록 / 선물함
│   │   │   └── rewards/         # 내 선물함 (직원확인으로 즉시 사용 처리)
│   │   ├── admin/                # 관리자 로그인 / 대시보드 / 고객관리 / 방문관리 / 선물관리 / VIP관리 / 설정
│   │   │   ├── login/            # 관리자 로그인
│   │   │   ├── customers/        # 고객 목록·검색 / 상세
│   │   │   ├── visits/           # 방문 기록 관리 (오늘 방문, 중복/비정상 확인, 수동 추가·취소)
│   │   │   ├── rewards/          # 선물 발급·사용 집계 / 선물 기준 관리
│   │   │   ├── vip/              # 해율 VIP 고객 관리
│   │   │   ├── settings/         # QR 관리 / 통계
│   │   │   │   └── qr-print/     # QR 인쇄용 A4 화면
│   │   │   └── actions.ts       # 관리자용 Server Actions
│   │   └── api/                 # API 라우트 (추후)
│   ├── lib/
│   │   ├── supabase/
│   │   │   ├── client.ts       # 브라우저용 클라이언트
│   │   │   ├── server.ts       # 서버용 클라이언트
│   │   │   └── admin.ts        # 관리자용 클라이언트
│   │   ├── session.ts          # 고객 세션 (쿠키)
│   │   ├── adminSession.ts     # 관리자 세션 (쿠키)
│   │   ├── qrSettings.ts       # 매장 QR 토큰 발급·재발급 (app_settings 테이블)
│   │   ├── tiers.ts            # 방문 등급 계산 (새싹~해율 VIP)
│   │   ├── constants.ts        # 상수
│   │   └── utils.ts            # 유틸리티 함수
│   ├── proxy.ts                 # QR 토큰 확인 후 방문 확인 쿠키 발급
│   └── types/
│       └── database.ts         # 타입 정의
├── supabase/
│   └── migrations/
│       ├── 001_initial_schema.sql
│       ├── 002_verify_employee_pin.sql
│       ├── 003_verify_admin_password.sql
│       ├── 004_reward_tiers.sql
│       ├── 005_reward_restore.sql
│       └── 006_customer_admin_note.sql
├── public/
│   ├── tiers/                  # 등급별 아이콘 (sprout/leaf/tree/forest/vip.svg)
│   └── manifest.json           # PWA 매니페스트
├── .env.example
├── .env.local                  # (git 제외)
└── README.md

---

개인정보 및 보안 주의사항

⚠️ 이 프로젝트는 시험판입니다. 실제 운영 전 다음 사항을 반드시 확인하세요.

• 개인정보처리방침과 이용약관을 법률 전문가에게 검토받으세요.
• SUPABASE_SERVICE_ROLE_KEY는 절대 클라이언트에 노출하지 마세요.
• 환경변수(.env.local)를 GitHub에 올리지 마세요.
• 관리자 비밀번호는 배포 후 즉시 변경하세요.

---

제작 진행 현황

단계	내용	상태
1단계	프로젝트 구조 + DB 설계	✅ 완료
2단계	신규회원 가입	✅ 완료
3단계	기존회원 접속	✅ 완료
4단계	QR 접속 + 방문등록 (매장 공통 QR 1개)	✅ 완료
5단계	전자여권 홈 화면	✅ 완료
6단계	방문기록 화면	✅ 완료
7단계	방문 등급(새싹~해율 VIP) + 3/5/10/20/30회 선물 자동 발급	✅ 완료
8단계	선물함 "직원확인" 버튼으로 즉시 사용 처리	✅ 완료
9단계	관리자 화면 (대시보드/고객관리/방문관리/선물관리/VIP관리/설정)	✅ 완료
10단계	개인정보 + 권한 보안 (QR 토큰 로테이션 포함)	✅ 완료
11단계	모바일 최적화	⬜ 대기
12단계	전체 테스트	🟡 진행 중
13단계	GitHub + Vercel 배포	✅ 완료