@sayren/mcp 0.5.1 → 0.6.0

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

@@ -1,10 +1,12 @@
+import { ApiError, type AvailablePaymentOption, paymentOptionKey } from "@sayren/storefront-sdk";
 import type { PaymentResult } from "@sayren/storefront-sdk/payments";
 import { createFileRoute, Link, useNavigate } from "@tanstack/react-router";
 import { createServerFn } from "@tanstack/react-start";
-import { useEffect, useState } from "react";
+import { useCallback, useEffect, useState } from "react";
 import { z } from "zod";
 import type { PublicConfig } from "../lib/config";
 import { API_BASE_URL, resolveStoreCode } from "../lib/config.server";
+import { forgetPaymentOptions, recallPaymentOptions } from "../lib/payment-options";
 import { paymentsFor } from "../lib/payments";
 import { safeRedirect } from "../lib/safe-redirect";
 
@@ -34,12 +36,15 @@ const POLL_TIMES = 15;
 type View =
   | { kind: "working" }
   | { kind: "processing" }
-  | { kind: "failed"; canceled: boolean; message: string }
+  | { kind: "failed"; paymentId: string; canceled: boolean; message: string }
   | { kind: "unknown" };
 
 /**
  * 결제 복귀 화면 — 결제 서비스가 리다이렉트 결제를 마치고 돌려보내는 곳이다. 결과는 주소의 결제 id로
  * 결제 상태를 조회해 정한다(`payments.result`). 같은 주소로 다시 열어도(뒤로 가기·새로고침) 안전하다.
+ *
+ * 실패·취소면 같은 결제를 다른 결제 옵션으로 다시 시도한다(`payments.retry`). 옵션은 주문서가 결제창을 열기 전에
+ * 남겨 둔 목록이다(`payment-options.ts`). 목록이 없으면 주문서로 돌아가 새로 결제한다.
  */
 export const Route = createFileRoute("/checkout/return")({
   validateSearch: returnSearch,
@@ -54,21 +59,34 @@ function PaymentReturn() {
   const { back } = Route.useSearch();
   const navigate = useNavigate();
   const [view, setView] = useState<View>({ kind: "working" });
+  const [retryError, setRetryError] = useState<string | null>(null);
+  // 남겨 둔 옵션은 탭 저장소에 있다 — 서버 렌더에는 없으므로 실패가 확정된 뒤(브라우저)에 읽는다
+  const [options, setOptions] = useState<AvailablePaymentOption[]>([]);
+  /** 다시 시도한 결제의 결과가 확인 중이면 올려서 결제 상태 조회를 처음부터 다시 돌린다(같은 결제 id다) */
+  const [round, setRound] = useState(0);
 
-  useEffect(() => {
-    let active = true;
-    const payments = paymentsFor(config);
-    const done = (orderId: string) =>
+  const complete = useCallback(
+    (paymentId: string, orderId: string) => {
+      forgetPaymentOptions(paymentId);
       void navigate({ to: "/checkout/complete", search: { orderId }, replace: true });
+    },
+    [navigate],
+  );
 
-    const show = (result: PaymentResult): boolean => {
+  /** 확정된 결과면 화면을 정하고 true. `PROCESSING`이면 false — 실패로 단정하지 않는다 */
+  const show = useCallback(
+    (result: PaymentResult): boolean => {
       if (result.status === "COMPLETED") {
-        done(result.orderId);
+        complete(result.paymentId, result.orderId);
         return true;
       }
       if (result.status === "CANCELED" || result.status === "FAILED") {
+        // 만료된 결제는 다시 시도할 수 없다(409 PAYMENT_EXPIRED) — 주문서로 돌아가 새로 결제한다
+        if (result.code === "EXPIRED") forgetPaymentOptions(result.paymentId);
+        setOptions(result.code === "EXPIRED" ? [] : recallPaymentOptions(result.paymentId));
         setView({
           kind: "failed",
+          paymentId: result.paymentId,
           canceled: result.status === "CANCELED",
           message: result.message,
         });
@@ -79,12 +97,24 @@ function PaymentReturn() {
         return true;
       }
       return false;
+    },
+    [complete],
+  );
+
+  useEffect(() => {
+    let active = true;
+    const payments = paymentsFor(config);
+    const settle = (result: PaymentResult): boolean => {
+      if (!active) return true;
+      return show(result);
     };
 
     const run = async () => {
+      // 다시 시도한 결제를 확인하는 중이면 처음부터 확인 중으로 보인다
+      if (round > 0) setView({ kind: "processing" });
       const first = await payments.result(window.location.href).catch(() => null);
       if (!active) return;
-      if (first && show(first)) return;
+      if (first && settle(first)) return;
       // 결과 확인 중 — 실패로 단정하지 않고 결제 상태를 다시 조회한다
       setView({ kind: "processing" });
       for (let i = 0; i < POLL_TIMES && active; i += 1) {
@@ -92,7 +122,7 @@ function PaymentReturn() {
         if (!active) return;
         const next = await payments.result(window.location.href).catch(() => null);
         if (!active) return;
-        if (next && show(next)) return;
+        if (next && settle(next)) return;
       }
       if (active) setView({ kind: "unknown" });
     };
@@ -101,7 +131,35 @@ function PaymentReturn() {
     return () => {
       active = false;
     };
-  }, [config, navigate]);
+  }, [config, show, round]);
+
+  /**
+   * 같은 결제를 다른 옵션으로 다시 시도한다. 클릭 핸들러에서 바로 부른다 — 팝업은 클릭 시점에 열어야 차단되지 않는다.
+   * 복귀 주소는 결제 시작 때의 값을 그대로 쓴다. 모바일은 이 탭이 결제 서비스로 이동했다가 다시 이 화면으로 돌아온다.
+   */
+  const retry = (paymentId: string, option: AvailablePaymentOption, previous: View) => {
+    setRetryError(null);
+    setView({ kind: "working" });
+    paymentsFor(config)
+      .retry(paymentId, { option })
+      .then((result) => {
+        if (result.status === "PROCESSING") setRound((value) => value + 1);
+        else show(result);
+      })
+      .catch((error: unknown) => {
+        // 결제창을 열지 못했다 — 방금 보던 실패 화면으로 되돌린다
+        setView(previous);
+        setRetryError(retryErrorMessage(error));
+        // 더 진행할 수 없는 결제면 옵션을 거두고 주문서로 돌아가게 한다
+        if (
+          error instanceof ApiError &&
+          (error.code === "PAYMENT_EXPIRED" || error.code === "ALREADY_PROCESSED")
+        ) {
+          forgetPaymentOptions(paymentId);
+          setOptions([]);
+        }
+      });
+  };
 
   return (
     <div className="mx-auto max-w-md space-y-6 py-16 text-center">
@@ -110,8 +168,8 @@ function PaymentReturn() {
           <h1 className="font-bold text-2xl">결제를 확인하고 있습니다</h1>
           <p className="text-muted text-sm">
             {view.kind === "processing"
-              ? "결제사에서 결과를 확인하는 중입니다. 이 화면을 닫지 말고 잠시만 기다려주십시오."
-              : "잠시만 기다려주십시오."}
+              ? "결제사에서 결과를 확인하는 중입니다. 이 화면을 닫지 말고 잠시만 기다려 주십시오."
+              : "잠시만 기다려 주십시오."}
           </p>
         </>
       ) : view.kind === "failed" ? (
@@ -120,18 +178,49 @@ function PaymentReturn() {
             {view.canceled ? "결제를 취소했습니다" : "결제하지 못했습니다"}
           </h1>
           {view.canceled ? null : <p className="text-muted text-sm">{view.message}</p>}
-          <div className="flex justify-center gap-2">
-            <a href={back ?? "/cart"} className="rounded-md bg-ink px-5 py-3 text-white">
-              다른 결제수단으로 다시 결제
-            </a>
-          </div>
+          {options.length ? (
+            <section aria-labelledby="retry-heading" className="space-y-2 text-left">
+              <h2 id="retry-heading" className="font-bold text-sm">
+                다른 결제수단으로 다시 결제
+              </h2>
+              <div className="grid gap-2">
+                {options.map((option) => (
+                  <button
+                    key={paymentOptionKey(option)}
+                    type="button"
+                    data-testid="retry-option"
+                    onClick={() => retry(view.paymentId, option, view)}
+                    className="flex items-center justify-between rounded-md border border-line px-4 py-3 text-sm hover:border-ink"
+                  >
+                    <span className="font-medium">{option.label}</span>
+                    <span className="text-muted text-xs">{option.pgName}</span>
+                  </button>
+                ))}
+              </div>
+              {retryError ? (
+                <p role="alert" className="text-point text-sm">
+                  {retryError}
+                </p>
+              ) : null}
+            </section>
+          ) : null}
+          <a
+            href={back ?? "/cart"}
+            className={
+              options.length
+                ? "inline-block text-sm underline"
+                : "inline-block rounded-md bg-ink px-5 py-3 text-white"
+            }
+          >
+            {options.length ? "주문서로 돌아가기" : "주문서로 돌아가 다시 결제"}
+          </a>
         </>
       ) : (
         <>
           <h1 className="font-bold text-2xl">결제 결과를 확인하지 못했습니다</h1>
           <p className="text-muted text-sm">
             결제를 마쳤다면 잠시 뒤 주문 내역에 나타납니다. 다시 결제하기 전에 주문 내역을 먼저
-            확인해주십시오.
+            확인해 주십시오.
           </p>
           <Link to="/orders" className="inline-block rounded-md border border-ink px-5 py-3">
             주문 내역
@@ -141,3 +230,20 @@ function PaymentReturn() {
     </div>
   );
 }
+
+function retryErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) {
+    switch (error.code) {
+      case "PAYMENT_OPTION_UNAVAILABLE":
+        return "지금 쓸 수 없는 결제수단입니다. 다른 결제수단을 골라 주십시오.";
+      case "PAYMENT_PROVIDER_UNAVAILABLE":
+        return "결제창을 준비하지 못했습니다. 다른 결제수단으로 시도해 주십시오.";
+      case "PAYMENT_IN_PROGRESS":
+        return "결제를 확인하고 있습니다. 잠시 뒤 주문 내역을 확인해 주십시오.";
+      case "PAYMENT_EXPIRED":
+      case "ALREADY_PROCESSED":
+        return "이 결제는 더 진행할 수 없습니다. 주문서로 돌아가 새로 결제해 주십시오.";
+    }
+  }
+  return "다시 결제하지 못했습니다. 주문서로 돌아가 새로 결제해 주십시오.";
+}

package/template/src/routes/guest-order.tsx

@@ -0,0 +1,171 @@
+import { ApiError, type MyOrder } from "@sayren/storefront-sdk";
+import { createFileRoute } from "@tanstack/react-router";
+import { createServerFn } from "@tanstack/react-start";
+import { useState } from "react";
+import { z } from "zod";
+import { ProductThumb } from "../components/product-thumb";
+import { SubmitButton } from "../components/submit-button";
+import { apiFor } from "../lib/api.server";
+import { formatDateTime, formatPrice } from "../lib/format";
+import { orderItemStatusLabel } from "../lib/order-status";
+
+const guestOrderSearch = z.object({
+  /** 주문 완료 화면이 주문번호를 채워 보낸다 */
+  orderId: z.string().optional().catch(undefined),
+});
+
+/**
+ * 비회원 주문 조회 — 주문번호와 주문할 때 적은 연락처·주문 조회 비밀번호로 찾는다.
+ * 비밀번호가 주소에 남지 않도록 서버 함수(POST)로 보낸다.
+ */
+const lookupGuestOrder = createServerFn({ method: "POST" })
+  .validator(z.object({ orderId: z.string(), phone: z.string(), orderPassword: z.string() }))
+  .handler(async ({ data }) => {
+    const orderId = data.orderId.trim();
+    const phone = data.phone.replace(/[^0-9]/g, "");
+    if (!orderId || !phone || !data.orderPassword) {
+      return { order: null, error: "주문번호·연락처·비밀번호를 모두 입력해 주십시오" };
+    }
+    try {
+      const order: MyOrder = await apiFor().myOrders.getGuestOrder(orderId, {
+        phone,
+        orderPassword: data.orderPassword,
+      });
+      return { order, error: null };
+    } catch (error) {
+      if (error instanceof ApiError && (error.status === 401 || error.status === 404)) {
+        return { order: null, error: "주문을 찾지 못했습니다. 입력한 내용을 확인해 주십시오" };
+      }
+      return { order: null, error: "조회하지 못했습니다. 잠시 후 다시 시도해 주십시오" };
+    }
+  });
+
+export const Route = createFileRoute("/guest-order")({
+  validateSearch: guestOrderSearch,
+  head: () => ({ meta: [{ title: "비회원 주문 조회" }] }),
+  component: GuestOrder,
+});
+
+function GuestOrder() {
+  const { orderId } = Route.useSearch();
+  const [order, setOrder] = useState<MyOrder | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [pending, setPending] = useState(false);
+
+  const submit = (event: React.FormEvent<HTMLFormElement>) => {
+    event.preventDefault();
+    const form = new FormData(event.currentTarget);
+    setPending(true);
+    setError(null);
+    void lookupGuestOrder({
+      data: {
+        orderId: String(form.get("orderId") ?? ""),
+        phone: String(form.get("phone") ?? ""),
+        orderPassword: String(form.get("orderPassword") ?? ""),
+      },
+    })
+      .then((result) => {
+        setOrder(result.order);
+        setError(result.error);
+      })
+      .catch(() => {
+        setOrder(null);
+        setError("조회하지 못했습니다. 잠시 후 다시 시도해 주십시오");
+      })
+      .finally(() => setPending(false));
+  };
+
+  return (
+    <div className="mx-auto max-w-lg space-y-6 py-10">
+      <div className="space-y-1">
+        <h1 className="font-bold text-2xl">비회원 주문 조회</h1>
+        <p className="text-muted text-sm">
+          주문할 때 입력한 연락처와 주문 조회 비밀번호를 넣어 주십시오.
+        </p>
+      </div>
+
+      <form onSubmit={submit} className="space-y-3">
+        <Field label="주문번호" name="orderId" defaultValue={orderId} placeholder="ord_" />
+        <Field label="연락처" name="phone" type="tel" placeholder="01012345678" />
+        <Field label="주문 조회 비밀번호" name="orderPassword" type="password" />
+        <SubmitButton
+          disabled={pending}
+          className="h-12 w-full rounded-md bg-ink font-semibold text-white disabled:opacity-50"
+        >
+          조회하기
+        </SubmitButton>
+      </form>
+      {error ? (
+        <p role="alert" className="text-point text-sm">
+          {error}
+        </p>
+      ) : null}
+
+      {order ? (
+        <section aria-label="주문 정보" className="space-y-3 rounded-lg border border-line p-5">
+          <div className="space-y-1">
+            <h2 className="font-bold text-lg">주문 {order.orderId}</h2>
+            <p className="text-muted text-sm">{formatDateTime(order.orderedAt)}</p>
+          </div>
+          <ul className="divide-y divide-line">
+            {order.items.map((item) => (
+              <li key={item.orderItemId} className="flex items-center gap-3 py-3 text-sm">
+                <ProductThumb
+                  src={item.thumbnailUrl}
+                  alt={item.productName}
+                  className="size-14 rounded-md bg-chip object-cover"
+                />
+                <span className="flex flex-1 flex-col gap-0.5">
+                  <span>{item.productName}</span>
+                  {item.optionName ? (
+                    <span className="text-muted text-xs">{item.optionName}</span>
+                  ) : null}
+                  <span className="text-muted text-xs">
+                    {orderItemStatusLabel(item.status)} · 수량 {item.quantity}개
+                  </span>
+                </span>
+                <span>{formatPrice(item.totalPrice)}</span>
+              </li>
+            ))}
+          </ul>
+          <div className="flex justify-between border-line border-t pt-2 font-bold text-sm">
+            <span>결제 금액</span>
+            <span>{formatPrice(order.payment.totalAmount)}</span>
+          </div>
+          <p className="text-muted text-xs">
+            취소·반품은 스토어 고객센터로 문의해 주십시오. 회원으로 주문하면 주문 내역에서 직접
+            신청할 수 있습니다.
+          </p>
+        </section>
+      ) : null}
+    </div>
+  );
+}
+
+function Field({
+  label,
+  name,
+  type = "text",
+  defaultValue,
+  placeholder,
+}: {
+  label: string;
+  name: string;
+  type?: string;
+  defaultValue?: string;
+  placeholder?: string;
+}) {
+  return (
+    <label className="block space-y-1">
+      <span className="text-sm">{label}</span>
+      <input
+        type={type}
+        name={name}
+        defaultValue={defaultValue}
+        placeholder={placeholder}
+        required
+        className="h-11 w-full rounded-md border border-line px-3"
+      />
+    </label>
+  );
+}

package/template/src/routes/index.tsx

@@ -20,9 +20,8 @@ const getHome = createServerFn({ method: "GET" }).handler(async () => {
 });
 
 export const Route = createFileRoute("/")({
-  head: () => ({
-    meta: [{ title: "스토어" }, { name: "description", content: "지금 인기 있는 상품" }],
-  }),
+  // 제목은 루트가 스토어 이름으로 정한다
+  head: () => ({ meta: [{ name: "description", content: "지금 인기 있는 상품" }] }),
   loader: () => getHome(),
   component: Home,
 });

package/template/src/routes/login.tsx

@@ -1,5 +1,5 @@
 import { ApiError, type SocialProvider } from "@sayren/storefront-sdk";
-import { createFileRoute } from "@tanstack/react-router";
+import { createFileRoute, Link } from "@tanstack/react-router";
 import { createServerFn } from "@tanstack/react-start";
 import { getRequestUrl } from "@tanstack/react-start/server";
 import { useState } from "react";
@@ -174,14 +174,18 @@ function Login() {
           <input
             type="email"
             name="email"
+            aria-label="이메일"
             placeholder="이메일"
+            autoComplete="email"
             required
             className="h-11 w-full rounded-md border border-line px-3"
           />
           <input
             type="password"
             name="password"
+            aria-label="비밀번호"
             placeholder="비밀번호"
+            autoComplete="current-password"
             required
             className="h-11 w-full rounded-md border border-line px-3"
           />
@@ -193,10 +197,25 @@ function Login() {
           </SubmitButton>
         </form>
       ) : null}
-      {error ? <p className="text-point text-sm">{error}</p> : null}
+      {error ? (
+        <p role="alert" className="text-point text-sm">
+          {error}
+        </p>
+      ) : null}
       {social.length ? (
         <p className="text-center text-muted text-xs">처음 소셜 로그인하면 가입이 함께 됩니다</p>
       ) : null}
+      <div className="flex justify-center gap-4 text-sm">
+        {/* 이메일·비밀번호 가입은 그 로그인 방법이 켜진 스토어에서만 된다 */}
+        {password ? (
+          <Link to="/signup" search={{ redirectTo }} className="underline">
+            회원가입
+          </Link>
+        ) : null}
+        <Link to="/guest-order" className="text-muted underline">
+          비회원 주문 조회
+        </Link>
+      </div>
     </div>
   );
 }

package/template/src/routes/orders.$orderId.tsx

@@ -15,6 +15,7 @@ import { ProductThumb } from "../components/product-thumb";
 import { SubmitButton } from "../components/submit-button";
 import { apiFor } from "../lib/api.server";
 import { formatDateTime, formatPrice } from "../lib/format";
+import { orderItemStatusLabel } from "../lib/order-status";
 import { readToken } from "../lib/session.server";
 
 const getOrder = createServerFn({ method: "GET" })
@@ -62,18 +63,18 @@ const createClaim = createServerFn({ method: "POST" })
   });
 
 function claimErrorMessage(error: unknown): string {
-  if (!(error instanceof ApiError)) return "접수하지 못했습니다. 잠시 후 다시 시도해주십시오.";
+  if (!(error instanceof ApiError)) return "접수하지 못했습니다. 잠시 후 다시 시도해 주십시오.";
   switch (error.code) {
     case "INVALID_QUANTITY":
-      return "남은 수량보다 많이 신청했습니다. 수량을 확인해주십시오.";
+      return "남은 수량보다 많이 신청했습니다. 수량을 확인해 주십시오.";
     case "CLAIM_IN_PROGRESS":
       return "이미 진행 중인 신청이 있습니다.";
     case "INVALID_STATUS":
-      return "지금은 신청할 수 없는 상태입니다. 주문 상태를 확인해주십시오.";
+      return "지금은 신청할 수 없는 상태입니다. 주문 상태를 확인해 주십시오.";
     case "PERIOD_EXPIRED":
       return "반품·교환 가능 기간이 지났습니다.";
     default:
-      return error.message || "접수하지 못했습니다. 잠시 후 다시 시도해주십시오.";
+      return error.message || "접수하지 못했습니다. 잠시 후 다시 시도해 주십시오.";
   }
 }
 
@@ -171,6 +172,7 @@ function OrderDetail() {
             <div className="flex items-center gap-4">
               <ProductThumb
                 src={item.thumbnailUrl}
+                alt={item.productName}
                 className="size-16 rounded-md bg-chip object-cover"
               />
               <span className="flex flex-1 flex-col gap-1 text-sm">
@@ -179,7 +181,7 @@ function OrderDetail() {
                   <span className="text-muted text-xs">{item.optionName}</span>
                 ) : null}
                 <span className="text-muted text-xs">
-                  {item.status} · 수량 {item.quantity}개
+                  {orderItemStatusLabel(item.status)} · 수량 {item.quantity}개
                   {item.canceledQuantity > 0
                     ? ` · 취소·반품 ${item.canceledQuantity}개 · 남은 수량 ${item.activeQuantity}개`
                     : null}
@@ -271,9 +273,9 @@ function ClaimForm({
   const quantity = Number(quantityText);
   const quantityError =
     quantityText.trim() === "" || !Number.isInteger(quantity)
-      ? "수량을 입력해주십시오."
+      ? "수량을 입력해 주십시오."
       : quantity < 1 || quantity > item.activeQuantity
-        ? `수량은 1개 이상 ${item.activeQuantity}개 이하로 입력해주십시오.`
+        ? `수량은 1개 이상 ${item.activeQuantity}개 이하로 입력해 주십시오.`
         : null;
   return (
     <form

package/template/src/routes/products.$productId.tsx

@@ -75,12 +75,16 @@ function ProductDetail() {
   return (
     <div className="grid gap-8 md:grid-cols-2">
       <div className="space-y-3">
-        <ProductThumb src={product.thumbnailUrl} className="w-full rounded-lg bg-chip" />
-        {product.images.slice(0, 4).map((image) => (
+        <ProductThumb
+          src={product.thumbnailUrl}
+          alt={product.name}
+          className="w-full rounded-lg bg-chip"
+        />
+        {product.images.slice(0, 4).map((image, index) => (
           <img
             key={image}
             src={image}
-            alt=""
+            alt={`${product.name} 이미지 ${index + 1}`}
             className="w-full rounded-lg bg-chip"
             loading="lazy"
           />
@@ -107,7 +111,7 @@ function ProductDetail() {
             setError(null);
             addToCart({ data: { productId: product.productId, optionId, quantity } })
               .then(() => navigate({ to: "/cart" }))
-              .catch(() => setError("장바구니에 담지 못했습니다. 다시 시도해주십시오"))
+              .catch(() => setError("장바구니에 담지 못했습니다. 다시 시도해 주십시오"))
               .finally(() => setSubmitting(false));
           }}
         >

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

@@ -54,6 +54,9 @@ function Products() {
 
   return (
     <div className="space-y-6">
+      <h1 className="font-bold text-2xl">
+        {applied.keyword ? `"${applied.keyword}" 검색 결과` : "전체 상품"}
+      </h1>
       {/* 하이드레이션 전에는 GET 폼으로 그대로 제출되고, 뒤에는 화면을 새로 그리지 않고 이동한다 */}
       <form
         action="/products"
@@ -70,6 +73,7 @@ function Products() {
         <input
           type="search"
           name="keyword"
+          aria-label="상품 검색"
           defaultValue={applied.keyword ?? ""}
           placeholder="상품 검색"
           className="h-11 flex-1 rounded-md border border-line px-3"