# 기본 쇼핑몰 필수 UX·완료 판정 가이드

`get_doc('commerce/storefront-baseline')` · `generate_commerce_code` 의 `status`/`missing_requirements` 해석 기준.

## 언제 읽나

- `generate_commerce_code` 로 쇼핑몰을 만들 때(특히 `framework="nextjs"`, `step="all"`).
- 기존 앱에 상품 상세 구매·장바구니·바로 구매·결과 페이지를 붙일 때.
- 응답이 `status: "incomplete"` 일 때 무엇이 빠졌는지 사용자에게 설명할 때.

## 필수 회원 기능

[필수 기능 목록](required-features.md)의 회원가입·로그인·마이페이지·정보 수정·비밀번호 변경/복구·본인 주문·배송지·탈퇴는 기본 범위다.
`completion.required_features`의 `api_blocked`가 남으면 구매 흐름이 검증돼도 전체 쇼핑몰은 incomplete다.
내장 가이드: `get_doc("commerce/required-features")`.

## 필수 흐름

홈 카탈로그(검색·카테고리·정렬·페이지) → 상품 상세(옵션·수량·재고·본문) → **장바구니** 또는 **바로 구매** →
(필요 시) 로그인 후 원래 화면으로 복귀 → 서버 견적 `POST /api/cart/quote` → 주문 준비 `POST /api/checkout`(단일 requestId) →
API 가 돌려준 주문서 `url` 로 **수정 없이** 이동 → `/checkout/return` 에서 서버가 확인한 `paid === true` 만 완료 표시 →
장바구니 주문이면 이번 주문 줄만 장바구니에서 뺀다.

모든 Commerce 호출은 서버(BFF)에서 SDK 로 한다. 브라우저에는 비밀키·회원 JWT·임의 upstream 프록시가 없다.

## 바로 구매 계약

- 장바구니 담기와 **별개의 버튼·별개의 intent** 다. 현재 선택한 상품+옵션+수량 1건만
  `sessionStorage` intent `{productId, optionId?, quantity, source:'buy_now', createdAt}` 로 고정하고 `/checkout/buy-now` 로 간다.
- 장바구니(`localStorage`)는 읽지도 쓰지도 않는다. cart 에 넣었다가 전체를 주문하는 우회는 금지.
  주문 성공·실패·취소 어느 경우에도 기존 cart 는 그대로다.
- 로그인이 필요하면 intent 를 남긴 채 `/auth/login?returnTo=/checkout/buy-now` 로 보낸다. returnTo 는 허용 목록
  (`/`, `/cart`, `/checkout/buy-now`, `/products/<24hex>`)만 통과하고 나머지는 `/` 로 바뀐다.
  복귀하면 상품·옵션·재고·가격을 서버에서 다시 조회·견적한다. 홈이나 전체 cart 로 보내지 않는다.
- intent 는 30분 뒤 만료되고 로그아웃하면 지운다. 만료·손상이면 "주문할 상품을 확인해 주세요" 와 상품으로 돌아갈 링크를 보인다.
- 주문 요청은 `startCheckout({ items: [item], source: 'buy_now' })` — 정확히 1건. 서버는 buy_now 다건을 `INVALID_CART` 로 거절한다.

## 구매할 수 없는 상태 — 이유 있는 disabled

| 상태 | 표시 문구(예) |
|---|---|
| 필수 옵션 미선택 | 옵션을 선택해 주세요 |
| 상품·옵션 품절, 재고 0 | 품절된 상품입니다 / 현재 구매할 수 없는 옵션입니다 |
| 수량 범위(1~99)·재고 초과 | 수량은 1~99개 사이로 선택해 주세요 / 남은 수량은 N개예요 |
| 정기구독 상품 | 정기배송 상품은 이 쇼핑몰에서 주문할 수 없어요 (서버도 `SUBSCRIPTION_UNSUPPORTED`) |
| 판매 예정(`sale_state=scheduled`) | 10월 10일 오전 10:00 판매 시작 (품절로 표시하지 않는다) |

버튼은 `disabled` + `aria-describedby` 로 이유 문구(`aria-live="polite"`)를 가리킨다. 클릭·Enter 어느 쪽도 요청 0건.

## 판매 예정 상품(판매 예약)

- 판매 예정(sale_state=scheduled) 상품은 품절로 표시하지 않는다. 상세에 남은 시간과 오픈 시각, 목록에 '판매 예정' 배지.
- 남은 시간은 `/v1/products` 응답의 `opens_in_ms` 를 받은 순간의 `performance.now()` 와 묶어 감산한다. 기기 시계(`Date.now()`)로 계산하지 않는다.
  문구: 1일 이상 "N일 N시간 N분 후 판매 시작", 1시간 미만 "N분 N초", 1분 미만 "곧 판매가 시작돼요". 오픈 시각은 "10월 10일 (토) 오전 10:00 · 한국 시간".
- 0 이 되면 0~1.5초 지터 뒤 상품을 다시 조회하고, `on_sale` 이면 버튼을 연다(새로고침 없이). 장바구니 버튼 자리에는 오픈 시각, 바로 구매는 disabled.
- 목록 카드는 "판매 예정" 배지와 이미지 하단 "10/10 (토) 10:00 오픈" 띠만 — 카운트다운은 넣지 않는다. 정렬은 판매 중과 같다.
- 시작 전 주문은 상점 서버가 `10724 PRODUCT_SALE_NOT_STARTED`(payload `sale_start_at`)로 거절한다. 서버 라우트는 409 `SALE_NOT_STARTED` 로 바꿔
  "아직 판매 전이에요. {오픈 시각}부터 구매할 수 있어요." 를 보이고 견적·상품을 다시 읽는다. 화면 잠금은 편의이고 보장은 서버다.

## 금액·배송 표시

- 판매가 / 옵션 추가금 / 수량 / 상품 금액 / 배송비 / 총 결제 예정 금액을 따로 보인다. 착불은 "착불 별도".
- 금액의 권위는 `cart/order-preview`의 `amounts`와 `quote_token`이다. `checkout_ready`가 false거나 견적 실패/만료면 disabled, `amounts:null`이면 합계는 "—"다. 배송지·우편번호는 묻지도 확인하지도 않는다 — 결제 요청에 필요 없고, 배송지와 지역 추가비는 호스팅 주문서에서 확정된다(견적은 서버의 고정 내륙 우편번호). 같은 구매자·기기를 유지한다.
- 출고 정보(`delivery.days`)가 있으면 "출고 예정: 주문 후 N일", 없으면 "출고 일정은 판매자 확인이 필요해요". 날짜를 지어내지 않는다.

## 주문 요청과 결과

- `lib/checkout-client` 의 `startCheckout` 만 쓴다: source+items 지문별 안정된 requestId(sessionStorage), 진행 중 요청 1개.
  화면도 `inFlight` ref·busy 상태로 한 번 더 막는다. 견적 로딩 중에는 버튼이 disabled 다.
- 결과 kind 별 처리:
  - `redirect` → `window.location.assign(outcome.url)`. URL 파싱·재조립·`__s` 처리·`/b` 조립 금지.
  - `expired` → 서버가 만료를 확정한 경우만. 다음 사용자 클릭에서 새 requestId("새 주문서로 결제하기").
  - `pending` → 같은 attempt 유지, 새 prepare 없음. `not_payable` → "이전 주문 결과 확인하기" 링크, 버튼 disabled.
  - `login_required` → 로그인 링크(returnTo). `error` 의 CART_CHANGED·OUT_OF_STOCK 등 → 견적을 다시 받는다.
- 결과 페이지는 query 의 success/status 를 무시하고 `/api/orders/result` 의 `paid === true` 일 때만 완료를 표시한다.
- 결제 페이지에서 뒤로 오면(bfcache) "이동 중" 상태를 풀어 준다.

## 결제 완료 후 장바구니 정리

- 시점: `/checkout/return` 이 `/api/orders/result` 에서 `paid === true` 를 받은 뒤에만. 입금 대기·실패·취소·조회 오류,
  query 의 success/paid 값으로는 장바구니를 건드리지 않는다.
- 대상: 장바구니 주문(`source:'cart'`)이 주문서 url 을 받을 때 `lib/checkout-client` 가 그 주문번호에 묶어 둔
  스냅샷(sessionStorage, 상품·옵션·수량)의 줄만. 같은 상품·옵션 줄에서 주문한 수량만큼 빼고 0 이 되면 줄을 지운다
  (`subtractOrderedLines`). 결제하는 동안 다른 탭에서 담은 상품과 늘린 수량은 남는다. 전체 비우기(`writeCart([])`)는 금지.
- 한 번만: 결과 화면이 `takeCartOrderSnapshot(orderNumber)` 로 스냅샷을 먼저 지운 뒤 뺀다. 새로고침·재확인해도 다시 빼지 않는다.
  주문번호는 URL 이 아니라 서버 응답의 값을 쓴다.
- 스냅샷이 없으면(다른 기기·브라우저에서 연 결과, 저장소 차단) 아무 줄도 지우지 않는다.
- 순서: paid 확인 → 장바구니 줄 차감 → `clearCheckoutAttempt('cart')`·`clearCheckoutAttempt('buy_now')`.
- 결과 화면은 `aria-live` 영역에 "주문한 수량만큼 장바구니에서 뺐어요." 와 남은 상품 링크를 보인다.
  열려 있는 다른 탭의 장바구니는 localStorage `storage` 이벤트로 갱신된다.
- 바로 구매는 스냅샷을 만들지 않는다. 결제 완료 뒤에도 장바구니는 그대로다.
- 서버 장바구니(`POST /v1/cart/checkout`, 직접 구현한 회원 장바구니 연동)는 결제 완료 시 commerce-api 가 주문한 줄을 지운다.
  클라이언트는 `DELETE /v1/cart/{id}` 를 보내지 않고, 주문서에서 돌아오면(`pageshow`) `GET /v1/cart` 로 다시 읽기만 한다.

## 목록·조회 상태

- 정상 0건(empty-state + 필터 초기화)과 네트워크 오류(`role="alert"` + 다시 시도하기)는 다른 화면이다.
- retry 는 같은 URL·body(같은 조회 의도)로 다시 요청한다. 늦게 온 이전 응답은 버린다.
- 페이지·검색어·카테고리·정렬은 URL(`?page&keyword&category_id&sort`)에 남겨 뒤로 가기·새로고침에도 유지한다.

## 접근성·반응형

- skip link, 옵션 select·수량 입력 label, 상태 문구 `aria-live`, 오류 `role="alert"`, 로딩 `role="status"`, `:focus-visible`.
- 390px·768px·1440px 에서 문서 가로 넘침 0. 버튼 52px, 모바일 수량 버튼 44px.
- Next 샘플은 기준 warm shop 토큰(`--canvas: #faf9f6`, `--ink: #292d26`, `--olive: #565f42` …)과 48px 옵션 select 를 유지한다. 기존 가맹점에 이 브랜드를 강제하지 않는다.

## 선택 기능

찜·리뷰 작성·쿠폰·정기구독·B2B 는 기본 쇼핑몰에서 `unavailable` 로 **명시**한다(응답 `completion.optional_features`).
명시된 비활성은 완료를 막지 않는다. 대신 비활성 선언한 기능의 CTA(예: "찜하기", "쿠폰 적용")가 화면에 있으면 누락으로 본다.

사용자가 요청하면 `generate_commerce_code(features=[…])`(nextjs, step="all")로 선택 기능을 얹는다 —
`reviews`(상품평 목록·작성) · `product-qna`(상품문의) · `notices`(공지사항) · `faq` · `inquiries`(1:1 문의) · `wishlist`(찜) · `benefits`(쿠폰함·적립금).
켠 기능은 `implemented` 로 바뀌고(찜·리뷰 작성·쿠폰), 필수 14개 판정과 별도로 `completion.features`·`verification.features`
(모든 선택 기능을 얹은 생성물의 빌드·기능별 브라우저 시나리오 기록)로 판정한다. 쿠폰·적립금 **적용**은 여전히 호스팅 주문서에서 한다.
features 가 비면 생성물은 기본과 바이트 단위로 같다. 정기구독·B2B 는 선택 기능으로도 제공하지 않는다.

## 완료 판정 — generate_commerce_code 응답

- `status`: `complete` | `incomplete`, `missing_requirements`: 빠진 항목 목록, `completion.verification`: 판정 근거.
- **complete = 모든 필수 회원 기능 API·구현 충족 + step="all" + 정적 manifest 전부 충족 + 같은 생성기 지문의 실행 검증 기록에서 실행 항목 전부 통과.**
  파일 존재·문자열 검사만으로 complete 를 주장하지 않는다. 생성기가 바뀌면 지문이 달라져 기록은 무효가 된다.
- 단일 step 응답은 부분집합이라 항상 incomplete 다.
- react/vue/nuxt/svelte/angular는 실행 템플릿을 제공하지 않고 현재 프레임워크를 유지하는 구현 가이드만 제공하므로 incomplete다.
  누락 목록을 사용자에게 그대로 전하고 "쇼핑몰 완성" 이라고 보고하지 않는다.

정적 manifest 항목:

- 경로: `route:catalog`, `route:product-detail`, `route:cart`, `route:buy-now`, `route:login`, `route:checkout-return`, `api:bff`
- 동작: `action:catalog-browse`, `action:add-to-cart`, `action:buy-now-independent`, `action:login-return`, `action:server-quote`,
  `action:single-attempt`, `action:hosted-url-unchanged`, `action:verified-result`, `action:cart-cleared-after-paid`
- 상태: `state:catalog`, `state:purchase-disabled`, `state:price-breakdown`, `state:shipping-info`, `state:checkout-outcomes`, `state:a11y`, `state:responsive`
- 경계: `boundary:client-secrets`, `boundary:no-legacy-proxy`
- 무결성: `integrity:handlers`(빈 handler·href="#"), `integrity:placeholders`(TODO), `integrity:links`(없는 라우트 링크), `integrity:imports`(없는 모듈·미선언 패키지), `integrity:paths`(같은 경로 다른 내용)

실행 검증 항목:

- `build:typecheck`, `build:next`
- `browser:account-hub`, `browser:account-orders`, `browser:account-addresses`, `browser:signup-blocked`
- `browser:catalog-states`, `browser:disabled-reasons`, `browser:buy-now-isolated`, `browser:cart-checkout`,
  `browser:cart-cleared-after-paid`, `browser:login-return`, `browser:duplicate-guard`, `browser:hosted-url-unchanged`, `browser:verified-result`, `browser:responsive`, `browser:a11y`

`browser:signup-blocked` 는 상점의 가입 정책이 가입을 받지 않을 때(`signup_enabled=false`) 가입 폼·제출이 없고, 로그인 상태가 바뀌지 않으며, 완료로 오인하지 않는지 본다.

추가 검증 항목(필수 아님 — complete 판정에는 들어가지 않고 스크립트가 함께 보고한다):

- `static:member-mode`: 회원 식별 방식 계약. `own_login` 이면 JWT·`users/session`·`users/logout`·자동 로그인 경로가 없고, 본인 프로필(`users/me`)은 서버 세션의 `user_id` 로 GET(쿼리)·PATCH(본문) 하며, `user_id` 는 서버 세션에서만 온다(브라우저 입력 없음)
- `server:origin-production`: `next start` 에서 `APP_ORIGIN` 과 다른 Origin 의 상태 변경 요청은 403
- `server:checkout-return-url`: `APP_ORIGIN` 이 http 면 `/api/checkout` 이 상점 서버 호출 없이 503 `CHECKOUT_RETURN_URL_NOT_REGISTERED`
- `server:origin-dev-port`: `APP_ORIGIN=http://localhost:3000` 인 채로 `next dev` 를 다른 포트로 띄워도 로그인·장바구니 요청이 Origin 검사를 통과하고 경고는 1회

## 실행 검증 스크립트 (bootpay-mcp 저장소)

```bash
npx tsx scripts/verify-generated-next.ts --node-modules <next·react·@bootpay/backend-js·typescript·playwright 가 설치된 node_modules> \
  [--out <임시 디렉터리>] [--port 3414] [--member-mode bootpay_jwt|own_login] [--keep] [--record]
```

- 생성기로 `nextjs`·`all` 산출물을 임시 디렉터리에 쓰고 node_modules 를 복사한다(APFS 는 `cp -c -R` 복제).
  Turbopack 은 프로젝트 루트 밖을 가리키는 symlink node_modules 를 거부한다.
- `.env.local` 은 placeholder 값만 쓴다. 브라우저의 `/api/*` 는 Playwright `page.route` fixture 로 대체해 운영 API 호출·주문 생성이 없다.
- `--record` 는 결과를 지문과 함께 `src/admin/tools/commerce-code/nextjs/verification-evidence.ts` 에 남긴다. 이 기록이 complete 의 근거다.
- 사용자 프로젝트에서는 같은 시나리오(바로 구매 격리·로그인 복귀·중복 클릭·url 원문 이동·paid 확인·결제 완료 후 장바구니 줄 차감·가로 넘침)를 사용자 테스트로 재현한다.
  fixture 통과는 운영 결제·자동 로그인 인계 완료의 증거가 아니다.

## 하지 말 것

- 브라우저 번들에 `SECRET_KEY`·회원 JWT, catch-all 프록시(`app/api/bootpay/[...path]`), localStorage JWT.
- 주문서 url 수정, `/b`·`__s` 직접 조립, invoice 경로에 일반 주문번호 사용.
- pending·unknown 결과에서 새 주문 자동 생성, 화면 로드 시 주문 생성.
- paid 확인 전 장바구니 정리, 결제 완료 후 장바구니 전체 비우기, 서버 장바구니에 클라이언트 `DELETE` 호출.
- 출고일·재고·리뷰·할인 지어내기.
