[D2C-38] 체크아웃·쿠폰 적용·주문/결제 시뮬레이션 흐름 구현

[jjunier]

개요

본 PR은 D2C-38 체크아웃·쿠폰 적용·주문/결제 시뮬레이션 흐름 구현 작업을 develop 브랜치에 통합하기 위한 PR입니다.

D2C-37에서 구현한 장바구니 화면과 상품 관리 흐름을 기반으로, 사용자가 장바구니에서 체크아웃으로 진입한 뒤 쿠폰을 적용하고 주문을 생성하며 결제 성공/실패 시뮬레이션을 수행할 수 있도록 구매 핵심 흐름을 구현했습니다.

이번 작업에서는 체크아웃 화면, 쿠폰 적용, 주문 생성, 결제 시뮬레이션, 장바구니 생명주기 조정, 쿠폰 재사용 차단, 수량 제한 정책 보완을 포함했습니다.

---

포함 범위

체크아웃 화면 구현

• 체크아웃 페이지 UI 구성
• 비로그인 상태 체크아웃 접근 제한
• cart_id가 없거나 유효하지 않을 때 안내 처리
• 장바구니 기반 체크아웃 정보 조회
• 주문 상품 목록 표시
• 상품명, 브랜드명, 수량, 단가, 상품별 금액 표시
• 결제 요약 카드 구성
• 상품 금액, 쿠폰 할인, 최종 결제 금액 표시

쿠폰 적용 흐름 구현

• 쿠폰 코드 입력 및 적용 기능 구현
• POST /carts/{cart_id}/apply-coupon API 연동
• 쿠폰 적용 후 입력값 초기화
• 적용된 쿠폰명 표시
• 쿠폰 할인 금액 및 최종 결제 금액 반영
• 빈 쿠폰 입력 시 안내 메시지 표시
• 동일 쿠폰 재적용 시 경고 메시지 표시
• 결제 성공 이력이 있는 쿠폰 재사용 차단
• 쿠폰 적용 API와 주문 생성 API 양쪽에서 재사용 방어 로직 추가

주문 생성 및 결제 시뮬레이션

• POST /orders 주문 생성 API 연동
• 주문 생성 후 생성된 주문 ID 표시
• POST /payments/simulate 결제 성공/실패 시뮬레이션 API 연동
• 결제 성공/실패 결과를 checkout 화면 내 임시 피드백으로 표시
• 결제 성공 시 초록 계열 피드백 표시
• 결제 실패 시 빨간 계열 피드백 표시
• 결제 시뮬레이션 완료 후 성공/실패 버튼 재클릭 방지
• 결제 결과 확인 후 주문 내역 화면 이동 CTA 제공

장바구니 생명주기 정책 조정

• 주문 생성 시점에는 장바구니를 active 상태로 유지
• 결제 성공 시점에만 장바구니를 checked_out 상태로 전환
• 결제 실패 시에는 장바구니를 active 상태로 유지
• 프론트엔드 localStorage의 d2c_cart_id도 결제 성공 시에만 제거
• 주문 생성 후 결제 전 상태에서 장바구니로 돌아갈 수 있도록 흐름 조정

수량 제한 정책 보완

• 상품별 최대 장바구니 수량을 99개로 통일
• 장바구니 수량 수정 요청 schema를 1~99개로 제한
• 장바구니 상품 추가 요청 schema를 1~99개로 제한
• 기존 장바구니 수량과 추가 수량의 합계가 99개를 초과하지 않도록 백엔드 검증 추가
• 장바구니 수량 입력 UI의 최대값을 99개로 조정

---

검증 결과

프론트엔드 타입 체크를 실행하여 정상 통과를 확인했습니다.

cd apps/web
npm run typecheck

프론트엔드 빌드를 실행하여 정상 통과를 확인했습니다.

cd apps/web
npm run build

프론트엔드 개발 서버와 백엔드 서버를 함께 실행하여 체크아웃·쿠폰·주문·결제 흐름을 수동 확인했습니다.

cd apps/api
uvicorn backend.main:app --reload

cd apps/web
npm run dev

수동 확인 항목:

• /cart에서 주문 단계로 이동 확인
• /checkout 화면 렌더링 확인
• 장바구니 상품 목록 및 결제 요약 표시 확인
• WELCOME10 쿠폰 적용 확인
• 쿠폰 적용 후 입력값 초기화 확인
• 적용된 쿠폰명 표시 확인
• 쿠폰 할인 금액 및 최종 결제 금액 반영 확인
• 빈 쿠폰 입력 시 안내 메시지 확인
• 동일 쿠폰 재적용 시 경고 메시지 확인
• 주문 생성 버튼 클릭 시 주문 ID 표시 확인
• 주문 생성 후 결제 성공/실패 시뮬레이션 버튼 활성화 확인
• 결제 성공 시뮬레이션 API 호출 및 결과 표시 확인
• 결제 실패 시뮬레이션 API 호출 및 결과 표시 확인
• 결제 시뮬레이션 완료 후 두 결제 버튼 비활성화 확인
• 결제 성공 후 장바구니 종료 확인
• 결제 실패 후 장바구니 유지 확인
• 결제 성공한 쿠폰 재사용 차단 확인
• 상품별 최대 수량 99개 제한 확인
• 주문 내역 화면 이동 CTA 표시 및 /orders 이동 확인

---

브랜치 통합 방식

이번 PR의 통합 흐름은 아래와 같습니다.

feature/D2C-38-checkout-order-payment-flow
→ develop

D2C-38 병합 후에는 develop 브랜치에서 D2C-39 전용 feature 브랜치를 새로 분기하여 주문 내역 화면 및 결제 상태 확인 흐름 구현을 진행합니다.

---

향후 브랜치 운영 원칙

Sprint 2에서는 아래 브랜치 운영 원칙을 유지합니다.

• Jira 이슈키별 독립 feature 브랜치 생성
• 각 feature 브랜치는 develop에서 분기
• 작업 완료 후 develop으로 개별 PR 생성
• PR 단위로 CI 검증 후 병합
• 의미 있는 사용자 흐름 단위가 완료되면 develop을 main에 병합
• main은 배포 기준 브랜치로 유지
• 기능 작업이 누적된 장기 브랜치는 지양

---

체크리스트

• develop 브랜치에서 분기한 feature 브랜치에서 작업
• D2C-38 이슈키를 PR 제목과 설명에 포함
• 체크아웃 화면 UI 구현
• 장바구니 기반 체크아웃 정보 조회 연동
• 쿠폰 적용 API 연동
• 쿠폰 할인 금액 및 최종 결제 금액 반영
• 쿠폰 재사용 차단 로직 추가
• 주문 생성 API 연동
• 결제 성공/실패 시뮬레이션 API 연동
• 결제 결과 피드백 표시
• 주문 내역 화면 이동 CTA 제공
• 장바구니 생명주기 정책 조정
• 상품별 최대 수량 99개 제한 반영
• 사용자 쿠폰함 기능은 D2C-58 후속 작업으로 분리
• .env, node_modules, dist, cache 파일이 커밋에 포함되지 않도록 확인
• 로컬에서 프론트엔드 typecheck / build / dev 실행 확인