@sayren/mcp 0.6.0 → 0.8.0

package/template/src/routes/checkout.index.tsx

@@ -1,3 +1,4 @@
+import { zodResolver } from "@hookform/resolvers/zod";
 import {
   ApiError,
   type CheckoutDelivery,
@@ -12,15 +13,30 @@ import type { PaymentResult } from "@sayren/storefront-sdk/payments";
 import { createFileRoute, redirect, useNavigate } from "@tanstack/react-router";
 import { createServerFn } from "@tanstack/react-start";
 import { getRequestUrl } from "@tanstack/react-start/server";
-import { useId, useState } from "react";
+import { useMemo, useRef, useState } from "react";
+import { useForm } from "react-hook-form";
 import { z } from "zod";
 import { SubmitButton } from "../components/submit-button";
+import { TextField } from "../components/text-field";
 import { apiFor } from "../lib/api.server";
 import { readCartToken } from "../lib/cart-session.server";
 import { checkoutIntentFrom, checkoutSearch } from "../lib/checkout-intent";
 import type { PublicConfig } from "../lib/config";
 import { API_BASE_URL, resolveStoreCode } from "../lib/config.server";
+import {
+  type AppliedCoupon,
+  COUPON_CODE_PATTERN,
+  couponErrorMessage,
+  couponRejectMessage,
+} from "../lib/coupon-code";
+import {
+  type CheckoutForm,
+  type CheckoutFormInput,
+  checkoutFormSchema,
+  WITHDRAWAL_AGREEMENT_MESSAGE,
+} from "../lib/form-schemas";
 import { formatPrice } from "../lib/format";
+import { pageTitle } from "../lib/page-title";
 import { forgetPaymentOptions, rememberPaymentOptions } from "../lib/payment-options";
 import { PAYMENT_RETURN_PATH, paymentsFor } from "../lib/payments";
 import { readToken } from "../lib/session.server";
@@ -72,11 +88,52 @@ const quoteDelivery = createServerFn({ method: "POST" })
     }
   });
 
+/**
+ * 쿠폰 코드 적용 — 금액 미리보기(`checkout.pricing`)로 적용 여부와 할인액을 확인한다. 주문서를 바꾸지 않고 쿠폰을 예약하지 않는다.
+ * 확정은 결제 시작이 같은 코드를 `coupons`로 보낼 때다. 구매자 토큰을 브라우저에 두지 않으려고 서버 함수로 부른다.
+ */
+const previewCoupon = createServerFn({ method: "POST" })
+  .validator(
+    z.object({
+      checkoutId: z.string(),
+      code: z.string().regex(COUPON_CODE_PATTERN),
+      zipCode: z.string(),
+    }),
+  )
+  .handler(async ({ data }) => {
+    const api = apiFor({ accessToken: readToken(), cartToken: readCartToken() });
+    try {
+      const pricing = await api.checkout.pricing(data.checkoutId, {
+        coupons: [{ code: data.code }],
+        zipCode: /^[0-9]{5}$/.test(data.zipCode) ? data.zipCode : undefined,
+      });
+      const result = pricing.coupons[0];
+      if (!result?.applied) {
+        return { coupon: null, error: couponRejectMessage(result?.rejectReason ?? null) };
+      }
+      if (!pricing.payable)
+        return { coupon: null, error: couponErrorMessage("PAYMENT_AMOUNT_TOO_LOW") };
+      const coupon: AppliedCoupon = {
+        code: result.code ?? data.code,
+        name: result.name,
+        discountAmount: result.discountAmount,
+      };
+      return { coupon, error: null };
+    } catch (error) {
+      return {
+        coupon: null,
+        error: couponErrorMessage(error instanceof ApiError ? error.code : null),
+      };
+    }
+  });
+
 const paymentForm = z.object({
   checkoutId: z.string(),
   option: paymentOptionSchema,
   /** 결제에 실패하면 돌아올 주문서 주소 */
   back: z.string(),
+  /** 배송지를 보내는가 — 주문서의 `requiresShipping`. false면(이용권·방문 수령 등) 배송지를 싣지 않는다 */
+  requiresShipping: z.boolean(),
   receiverName: z.string(),
   phone: z.string(),
   zipCode: z.string(),
@@ -88,6 +145,10 @@ const paymentForm = z.object({
   orderPassword: z.string(),
   /** 현금영수증 신청 — 계좌이체·가상계좌에서 구매자가 켰을 때만 */
   cashReceipt: cashReceiptRequestSchema.optional(),
+  /** 적용한 쿠폰 코드 — 미리보기로 확인한 값 */
+  couponCode: z.string().regex(COUPON_CODE_PATTERN).optional(),
+  /** 청약철회 제한 동의 — 주문서의 `withdrawal.required`가 true일 때 구매자가 체크한 값 */
+  withdrawalAgreement: z.boolean().optional(),
 });
 
 /** 결제 시작은 서버에서 한다 — 토큰이 브라우저 JS에 노출되지 않는다. 결제창 호출 값(공개 값)만 내려준다 */
@@ -103,14 +164,16 @@ const startPayment = createServerFn({ method: "POST" })
       const start = await api.checkout.startPayment(data.checkoutId, {
         option: data.option,
         returnUrl: returnUrl.toString(),
-        shippingAddress: {
-          receiverName: data.receiverName,
-          phone: data.phone,
-          zipCode: data.zipCode,
-          address1: data.address1,
-          address2: data.address2 || undefined,
-          deliveryMemo: data.deliveryMemo || undefined,
-        },
+        shippingAddress: data.requiresShipping
+          ? {
+              receiverName: data.receiverName,
+              phone: data.phone,
+              zipCode: data.zipCode,
+              address1: data.address1,
+              address2: data.address2 || undefined,
+              deliveryMemo: data.deliveryMemo || undefined,
+            }
+          : undefined,
         guest: accessToken
           ? undefined
           : {
@@ -120,14 +183,33 @@ const startPayment = createServerFn({ method: "POST" })
               orderPassword: data.orderPassword,
             },
         cashReceipt: data.cashReceipt,
+        ...(data.couponCode ? { coupons: [{ code: data.couponCode }] } : {}),
+        // 제한 상품이 없는 주문은 보내지 않는다 — 빠지면 서버가 400 WITHDRAWAL_AGREEMENT_REQUIRED다
+        ...(data.withdrawalAgreement ? { withdrawalAgreement: true } : {}),
       });
       // 결제 시작 값은 JSON으로 넘기고 브라우저에서 SDK 스키마로 다시 읽는다 — 서버 함수 직렬화 타입에 맞춘다
-      return { start: JSON.stringify(start), error: null };
+      return { start: JSON.stringify(start), error: null, couponFailed: false };
     } catch (error) {
-      return { start: null, error: startErrorMessage(error) };
+      // 쿠폰 때문에 시작하지 못했으면 화면이 쿠폰을 풀고 쿠폰 칸에 안내한다 — 같은 쿠폰으로 다시 눌러도 같은 오류다
+      const couponFailed =
+        error instanceof ApiError &&
+        (COUPON_START_ERRORS as readonly string[]).includes(error.code);
+      return { start: null, error: startErrorMessage(error), couponFailed };
     }
   });
 
+/** 결제 시작이 쿠폰 때문에 거절된 오류 코드 */
+const COUPON_START_ERRORS = [
+  "COUPON_NOT_FOUND",
+  "COUPON_NOT_APPLICABLE",
+  "COUPON_CHANGED",
+  "COUPON_IN_USE",
+  "COUPON_LIMIT_REACHED",
+  "COUPON_EXHAUSTED",
+  "COUPONS_UNAVAILABLE",
+  "PAYMENT_AMOUNT_TOO_LOW",
+] as const;
+
 function startErrorMessage(error: unknown): string {
   if (!(error instanceof ApiError))
     return "결제를 시작하지 못했습니다. 잠시 후 다시 시도해 주십시오.";
@@ -138,8 +220,24 @@ function startErrorMessage(error: unknown): string {
       return "결제창을 준비하지 못했습니다. 다른 결제수단으로 시도해 주십시오.";
     case "PAYMENT_NOT_CONFIGURED":
       return "결제 수단을 준비하고 있습니다. 잠시 후 다시 시도해 주십시오.";
+    case "WITHDRAWAL_AGREEMENT_REQUIRED":
+      return WITHDRAWAL_AGREEMENT_MESSAGE;
     case "CASH_RECEIPT_NOT_AVAILABLE":
       return "현금영수증은 계좌이체·가상계좌 결제에서만 신청할 수 있습니다.";
+    case "COUPON_NOT_APPLICABLE": {
+      // 적용하지 못한 이유가 오류에 실려 온다(`details.coupons[].reason`)
+      const rejected = (error.details?.coupons as Array<{ reason?: string }> | undefined)?.[0];
+      return couponRejectMessage(rejected?.reason ?? null);
+    }
+    case "TOO_MANY_REQUESTS":
+    case "COUPON_NOT_FOUND":
+    case "COUPON_CHANGED":
+    case "COUPON_IN_USE":
+    case "COUPON_LIMIT_REACHED":
+    case "COUPON_EXHAUSTED":
+    case "COUPONS_UNAVAILABLE":
+    case "PAYMENT_AMOUNT_TOO_LOW":
+      return couponErrorMessage(error.code);
     case "RETURN_URL_NOT_ALLOWED":
       return "이 쇼핑몰 주소에서는 결제할 수 없습니다. 셀러 콘솔 설정 › 결제에서 결제 도메인을 확인해 주십시오.";
     default:
@@ -151,7 +249,7 @@ export const Route = createFileRoute("/checkout/")({
   validateSearch: checkoutSearch,
   loaderDeps: ({ search }) => search,
   loader: ({ deps, location }) => createCheckout({ data: { search: deps, back: location.href } }),
-  head: () => ({ meta: [{ title: "주문서" }] }),
+  head: ({ matches }) => ({ meta: [{ title: pageTitle(matches, "주문서") }] }),
   component: Checkout,
 });
 
@@ -161,41 +259,124 @@ function Checkout() {
   const [notice, setNotice] = useState<string | null>(null);
   const [submitting, setSubmitting] = useState(false);
   const options = checkout.paymentOptions;
-  const [selected, setSelected] = useState(options[0] ? paymentOptionKey(options[0]) : "");
+  /** 배송이 필요한 주문인가 — false면(이용권·방문 수령 등만 담은 주문) 배송지·배송비를 보이지 않는다 */
+  const shipping = checkout.requiresShipping;
+  /** 청약철회 제한 상품(제공이 시작되면 취소·반품할 수 없는 파일·코드·이용권)이 있는가 — 결제 전에 안내하고 동의를 받는다 */
+  const withdrawal = checkout.withdrawal;
+  const defaultOptionKey = options[0] ? paymentOptionKey(options[0]) : "";
+  /**
+   * 폼 스키마는 주문서마다 한 번 만든다 — 비회원 여부와 현금영수증을 받을 수 있는 결제 옵션이 주문서에서 정해진다.
+   * 결제 시작 직전의 동기 검사와 `zodResolver`가 같은 스키마를 쓴다.
+   */
+  const schema = useMemo(
+    () =>
+      checkoutFormSchema({
+        guest: !member,
+        shipping,
+        withdrawal: withdrawal.required,
+        cashReceiptOptionKeys: new Set(
+          options.filter((option) => cashReceiptAvailable(option.method)).map(paymentOptionKey),
+        ),
+      }),
+    [member, options, shipping, withdrawal.required],
+  );
+  const form = useForm<CheckoutFormInput, unknown, CheckoutForm>({
+    resolver: zodResolver(schema),
+    // 입력 칸의 기본값은 비워 둔다 — 하이드레이션 전에 입력한 값을 그대로 읽는다
+    defaultValues: {
+      paymentOption: defaultOptionKey,
+      cashReceiptOn: false,
+      cashReceiptType: "INCOME_DEDUCTION",
+      withdrawalAgreed: false,
+    },
+  });
+  const { errors } = form.formState;
+  const selected = form.watch("paymentOption");
+  const cashReceiptOn = form.watch("cashReceiptOn");
+  const cashReceiptType = form.watch("cashReceiptType");
   /**
    * 배송지를 반영한 금액. 배송비 미리보기와 결제 시작 응답이 덮어쓴다 — 최종 금액은 결제 시작 응답의 `amounts`다
    * (서버가 보낸 배송지로 배송비를 다시 계산한다).
    */
   const [quote, setQuote] = useState<DeliveryQuoteResult | null>(null);
+  /** 결제 시작 응답이 준 확정 금액인가 — 이미 쿠폰 할인이 들어 있어 화면에서 다시 빼지 않는다 */
+  const [quoteConfirmed, setQuoteConfirmed] = useState(false);
+  const [coupon, setCoupon] = useState<AppliedCoupon | null>(null);
+  /** 쿠폰 칸은 비제어 입력이다 — 하이드레이션 전에 입력한 값도 남는다. 쿠폰을 풀면 이 값으로 칸을 다시 채운다 */
+  const couponInputRef = useRef<HTMLInputElement>(null);
+  const [couponDraft, setCouponDraft] = useState("");
+  const [couponError, setCouponError] = useState<string | null>(null);
+  const [couponBusy, setCouponBusy] = useState(false);
+  /**
+   * 팝업에서 취소·실패한 결제. 입력이 그대로면 새 결제를 만들지 않고 이 결제를 다른 옵션으로 다시 시도한다(`payments.retry`) —
+   * 새 결제를 만들면 앞 결제가 결제 시간(10분) 동안 쿠폰을 잡고 있어 쿠폰 한도에 걸린다.
+   */
+  const [pending, setPending] = useState<{ paymentId: string; signature: string } | null>(null);
   /** 같은 우편번호로 blur가 반복돼도 다시 부르지 않는다 */
   const [quotedZip, setQuotedZip] = useState<string | null>(null);
-  const amounts = quote?.amounts ?? checkout.amounts;
+  const baseAmounts = quote?.amounts ?? checkout.amounts;
   const delivery = quote?.delivery ?? checkout.delivery;
+  // 총액은 할인 전 금액에서 매번 계산한다. 결제 시작 응답(확정)이면 그 할인을, 아니면 미리보기 할인을 뺀다 —
+  // 쿠폰 할인은 배송지와 무관하다(배송비 쿠폰 없음)
+  const couponDiscount = coupon
+    ? quoteConfirmed
+      ? baseAmounts.couponDiscountAmount
+      : coupon.discountAmount
+    : 0;
+  const deliveryDiscount = quoteConfirmed ? baseAmounts.deliveryDiscountAmount : 0;
+  const totalAmount =
+    baseAmounts.productAmount + baseAmounts.deliveryFee - couponDiscount - deliveryDiscount;
+
+  /** 쿠폰을 푼다 — 코드는 칸에 되돌린다 */
+  const releaseCoupon = (code: string | null) => {
+    setCouponDraft(code ?? "");
+    setCoupon(null);
+    setQuoteConfirmed(false);
+  };
+
+  const applyCoupon = () => {
+    if (couponBusy) return;
+    const code = (couponInputRef.current?.value ?? "").trim();
+    if (!COUPON_CODE_PATTERN.test(code)) {
+      setCouponError("쿠폰 코드는 영문·숫자·-·_ 6~30자입니다.");
+      return;
+    }
+    setCouponBusy(true);
+    setCouponError(null);
+    void previewCoupon({
+      data: { checkoutId: checkout.checkoutId, code, zipCode: form.getValues("zipCode") ?? "" },
+    })
+      .then(({ coupon: next, error }) => {
+        setCouponDraft(code);
+        setCoupon(next);
+        setQuoteConfirmed(false);
+        setCouponError(error);
+      })
+      .catch(() => setCouponError(couponErrorMessage(null)))
+      .finally(() => setCouponBusy(false));
+  };
 
-  // 디바운스 타이머 대신 blur에서 부른다 — 우편번호는 5자리를 한 번에 채우는 값이고, FormData 폼에
-  // 입력 상태를 따로 들지 않아도 된다
+  // 디바운스 타이머 대신 blur에서 부른다 — 우편번호는 5자리를 한 번에 채우는 값이다
   const handleZipBlur = (zipCode: string) => {
     if (!/^[0-9]{5}$/.test(zipCode) || zipCode === quotedZip) return;
     setQuotedZip(zipCode);
     void quoteDelivery({ data: { checkoutId: checkout.checkoutId, zipCode } })
       .then(({ quote: next, error }) => {
-        if (next) setQuote(next);
-        else {
+        if (next) {
+          setQuote(next);
+          setQuoteConfirmed(false);
+        } else {
           setQuotedZip(null);
           setNotice(error);
         }
       })
       .catch(() => setQuotedZip(null));
   };
-  const [cashReceiptOn, setCashReceiptOn] = useState(false);
-  const [cashReceiptType, setCashReceiptType] = useState<"INCOME_DEDUCTION" | "EXPENSE_PROOF">(
-    "INCOME_DEDUCTION",
-  );
   const selectedOption = options.find((item) => paymentOptionKey(item) === selected);
   // 현금영수증은 계좌이체·가상계좌에서만 받는다
   const cashReceiptShown = !!selectedOption && cashReceiptAvailable(selectedOption.method);
 
-  const settle = (result: PaymentResult, back: string) => {
+  const settle = (result: PaymentResult, back: string, signature: string) => {
     if (result.status === "COMPLETED") {
       forgetPaymentOptions(result.paymentId);
       void navigate({
@@ -214,6 +395,8 @@ function Checkout() {
       });
       return;
     }
+    // 같은 입력으로 다시 누르면 이 결제를 다른 옵션으로 이어 간다
+    if (result.status !== "INVALID") setPending({ paymentId: result.paymentId, signature });
     setNotice(
       result.status === "CANCELED"
         ? "결제를 취소했습니다. 다른 결제수단으로 다시 시도해 주십시오."
@@ -223,63 +406,104 @@ function Checkout() {
     );
   };
 
+  /**
+   * 결제창은 클릭에서 동기로 열어야 팝업 차단에 걸리지 않는다. `form.handleSubmit`은 검증을 기다린 뒤 부르므로
+   * 여기서는 같은 스키마로 먼저 동기 검사하고, 통과하면 바로 빈 창을 연다. 실패하면 `handleSubmit`으로 칸마다
+   * 오류를 보이고 첫 오류 칸으로 옮긴다.
+   */
   const handleSubmit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
-    const option = options.find((item) => paymentOptionKey(item) === selected);
+    const parsed = schema.safeParse(form.getValues());
+    if (!parsed.success) {
+      void form.handleSubmit(() => undefined)();
+      return;
+    }
+    const values = parsed.data;
+    const option = options.find((item) => paymentOptionKey(item) === values.paymentOption);
     if (!option) {
       setNotice("결제수단을 골라 주십시오.");
       return;
     }
-    const form = new FormData(event.currentTarget);
-    const field = (name: string) => String(form.get(name) ?? "");
-    let cashReceipt: z.infer<typeof cashReceiptRequestSchema> | undefined;
-    if (cashReceiptShown && cashReceiptOn) {
-      const parsed = cashReceiptRequestSchema.safeParse({
-        type: cashReceiptType,
-        identityNumber: field("cashReceiptNumber"),
-      });
-      if (!parsed.success) {
-        setNotice(parsed.error.issues[0]?.message ?? "현금영수증 번호를 확인해 주십시오.");
-        return;
-      }
-      cashReceipt = parsed.data;
-    }
+    const cashReceipt =
+      cashReceiptAvailable(option.method) && values.cashReceiptOn
+        ? { type: values.cashReceiptType, identityNumber: values.cashReceiptNumber ?? "" }
+        : undefined;
     const back = window.location.pathname + window.location.search;
     const payments = paymentsFor(config);
     // 결제창은 클릭 시점에 열어야 팝업 차단에 걸리지 않는다 — 서버 함수를 기다리기 전에 빈 창을 먼저 연다
     const paymentWindow = payments.prepareWindow();
     setSubmitting(true);
     setNotice(null);
+    // 결제 금액을 정하는 입력 — 앞 결제와 같으면 그 결제를 이어 간다
+    const signature = JSON.stringify([
+      values.receiverName ?? "",
+      values.phone ?? "",
+      values.zipCode ?? "",
+      values.address1 ?? "",
+      values.address2 ?? "",
+      values.deliveryMemo ?? "",
+      values.guestName ?? "",
+      values.email ?? "",
+      values.orderPassword ?? "",
+      coupon?.code ?? null,
+    ]);
+    if (pending && pending.signature === signature) {
+      void payments
+        .retry(pending.paymentId, { option, cashReceipt, window: paymentWindow })
+        .then((result) => settle(result, back, signature))
+        .catch((error: unknown) => {
+          paymentWindow.close();
+          // 이어 갈 수 없는 결제다(시간 지남 등) — 다음 클릭은 새 결제를 만든다
+          setPending(null);
+          setNotice(
+            error instanceof ApiError && error.code === "PAYMENT_EXPIRED"
+              ? "결제 시간이 지났습니다. 결제하기를 다시 눌러 주십시오."
+              : "결제를 다시 시작하지 못했습니다. 결제하기를 다시 눌러 주십시오.",
+          );
+        })
+        .finally(() => setSubmitting(false));
+      return;
+    }
+    setPending(null);
     void startPayment({
       data: {
         checkoutId: checkout.checkoutId,
         option,
         back,
-        receiverName: field("receiverName"),
-        phone: field("phone"),
-        zipCode: field("zipCode"),
-        address1: field("address1"),
-        address2: field("address2"),
-        deliveryMemo: field("deliveryMemo"),
-        guestName: field("guestName"),
-        email: field("email"),
-        orderPassword: field("orderPassword"),
+        requiresShipping: shipping,
+        receiverName: values.receiverName ?? "",
+        phone: values.phone ?? "",
+        zipCode: values.zipCode ?? "",
+        address1: values.address1 ?? "",
+        address2: values.address2 ?? "",
+        deliveryMemo: values.deliveryMemo ?? "",
+        guestName: values.guestName ?? "",
+        email: values.email ?? "",
+        orderPassword: values.orderPassword ?? "",
         cashReceipt,
+        couponCode: coupon?.code,
+        withdrawalAgreement: withdrawal.required ? values.withdrawalAgreed === true : undefined,
       },
     })
-      .then(async ({ start, error }) => {
+      .then(async ({ start, error, couponFailed }) => {
         if (!start) {
           paymentWindow.close();
-          setNotice(error);
+          if (couponFailed && coupon) {
+            releaseCoupon(coupon.code);
+            setCouponError(error);
+          } else {
+            setNotice(error);
+          }
           return;
         }
         const paymentStart = paymentStartSchema.parse(JSON.parse(start));
         // 확정 금액 — 서버가 보낸 배송지로 배송비를 다시 계산했다. 화면에 보여 준 금액과 다를 수 있다
         setQuote({ amounts: paymentStart.amounts, delivery: paymentStart.delivery });
+        setQuoteConfirmed(true);
         // 리다이렉트 결제가 실패해 복귀 화면으로 오면 같은 결제를 다른 옵션으로 다시 시도한다 — 그때 쓸 목록
         rememberPaymentOptions(paymentStart.paymentId, options);
         // 결제 서비스가 결제창을 그린다. 팝업이면 결과를 여기서 받고, 리다이렉트면 이 탭이 떠난다
-        settle(await payments.open(paymentStart, { window: paymentWindow }), back);
+        settle(await payments.open(paymentStart, { window: paymentWindow }), back, signature);
       })
       .catch(() => {
         paymentWindow.close();
@@ -291,31 +515,86 @@ function Checkout() {
   return (
     <div className="grid gap-8 md:grid-cols-[minmax(0,1.4fr)_minmax(0,1fr)] md:items-start">
       <form onSubmit={handleSubmit} className="space-y-6">
-        <section className="space-y-3">
-          <h2 className="font-bold text-lg">배송지</h2>
-          <Field label="수령인" name="receiverName" defaultValue={member?.name ?? ""} required />
-          <Field label="연락처" name="phone" placeholder="01012345678" required />
-          <Field
-            label="우편번호"
-            name="zipCode"
-            placeholder="04524"
-            required
-            onBlur={handleZipBlur}
-            hint="입력하면 지역 추가 배송비까지 반영한 배송비를 보여 줍니다"
-          />
-          <Field label="주소" name="address1" required />
-          <Field label="상세 주소" name="address2" />
-          <Field label="배송 메모" name="deliveryMemo" />
-        </section>
+        {/* 배송이 필요 없는 주문(이용권·방문 수령 등)은 배송지를 받지 않는다 */}
+        {shipping ? (
+          <section className="space-y-3">
+            <h2 className="font-bold text-lg">배송지</h2>
+            <TextField
+              label="수령인"
+              registration={form.register("receiverName")}
+              error={errors.receiverName?.message}
+              defaultValue={member?.name ?? ""}
+              required
+            />
+            <TextField
+              label="연락처"
+              registration={form.register("phone")}
+              error={errors.phone?.message}
+              type="tel"
+              placeholder="01012345678"
+              required
+            />
+            <TextField
+              label="우편번호"
+              registration={form.register("zipCode", {
+                onBlur: (event: React.FocusEvent<HTMLInputElement>) =>
+                  handleZipBlur(event.target.value.trim()),
+              })}
+              error={errors.zipCode?.message}
+              placeholder="04524"
+              required
+              hint="입력하면 지역 추가 배송비까지 반영한 배송비를 보여 줍니다"
+            />
+            <TextField
+              label="주소"
+              registration={form.register("address1")}
+              error={errors.address1?.message}
+              required
+            />
+            <TextField
+              label="상세 주소"
+              registration={form.register("address2")}
+              error={errors.address2?.message}
+            />
+            <TextField
+              label="배송 메모"
+              registration={form.register("deliveryMemo")}
+              error={errors.deliveryMemo?.message}
+            />
+          </section>
+        ) : null}
 
         {member ? null : (
           <section className="space-y-3">
             <h2 className="font-bold text-lg">비회원 주문</h2>
-            <Field label="주문자명" name="guestName" required />
-            <Field label="이메일" name="email" type="email" required />
-            <Field
+            <TextField
+              label="주문자명"
+              registration={form.register("guestName")}
+              error={errors.guestName?.message}
+              required
+            />
+            {/* 배송지가 없는 주문은 주문자 연락처를 여기서 받는다(배송지 칸의 연락처가 없다) */}
+            {shipping ? null : (
+              <TextField
+                label="연락처"
+                registration={form.register("phone")}
+                error={errors.phone?.message}
+                type="tel"
+                placeholder="01012345678"
+                required
+              />
+            )}
+            <TextField
+              label="이메일"
+              registration={form.register("email")}
+              error={errors.email?.message}
+              type="email"
+              required
+            />
+            <TextField
               label="주문 조회 비밀번호"
-              name="orderPassword"
+              registration={form.register("orderPassword")}
+              error={errors.orderPassword?.message}
               type="password"
               required
               hint="주문 내역을 찾을 때 쓸 6자 이상 비밀번호입니다"
@@ -339,12 +618,12 @@ function Checkout() {
                     }`}
                   >
                     <span className="flex items-center gap-2">
+                      {/* 서버 HTML에도 첫 옵션이 선택돼 있도록 defaultChecked를 함께 준다 */}
                       <input
                         type="radio"
-                        name="paymentOption"
+                        {...form.register("paymentOption")}
                         value={key}
-                        checked={selected === key}
-                        onChange={() => setSelected(key)}
+                        defaultChecked={key === defaultOptionKey}
                       />
                       <span className="font-medium">{option.label}</span>
                     </span>
@@ -354,17 +633,16 @@ function Checkout() {
               })}
             </div>
           )}
+          {errors.paymentOption ? (
+            <p className="text-point text-xs">{errors.paymentOption.message}</p>
+          ) : null}
         </fieldset>
 
         {cashReceiptShown ? (
           <fieldset className="space-y-3">
             <legend className="mb-3 font-bold text-lg">현금영수증</legend>
             <label className="flex items-center gap-2 text-sm">
-              <input
-                type="checkbox"
-                checked={cashReceiptOn}
-                onChange={(event) => setCashReceiptOn(event.target.checked)}
-              />
+              <input type="checkbox" {...form.register("cashReceiptOn")} />
               현금영수증 신청
             </label>
             {cashReceiptOn ? (
@@ -372,24 +650,21 @@ function Checkout() {
                 <label className="block space-y-1">
                   <span className="text-sm">용도</span>
                   <select
-                    name="cashReceiptType"
-                    value={cashReceiptType}
-                    onChange={(event) =>
-                      setCashReceiptType(event.target.value as typeof cashReceiptType)
-                    }
+                    {...form.register("cashReceiptType")}
                     className="w-full rounded-md border border-line px-3 py-2"
                   >
                     <option value="INCOME_DEDUCTION">소득공제</option>
                     <option value="EXPENSE_PROOF">지출증빙</option>
                   </select>
                 </label>
-                <Field
+                <TextField
                   label={
                     cashReceiptType === "EXPENSE_PROOF"
                       ? "사업자등록번호"
                       : "휴대폰 번호 또는 현금영수증카드 번호"
                   }
-                  name="cashReceiptNumber"
+                  registration={form.register("cashReceiptNumber")}
+                  error={errors.cashReceiptNumber?.message}
                   required
                 />
               </>
@@ -397,11 +672,80 @@ function Checkout() {
           </fieldset>
         ) : null}
 
+        <section className="space-y-3">
+          <h2 className="font-bold text-lg">쿠폰</h2>
+          {coupon ? (
+            <div className="flex items-center justify-between gap-3 rounded-md border border-line px-3 py-2 text-sm">
+              <span className="flex flex-col">
+                <span className="font-medium">{coupon.name}</span>
+                <span className="text-muted text-xs">
+                  {coupon.code} · {formatPrice(coupon.discountAmount)} 할인
+                </span>
+              </span>
+              <button
+                type="button"
+                className="text-muted text-sm underline"
+                onClick={() => releaseCoupon(coupon.code)}
+              >
+                쿠폰 빼기
+              </button>
+            </div>
+          ) : (
+            <div className="flex gap-2">
+              {/* 결제 폼 안이라 Enter가 결제를 시작하지 않게 막고 쿠폰만 적용한다 */}
+              <input
+                ref={couponInputRef}
+                defaultValue={couponDraft}
+                onKeyDown={(event) => {
+                  if (event.key !== "Enter") return;
+                  event.preventDefault();
+                  applyCoupon();
+                }}
+                aria-label="쿠폰 코드"
+                placeholder="쿠폰 코드"
+                autoComplete="off"
+                className="h-11 min-w-0 flex-1 rounded-md border border-line px-3 uppercase"
+              />
+              <button
+                type="button"
+                disabled={couponBusy}
+                onClick={applyCoupon}
+                className="h-11 rounded-md border border-ink px-4 font-medium text-sm disabled:opacity-50"
+              >
+                적용
+              </button>
+            </div>
+          )}
+          {couponError ? (
+            <p role="alert" className="text-point text-xs">
+              {couponError}
+            </p>
+          ) : null}
+        </section>
+
+        {withdrawal.required ? (
+          <section className="space-y-3">
+            <h2 className="font-bold text-lg">청약철회 제한 안내</h2>
+            <p className="whitespace-pre-line rounded-md bg-chip px-3 py-2 text-sm">
+              {withdrawal.notice}
+            </p>
+            <label className="flex items-start gap-2 text-sm">
+              <input type="checkbox" className="mt-1" {...form.register("withdrawalAgreed")} />
+              <span>위 청약철회 제한 안내를 확인했으며 동의합니다</span>
+            </label>
+            {errors.withdrawalAgreed ? (
+              <p role="alert" className="text-point text-xs">
+                {errors.withdrawalAgreed.message}
+              </p>
+            ) : null}
+          </section>
+        ) : null}
+
         <SubmitButton
-          disabled={submitting || options.length === 0}
+          disabled={submitting || couponBusy || options.length === 0}
           className="h-12 w-full rounded-md bg-ink font-semibold text-white disabled:opacity-50"
         >
-          {formatPrice(amounts.totalAmount)} 결제하기
+          {formatPrice(totalAmount)} 결제하기
         </SubmitButton>
       </form>
 
@@ -425,21 +769,25 @@ function Checkout() {
           ))}
         </ul>
         <dl className="space-y-1 border-line border-t pt-3 text-sm">
-          <Row label="상품 금액" value={formatPrice(amounts.productAmount)} />
-          {/* 배송비는 배송 묶음(같은 출고지 + 같은 배송 정책)마다 한 번 붙고, 지역 추가 배송비는 묶음마다 더한다 */}
-          <Row label="기본 배송비" value={formatPrice(delivery.baseFee)} />
-          {delivery.remoteSurcharge > 0 ? (
+          <Row label="상품 금액" value={formatPrice(baseAmounts.productAmount)} />
+          {/* 배송비는 배송 묶음(같은 출고지 + 같은 배송 정책)마다 한 번 붙고, 지역 추가 배송비는 묶음마다 더한다.
+              배송이 필요 없는 주문은 배송비가 없다 */}
+          {shipping ? <Row label="기본 배송비" value={formatPrice(delivery.baseFee)} /> : null}
+          {shipping && delivery.remoteSurcharge > 0 ? (
             <Row
               label={`${delivery.remoteAreaLabel ?? "지역"} 추가 배송비`}
               value={formatPrice(delivery.remoteSurcharge)}
             />
           ) : null}
+          {couponDiscount > 0 ? (
+            <Row label="쿠폰 할인" value={`−${formatPrice(couponDiscount)}`} />
+          ) : null}
           <div className="flex justify-between border-line border-t pt-2 font-bold">
             <dt>총 결제금액</dt>
-            <dd>{formatPrice(amounts.totalAmount)}</dd>
+            <dd>{formatPrice(totalAmount)}</dd>
           </div>
         </dl>
-        {deliveryNotes(delivery).map((note) => (
+        {(shipping ? deliveryNotes(delivery) : []).map((note) => (
           <p key={note} className="text-muted text-xs">
             {note}
           </p>
@@ -470,60 +818,6 @@ function deliveryNotes(delivery: CheckoutDelivery): string[] {
   return notes;
 }
 
-function Field({
-  label,
-  name,
-  type = "text",
-  defaultValue,
-  placeholder,
-  required,
-  hint,
-  onBlur,
-}: {
-  label: string;
-  name: string;
-  type?: string;
-  defaultValue?: string;
-  placeholder?: string;
-  required?: boolean;
-  hint?: string;
-  onBlur?: (value: string) => void;
-}) {
-  const hintId = useId();
-  return (
-    <label className="block space-y-1">
-      <span className="text-sm">
-        {label}
-        {/* 필수 표시는 눈으로만 본다 — 입력의 required가 보조 기술에 필수임을 알린다 */}
-        {required ? (
-          <span aria-hidden="true" className="text-point">
-            {" "}
-            *
-          </span>
-        ) : null}
-      </span>
-      {/* 프리필은 defaultValue로 준다 — SSR HTML에 값이 실린다 */}
-      <input
-        type={type}
-        name={name}
-        defaultValue={defaultValue}
-        placeholder={placeholder}
-        required={required}
-        // 이름은 라벨 글자 그대로다(필수 표시·안내 문구는 빼고) — 안내는 aria-describedby로 잇는다
-        aria-label={label}
-        aria-describedby={hint ? hintId : undefined}
-        onBlur={onBlur ? (event) => onBlur(event.target.value) : undefined}
-        className="h-11 w-full rounded-md border border-line px-3"
-      />
-      {hint ? (
-        <span id={hintId} className="block text-muted text-xs">
-          {hint}
-        </span>
-      ) : null}
-    </label>
-  );
-}
-
 function Row({ label, value }: { label: string; value: string }) {
   return (
     <div className="flex justify-between">