[WORKSOUT] 기프트카드 주문 상세

화면 정보

Screen ID	Screen Title	Screen Path
ORD-GIFT-01	기프트카드 주문 상세	`/mypage/order/{orderNumber}` (기프트카드 분기)

개요

기프트카드 상품(isGiftCard == true) 주문의 상세 화면(AC_205_Order_Detail [Giftcard]). 일반 주문 상세(ORD-DETAIL-01)와 동일 엔드포인트를 사용하되 isGiftCard 값으로 화면을 분기한다. common 대응 문서 없음.

화면 구성

AC_205_Order_Detail [Giftcard]
├── 헤더                    ← 뒤로가기 / "주문 상세"
├── 기본 정보               ← 매장명 / 주문번호 / 주문일
├── 주문 상품 정보
│   ├── 주문 취소 버튼      ← 조건부 표시
│   ├── 체크박스 + 상품 정보
│   └── 제한사항 안내       ← 마일리지/쿠폰 사용 불가 문구
├── 안내사항               ← 기프트카드 사용 방법 / 코드 등록 절차
├── 주문자 정보
├── 수취인 정보             ← 수령인명 / 전화번호 / 선물 메시지
├── 배송 정보
└── 결제 정보

일반 주문 상세(ORD-DETAIL-01)와의 차이점

항목	일반 (ORD-DETAIL-01)	기프트카드 (ORD-GIFT-01)
구매 확정 버튼	있음 (수동)	없음 (수령인 코드 등록 시 자동 처리)
사이즈 변경	가능	불가
교환/반품	가능	불가 (취소만 가능)
마일리지 사용/적립	가능	불가 (`unavailableMileage == true`)
쿠폰 사용	가능	불가 (`unavailableCoupon == true`)
배송비	상품별 다름	보통 0원
수취인 정보 영역	없음	있음 (선물 메시지 포함)

정책

주문 취소 버튼 조건

항목	기준
표시 조건	`shippingStatus == READY_DELIVERY`
취소 가능	`productStatus == PREPARING`
취소 불가	`productStatus == CONFIRMED` (이미 코드 등록 완료)
취소 불가 시 문구	“이미 사용된 기프트카드는 취소할 수 없습니다”

취소 버튼 클릭 시 주문 취소 화면(ORD-CXL-LIST-01 상위 흐름, AC_202_Order_Cancel)으로 이동한다. WORKSOUT의 기프트카드 취소 가능 조건은 일반 상품과 다르다(productStatus == PREPARING 기준).

기프트카드 상태 흐름

배송 상태	의미	productStatus
`READY`	기프트카드 발송 전	`PREPARING`
`DELIVERED`	기프트카드 코드 발송 완료	`PREPARING` → 수령 대기
`CONFIRMED`	수령인이 코드 등록 완료	`CONFIRMED`

자동 확정 트리거: 수령인이 마일리지(AC_130_Mileage)에서 기프트카드 코드번호를 등록하면 productStatus가 CONFIRMED으로 자동 변경된다. 별도 운영 개입 불필요.

상품 제한사항 표시

필드	표시 문구
`unavailableMileage == true`	“적립금 사용/적립이 불가합니다.”
`unavailableCoupon == true`	“쿠폰 사용이 불가합니다.”

기프트카드 주문은 항상 두 필드가 true이다.

수취인 정보 표시 기준

항목	필드	비고
수령인명	`receiverName`	—
수취인 전화번호	`receiverPhone`	—
선물 메시지	`shippingRequest`	미입력 시 빈 공간 표시 (별도 안내 없음)

수령인 구분

유형	특징
자가용	주문자 = 수령인 (동일 정보)
선물용	주문자 ≠ 수령인 (다른 정보)

API 연동

1. 기프트카드 주문 상세 조회

엔드포인트: GET /v1/orders/histories/{orderNumber}

일반 주문 상세와 동일한 엔드포인트. isGiftCard == true 여부로 화면 분기.

필드	활용
`isGiftCard`	`true`이면 이 화면으로 분기
`shippingStatus`	취소 버튼 표시 조건
`products[].productStatus`	취소 가능 여부 판단 (`PREPARING` vs `CONFIRMED`)
`products[].unavailableMileage`	마일리지 제한 문구 표시
`products[].unavailableCoupon`	쿠폰 제한 문구 표시
`products[].earnedMileage`	기프트카드는 보통 `0`
`receiverName`, `receiverPhone`	수취인 정보
`shippingRequest`	선물 메시지
`productPrice`, `deliveryPrice`, `usedMoney`, `discountPrice`, `couponDiscount`, `usedMileage`, `paidPrice`, `payMethod`, `paidAt`, `earnedMileage`	결제 관련 필드

기프트카드 식별 필드 예시

{
  "isGiftCard": true,
  "products": [
    {
      "unavailableMileage": true,
      "unavailableCoupon": true,
      "earnedMileage": 0,
      "productStatus": "CONFIRMED"
    }
  ]
}

2. 화면 분기 처리

GET /v1/orders/histories/{orderNumber} 응답 후
├── isGiftCard == true  → 기프트카드 주문 상세(ORD-GIFT-01) 렌더링
└── isGiftCard == false → 일반 주문 상세(ORD-DETAIL-01) 렌더링

에러 처리 요약

증상	예상 원인	1차 조치
화면 자체 미로드	API 실패 또는 `orderNumber` 미전달	API 응답 및 파라미터 확인
일반 상세로 잘못 진입	`isGiftCard` 분기 처리 누락	응답 `isGiftCard` 값 기준 분기 확인
취소 버튼 미표시	`shippingStatus` 조건 불충족	`READY_DELIVERY` 상태인지 확인
취소 시도 시 오류	`productStatus == CONFIRMED` 상태	“이미 사용된 기프트카드” 안내 처리 확인
`productStatus`가 CONFIRMED인데 고객이 모름	수령인이 코드 등록한 것	마일리지(AC_130) 코드 등록 여부 확인

미결 사항

항목	내용
라플 기프트카드 조합 여부	기프트카드 상품이 라플 유형 주문으로도 존재하는지 원본에 명시 없음 — 확인 필요

변경 이력

버전	날짜	변경 내용
v1.0	2026-07-30	최초 작성 (기프트카드 주문 상세 마스터.md 전체 기반)