@sayren/mcp 0.6.1 → 0.8.0

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

@@ -1,14 +1,26 @@
+import { zodResolver } from "@hookform/resolvers/zod";
 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 { useForm } from "react-hook-form";
 import { z } from "zod";
+import { FulfillmentCodes } from "../components/fulfillment-codes";
+import { FulfillmentDownloads } from "../components/fulfillment-downloads";
 import { ProductThumb } from "../components/product-thumb";
 import { SubmitButton } from "../components/submit-button";
+import { TextField } from "../components/text-field";
 import { apiFor } from "../lib/api.server";
+import { type CodeRevealResult, codeRevealErrorMessage, normalizePhone } from "../lib/code-reveal";
+import { type DownloadResult, downloadErrorMessage } from "../lib/download";
+import {
+  type GuestOrderLookup,
+  type GuestOrderLookupInput,
+  guestOrderLookupSchema,
+} from "../lib/form-schemas";
 import { formatDateTime, formatPrice } from "../lib/format";
 import { guestLookupLockedMessage } from "../lib/guest-order";
-import { orderItemStatusLabel } from "../lib/order-status";
+import { orderItemStatusLabel, withdrawalRestrictedLabel } from "../lib/order-status";
 import { pageTitle } from "../lib/page-title";
 
 const guestOrderSearch = z.object({
@@ -24,7 +36,7 @@ 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, "");
+    const phone = normalizePhone(data.phone);
     if (!orderId || !phone || !data.orderPassword) {
       return { order: null, error: "주문번호·연락처·비밀번호를 모두 입력해 주십시오" };
     }
@@ -46,6 +58,58 @@ const lookupGuestOrder = createServerFn({ method: "POST" })
     }
   });
 
+/**
+ * 비회원 코드 열람 — 조회에 쓴 연락처·주문 조회 비밀번호로 다시 확인한다(주문 조회와 같은 시도 한도).
+ * 비밀번호는 서버 함수 본문(POST)으로만 보내고 주소에 남기지 않는다.
+ */
+const revealGuestCode = createServerFn({ method: "POST" })
+  .validator(
+    z.object({
+      orderId: z.string(),
+      orderItemId: z.string(),
+      phone: z.string(),
+      orderPassword: z.string(),
+    }),
+  )
+  .handler(async ({ data }): Promise<CodeRevealResult> => {
+    try {
+      const result = await apiFor().myOrders.revealGuestCode(data.orderId, data.orderItemId, {
+        phone: normalizePhone(data.phone),
+        orderPassword: data.orderPassword,
+      });
+      return { codes: result.codes, error: null };
+    } catch (error) {
+      return { codes: null, error: codeRevealErrorMessage(error) };
+    }
+  });
+
+/**
+ * 비회원 파일 받기 — 조회에 쓴 연락처·주문 조회 비밀번호로 다시 확인하고 서명 주소(수명 300초)를 받는다. 받을 때마다
+ * 횟수를 하나 쓴다. 비밀번호는 서버 함수 본문(POST)으로만 보내고 주소에 남기지 않는다.
+ */
+const createGuestDownload = createServerFn({ method: "POST" })
+  .validator(
+    z.object({
+      orderId: z.string(),
+      orderItemId: z.string(),
+      assetId: z.string(),
+      phone: z.string(),
+      orderPassword: z.string(),
+    }),
+  )
+  .handler(async ({ data }): Promise<DownloadResult> => {
+    try {
+      const link = await apiFor().myOrders.createGuestDownload(data.orderId, data.orderItemId, {
+        phone: normalizePhone(data.phone),
+        orderPassword: data.orderPassword,
+        assetId: data.assetId,
+      });
+      return { url: link.url, fileName: link.fileName, remaining: link.remaining, error: null };
+    } catch (error) {
+      return { url: null, error: downloadErrorMessage(error) };
+    }
+  });
+
 export const Route = createFileRoute("/guest-order")({
   validateSearch: guestOrderSearch,
   head: ({ matches }) => ({
@@ -61,31 +125,27 @@ export const Route = createFileRoute("/guest-order")({
 function GuestOrder() {
   const { orderId } = Route.useSearch();
   const [order, setOrder] = useState<MyOrder | null>(null);
+  // 코드 열람에 다시 쓰는 조회 값 — 이 컴포넌트 상태에만 둔다(주소·스토리지에 남기지 않는다)
+  const [lookup, setLookup] = useState<GuestOrderLookup | null>(null);
   const [error, setError] = useState<string | null>(null);
-  const [pending, setPending] = useState(false);
+  const form = useForm<GuestOrderLookupInput, unknown, GuestOrderLookup>({
+    resolver: zodResolver(guestOrderLookupSchema),
+  });
+  const { errors, isSubmitting } = form.formState;
 
-  const submit = (event: React.FormEvent<HTMLFormElement>) => {
-    event.preventDefault();
-    const form = new FormData(event.currentTarget);
-    setPending(true);
+  const submit = form.handleSubmit(async (values) => {
     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));
-  };
+    try {
+      const result = await lookupGuestOrder({ data: values });
+      setOrder(result.order);
+      setLookup(result.order ? values : null);
+      setError(result.error);
+    } catch {
+      setOrder(null);
+      setLookup(null);
+      setError("조회하지 못했습니다. 잠시 후 다시 시도해 주십시오");
+    }
+  });
 
   return (
     <div className="mx-auto max-w-lg space-y-6 py-10">
@@ -97,11 +157,32 @@ function GuestOrder() {
       </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" />
+        {/* 주문 완료 화면이 주문번호를 채워 보낸다 — 서버 HTML에 값이 실리도록 defaultValue로 준다 */}
+        <TextField
+          label="주문번호"
+          registration={form.register("orderId")}
+          error={errors.orderId?.message}
+          defaultValue={orderId}
+          placeholder="ord_"
+          required
+        />
+        <TextField
+          label="연락처"
+          registration={form.register("phone")}
+          error={errors.phone?.message}
+          type="tel"
+          placeholder="01012345678"
+          required
+        />
+        <TextField
+          label="주문 조회 비밀번호"
+          registration={form.register("orderPassword")}
+          error={errors.orderPassword?.message}
+          type="password"
+          required
+        />
         <SubmitButton
-          disabled={pending}
+          disabled={isSubmitting}
           className="h-12 w-full rounded-md bg-ink font-semibold text-white disabled:opacity-50"
         >
           조회하기
@@ -121,22 +202,59 @@ function GuestOrder() {
           </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}개
+              <li key={item.orderItemId} className="space-y-2 py-3 text-sm">
+                <div className="flex items-center gap-3">
+                  <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.fulfillmentType)} · 수량{" "}
+                      {item.quantity}개
+                    </span>
+                    {withdrawalRestrictedLabel(item) ? (
+                      <span className="text-muted text-xs">{withdrawalRestrictedLabel(item)}</span>
+                    ) : null}
                   </span>
-                </span>
-                <span>{formatPrice(item.totalPrice)}</span>
+                  <span>{formatPrice(item.totalPrice)}</span>
+                </div>
+                {lookup ? (
+                  <FulfillmentCodes
+                    item={item}
+                    reveal={() =>
+                      revealGuestCode({
+                        data: {
+                          orderId: order.orderId,
+                          orderItemId: item.orderItemId,
+                          phone: lookup.phone,
+                          orderPassword: lookup.orderPassword,
+                        },
+                      })
+                    }
+                  />
+                ) : null}
+                {lookup ? (
+                  <FulfillmentDownloads
+                    item={item}
+                    download={(assetId) =>
+                      createGuestDownload({
+                        data: {
+                          orderId: order.orderId,
+                          orderItemId: item.orderItemId,
+                          assetId,
+                          phone: lookup.phone,
+                          orderPassword: lookup.orderPassword,
+                        },
+                      })
+                    }
+                  />
+                ) : null}
               </li>
             ))}
           </ul>
@@ -153,31 +271,3 @@ function GuestOrder() {
     </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/orders.$orderId.tsx

@@ -11,11 +11,19 @@ import { createFileRoute, Link, notFound, redirect, useRouter } from "@tanstack/
 import { createServerFn } from "@tanstack/react-start";
 import { useState } from "react";
 import { z } from "zod";
+import { FulfillmentCodes } from "../components/fulfillment-codes";
+import { FulfillmentDownloads } from "../components/fulfillment-downloads";
 import { ProductThumb } from "../components/product-thumb";
 import { SubmitButton } from "../components/submit-button";
 import { apiFor } from "../lib/api.server";
+import { type CodeRevealResult, codeRevealErrorMessage } from "../lib/code-reveal";
+import { type DownloadResult, downloadErrorMessage } from "../lib/download";
 import { formatDateTime, formatPrice } from "../lib/format";
-import { orderItemStatusLabel } from "../lib/order-status";
+import {
+  orderItemStatusLabel,
+  WITHDRAWAL_RESTRICTED_CLAIM_MESSAGE,
+  withdrawalRestrictedLabel,
+} from "../lib/order-status";
 import { pageTitle } from "../lib/page-title";
 import { readToken } from "../lib/session.server";
 
@@ -34,6 +42,42 @@ const getOrder = createServerFn({ method: "GET" })
     }
   });
 
+/**
+ * 코드 열람 — 코드 발급 상품의 평문 코드를 받는다. 처음 연 시각이 기록된다. 구매자 토큰은 서버에만 두므로 서버
+ * 함수에서 부르고, 평문은 응답으로만 돌려준다(저장하지 않는다).
+ */
+const revealCode = createServerFn({ method: "POST" })
+  .validator(z.object({ orderItemId: z.string() }))
+  .handler(async ({ data }): Promise<CodeRevealResult> => {
+    const accessToken = readToken();
+    if (!accessToken) throw redirect({ to: "/login", search: { redirectTo: "/orders" } });
+    try {
+      const result = await apiFor({ accessToken }).myOrders.revealCode(data.orderItemId);
+      return { codes: result.codes, error: null };
+    } catch (error) {
+      return { codes: null, error: codeRevealErrorMessage(error) };
+    }
+  });
+
+/**
+ * 파일 받기 — 파일 다운로드 상품의 서명 주소(수명 300초)를 받는다. 받을 때마다 횟수를 하나 쓴다. 구매자 토큰은 서버에만
+ * 두므로 서버 함수에서 부르고, 주소는 응답으로만 돌려준다(저장하지 않는다).
+ */
+const createDownload = createServerFn({ method: "POST" })
+  .validator(z.object({ orderItemId: z.string(), assetId: z.string() }))
+  .handler(async ({ data }): Promise<DownloadResult> => {
+    const accessToken = readToken();
+    if (!accessToken) throw redirect({ to: "/login", search: { redirectTo: "/orders" } });
+    try {
+      const link = await apiFor({ accessToken }).myOrders.createDownload(data.orderItemId, {
+        assetId: data.assetId,
+      });
+      return { url: link.url, fileName: link.fileName, remaining: link.remaining, error: null };
+    } catch (error) {
+      return { url: null, error: downloadErrorMessage(error) };
+    }
+  });
+
 /**
  * 취소·반품 접수 — 수량을 실으면 그 수량만 접수된다(생략하면 남은 수량 전체).
  * 상한은 주문 상품의 `activeQuantity`이고 넘기면 서버가 400 `INVALID_QUANTITY`로 거절한다.
@@ -74,6 +118,8 @@ function claimErrorMessage(error: unknown): string {
       return "지금은 신청할 수 없는 상태입니다. 주문 상태를 확인해 주십시오.";
     case "PERIOD_EXPIRED":
       return "반품·교환 가능 기간이 지났습니다.";
+    case "WITHDRAWAL_RESTRICTED":
+      return WITHDRAWAL_RESTRICTED_CLAIM_MESSAGE;
     default:
       return error.message || "접수하지 못했습니다. 잠시 후 다시 시도해 주십시오.";
   }
@@ -184,15 +230,30 @@ function OrderDetail() {
                   <span className="text-muted text-xs">{item.optionName}</span>
                 ) : null}
                 <span className="text-muted text-xs">
-                  {orderItemStatusLabel(item.status)} · 수량 {item.quantity}개
+                  {orderItemStatusLabel(item.status, item.fulfillmentType)} · 수량 {item.quantity}개
                   {item.canceledQuantity > 0
                     ? ` · 취소·반품 ${item.canceledQuantity}개 · 남은 수량 ${item.activeQuantity}개`
                     : null}
                 </span>
+                {withdrawalRestrictedLabel(item) ? (
+                  <span className="text-muted text-xs">{withdrawalRestrictedLabel(item)}</span>
+                ) : null}
               </span>
               <span className="text-sm">{formatPrice(item.totalPrice)}</span>
             </div>
 
+            <FulfillmentInfo item={item} />
+            <FulfillmentCodes
+              item={item}
+              reveal={() => revealCode({ data: { orderItemId: item.orderItemId } })}
+            />
+            <FulfillmentDownloads
+              item={item}
+              download={(assetId) =>
+                createDownload({ data: { orderItemId: item.orderItemId, assetId } })
+              }
+            />
+
             {claimableTypes(item.status).length > 0 &&
             !item.claimStatus &&
             item.activeQuantity > 0 ? (
@@ -247,6 +308,37 @@ function OrderDetail() {
   );
 }
 
+/**
+ * 배송이 없는 상품의 받는 방법 — 방문 수령 장소와 셀러가 제공 처리하며 남긴 이용 안내(이슈 #48).
+ * 배송 상품이거나 보여 줄 것이 없으면 그리지 않는다. 배송 상품이 아니므로 배송 조회 링크가 없다.
+ */
+function FulfillmentInfo({ item }: { item: MyOrderItem }) {
+  const pickup = item.fulfillmentType === "PICKUP" ? item.pickupLocation : null;
+  const note = item.fulfillment?.status === "FULFILLED" ? item.fulfillment.note : null;
+  if (!pickup && !note) return null;
+  return (
+    <dl className="space-y-2 rounded-md bg-chip p-3 text-xs">
+      {pickup ? (
+        <div className="space-y-0.5">
+          <dt className="font-semibold">수령 장소</dt>
+          <dd>{pickup.name}</dd>
+          <dd className="text-muted">
+            ({pickup.zipCode}) {pickup.address1}
+            {pickup.address2 ? ` ${pickup.address2}` : ""}
+          </dd>
+          <dd className="text-muted">{pickup.phone}</dd>
+        </div>
+      ) : null}
+      {note ? (
+        <div className="space-y-0.5">
+          <dt className="font-semibold">이용 안내</dt>
+          <dd className="whitespace-pre-line">{note}</dd>
+        </div>
+      ) : null}
+    </dl>
+  );
+}
+
 /**
  * 취소·반품 접수 폼. 수량 기본값은 남은 수량 전체이고 입력값은 `activeQuantity`까지다.
  * 서버 렌더한 마크업에 값이 그대로 남아야 하므로 프리필은 `defaultValue`로 준다.

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

@@ -1,43 +1,33 @@
-import { createFileRoute, Link, useNavigate } from "@tanstack/react-router";
-import { createServerFn } from "@tanstack/react-start";
-import { z } from "zod";
+import { productSortSchema } from "@sayren/storefront-sdk";
+import { useSuspenseQuery } from "@tanstack/react-query";
+import { createFileRoute, Link } from "@tanstack/react-router";
+import { useQueryStates } from "nuqs";
 import { ProductCard } from "../components/product-card";
 import { useTrack } from "../lib/analytics";
-import { apiFor } from "../lib/api.server";
+import { categoriesQuery, productsQuery } from "../lib/catalog-queries";
 import { pageTitle } from "../lib/page-title";
-
-/** 목록·검색 조건 — URL에 둔다. 공유·뒤로가기가 그대로 동작한다 */
-const productsSearch = z.object({
-  keyword: z.string().optional().catch(undefined),
-  categoryId: z.string().optional().catch(undefined),
-  sort: z.enum(["recommend", "latest"]).optional().catch(undefined),
-  page: z.coerce.number().int().min(1).optional().catch(undefined),
-});
-type ProductsSearch = z.infer<typeof productsSearch>;
-
-const searchProducts = createServerFn({ method: "GET" })
-  .validator(productsSearch)
-  .handler(async ({ data }) => {
-    const api = apiFor();
-    const [categories, page] = await Promise.all([
-      api.catalog.listCategories(),
-      api.catalog.searchProducts({ ...data, page: data.page ?? 1, size: 24 }),
-    ]);
-    return { categories, page };
-  });
+import { parseProductsSearch, productsSearchParams, SORT_LABELS } from "../lib/products-search";
 
 export const Route = createFileRoute("/products/")({
-  validateSearch: productsSearch,
+  // 목록·검색 조건은 URL에 둔다 — 읽는 규칙은 nuqs 파서 하나다(`lib/products-search.ts`)
+  validateSearch: parseProductsSearch,
   loaderDeps: ({ search }) => search,
-  loader: ({ deps }) => searchProducts({ data: deps }),
+  // 서버 렌더에서 미리 받아 쿼리 캐시에 넣는다. 화면은 같은 쿼리를 캐시에서 읽는다
+  loader: ({ context, deps }) =>
+    Promise.all([
+      context.queryClient.ensureQueryData(categoriesQuery()),
+      context.queryClient.ensureQueryData(productsQuery(deps)),
+    ]),
   head: ({ matches }) => ({ meta: [{ title: pageTitle(matches, "전체 상품") }] }),
   component: Products,
 });
 
 function Products() {
-  const { categories, page } = Route.useLoaderData();
   const applied = Route.useSearch();
-  const navigate = useNavigate();
+  const { data: categories } = useSuspenseQuery(categoriesQuery());
+  const { data: page } = useSuspenseQuery(productsQuery(applied));
+  // 검색어·정렬을 바꾸면 URL만 고친다. 라우터가 바뀐 조건으로 loader를 다시 부른다
+  const [, setSearch] = useQueryStates(productsSearchParams, { history: "push" });
   useTrack(
     applied.keyword
       ? { name: "search", query: applied.keyword, resultCount: page.totalElements }
@@ -61,14 +51,12 @@ function Products() {
       {/* 하이드레이션 전에는 GET 폼으로 그대로 제출되고, 뒤에는 화면을 새로 그리지 않고 이동한다 */}
       <form
         action="/products"
-        className="flex gap-2"
+        className="flex flex-wrap gap-2"
         onSubmit={(event) => {
           event.preventDefault();
           const keyword = String(new FormData(event.currentTarget).get("keyword") ?? "").trim();
-          void navigate({
-            to: "/products",
-            search: { keyword: keyword || undefined, categoryId: applied.categoryId },
-          });
+          // 새 검색은 1페이지부터 — 카테고리·정렬은 그대로 둔다
+          void setSearch({ keyword: keyword || null, page: null });
         }}
       >
         <input
@@ -77,7 +65,7 @@ function Products() {
           aria-label="상품 검색"
           defaultValue={applied.keyword ?? ""}
           placeholder="상품 검색"
-          className="h-11 flex-1 rounded-md border border-line px-3"
+          className="h-11 min-w-0 flex-1 rounded-md border border-line px-3"
         />
         {applied.categoryId ? (
           <input type="hidden" name="categoryId" value={applied.categoryId} />
@@ -85,6 +73,22 @@ function Products() {
         <button type="submit" className="h-11 rounded-md bg-ink px-5 font-semibold text-white">
           검색
         </button>
+        <select
+          name="sort"
+          aria-label="정렬"
+          value={applied.sort ?? "recommend"}
+          onChange={(event) => {
+            const sort = productSortSchema.parse(event.target.value);
+            void setSearch({ sort, page: null });
+          }}
+          className="h-11 rounded-md border border-line px-3 text-sm"
+        >
+          {productSortSchema.options.map((sort) => (
+            <option key={sort} value={sort}>
+              {SORT_LABELS[sort]}
+            </option>
+          ))}
+        </select>
       </form>
 
       <div className="flex flex-wrap gap-2">
@@ -118,27 +122,21 @@ function Products() {
         </div>
       )}
 
-      <Pagination page={page.page} totalPages={page.totalPages} search={applied} />
+      <Pagination page={page.page} totalPages={page.totalPages} />
     </div>
   );
 }
 
-function Pagination({
-  page,
-  totalPages,
-  search,
-}: {
-  page: number;
-  totalPages: number;
-  search: ProductsSearch;
-}) {
+/** 페이지 이동은 링크다 — 자바스크립트 없이도 넘어가고, 다른 조건은 그대로 둔다 */
+function Pagination({ page, totalPages }: { page: number; totalPages: number }) {
   if (totalPages <= 1) return null;
+  const pageOf = (next: number) => (next > 1 ? next : undefined);
   return (
     <nav className="flex items-center justify-center gap-3 text-sm">
       {page > 1 ? (
         <Link
           to="/products"
-          search={{ ...search, page: page - 1 }}
+          search={(prev) => ({ ...prev, page: pageOf(page - 1) })}
           className="rounded-md border border-line px-3 py-1.5"
         >
           이전
@@ -150,7 +148,7 @@ function Pagination({
       {page < totalPages ? (
         <Link
           to="/products"
-          search={{ ...search, page: page + 1 }}
+          search={(prev) => ({ ...prev, page: pageOf(page + 1) })}
           className="rounded-md border border-line px-3 py-1.5"
         >
           다음