[WORKSOUT] 바코드

화면 정보

Screen ID	Screen Title	Screen Path
BARC-01	바코드	풀스크린 모달

개요

매장 POS 스캔용 회원 바코드 화면. 마이페이지 홈 (로그인 케이스)에서 바코드 아이콘 클릭 시 진입.

연동 시스템: 회원 시스템 · 쿠폰 시스템 · 매장 POS

---

화면 구성

BARC-01 (풀스크린 모달)
├── 헤더 X 버튼              ← 클릭 시 모달 닫기
├── 안내 텍스트              ← "{userName}님의 정보입니다."
├── 바코드 영역              ← user.userCode 기반 생성 (POS 스캔용)
├── 생년월일
├── 핸드폰 번호              ← 000-0000-0000 형식
├── 적립금 (마일리지)        ← 천 단위 구분자 + "원"
├── 예치금                   ← 천 단위 구분자 + "원"
└── 쿠폰                     ← 사용 가능 쿠폰 수 + 드롭다운 이름 목록

표시 정보 출처 및 형식

항목	데이터 출처	표시 형식
생년월일	user.userBirth	원본 값 그대로 표시
핸드폰 번호	user.userPhone	000-0000-0000 포맷팅
적립금	user.ownPoint	천 단위 구분 + “원”
예치금	user.ownMoney	천 단위 구분 + “원”
쿠폰 수	클라이언트 필터링된 쿠폰 개수	“N개” 표시
쿠폰 목록	클라이언트 필터링된 쿠폰 이름	드롭다운 펼침 시 이름 나열

---

정책

바코드 운영 기준

항목	기준
바코드 데이터	user.userCode
바코드 하단 숫자	미표시
POS 연동	스캔 시 매장 POS에 사용자 정보 즉시 표시
userCode 없을 때	“바코드를 생성할 수 없습니다” 메시지 + 직원 안내

바코드가 화면에 보이더라도 POS에서 인식되지 않는 경우가 있다. 이 경우 매장 직원에게 안내하여 수동 확인을 유도한다. 앱 자체의 바코드 생성 오류와 POS 인식 실패는 원인이 다를 수 있으므로, CS 접수 시 구분하여 확인해야 한다.

바코드 생성 스펙

라이브러리: react-barcode

<Barcode
  value={String(userCode)}
  width={4}
  height={120}
  displayValue={false}
/>

설정값	의미
value	userCode를 String으로 변환
width	바 두께 4
height	바코드 높이 120
displayValue	false (하단 숫자 미표시)

쿠폰 표시 기준

표시 대상: 아래 조건을 모두 통과한 쿠폰만 노출

제외 조건	설명
issuedType == DISCOUNT_KEY	할인 키 타입 쿠폰 제외
couponStatus == USE_N	사용 불가 상태 제외
couponStatus == USE_C	사용 완료 상태 제외

드롭다운 동작

• 접힘 상태: 사용 가능 쿠폰 수만 표시
• 펼침 상태: 조건을 통과한 쿠폰들의 이름 나열
• 쿠폰 없을 때: “보유한 쿠폰이 없습니다” 표시

이 화면에서 표시되는 쿠폰 수는 마이페이지 홈의 availableCouponCount와 집계 기준이 다를 수 있다. 마이페이지 홈은 API가 반환하는 availableCouponCount를 그대로 사용하는 반면, 바코드 화면은 클라이언트에서 직접 필터링한 결과를 사용한다. 수치가 다르게 보인다면 이 구조 차이를 먼저 확인한다.

데이터 없음 처리

상황	처리
userCode 없음	“바코드를 생성할 수 없습니다” + 직원 안내
생년월일 없음	“생년월일 정보 없음” 표시
전화번호 없음	“전화번호 정보 없음” 표시
적립금/예치금 없음	0원으로 표시
쿠폰 없음	“보유한 쿠폰이 없습니다” 표시

---

API 연동

사용자 정보 조회

엔드포인트: GET /v1/users/info — 바코드 화면 진입 시 호출

필드	활용
userName	안내 텍스트 “{userName}님의 정보입니다.”
userCode	바코드 생성 value
userBirth	생년월일 원본 표시
userPhone	전화번호 포맷팅
ownPoint	적립금 금액 포맷팅
ownMoney	예치금 금액 포맷팅
availableCouponCount	쿠폰 수 참고값

쿠폰 목록 조회

엔드포인트: 사용자 쿠폰 조회 API (엔드포인트 별도 확인 필요) — 바코드 화면 진입 시 호출

클라이언트 필터링 조건

userCoupons.filter(coupon =>
  coupon.issuedType !== IssuedType.DISCOUNT_KEY &&
  coupon.couponStatus !== 'USE_N' &&
  coupon.couponStatus !== 'USE_C'
)

표시 데이터: 필터링된 쿠폰의 couponName 나열

데이터 포맷팅

전화번호

userPhone?.replace(/(\d{3})(\d{4})(\d{4})/, '$1-$2-$3')
// "01012345678" → "010-1234-5678"

금액

(user?.ownPoint ?? 0).toLocaleString() + ' 원'
(user?.ownMoney ?? 0).toLocaleString() + ' 원'
// null/undefined → 0으로 처리

에러 처리 요약

증상	예상 원인	1차 조치
사용자 정보 미로드	GET /v1/users/info 실패	오류 메시지 + 재시도 버튼
쿠폰 정보 미로드	쿠폰 조회 API 실패	“쿠폰 정보를 불러올 수 없습니다” 표시
바코드 미생성	userCode 없음	“바코드를 생성할 수 없습니다” 메시지
전화번호 포맷팅 실패	정규식 미매칭 (자릿수 오류 등)	원본 데이터 그대로 표시
금액 포맷팅 실패	toLocaleString() 오류	원본 숫자 + “원” 표시
쿠폰 필터링 오류	클라이언트 예외	전체 쿠폰 목록 표시 (안전 fallback)

---

미결 사항

항목	내용
쿠폰 목록 조회 API 엔드포인트	원본 문서에도 “별도 확인 필요”로 명시됨 — 개발팀 확인 필요

---

변경 이력

버전	날짜	변경 내용
v1.0	2026-07-30	최초 작성 (바코드 마스터.md 이전)