# Commerce 쇼핑몰 개발 — invoice 프론트 규칙과 공개 v1 계약

기준: 2026-09-17 로컬 `invoice-frontend`와 `commerce-api` 소스. API의 2026-09-14 견적·구매자 결과 계약을 반영한다.
운영 배포 여부나 실결제 성공을 확인한 문서는 아니다. 연결 환경에서 계약이 다르면 자동으로 구형 API로 우회하지 말고 차이를 보고한다.
회원 지정 규칙은 commerce `docs/api/v1` 2026-09-28 계약을 반영한다(아래 §3, 운영 배포 후 적용).

## 1. 구현 전에 결정할 경계

- 기존 프로젝트의 프레임워크·컴포넌트·디자인을 유지한다. invoice는 구매 UX의 참고 구현이며 외부 쇼핑몰 전체를 invoice로 바꾸라는 뜻이 아니다.
- invoice 기준 신규 Vue는 Nuxt 4/Vue 3, HTML `<template>`, 순수 CSS `<style scoped>`, PascalCase 컴포넌트, `<script setup lang="ts">`, 개별 `const` 화살표 함수, Pinia setup store와 `storeToRefs`를 사용한다.
- 현재 invoice는 Tailwind v4/DaisyUI v5다. 오래된 Pug·`__` separator 지침을 새 HTML 파일에 적용하지 않는다. 기존 Pug를 수정하는 경우에만 해당 파일의 문법을 유지한다.
- 적용 근거는 대상 파일·`package.json`·현재 디자인 규칙과 최신 워크스페이스 `_guide`를 함께 확인한다. 지침끼리 충돌하면 오래된 규칙을 다른 프로젝트의 공통 규칙으로 퍼뜨리지 않는다.
- SSR에서 `window`·스토리지는 mount/client 경계 안에서 접근한다. `$confirm`은 취소 시 reject한다. invoice의 전역 함수·prototype은 외부 앱에 있다고 가정하지 않는다.
- 기존 버튼·입력·모달·간격·오류 표시를 재사용한다. warm-shop 색상과 고정 치수는 Next 샘플의 디자인이지 모든 가맹점의 필수 브랜드 규칙이 아니다.

| 참고 대상 | 재사용할 것 | 그대로 복사하지 않을 것 |
|---|---|---|
| invoice 화면 | 옵션·재고·수량, 구매 불가 이유, 로그인 복귀, 모바일 상태·접근성 | 내부 `mall/*` 경로, `useHttp().commerceApiHttp`, 숫자 enum, 내부 전역 함수 |
| commerce-api v1 | controller·service·응답 serializer·격리 테스트의 공개 계약 | 내부 mall/admin 인증·필드, 과거 SDK 타입만 보고 추측한 envelope |
| 가맹점 BFF | 서버 Basic Auth, HttpOnly 세션, 허용한 라우트별 입력 검증 | 브라우저 secret/JWT, 임의 path/method를 전달하는 catch-all 프록시 |

Invoice 내부 HTTP의 `Bootpay-Client-Key`·`Bootpay-Subdomain`·`Bootpay-Mall-Host`를 공개 v1의 서버 Basic Auth 대신 쓰지 않는다.
호스팅 `/b`와 `__tc`·`__du` 설정은 API/호스팅 화면의 책임이다. 가맹점에서 세션 암호화 URL을 새로 만들지 않는다.

## 2. 구현 순서와 지원 범위

1. 이미 받은 Commerce 키를 서버 환경변수로 재사용한다. 없을 때만 관리자에서 현재 프로젝트의 키를 확인한다. 기본 `auto_setup=false`; 설정·sandbox 변경은 별도 요청 범위다.
2. 서버에서 `GET /v1/store`로 실제 상점·회원/비회원 정책을 확인하고 카탈로그 → 상세 → 장바구니/바로 구매 → 로그인 복귀를 붙인다.
3. `POST /v1/cart/order-preview` → `quote_token` → `POST /v1/orders/prepare` → 반환 URL 원문 이동 → `GET /v1/orders/{order_number}/result`를 구현한다.
4. 지원하는 기능만 CTA로 노출한다. 단건 개인 주문 견적은 구독을 지원하지 않는다. 추가옵션·기업/부서·쿠폰·포인트·구독·리뷰 작성은 해당 v1 계약과 구현을 확인한 뒤 확장한다.
   Next.js 는 `generate_commerce_code(features=[…])`가 상품평·상품문의·공지·FAQ·1:1 문의·찜·쿠폰함/적립금을 같은 BFF 구조로 생성한다(쿠폰·적립금 적용은 호스팅 주문서).
5. 생성 결과의 `status`와 `missing_requirements`를 확인한다. Next.js 외 프레임워크에는 현재 실행 코드 대신 이 구현 가이드를 반환한다. 기존 템플릿의 브라우저 JWT·범용 프록시·잘못된 장바구니 필드는 재사용하지 않는다. 선택한 프레임워크를 유지하며 명시적인 BFF를 구현한다.

### 생성 앱의 회원 모드 — `generate_commerce_code(member_mode)`

| `member_mode` | 회원 식별 | 쓸 수 없는 것 |
|---|---|---|
| `bootpay_jwt`(기본·권장) | 로그인 응답 JWT 를 봉인 서버 세션에 두고 `Bootpay-User-JWT` 헤더로 보낸다 | — |
| `own_login` | 쇼핑몰 서버가 자기 로그인 세션으로 회원을 관리한다. `users/login` 응답의 `user_id` 만 서버 세션에 봉인하고 JWT 는 버린다. 모든 회원 요청에 서버 세션의 `user_id` 를 넣는다(GET/DELETE 쿼리, 그 밖은 본문). `Bootpay-User-JWT` 는 보내지 않고, 브라우저에는 원문 id 대신 해시를 내린다 | `/b` 자동 로그인(`use_auto_login=false`), `users/session` — 본인 프로필(`users/me`)은 서버 세션 `user_id` 로 생성된다(GET 쿼리·PATCH 본문) |

- `own_login` 은 사용자가 자체 로그인 세션을 명시했을 때만 쓴다. secret_key 가 새면 임의 회원으로 행동할 수 있고, commerce 운영 배포 전에는 운영에서 동작하지 않을 수 있다(운영 배포 후 적용, 기본값 아님).
- `own_login` 에서도 본인 프로필(`users/me`, `user_id`)·비밀번호 변경·탈퇴(`user_id`)와 비밀번호 찾기(`login_id`)는 유지된다.
- 오류 매핑: 2302(`USER_NOT_MATCH`) → 다시 로그인, 2300(`USER_NOT_FOUND`) → 세션에서 회원을 지운 뒤 로그인, 420(`USER_SESSION_INVALID`) → 로그인 필요.

### 개발 서버 Origin

- `next dev` 는 `APP_ORIGIN` 과 같은 Origin 외에 요청 Host 와 같은 Origin(다른 포트·LAN IP)도 받고, 서버 콘솔에 `app_origin_mismatch` 경고로 기대값·실제값과 `.env.local` 의 `APP_ORIGIN` 을 고치라는 안내를 한 번 남긴다.
- `next start`(운영)는 `APP_ORIGIN` 과 같은 Origin 의 상태 변경 요청만 받는다. 다르면 403 `INVALID_ORIGIN`.

## 3. 서버 견적 → 주문 준비

`BootpayCommerce`의 확인된 저수준 `post/get`을 사용할 수 있다. SDK에 신규 고수준 메서드가 있다고 추측하지 않는다.
SDK base URL이 `/v1`을 포함하므로 저수준 경로는 `cart/order-preview`, `orders/prepare`다.

```json
{
  "cart_items": [{ "product_id": "<product_id>", "product_option_id": "<option_id>", "quantity": 2 }],
  "shipping_address": { "zipcode": "12345" }
}
```

- 모든 호출은 서버 Basic Auth. 회원은 아래 회원 지정 규칙의 같은 값, 게스트는 BFF 세션에서 만든 안정적인 `Bootpay-Device-UUID`를 견적·준비·결과 내내 유지한다. 회원 세션이 만료됐으면 로그인 복귀로 처리하고 비회원 주문으로 조용히 내리지 않는다.
- 회원 지정: Bootpay-User-JWT 또는 user_id(24자리 회원 ID 또는 가맹점 외부 ID ex_uid) 또는 login_id 중 하나 — JWT 우선, 함께 보낸 값이 다른 회원이면 403 USER_NOT_MATCH(2302), user_id·login_id 는 secret_key(Basic) 서버 호출에서만 받는다. 값은 쇼핑몰 서버가 자기 로그인 세션에서 꺼내고 브라우저가 보낸 값을 그대로 쓰지 않는다.
- user_id·login_id 모드는 commerce 2026-09-28 계약이며 운영 배포 후 적용 — 그 전 운영에서는 JWT 모드만 동작하므로 기본값으로 켜지 않는다.
- 예외: users/session 은 JWT 전용(user_id 계열 400), password-recovery 는 user_id 계열 거절.
- 견적·결제 준비는 회원이 선택인 API 다. 무효 JWT 만 보내면 비회원 견적이 되므로(무효 JWT 와 `user_id`를 함께 보내면 그 회원) 서버가 세션 만료를 먼저 판정한다. 모드별 오류 코드는 설치 스킬의 `contracts.md` §3.
- 입력 최대 50줄, 수량 정수 1~999. 같은 상품+옵션은 서버가 합산하며 합산 수량도 999 이하. 결과 `source_indexes` 또는 상품+옵션 키로 대조한다. 입력/출력 줄 수와 순서가 같다고 가정하지 않는다.
- 응답은 raw `checkout_ready`, `quote_token`, `expires_at`, `currency`, `items`, `amounts`, `shipping_status`, `errors`다. `items`의 `unit_price/subtotal`과 `amounts.product_price/delivery_price/total_price`를 쓴다.
- `checkout_ready === true`이고 토큰이 유효할 때만 주문 버튼을 활성화한다. 토큰은 10분 유효하며 재고 예약이 아니다.
- **배송지 정책** — 결제 요청(`orders/prepare`)에 배송지·우편번호는 필요 없다. 배송지와 제주·도서산간 추가비는 호스팅 주문서가 입력받아 확정한다(결제 전 배송지 반영 시 배송비·총액 재계산). 쇼핑몰(장바구니·바로 구매·결제 버튼)은 주소를 묻거나 확인하거나 배송지 등록을 요구하지 않고, 배송지 때문에 결제 요청을 막지 않는다. `cart/order-preview` 는 추가비 정책 상점에서 우편번호가 없으면 `requires_address`(토큰 없음)를 주므로, 서버가 지역 추가비가 붙지 않는 고정 내륙 우편번호로 견적한다(생성 코드 `BASE_QUOTE_ZIPCODE`) — 우편번호 없이 만든 주문과 같고 주문서에서 다시 계산된다. 상품 불가 시 `amounts:null`을 처리하며, 구매 가능한 일부만 합산하는 구형 `summary`로 대체하지 않는다.
- 옵션 추가금·할인·지역 배송비는 서버 견적이 계산한다. 착불 `delivery_groups[].collect_on_delivery/collect_fee`는 별도 안내하고 선결제 합계에 다시 더하지 않는다. 로컬 가격 계산은 표시 추정치다.
- `cart/validate`는 가용성/표시 검증에 쓸 수 있지만 신규 결제 준비의 권위 금액·토큰을 대신하지 않는다.

```json
{
  "quote_token": "<server_quote_token>",
  "uct": 1,
  "response_type": "url",
  "redirect_url": "https://<registered_merchant_host>/checkout/return",
  "use_auto_login": true
}
```

- 동일 구매자·기기 헤더와 `Idempotency-Key`로 prepare한다. `price/products`는 생략 가능하다. 함께 보내면 서명된 견적의 상품·옵션·수량·상품 합계와 일치해야 한다.
- `redirect_url`은 등록된 HTTPS 호스트여야 한다. localhost HTTP는 신규 견적 계약에서 허용되지 않는다. 로컬 fixture 검증과 실제 호스팅 연동 검증을 구분한다.
- 같은 구매 시도의 토큰·본문·멱등키를 고정한다. 동일 키+동일 요청은 견적 만료 후에도 기존 결과를 재생한다. 새 토큰으로 본문을 바꾸면서 키를 재사용하면 충돌한다.
- 18140/18141/18142/18143(견적 무효/만료/구매자 불일치/가격 변경), 18160(멱등 충돌 → `IDEMPOTENCY_CONFLICT`, conflict), 18161(처리 중 → `CHECKOUT_PENDING`, pending — 새 주문을 만들지 않고 상태를 다시 확인), 18162(redirect 불가)를 구분한다. 재견적과 금액 확인 후 **다음 사용자 클릭**에서만 새 시도를 시작한다. 결과 불명이면 키·토큰을 자동 교체하지 않는다.
- 18162(`ORDER_PREPARE_REDIRECT_URL_NOT_ALLOWED`)는 통신 오류가 아니라 설정 거절이다. "잠시 후 다시 시도"로 안내하지 않고 재시도 불가 오류(`CHECKOUT_RETURN_URL_NOT_REGISTERED`, 503)로 바꾼다. 서버 콘솔에는 원인(`APP_ORIGIN` 값)과 고칠 곳(결제 복귀 도메인 등록)을 남기고 브라우저 응답에는 설정값을 넣지 않는다.
  복귀 주소가 http(로컬)이면 보내 봐야 거절되므로 prepare 를 부르지 않고 같은 오류로 막는다. 상점 서버가 오류 코드와 함께 거절한 그 밖의 응답은 `UPSTREAM_REJECTED`, 응답 자체를 못 받은 통신 실패만 `UPSTREAM_UNAVAILABLE`(재시도 가능)이다.
- `quote_token` 빈 값/무효를 누락시켜 legacy `price/products` 계약으로 재시도하지 않는다. 구형 계약은 명시적인 기존 연동 호환에만 남긴다.

### 로컬에서 결제까지 검증하기

1. localhost 는 결제 복귀 도메인으로 등록할 수 없다. https 터널(예: `cloudflared tunnel --url http://localhost:3000`, `ngrok http 3000`)로 받은 https 호스트를 쓴다.
2. 그 호스트를 `APP_ORIGIN`으로 두고 앱을 다시 띄운다(`.env.local`).
3. 사용자 승인 후 그 호스트를 결제 복귀 도메인으로 등록한다 — 관리자 MCP `list_checkout_return_domains`로 확인하고 `register_checkout_return_domain`으로 추가(기존 도메인 보존, CORS·소셜 로그인 허용에도 쓰임). 관리자 화면 「개발자 설정 > 허용 도메인」에서도 등록할 수 있다(https:// 없이 호스트만, 커머스 키가 속한 프로젝트에서).
4. 결제하기 → hosted 주문서 이동을 확인하고, 검증이 끝나면 임시 터널 도메인은 `unregister_checkout_return_domain`으로 해제한다.

## 4. 호스팅 이동과 구매자 결과

- JWT 회원은 `use_auto_login:true`, 비회원과 `user_id`로만 지정한 회원은 false(자동 로그인 URL 은 유효한 JWT 가 있어야 만들고, `user_id`만이면 401). 응답 `url`을 그대로 이동한다. 회원 `/b` 누락 시 이미 생성된 주문번호를 보존하고 자동 재주문하지 않는다.
- 비회원 prepare 응답의 `result_token`·`result_token_expires_at`은 주문/세션 소유 기록과 함께 서버에 저장한다. 응답 URL의 `__s`도 bearer다. 로그·문서·localStorage에 보관하지 않는다. URL은 브라우저 이동에만 전달한다.
- `GET /v1/orders/{order_number}/result`: 회원은 JWT 또는 서버 세션의 `user_id`, 비회원은 `Bootpay-Order-Result-Token`과 같은 기기 UUID를 전송한다. 게스트 토큰은 24시간, 무효 401·만료 410. 회원의 타인 주문은 404다.
- 응답 `payment_status`는 `pending/paid/partially_refunded/refunded/failed/cancelled`. `fulfillment_status`, `amounts`(상품·배송·총액·결제·환불), `items`, `updated_at`을 사용한다. 예전 `sdk/payload.status`·`payment_completed` enum과 섞지 않는다.
- `paid`만 결제 완료로 표시하고 부분/전체 환불은 별도 상태로 보인다. 쿼리의 `success/paid`를 믿지 않는다. pending 재조회는 `Retry-After`(보통 3초, 입금 대기 60초)를 존중하며 새 주문을 만들지 않는다.
- 장바구니 결제 완료 시 해당 주문 스냅샷 줄의 수량만 한 번 차감한다. 바로 구매는 장바구니를 바꾸지 않는다. 서버 회원 장바구니는 결제 후 GET으로 갱신한다.

## 5. 자주 혼동하는 v1 계약

| 기능 | 공개 계약 |
|---|---|
| 회원 장바구니 | `GET /v1/cart`의 `cart_items`와 `cart_item_id`; `data.list` 아님 |
| 기존 서버 장바구니 체크아웃 | `POST /v1/cart/checkout`의 `item_ids`, 선택/그룹 응답 `order_pre_id/url`; `cart_item_ids/prepare_id/redirect` 아님 |
| 구매자 가입 | `POST /v1/users/signup`의 `password/term_ids`; `finish/standby/pending_approval` + `requires_login:true`, 별도 로그인 필요 |
| 외부 회원 동기화 | `users/join`은 서버 관리 연동. 구매자 가입 폼에 노출하지 않음 |
| 상품·리뷰 목록 | `list/count/page/limit`; 카탈로그 상세는 `products/total_count/page/per/has_more` |
| 공개 상품 상세 | v1이 프로젝트·노출 범위를 확인한다. 다른 프로젝트의 내부 상세 API로 우회하지 않음 |

## 6. 완료 증거

- 실제 v1 형태의 fixture로 옵션가·중복줄 병합·품절·회원/비회원·주소 필요·견적 만료/가격 변경·중복 클릭·결과 불명·입금 대기·환불·타인 주문을 검증한다.
- 새 프론트 파일의 규칙, 타입 검사·빌드, 모바일 overflow·키보드·오류/empty/loading을 확인한다. 상품 정보·재고·할인·후기를 지어내지 않는다.
- fixture 통과는 운영 API 배포·실결제·호스팅 쿠키 인계 증거가 아니다. 실제 환경에서는 `/b` → 쿠키 → 세션 구매자 일치까지 별도로 확인한다.
- 참고 소스: invoice `package.json`, `design.md`, `app/components/product/head/ProductOptions.vue`, `app/vendor/composables/http/commerce-http.ts`; API `app/controllers/v1/cart_controller.rb`, `app/services/v1/order_quote_service.rb`, `order_prepare_service.rb`, `order_result_service.rb`, `user_signup_service.rb`, `test/isolated/sf03_authoritative_quote_test.rb`, `sf04_prepare_idempotency_test.rb`, `sf05_owned_order_result_test.rb`.

세부 인증/SDK는 `get_doc('commerce/storefront-development')`와 설치 스킬의 `contracts.md`, 호스팅은 `get_doc('commerce/hosted-checkout-session')`, 상세 본문은 `get_doc('product/block-rendering')`, 기본 UX는 `get_doc('commerce/storefront-baseline')`를 읽는다.
