해율 자연의 흐름 전자여권
자연의 흐름을 맛으로 전합니다.
해율만두전골에서 운영하는 전자여권형 멤버십 웹앱입니다.
매장 전체에서 동일한 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 데이터베이스 설정
- supabase.com에서 무료 프로젝트를 생성합니다.
- 프로젝트 대시보드 > SQL Editor를 엽니다.
supabase/migrations/001_initial_schema.sql 파일 내용을 복사하여 실행합니다.- 이어서
supabase/migrations/003_verify_admin_password.sql 파일 내용을 복사하여 실행합니다. (관리자 비밀번호 확인용 함수)
- 이어서
supabase/migrations/004_reward_tiers.sql 파일 내용을 복사하여 실행합니다. (3/5/10/20/30회 선물 + 자동 발급 트리거)
- 시험 데이터가 자동으로 생성됩니다.
002_verify_employee_pin.sql은 예전에 있었던 직원 PIN 확인 화면(/staff, 현재는 제거됨)을 위한 함수라 신규 설치 시에는 실행하지 않아도 됩니다.
5. 개발 서버 실행
npm run dev
브라우저에서 http://localhost:3000을 열어 확인하세요.
Supabase 프로젝트 생성 방법
- supabase.com에 접속하여 회원가입/로그인합니다.
- New Project 버튼을 클릭합니다.
- 프로젝트 이름:
haeyul-passport
- 데이터베이스 비밀번호: 안전한 비밀번호를 설정하세요.
- 지역(Region): Northeast Asia (Tokyo) 또는 가장 가까운 지역을 선택하세요.
- Create new project를 클릭하면 1~2분 내에 생성됩니다.
- 프로젝트가 생성되면 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
- GitHub에 이 저장소를 푸시합니다.
- vercel.com에서 New Project를 클릭합니다.
- GitHub 저장소를 연결합니다.
- 환경변수를 설정합니다 (
.env.example 참고).
- 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 배포 | ✅ 완료 |
