[공통] 주문 상세 · 취소 · 사이즈 변경

화면 정보

Screen ID	Screen Title	Screen Path
ORD-DETAIL-01	주문 상세	`/mypage/order/{orderNumber}`
ORD-CXL-01	주문 취소	`/mypage/order/{orderNumber}/cancel`
ORD-SIZE-01	사이즈 변경	`/mypage/order/{orderNumber}/size`

개요

주문 상세(ORD-DETAIL-01), 주문 취소(ORD-CXL-01), 사이즈 변경(ORD-SIZE-01) 정책. 회원·비회원 공통 기준이며, 비회원은 customerName / customerPhone 파라미터로 인증을 대체한다.

ORD-DETAIL-01 — 주문 상세

화면 구성

주문 상세 (ORD-DETAIL-01 / ORD-LOOKUP-02)
├── 헤더                    ← 뒤로가기 / "주문 상세 내역"
├── 기본 정보               ← 매장명 / 주문번호 / 주문일 / 결제일
├── 주문 상품 정보
│   ├── 상품 선택 체크박스  ← 전체 선택 카운트 표시
│   ├── 상단 버튼           ← 주문 취소 / 사이즈 변경 / 반품 신청
│   ├── 상품 상세 정보
│   └── 구매 확정 버튼 (상품별)
├── 배송 정보               ← 배송지 변경 버튼 포함
├── 결제 정보
└── 안내사항

매장 정보 표시 기준

조건	표시 기준
`isOffline = false`	스토어별 온라인 매장명
`isOffline = true`	`offlineStoreName`
라플 유형	라플 스토어

온라인 매장 표시 문구는 스토어별 문서에서 정의한다.

상단 버튼 활성화 조건

체크박스로 상품을 선택해야 버튼이 활성화된다. 선택된 모든 상품이 조건을 만족해야 활성화.

주문 취소

상품 유형	취소 가능 조건
일반 상품	`productStatus == PENDING`
기프트카드	`productStatus != CONFIRMED`

사이즈 변경

항목	조건
상품 상태	선택 상품 전체 `productStatus == PENDING`
배송 상태	`shippingStatus == READY`
주문 상태	`status != CANCELED`
라플 상품	라플 유형 주문 → 변경 불가 (스토어 문서에서 라플 식별 기준 정의)
기프트카드	`isGiftCard == true` → 변경 불가
onlyPay 상품	`onlyPay == true` → 변경 불가
원 상품과 다른 상품 사이즈	동일 상품 내 사이즈만 변경 가능
현재 사이즈와 동일 선택	변경 불가 (“변경할 사이즈를 선택해주세요” 토스트)

비회원은 기프트카드 상품 주문 불가이므로 기프트카드 조건은 실질적으로 비회원에게 적용되지 않는다.

반품 신청

조건	기준
상품 상태	`productStatus == DELIVERED` 또는 `RETURNED`
최종 처리 제외	`productStatus != CANCELED` AND `!= CONFIRMED`
중복 방지	`latestRequest == null`

구매 확정

항목	기준
단위	상품별 개별 처리 (`orderProductId` 기준)
클릭 동작	확인 팝업 표시 → 확정 선택 시 API 호출
교환 상품	`latestRequest == EXCHANGE`이면 `latestRequestOrderNumber` 함께 처리

배송지 변경 버튼 표시 조건

조건	기준
배송 상태	`shippingStatus == READY`
주문 상태	`status != CANCELED`
주문 유형	`isOffline == false` (온라인 주문만)

상품별 제한사항 표시

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

결제 정보 항목

항목	필드
총 주문 금액	`totalPrice`
상품 금액	`productPrice`
배송비	`deliveryPrice`
총 할인	`discountPrice`
쿠폰 할인	`couponDiscount`
마일리지 사용	`usedMileage`
예치금 사용	`usedMoney`
총 결제 금액	`paidPrice`
마일리지 적립	`earnedMileage`
결제 수단	`payMethod`
적용 쿠폰	`appliedCoupons[]`

ORD-CXL-01 — 주문 취소

화면 구성

주문 취소 (ORD-CXL-01)
├── 헤더                    ← 뒤로가기 / "주문 취소"
├── 기본 정보               ← 매장명 / 주문번호 / 주문일
├── 취소 사유 선택          ← 드롭다운 (기타 선택 시 입력 필드 추가)
├── 취소 상품 상세          ← 이미지 / 브랜드 / 상품명 / 사이즈 / 수량 / 가격
├── 주문자 정보
├── 배송 정보
├── 취소 상세 정보          ← 총 주문 / 할인 / 환불 금액
└── 주문 취소 버튼          ← 사유 선택 시 활성화

취소 사유 선택

옵션
단순 변심
배송 지연
제품정보 상이
서비스 불만족
기타 사유

“기타 사유” 선택 시 텍스트 입력 필드 추가 노출 (빈 값 허용)
사유 미선택 시 “주문 취소” 버튼 비활성화

환불 금액 표시 기준

항목	기준
총 환불 금액	`willCancelAmount` (빨간색 표시)
반환 예치금	`willReturnMoney`
반환 적립금	`willReturnMileage`
결제 수단 환불	`payMethod` 값에 따른 한국어 안내
총 할인 금액	라플 유형 주문이면 숨김

주문 취소 버튼 동작

“주문 취소” 클릭 → “정말로 주문을 취소하시겠습니까?” 팝업
확인 → 취소 API 호출
성공 → 결제 취소 내역(ORD-CXL-LIST-01)으로 이동
실패 → 오류 메시지, 현재 화면 유지

ORD-SIZE-01 — 사이즈 변경

화면 구성

사이즈 변경 (ORD-SIZE-01)
├── 헤더                    ← 뒤로가기 / "사이즈 변경"
├── 기본 정보               ← 매장명 / 주문번호 / 결제일
├── 주문 상품 정보          ← 이미지 / 브랜드 / 상품명 / 현재 사이즈 / 수량
├── 사이즈 선택 드롭다운    ← 재고 있는 사이즈만 표시
├── 주문자 정보
├── 배송 정보
├── 결제 정보 (총 주문 금액)
└── 저장 / 취소 버튼

사이즈 선택 드롭다운

항목	기준
기본값	현재 주문된 `sizeName`
표시 옵션	`isSoldOut == false`인 사이즈만
단독 사이즈	`isLast == true`이면 “S (단독)” 형태 표시
안내 문구	“재고가 있는 사이즈만 표시됩니다”
전체 품절 시	“변경 가능한 사이즈가 없습니다”

저장 버튼 동작

상황	동작
기존 사이즈와 동일 선택	“변경할 사이즈를 선택해주세요” 토스트, 저장 안 됨
다른 사이즈 선택	사이즈 변경 API 호출
성공	“사이즈 변경이 완료되었습니다” 토스트 → 주문 상세로 복귀
실패	오류 메시지, 현재 화면 유지

API 연동

1. 주문 상세 조회

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

필드	활용
`orderNumber`, `orderedAt`, `paidAt`	기본 정보
`store`, `isOffline`, `offlineStoreName`	매장 정보
`isGiftCard`	사이즈 변경 가능 여부 판단
`status`, `shippingStatus`	배송지 변경 / 취소 조건 판단
`products[].productStatus`	버튼 활성화 조건 판단
`products[].latestRequest`	반품/교환 중복 신청 방지
`products[].latestRequestOrderNumber`	교환 상품 구매 확정 시 사용
`products[].unavailableMileage` / `unavailableCoupon`	제한사항 표시
`products[].earnedMileage`	적립 예정 마일리지
`productPrice`, `deliveryPrice`, `discountPrice`, `couponDiscount`, `usedMileage`, `usedMoney`, `totalPrice`, `paidPrice`, `earnedMileage`, `payMethod`	결제 정보
`appliedCoupons[]`	적용 쿠폰 목록

2. 취소·반품 사전 정보 조회

엔드포인트: POST /v1/orders/requests/{orderNumber}/pre-paid

{
  "customerName": "string",
  "customerPhone": "string",
  "orderProductIds": [0],
  "orderRequestType": "CANCEL"
}

응답 필드	활용
`willCancelAmount`	총 환불 금액
`willReturnMoney`	반환 예치금
`willReturnMileage`	반환 적립금
`deliveryAmount`	배송비

3. 주문 취소 실행

엔드포인트: POST /v1/orders/requests/{orderNumber}/cancel

{
  "cancelOrderProducts": [
    {
      "cancelOrderProductId": 0,
      "cancelReason": "단순 변심"
    }
  ],
  "customerName": "string",
  "customerPhone": "string"
}

성공 → 결제 취소 내역(ORD-CXL-LIST-01)으로 이동
cancelReason: 기타 사유 선택 시 입력 텍스트 사용

4. 사이즈 조회

엔드포인트: GET /v1/products/{productId}/sizes

필드	활용
`sizeName`	드롭다운 옵션 라벨
`productSizeId`	변경 API 요청 시 사용
`isSoldOut`	`false`인 것만 노출
`isLast`	`true`이면 “(단독)” 표시

5. 사이즈 변경 실행

엔드포인트: POST /v1/orders/change/{orderNumber}/size

{
  "changeToProductSizeId": 0,
  "orderProductId": 0
}

성공 → 토스트 후 주문 상세로 복귀 및 데이터 갱신

6. 배송지 변경

목적	엔드포인트
변경 가능 여부 확인	`GET /v1/orders/change/{orderNumber}/available`
배송지 목록 조회	`GET /v1/users/addresses`
배송지 변경 저장	`POST /v1/orders/change/{orderNumber}/address`

기존 배송지: userAddressId 전달
새 배송지: newUserAddress 객체 전달

7. 구매 확정

엔드포인트: POST /v1/orders/confirms/{orderNumber}

{
  "customerName": "string",
  "customerPhone": "string",
  "orderProductIds": [0]
}

교환 상품(latestRequest == EXCHANGE)은 latestRequestOrderNumber 함께 처리
성공 시 해당 상품 상태 CONFIRMED으로 업데이트

에러 처리 요약

증상	예상 원인	1차 조치
주문 상세 미로드	API 실패 또는 `orderNumber` 미전달	API 응답 및 파라미터 확인
버튼 전체 비활성화	상품 미선택 또는 상태 조건 불충족	체크박스 선택 상태 + `productStatus` 확인
사이즈 변경 버튼 비활성화	라플/기프트카드/onlyPay 상품, 또는 상태 조건 불충족	상품 조건 및 `shippingStatus` 확인
취소 후 ORD-CXL-LIST-01 미이동	취소 API 실패 또는 네비게이션 누락	성공 응답 후 이동 로직 확인
사이즈 드롭다운 비어있음	전체 품절 또는 API 실패	`isSoldOut` 값 및 API 응답 확인
사이즈 변경 후 상세 미갱신	복귀 후 데이터 재조회 미실행	주문 상세 진입 시 재호출 확인
배송지 변경 버튼 미표시	`shippingStatus` / `isOffline` 조건 불충족	조건 값 확인
구매 확정 팝업 미표시	팝업 분기 누락	클릭 이벤트 → 팝업 → API 호출 순서 확인

변경 이력

버전	날짜	변경 내용
v1.0	2026-07-06	최초 작성