Standard Checkout

docs/hcs-asset/standard-checkout.md

id: 'standard-checkout' status: not-started

Standard Checkout

Reference

기준 소스: apps/makitt-standard-commerce/src/components/assets/standard-checkout/standard-checkout.tsx
구조: 국가선택 → 배송지폼 → 배송옵션 → 쿠폰/적립금 → 결제수단 + payment-widget → 가격요약 → 결제버튼

React Component

Path: apps/makitt-standard-commerce/src/components/assets/standard-checkout/
Status: implemented
데이터 흐름:
- shopApi.getCheckout(checkoutId)
- shopApi.updateCheckoutShippingAddress()
- shopApi.updateCheckoutShipping()
- shopApi.applyCheckoutCoupon() / removeCheckoutCoupon()
- shopApi.applyCheckoutPoints()
- shopApi.updateCheckoutPaymentMethod()
- shopApi.prepareCheckoutPayment() → executePaymentSession()
반응형: single column, max-width 제한

HCS Asset

Path: apps/builder/data/hcs-asset/standard-checkout.json
Status: not-started
UI Kit / Group: standard-commerce / checkout
구현 범위:
- 배송지 입력 (firstName/lastName 분리, phoneCountryCode)
- 배송메모/출입방법 (ShippingFieldConfig 기반)
- 배송 옵션 선택 (line item별)
- 보유 쿠폰 적용/해제 + 할인코드 입력
- 적립금 적용
- 결제 수단 선택 + payment-widget 컴포넌트
- pricing breakdown (서버 formatted 값 바인딩)
- 예상 적립 포인트
- checkout.pay domain action 연결

Prerequisites

makitt-server (shop-api)

API	Method	Endpoint	Status
Get Checkout	GET	`/checkout/{checkoutId}`	available
Update Shipping Address	PUT	`/checkout/{checkoutId}/shipping-address`	available
Update Shipping	PUT	`/checkout/{checkoutId}/shipping`	available
Apply Coupon	POST	`/checkout/{checkoutId}/coupons`	available
Remove Coupon	DELETE	`/checkout/{checkoutId}/coupons/{code}`	available
Apply Customer Coupon	POST	`/checkout/{checkoutId}/coupons/customer`	available
Apply Points	POST	`/checkout/{checkoutId}/points`	available
Remove Points	DELETE	`/checkout/{checkoutId}/points`	available
Available Coupons	GET	`/checkout/{checkoutId}/available-coupons`	available
Payment Settings	GET	`/payment-settings`	available
Update Payment Method	PUT	`/checkout/{checkoutId}/payment-method`	available
Prepare Payment	POST	`/checkout/{checkoutId}/payments/prepare`	available

makitt-server (admin-api)

API	Method	Endpoint	Status
Payment Processor Settings	GET/PUT	`/shops/{shopId}/payment-settings`	available

makitt-server (도메인/모델링)

항목	내용	Status
Checkout Entity	PK: `CHECKOUT#{checkoutId}`, SK: `METADATA`	available
PricingSummary	subtotal, productDiscount, couponDiscount, promotionDiscount, pointsDiscount, total	available
AppliedCoupon	다중 쿠폰 적용 (checkout 임베디드)	available
ShippingFieldConfig	market별 배송메모/출입방법 설정	available
Payment Entity	PK: `PAYMENT#{paymentId}`, SK: `METADATA`	available
PaymentApplication	prepare, reconcile, cancel	available
CurrencyFormatter	서버 사이드 금액 포매팅	available

makitt-web (셀러 어드민 UI)

기능	설명	Status
Payment Processor 설정	PG 키 입력, 결제수단 활성화	available

makitt-shop (HCS 렌더링)

항목	설명	Status
`checkout.detail` resource	체크아웃 전체 데이터 조회	available
`checkout.availableCoupons` resource	적용 가능 쿠폰 목록	available
`checkout.paymentMethods` resource	결제 수단 목록	available
`checkout.updateAddress` action	배송지 저장	available
`checkout.updateShipping` action	배송 옵션 변경	available
`checkout.applyCoupon` action	쿠폰 적용	available
`checkout.removeCoupon` action	쿠폰 해제	available
`checkout.applyPoints` action	적립금 적용	available
`checkout.removePoints` action	적립금 해제	available
`checkout.updatePaymentMethod` action	결제 수단 변경	available
`checkout.pay` action	결제 실행 (PG 오케스트레이션)	available
`payment-widget` renderer	PG SDK 마운트 컴포넌트	available (placeholder)

HCS Conversion Notes

checkout 데이터는 checkout.detail resource로 section에 바인딩, as: "checkout"으로 접근
가격 표시는 모두 서버 formatted 값 사용: {{checkout.pricing.formattedTotal}} 등
쿠폰 적용/해제는 refreshResource 패턴으로 checkout 데이터 갱신 필요
배송지 폼은 form + field 패턴 사용, submit → checkout.updateAddress action
payment-widget은 checkout resource 하위에 배치하여 {{checkout.checkoutId}}를 바인딩
결제 버튼은 checkout.pay action에 checkoutId, returnUrl, cancelUrl을 target으로 전달
배송메모 옵션은 ShippingFieldConfig에서 서버가 제공 → select 컴포넌트로 바인딩
country 변경 시 배송 옵션, 결제 수단이 변경될 수 있으므로 refreshResource 체인 필요