@sayren/mcp 0.6.0 → 0.8.0

package/template/src/lib/download.ts

@@ -0,0 +1,41 @@
+import { ApiError } from "@sayren/storefront-sdk";
+import { guestLookupLockedMessage } from "./guest-order";
+
+/**
+ * 파일 다운로드 상품의 파일 받기 (sayren 이슈 #48).
+ *
+ * 주문 상세에는 횟수·기한·파일 이름만 온다. 「다운로드」를 누르면 서버 함수가 `myOrders.createDownload`(회원)·
+ * `myOrders.createGuestDownload`(비회원)로 수명 300초의 서명 주소를 받아 브라우저가 바로 그 주소로 간다.
+ * 주소는 받을 때마다 횟수를 하나 쓰므로 저장하거나 공유하지 않는다.
+ */
+
+/** 서버 함수 결과 — ApiError는 서버 함수 경계를 넘지 못하므로 문구로 바꿔 돌려준다 */
+export type DownloadResult =
+  | { url: string; fileName: string; remaining: number; error: null }
+  | { url: null; error: string };
+
+/** 다운로드 실패 → 구매자에게 보일 문구 */
+export function downloadErrorMessage(error: unknown): string {
+  if (error instanceof ApiError) {
+    if (error.code === "DOWNLOAD_LIMIT_REACHED") return "다운로드 횟수를 모두 사용했습니다";
+    if (error.code === "DOWNLOAD_EXPIRED") return "다운로드 기간이 지났습니다";
+    if (error.status === 404) return "받을 파일이 없습니다. 주문 상태를 확인해 주십시오";
+    // 비회원 다운로드는 비회원 주문 조회와 같은 시도 한도를 쓴다
+    if (error.status === 429) return guestLookupLockedMessage(error.details?.retryAfterSeconds);
+  }
+  return "파일을 받지 못했습니다. 잠시 후 다시 시도해 주십시오";
+}
+
+/** 파일 크기 — 1024 단위, 소수 한 자리. 모르면 빈 문자열 */
+export function formatFileSize(bytes: number | null | undefined): string {
+  if (bytes === null || bytes === undefined || bytes < 0) return "";
+  if (bytes < 1024) return `${bytes}B`;
+  const units = ["KB", "MB", "GB"];
+  let size = bytes / 1024;
+  let unit = 0;
+  while (size >= 1024 && unit < units.length - 1) {
+    size /= 1024;
+    unit += 1;
+  }
+  return `${size.toFixed(1)}${units[unit]}`;
+}

package/template/src/lib/form-schemas.test.ts

@@ -0,0 +1,144 @@
+import { describe, expect, it } from "vitest";
+import {
+  checkoutFormSchema,
+  guestOrderLookupSchema,
+  signupFormSchema,
+  WITHDRAWAL_AGREEMENT_MESSAGE,
+} from "./form-schemas";
+
+const messageOf = (result: { success: boolean; error?: { issues: { message: string }[] } }) =>
+  result.error?.issues[0]?.message;
+
+describe("가입 폼", () => {
+  const valid = {
+    email: " buyer@example.com ",
+    password: "password-1",
+    name: "구매자",
+    phone: "",
+    agreements: { terms: true, privacy: true, marketing: false },
+  };
+
+  it("앞뒤 공백을 지우고 휴대폰은 비워 둘 수 있다", () => {
+    const parsed = signupFormSchema.parse(valid);
+    expect(parsed.email).toBe("buyer@example.com");
+    expect(parsed.phone).toBe("");
+  });
+
+  it("비밀번호 조합은 SDK 규칙으로 막는다", () => {
+    expect(messageOf(signupFormSchema.safeParse({ ...valid, password: "aaaaaaaaaa" }))).toBe(
+      "영문/숫자/특수문자 중 2종 이상을 조합해야 합니다",
+    );
+  });
+
+  it("필수 동의가 없으면 안내한다", () => {
+    const result = signupFormSchema.safeParse({
+      ...valid,
+      agreements: { terms: false, privacy: true, marketing: false },
+    });
+    expect(messageOf(result)).toBe("필수 약관에 동의해 주십시오");
+  });
+});
+
+describe("비회원 주문 조회 폼", () => {
+  it("연락처는 숫자만 남긴다", () => {
+    const parsed = guestOrderLookupSchema.parse({
+      orderId: " ord_1 ",
+      phone: "010-1234-5678",
+      orderPassword: "secret",
+    });
+    expect(parsed).toEqual({ orderId: "ord_1", phone: "01012345678", orderPassword: "secret" });
+  });
+
+  it("연락처 형식이 아니면 안내한다", () => {
+    const result = guestOrderLookupSchema.safeParse({
+      orderId: "ord_1",
+      phone: "1234",
+      orderPassword: "secret",
+    });
+    expect(messageOf(result)).toContain("연락처 형식");
+  });
+});
+
+describe("주문서 폼", () => {
+  const shipping = {
+    receiverName: "홍길동",
+    phone: "01012345678",
+    zipCode: "04524",
+    address1: "서울특별시 중구 세종대로 110",
+    address2: "",
+    deliveryMemo: "",
+    paymentOption: "tosspayments:TRANSFER",
+    cashReceiptOn: false,
+    cashReceiptType: "INCOME_DEDUCTION" as const,
+  };
+  const cashKeys = new Set(["tosspayments:TRANSFER"]);
+
+  it("회원은 비회원 주문 정보 없이 통과한다", () => {
+    const schema = checkoutFormSchema({ guest: false, cashReceiptOptionKeys: cashKeys });
+    expect(schema.safeParse(shipping).success).toBe(true);
+  });
+
+  it("배송이 필요 없는 주문은 배송지 없이 통과하고, 비회원이면 연락처만 받는다", () => {
+    const member = checkoutFormSchema({
+      guest: false,
+      cashReceiptOptionKeys: cashKeys,
+      shipping: false,
+    });
+    expect(
+      member.safeParse({
+        paymentOption: "tosspayments:CARD",
+        cashReceiptOn: false,
+        cashReceiptType: "INCOME_DEDUCTION",
+      }).success,
+    ).toBe(true);
+    const guest = checkoutFormSchema({
+      guest: true,
+      cashReceiptOptionKeys: cashKeys,
+      shipping: false,
+    });
+    const guestInput = {
+      paymentOption: "tosspayments:CARD",
+      cashReceiptOn: false,
+      cashReceiptType: "INCOME_DEDUCTION" as const,
+      guestName: "홍길동",
+      email: "guest@example.com",
+      orderPassword: "123456",
+    };
+    expect(guest.safeParse(guestInput).success).toBe(false);
+    expect(guest.safeParse({ ...guestInput, phone: "01012345678" }).success).toBe(true);
+  });
+
+  it("비회원은 주문 조회 비밀번호 6자 이상이 필요하다", () => {
+    const schema = checkoutFormSchema({ guest: true, cashReceiptOptionKeys: cashKeys });
+    const result = schema.safeParse({
+      ...shipping,
+      guestName: "홍길동",
+      email: "guest@example.com",
+      orderPassword: "12345",
+    });
+    expect(messageOf(result)).toBe("주문 조회 비밀번호는 6자 이상이어야 합니다");
+  });
+
+  it("청약철회 제한 상품이 있으면 동의를 요구하고, 없으면 묻지 않는다", () => {
+    const restricted = checkoutFormSchema({
+      guest: false,
+      cashReceiptOptionKeys: cashKeys,
+      withdrawal: true,
+    });
+    expect(messageOf(restricted.safeParse({ ...shipping, withdrawalAgreed: false }))).toBe(
+      WITHDRAWAL_AGREEMENT_MESSAGE,
+    );
+    expect(restricted.safeParse({ ...shipping }).success).toBe(false);
+    expect(restricted.safeParse({ ...shipping, withdrawalAgreed: true }).success).toBe(true);
+    const plain = checkoutFormSchema({ guest: false, cashReceiptOptionKeys: cashKeys });
+    expect(plain.safeParse({ ...shipping, withdrawalAgreed: false }).success).toBe(true);
+  });
+
+  it("현금영수증은 받을 수 있는 결제 옵션에서 신청했을 때만 번호를 검사한다", () => {
+    const schema = checkoutFormSchema({ guest: false, cashReceiptOptionKeys: cashKeys });
+    const on = { ...shipping, cashReceiptOn: true, cashReceiptNumber: "12" };
+    expect(schema.safeParse(on).success).toBe(false);
+    expect(schema.safeParse({ ...on, paymentOption: "tosspayments:CARD" }).success).toBe(true);
+    expect(schema.safeParse({ ...on, cashReceiptNumber: "01012345678" }).success).toBe(true);
+  });
+});

package/template/src/lib/form-schemas.ts

@@ -0,0 +1,131 @@
+import {
+  cashReceiptRequestSchema,
+  cashReceiptTypeSchema,
+  guestInfoSchema,
+  shippingAddressInputSchema,
+  signupRequestSchema,
+} from "@sayren/storefront-sdk";
+import { z } from "zod";
+
+/**
+ * 폼 스키마 — react-hook-form의 `zodResolver`에 넣는다.
+ *
+ * 입력 규칙(비밀번호 조합·휴대폰·우편번호·현금영수증 번호)은 SDK 스키마가 원천이다. 여기서는 화면 입력 모양
+ * (빈 칸은 `""`, 동의는 체크박스)에 맞추고 안내 문구를 붙이기만 한다. 서버 함수는 보내기 전에 SDK 스키마로
+ * 다시 확인하고 서버도 같은 규칙으로 거절하므로, 이 검사는 입력하는 동안의 안내다.
+ */
+
+/** SDK 규칙을 그대로 쓰되 안내 문구만 바꾼다(SDK 스키마 일부는 문구가 없다) */
+const matches = (schema: z.ZodType, message: string) =>
+  z.string().refine((value) => schema.safeParse(value).success, message);
+
+// ── 회원가입 ─────────────────────────────────────────────────────────────
+
+const signupPhone = signupRequestSchema.shape.phone.unwrap();
+
+export const signupFormSchema = z.object({
+  email: z.string().trim().pipe(z.email("이메일 형식을 확인해 주십시오")),
+  password: signupRequestSchema.shape.password,
+  name: z.string().trim().min(1, "이름을 입력해 주십시오").max(50, "이름은 50자까지입니다"),
+  /** 선택 입력 — 비우면 보내지 않는다 */
+  phone: z
+    .string()
+    .trim()
+    .refine(
+      (value) => value === "" || signupPhone.safeParse(value).success,
+      "휴대폰 번호 형식을 확인해 주십시오 (예: 01012345678)",
+    ),
+  // 체크박스는 체크 전 false다 — 입력은 boolean으로 받고 필수 동의만 true를 요구한다
+  agreements: z.object({
+    terms: z.boolean().refine((agreed) => agreed, "필수 약관에 동의해 주십시오"),
+    privacy: z.boolean().refine((agreed) => agreed, "필수 약관에 동의해 주십시오"),
+    marketing: z.boolean(),
+  }),
+});
+
+export type SignupFormInput = z.input<typeof signupFormSchema>;
+export type SignupForm = z.output<typeof signupFormSchema>;
+
+// ── 비회원 주문 조회 ──────────────────────────────────────────────────────
+
+export const guestOrderLookupSchema = z.object({
+  orderId: z.string().trim().min(1, "주문번호를 입력해 주십시오"),
+  // 하이픈·공백을 넣어도 숫자만 읽는다
+  phone: z
+    .string()
+    .transform((value) => value.replace(/[^0-9]/g, ""))
+    .pipe(matches(guestInfoSchema.shape.phone, "연락처 형식을 확인해 주십시오 (예: 01012345678)")),
+  orderPassword: z.string().min(1, "주문 조회 비밀번호를 입력해 주십시오"),
+});
+
+export type GuestOrderLookupInput = z.input<typeof guestOrderLookupSchema>;
+export type GuestOrderLookup = z.output<typeof guestOrderLookupSchema>;
+
+// ── 주문서 ───────────────────────────────────────────────────────────────
+
+/** 청약철회 제한 동의 누락 — 폼 검사와 서버 400 `WITHDRAWAL_AGREEMENT_REQUIRED`가 같은 문구를 쓴다 */
+export const WITHDRAWAL_AGREEMENT_MESSAGE = "청약철회 제한 안내에 동의해 주십시오";
+
+/**
+ * 주문서 폼. 비회원 주문 정보는 비회원일 때만 받고, 현금영수증은 계좌이체·가상계좌 옵션을 골랐고 신청을 켰을 때만
+ * 검사한다(`cashReceiptOptionKeys`는 그런 결제 옵션의 키).
+ *
+ * 배송지는 주문서의 `requiresShipping`이 true일 때만 받는다(`shipping`, 생략하면 true). 배송이 필요 없는 주문(이용권·방문
+ * 수령 등)은 배송지 칸이 없고, 연락처는 비회원 주문자 연락처로만 받는다.
+ *
+ * 청약철회 제한 동의는 주문서의 `withdrawal.required`가 true일 때만 요구한다(`withdrawal`, 생략하면 false). 결제 시작이
+ * `withdrawalAgreement: true`로 보낸다.
+ */
+export function checkoutFormSchema(options: {
+  guest: boolean;
+  cashReceiptOptionKeys: ReadonlySet<string>;
+  shipping?: boolean;
+  withdrawal?: boolean;
+}) {
+  const shipping = shippingAddressInputSchema.shape;
+  const address = options.shipping ?? true;
+  const optional = z.string().optional();
+  return z
+    .object({
+      receiverName: address ? z.string().trim().pipe(shipping.receiverName) : optional,
+      phone:
+        address || options.guest ? z.string().trim().pipe(shipping.phone) : z.string().optional(),
+      zipCode: address ? z.string().trim().pipe(shipping.zipCode) : optional,
+      address1: address ? z.string().trim().pipe(shipping.address1) : optional,
+      address2: address ? z.string().trim() : optional,
+      deliveryMemo: address ? z.string().trim().max(100, "배송 메모는 100자까지입니다") : optional,
+      guestName: options.guest
+        ? z.string().trim().min(1, "주문자명을 입력해 주십시오")
+        : z.string().optional(),
+      email: options.guest
+        ? z.string().trim().pipe(z.email("이메일 형식을 확인해 주십시오"))
+        : z.string().optional(),
+      orderPassword: options.guest ? guestInfoSchema.shape.orderPassword : z.string().optional(),
+      paymentOption: z.string().min(1, "결제수단을 골라 주십시오."),
+      cashReceiptOn: z.boolean(),
+      cashReceiptType: cashReceiptTypeSchema,
+      cashReceiptNumber: z.string().optional(),
+      // 체크박스는 체크 전 false다 — 제한 상품이 있는 주문만 true를 요구한다
+      withdrawalAgreed: options.withdrawal
+        ? z.boolean().refine((agreed) => agreed, WITHDRAWAL_AGREEMENT_MESSAGE)
+        : z.boolean().optional(),
+    })
+    .superRefine((value, ctx) => {
+      if (!value.cashReceiptOn || !options.cashReceiptOptionKeys.has(value.paymentOption)) return;
+      const parsed = cashReceiptRequestSchema.safeParse({
+        type: value.cashReceiptType,
+        identityNumber: value.cashReceiptNumber ?? "",
+      });
+      if (!parsed.success) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["cashReceiptNumber"],
+          message: parsed.error.issues[0]?.message ?? "현금영수증 번호를 확인해 주십시오.",
+        });
+      }
+    });
+}
+
+export type CheckoutFormSchema = ReturnType<typeof checkoutFormSchema>;
+export type CheckoutFormInput = z.input<CheckoutFormSchema>;
+export type CheckoutForm = z.output<CheckoutFormSchema>;

package/template/src/lib/guest-order.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from "vitest";
+import { guestLookupLockedMessage } from "./guest-order";
+
+describe("guestLookupLockedMessage", () => {
+  it("남은 시간을 분 단위로 올려 알린다", () => {
+    expect(guestLookupLockedMessage(1800)).toBe(
+      "조회 시도가 너무 많습니다. 30분 뒤에 다시 시도해 주십시오",
+    );
+    expect(guestLookupLockedMessage(61)).toContain("2분 뒤");
+  });
+
+  it("남은 시간을 모르면 잠시 후로 안내한다", () => {
+    expect(guestLookupLockedMessage(undefined)).toBe(
+      "조회 시도가 너무 많습니다. 잠시 후 다시 시도해 주십시오",
+    );
+    expect(guestLookupLockedMessage("30")).toContain("잠시 후");
+  });
+});

package/template/src/lib/guest-order.ts

@@ -0,0 +1,13 @@
+/**
+ * 비회원 주문 조회 잠금 안내 — API는 주문번호마다 시도 한도를 두고, 넘으면 429 `TOO_MANY_REQUESTS`와
+ * 남은 시간(`details.retryAfterSeconds`)을 준다. 남은 시간은 분 단위로 올려 알린다.
+ */
+export function guestLookupLockedMessage(retryAfterSeconds: unknown): string {
+  const minutes =
+    typeof retryAfterSeconds === "number" && retryAfterSeconds > 0
+      ? Math.ceil(retryAfterSeconds / 60)
+      : null;
+  return minutes
+    ? `조회 시도가 너무 많습니다. ${minutes}분 뒤에 다시 시도해 주십시오`
+    : "조회 시도가 너무 많습니다. 잠시 후 다시 시도해 주십시오";
+}

package/template/src/lib/order-status.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { orderItemStatusLabel, withdrawalRestrictedLabel } from "./order-status";
+
+describe("주문 상품 상태 라벨", () => {
+  it("배송 상품은 배송 단계로 보인다", () => {
+    expect(orderItemStatusLabel("DELIVERED")).toBe("배송 완료");
+    expect(orderItemStatusLabel("DELIVERED", "SHIPPING")).toBe("배송 완료");
+    expect(orderItemStatusLabel("CONFIRMED", "SHIPPING")).toBe("발송 준비");
+  });
+
+  it("배송이 없는 상품의 DELIVERED는 제공 완료, 방문 수령은 수령 완료다", () => {
+    expect(orderItemStatusLabel("DELIVERED", "SERVICE")).toBe("제공 완료");
+    expect(orderItemStatusLabel("DELIVERED", "PICKUP")).toBe("수령 완료");
+    expect(orderItemStatusLabel("CONFIRMED", "SERVICE")).toBe("준비 중");
+    expect(orderItemStatusLabel("PAID", "PICKUP")).toBe("결제 완료");
+  });
+
+  it("모르는 상태는 코드 그대로다", () => {
+    expect(orderItemStatusLabel("ON_HOLD", "SERVICE")).toBe("ON_HOLD");
+  });
+});
+
+describe("청약철회 제한 표시", () => {
+  it("제한 주문상품에만 라벨을 붙인다", () => {
+    expect(withdrawalRestrictedLabel({ withdrawalRestricted: true })).toBe("청약철회 제한 상품");
+    expect(withdrawalRestrictedLabel({ withdrawalRestricted: false })).toBeNull();
+    expect(withdrawalRestrictedLabel({})).toBeNull();
+  });
+});

package/template/src/lib/order-status.ts

@@ -1,4 +1,4 @@
-import type { OrderItemStatus } from "@sayren/storefront-sdk";
+import { isShippingFulfillment, type OrderItemStatus } from "@sayren/storefront-sdk";
 
 /** 주문 상품 상태 라벨 — 화면에 코드 대신 보인다. 서버가 상태를 더하면 코드 그대로 보인다 */
 const ORDER_ITEM_STATUS_LABELS: Record<OrderItemStatus, string> = {
@@ -12,6 +12,32 @@ const ORDER_ITEM_STATUS_LABELS: Record<OrderItemStatus, string> = {
   CANCELED: "취소",
 };
 
-export function orderItemStatusLabel(status: string): string {
+/**
+ * 배송이 없는 상품(이용권·방문 수령 등)의 상태 라벨. 제공 완료는 `DELIVERED`를 그대로 쓰므로 표시만 바꾼다 —
+ * 방문 수령은 「수령 완료」, 그 밖의 유형은 「제공 완료」다.
+ */
+function nonShippingLabel(status: string, fulfillmentType: string): string | null {
+  if (status === "CONFIRMED") return "준비 중";
+  if (status === "DELIVERED") return fulfillmentType === "PICKUP" ? "수령 완료" : "제공 완료";
+  return null;
+}
+
+export function orderItemStatusLabel(status: string, fulfillmentType?: string | null): string {
+  if (fulfillmentType && !isShippingFulfillment(fulfillmentType)) {
+    const label = nonShippingLabel(status, fulfillmentType);
+    if (label) return label;
+  }
   return ORDER_ITEM_STATUS_LABELS[status as OrderItemStatus] ?? status;
 }
+
+/**
+ * 청약철회 제한 주문상품(이슈 #48) — 구매자가 결제 전에 동의했고, 제공이 시작되면(첫 다운로드·열람) 단순 변심 취소·반품을
+ * 받지 않는다. 주문 상세·비회원 주문 조회가 상품 옆에 붙인다.
+ */
+export function withdrawalRestrictedLabel(item: { withdrawalRestricted?: boolean }): string | null {
+  return item.withdrawalRestricted ? "청약철회 제한 상품" : null;
+}
+
+/** 제공이 시작된 청약철회 제한 상품의 취소·반품 접수 거절(409 `WITHDRAWAL_RESTRICTED`) 안내 */
+export const WITHDRAWAL_RESTRICTED_CLAIM_MESSAGE =
+  "제공이 시작된 상품이라 취소·반품을 접수할 수 없습니다.";

package/template/src/lib/page-title.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from "vitest";
+import { pageTitle } from "./page-title";
+
+const root = { loaderData: { store: { name: "나의첫번째몰", logoUrl: null } } };
+
+describe("pageTitle", () => {
+  it("화면 이름 뒤에 스토어 이름을 붙인다", () => {
+    expect(pageTitle([root, { loaderData: {} }], "회원가입")).toBe("회원가입 | 나의첫번째몰");
+  });
+
+  it("화면 이름이 없으면 스토어 이름만 쓴다", () => {
+    expect(pageTitle([root])).toBe("나의첫번째몰");
+  });
+
+  it("스토어 이름을 읽지 못하면 기본 이름을 쓴다", () => {
+    expect(pageTitle([{ loaderData: { store: null } }], "장바구니")).toBe("장바구니 | 스토어");
+    expect(pageTitle([], "장바구니")).toBe("장바구니 | 스토어");
+  });
+});

package/template/src/lib/page-title.ts

@@ -0,0 +1,23 @@
+/** 스토어 이름을 읽지 못했을 때 탭 제목 */
+export const FALLBACK_STORE_NAME = "스토어";
+
+/** 루트 라우트 loader가 내려 주는 스토어 이름 — `__root.tsx`의 `RootData.store` */
+function storeNameOf(matches: ReadonlyArray<{ loaderData?: unknown }>): string | null {
+  const root = matches[0]?.loaderData as { store?: { name?: unknown } | null } | undefined;
+  const name = root?.store?.name;
+  return typeof name === "string" && name.trim() ? name : null;
+}
+
+/**
+ * 탭 제목 — `{화면} | {스토어 이름}`. 홈처럼 화면 이름이 없으면 스토어 이름만 쓴다.
+ * 라우트 `head`의 `matches`를 그대로 넘긴다(루트 loader가 스토어 이름을 싣는다).
+ *
+ * 확장 지점 — 구분자나 순서를 바꾸려면 여기만 고친다.
+ */
+export function pageTitle(
+  matches: ReadonlyArray<{ loaderData?: unknown }>,
+  screen?: string | null,
+): string {
+  const store = storeNameOf(matches) ?? FALLBACK_STORE_NAME;
+  return screen ? `${screen} | ${store}` : store;
+}

package/template/src/lib/products-search.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, it } from "vitest";
+import { parseProductsSearch } from "./products-search";
+
+describe("상품 목록 URL 상태", () => {
+  it("기본값(1페이지·추천순)과 빈 값은 비운다", () => {
+    expect(parseProductsSearch({ page: 1, sort: "recommend", keyword: " " })).toEqual({
+      keyword: undefined,
+      categoryId: undefined,
+      sort: undefined,
+      page: undefined,
+    });
+  });
+
+  it("라우터가 숫자로 푼 값도 문자열로 다시 읽는다", () => {
+    expect(
+      parseProductsSearch({ keyword: 123, page: 2, sort: "latest", categoryId: "cat_1" }),
+    ).toEqual({ keyword: "123", categoryId: "cat_1", sort: "latest", page: 2 });
+  });
+
+  it("잘못된 정렬·페이지는 오류 대신 기본값으로 읽는다", () => {
+    const search = parseProductsSearch({ sort: "cheapest", page: "abc" });
+    expect(search.sort).toBeUndefined();
+    expect(search.page).toBeUndefined();
+  });
+});

package/template/src/lib/products-search.ts

@@ -0,0 +1,49 @@
+import { type ProductSort, productSortSchema } from "@sayren/storefront-sdk";
+import { createLoader, parseAsInteger, parseAsString, parseAsStringLiteral } from "nuqs";
+
+/**
+ * 상품 목록의 URL 상태(검색어·카테고리·정렬·페이지) — nuqs 파서가 원천이다.
+ *
+ * 라우트의 `validateSearch`(서버·브라우저 공통, loader 입력)와 화면의 `useQueryStates`(검색·정렬 변경)가 같은
+ * 파서를 쓴다. 조건이 URL에 있으니 공유·새로고침·뒤로가기가 그대로 동작한다. 기본값(1페이지·추천순)은 주소에서 뺀다.
+ */
+export const productsSearchParams = {
+  keyword: parseAsString,
+  categoryId: parseAsString,
+  // 정렬 값은 SDK 스키마가 원천이다. 기본값은 서버 기본값과 같은 추천순이다
+  sort: parseAsStringLiteral(productSortSchema.options).withDefault("recommend"),
+  page: parseAsInteger.withDefault(1),
+};
+
+const loadProductsSearch = createLoader(productsSearchParams);
+
+/** 라우트가 쓰는 검색 조건. 기본값인 항목은 비워 두어 링크가 주소에 싣지 않는다 */
+export interface ProductsSearch {
+  keyword?: string;
+  categoryId?: string;
+  sort?: ProductSort;
+  page?: number;
+}
+
+/**
+ * 주소의 검색 파라미터를 읽는다. 잘못된 값(없는 정렬, 숫자가 아닌 페이지)은 오류 화면 대신 기본값으로 읽는다.
+ * 라우터는 `?page=2`를 숫자로, `?keyword=%22a%22`를 문자열로 먼저 풀어 두므로 nuqs 로더가 다시 문자열로 읽는다.
+ */
+export function parseProductsSearch(raw: Record<string, unknown>): ProductsSearch {
+  const { keyword, categoryId, sort, page } = loadProductsSearch(raw as Record<string, string>);
+  return {
+    keyword: keyword?.trim() || undefined,
+    categoryId: categoryId || undefined,
+    sort: sort === "recommend" ? undefined : sort,
+    page: page > 1 ? page : undefined,
+  };
+}
+
+export const SORT_LABELS: Record<ProductSort, string> = {
+  recommend: "추천순",
+  latest: "최신순",
+  priceAsc: "낮은 가격순",
+  priceDesc: "높은 가격순",
+  reviewCount: "리뷰 많은순",
+  ratingDesc: "평점 높은순",
+};

package/template/src/router.tsx

@@ -1,13 +1,38 @@
+import { QueryClient } from "@tanstack/react-query";
 import { createRouter } from "@tanstack/react-router";
+import { setupRouterSsrQueryIntegration } from "@tanstack/react-router-ssr-query";
 import { routeTree } from "./routeTree.gen";
 
+/** 라우트 loader가 받는 문맥 — loader가 `queryClient.ensureQueryData`로 미리 받아 둔다 */
+export interface RouterContext {
+  queryClient: QueryClient;
+}
+
 export function getRouter() {
-  return createRouter({
+  // 요청마다 새로 만든다 — 서버 렌더에서 다른 구매자의 캐시가 섞이지 않는다
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: {
+        // 서버가 받아 둔 데이터를 하이드레이션 직후 다시 부르지 않는다
+        staleTime: 30_000,
+        refetchOnWindowFocus: false,
+        retry: 1,
+      },
+    },
+  });
+
+  const router = createRouter({
     routeTree,
+    context: { queryClient } satisfies RouterContext,
     scrollRestoration: true,
     // 주문서는 들어올 때마다 세션을 만든다. 마우스를 올린 것만으로 만들지 않도록 미리 불러오기를 끈다
     defaultPreload: false,
   });
+
+  // 서버에서 채운 쿼리 캐시를 HTML에 실어 보내고 브라우저에서 되살린다(QueryClientProvider도 여기서 감싼다)
+  setupRouterSsrQueryIntegration({ router, queryClient });
+
+  return router;
 }
 
 declare module "@tanstack/react-router" {

package/template/src/routes/__root.tsx

@@ -1,5 +1,5 @@
 import {
-  createRootRoute,
+  createRootRouteWithContext,
   type ErrorComponentProps,
   HeadContent,
   Link,
@@ -8,11 +8,14 @@ import {
   useRouterState,
 } from "@tanstack/react-router";
 import { createServerFn } from "@tanstack/react-start";
+import { NuqsAdapter } from "nuqs/adapters/tanstack-router";
 import { useEffect } from "react";
 import { SiteHeader, type StoreBrand } from "../components/site-header";
 import { type AnalyticsConfig, startAnalytics } from "../lib/analytics";
 import { apiFor } from "../lib/api.server";
 import { ANALYTICS_DEBUG, API_BASE_URL, resolveStoreCode } from "../lib/config.server";
+import { FALLBACK_STORE_NAME } from "../lib/page-title";
+import type { RouterContext } from "../router";
 import appCss from "../styles.css?url";
 
 /** 방문 분석 설정 — 서버 값(`process.env`)이라 서버 함수로 내려준다 */
@@ -42,13 +45,14 @@ interface RootData {
   store: StoreBrand | null;
 }
 
-export const Route = createRootRoute({
+export const Route = createRootRouteWithContext<RouterContext>()({
   head: ({ loaderData }) => ({
     meta: [
       { charSet: "utf-8" },
       { name: "viewport", content: "width=device-width, initial-scale=1" },
-      // 화면마다 제목을 덮어쓴다. 여기 값은 제목을 정하지 않은 화면의 기본값이다
-      { title: loaderData?.store?.name ?? "스토어" },
+      // 화면마다 `{화면} | {스토어 이름}`으로 덮어쓴다(`lib/page-title.ts`). 여기 값은 홈처럼
+      // 화면 이름이 없는 곳의 제목이다
+      { title: loaderData?.store?.name ?? FALLBACK_STORE_NAME },
     ],
     links: [
       { rel: "stylesheet", href: appCss },
@@ -79,8 +83,11 @@ function RootDocument({ children }: { children: React.ReactNode }) {
         <HeadContent />
       </head>
       <body className="min-h-screen bg-white text-ink">
-        <SiteHeader store={store} />
-        <main className="mx-auto w-full max-w-5xl px-4 py-8">{children}</main>
+        {/* URL 검색 파라미터(목록 검색어·카테고리·정렬·페이지)는 nuqs로 읽고 바꾼다 */}
+        <NuqsAdapter>
+          <SiteHeader store={store} />
+          <main className="mx-auto w-full max-w-5xl px-4 py-8">{children}</main>
+        </NuqsAdapter>
         <Scripts />
       </body>
     </html>

package/template/src/routes/account.tsx

@@ -11,6 +11,7 @@ import { z } from "zod";
 import { SubmitButton } from "../components/submit-button";
 import { apiFor, authFor } from "../lib/api.server";
 import { formatDateTime } from "../lib/format";
+import { pageTitle } from "../lib/page-title";
 import { readToken, signOut } from "../lib/session.server";
 import { SOCIAL_BUTTONS } from "../lib/social-buttons";
 import { writeSocialLogin } from "../lib/social-login.server";
@@ -181,7 +182,7 @@ function accountErrorMessage(error: unknown): string {
 export const Route = createFileRoute("/account")({
   validateSearch: accountSearch,
   loader: () => getAccount(),
-  head: () => ({ meta: [{ title: "내 정보" }] }),
+  head: ({ matches }) => ({ meta: [{ title: pageTitle(matches, "내 정보") }] }),
   component: Account,
 });