고객 메뉴

고객 메뉴는 handy.cafe/{your-slug}에 있는 공개 웹 페이지입니다. 고객은 테이블의 QR 코드를 스캔해 이 페이지에 접속합니다. 이 문서는 고객 흐름 전체를 설명하므로, 직원에게 안내하거나 도입 계획을 세울 때 활용할 수 있습니다.

URL 구조

각 테이블에는 handy.cafe/{cafe-slug}/{table-code} 형식의 고유 URL이 있습니다. QR 코드에는 이 URL과, 스티커가 진짜임을 증명하는 짧은 수명의 토큰이 함께 인코딩됩니다. 고객이 QR을 스캔하면 다음 순서로 진행됩니다.

1. 휴대폰이 기본 브라우저에서 URL을 엽니다.
2. 페이지가 클라우드 API를 통해 슬러그와 테이블 코드를 해석합니다.
3. 테이블이 out_of_order이면 사용 불가 안내가 표시됩니다.
4. 테이블이 idle이면 직원이 아직 고객을 앉히지 않았다는 설명과 함께 도움을 요청하라는 안내가 나타납니다.
5. 테이블이 in_use이면 6자리 보안 코드를 입력하라고 요청합니다.

보안 코드 확인

보안 코드는 현재 그 테이블에 앉아 있는 고객만 주문할 수 있도록 보장합니다. 사진이나 매장 밖에서 QR을 본 사람이 부정 주문을 넣는 일을 막아 줍니다.

고객이 코드를 입력하면 다음 순서로 처리됩니다.

1. API가 테이블에 저장된 해시 값과 코드를 검증합니다.
2. 유효하면 세션이 생성되고 토큰이 반환됩니다.
3. 토큰은 쿠키(hc_menu_session)에 저장됩니다. Bearer 토큰 대체 경로도 기기의 로컬 저장소에 유지됩니다. 일부 설정에서 서드파티 쿠키가 차단될 수 있는 iPhone Safari에서는 이 방식이 필요합니다.
4. 고객은 메뉴로 이동합니다.

세션은 발급 후 24시간 동안 유효합니다. 고객이 브라우저를 닫았다가 같은 기기에서 다시 와도 세션은 유지되며, 재검증 없이 다시 들어올 수 있습니다.

언어

메뉴는 아랍어, 독일어, 그리스어, 영어, 스페인어, 페르시아어, 프랑스어, 힌디어, 인도네시아어, 이탈리아어, 일본어, 한국어, 말레이어, 폴란드어, 포르투갈어, 루마니아어, 러시아어, 태국어, 타갈로그어, 터키어, 우크라이나어, 우르두어, 베트남어, 중국어의 24개 언어를 지원합니다.

첫 방문 시 브라우저의 Accept-Language 헤더를 확인해 가장 잘 맞는 언어를 선택합니다. 고객은 메뉴 상단의 선택기를 사용해 언제든지 언어를 바꿀 수 있습니다. 선택한 언어는 세션 동안 기억됩니다.

상품명, 설명, 재료는 자동 번역되지 않습니다. 메뉴 편집기에 입력한 언어 그대로 표시됩니다. "장바구니에 담기", "결제" 같은 UI 라벨과 결제 흐름 메시지는 모두 현지화됩니다.

테마

메뉴는 라이트 테마와 다크 테마를 지원합니다. 기본값은 기기 인식 방식입니다. 고객의 운영체제가 다크 모드라면 메뉴도 다크 모드로 열립니다. 상단의 테마 전환 스위치로 직접 바꿀 수 있습니다.

브랜드 헤더

메뉴 상단의 헤더에는 다음 항목이 표시됩니다.

이 필드들을 잘 꾸미면 고객이 매장 실제 간판과 같은 브랜드를 메뉴에서도 인식할 수 있습니다.

메뉴 탐색

메뉴는 카테고리별로 묶여 있습니다. 카테고리 안에서는 상품이 썸네일, 이름, 짧은 설명, 가격과 함께 표시됩니다.

상품을 탭하면 상품 시트가 열립니다. 시트에는 다음이 표시됩니다.

• 전체 사진
• 마크다운 설명
• 재료 한 줄
• 준비 시간 칩(메뉴에 준비 시간 표시가 켜져 있을 때만)
• 구성된 경우 단위 레이블(예: "250 ml")
• 상품에 연결된 각 변형 그룹의 선택기
• 수량 스테퍼
• 장바구니에 담기 버튼

필수 변형 그룹이 있으면 고객이 옵션을 선택할 때까지 장바구니에 담기 버튼이 비활성화됩니다.

장바구니

장바구니 아이콘은 모든 화면에서 접근할 수 있도록 고정된 위치에 있습니다. 사이트 안에서 이동해도 장바구니 내용은 유지됩니다. 장바구니에서 메뉴로, 다시 돌아와도 항목이 사라지지 않습니다.

장바구니에서 고객은 다음을 할 수 있습니다.

• 줄별 수량 조절
• 줄 삭제
• 선택 사항 메모 추가
• 전화번호 제공(선택 사항)

소계, 부가세, 총액은 실시간으로 표시됩니다.

주문하기

결제 단계에서는 구성에 따라 하나 또는 두 개의 결제 수단이 표시됩니다.

현금

온라인 결제가 설정에서 비활성화되어 있으면 현금만 표시됩니다. 고객이 주문을 확인하면 즉시 제출됩니다. 주문이 도착하면 고객은 캐셔에게 결제합니다.

온라인 (Stripe Checkout)

온라인 결제가 활성화되어 있으면 온라인이 선택지로 나타납니다. 제출 시 다음이 진행됩니다.

1. 주문이 대기 상태로 생성됩니다.
2. Stripe Checkout 클라이언트 시크릿이 반환됩니다.
3. Stripe 임베디드 UI가 인라인으로 열립니다. 고객은 카드 정보를 입력합니다.
4. 승인에 성공하면 Stripe가 청구를 확정하고 주문이 결제 완료로 바뀝니다.
5. 고객은 성공 페이지를 봅니다.

결제가 실패하거나 중단되면 주문은 대기 상태로 남습니다. 같은 세션에서 다시 시도할 수 있고, 직원이 주문을 주문 대시보드에서 취소할 수도 있습니다.

성공 페이지

성공적으로 제출된 뒤 고객은 영수증 페이지로 이동합니다. 이 페이지에는 다음이 표시됩니다.

• 주문 번호와 시간
• 수량, 변형, 줄별 합계가 포함된 모든 항목
• 소계, 부가세, 총액
• 결제 수단
• 결제 상태 아이콘(현금은 대기, 온라인은 결제 완료)
• 세션을 유지한 채 메뉴로 돌아가는 "다시 주문하기" CTA
• "메뉴로 돌아가기" 링크

주문 상태 폴링

제출 후에는 고객 화면이 상태 엔드포인트를 폴링해 주방 업데이트를 반영합니다. 직원이 항목을 preparing에서 ready로 바꾸면, 고객은 몇 초 안에 해당 줄의 배지 업데이트를 볼 수 있습니다.

이 기능은 카운터 픽업 서비스에 특히 유용합니다. 고객은 메뉴가 주문 준비 완료를 알려 줄 때까지 테이블에서 편하게 기다리면 됩니다.

고객이 할 수 없는 것

• 보안 코드 없이 메뉴를 볼 수 없습니다. 검증 단계는 항상 필요합니다.
• idle이나 out_of_order 상태의 테이블에는 주문할 수 없습니다.
• 제출한 주문을 고객이 직접 수정하거나 취소할 수는 없습니다. 취소는 주문 대시보드에서 직원이 수행합니다.

깔끔한 고객 경험을 위한 팁

• QR 스티커에는 카페 이름과 "스캔해서 주문하세요. 코드는 직원에게 문의하세요." 같은 명확한 안내를 넣으세요. 그렇지 않으면 고객이 검증 단계를 놓치는 경우가 있습니다.
• 카테고리와 상품 이름은 짧게 유지하세요. 이름이 길면 모바일에서 줄이 바뀌고 이미지가 아래로 밀립니다.
• 상품마다 최소 한 장의 사진을 올리세요. 사진 위주의 메뉴가 텍스트만 있는 메뉴보다 주문 전환율이 높습니다.
• 동적 추정치가 학습되기 전까지는 메뉴에 준비 시간 표시를 켜지 마세요. 처음 30일 동안은 정적 값이 너무 크거나 너무 작을 수 있고, 고객이 이를 알아챌 수 있습니다.
• 고객에게 문을 열기 전에 본인 휴대폰으로 전체 흐름을 먼저 테스트하세요. 실제 QR을 스캔하고, 코드를 입력하고, 테스트 주문을 넣고, 그 주문이 대시보드에 표시되는지 확인합니다.