@sayren/mcp 0.2.1 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/mcp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "type": "module",
   "bin": {
     "sayren-mcp": "./dist/index.mjs"
@@ -12,8 +12,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.22.0",
     "zod": "^4.6.5",
-    "@sayren/store-sdk": "^0.9.0",
-    "@sayren/storefront-sdk": "^0.9.0"
+    "@sayren/storefront-sdk": "^0.11.0",
+    "@sayren/store-sdk": "^0.11.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.5.14",

package/template/.template-meta.json

@@ -7,8 +7,8 @@
     "zod": "^4.6.5"
   },
   "versions": {
-    "@sayren/store-sdk": "0.9.0",
-    "@sayren/storefront-sdk": "0.9.0",
+    "@sayren/store-sdk": "0.11.0",
+    "@sayren/storefront-sdk": "0.11.0",
     "@sayren/ui": "0.1.0"
   }
 }

package/template/README.md

@@ -1,7 +1,8 @@
 # 스토어프론트 템플릿 (TanStack Router · TanStack Start SSR)
 
 sayren MCP가 내려주는 스토어프론트 시작점이다. 구매 흐름 전체가 이미 붙어 있다.
-홈, 목록·검색, 상세, 장바구니, 주문서·결제(결제수단 선택 → 결제창 → 결제 복귀), 완료, 로그인, 주문 내역이다.
+홈, 목록·검색, 상세, 장바구니, 주문서·결제(결제수단 선택 → 결제창 → 결제 복귀), 완료, 로그인,
+주문 내역·주문 상세(취소·반품 신청)다.
 
 ## 시작하기
 
@@ -51,6 +52,14 @@ EU 등 분석 쿠키에 사전 동의가 필요한 지역의 구매자를 받는
 | 헤더·전역 내비 | `src/components/site-header.tsx` |
 | 상품 카드 | `src/components/product-card.tsx` |
 | 화면 추가 | `src/routes/`에 파일 추가 |
+| 약관 동의 | `src/routes/account.tsx`(동의 상태·재동의)·`src/routes/login.tsx`(소셜 가입 동의) |
+
+소셜 로그인은 공급자 화면을 거치므로 구매자가 무엇에 동의했는지는 이 앱만 안다. 이 템플릿은 로그인 화면에서 동의를
+받지 않고(기존 회원의 로그인까지 막히지 않게) **가입된 뒤 계정 화면에서 받는다** — 필수 동의 이력이 없는 구매자는
+`GET /me`의 `reconsentRequired`가 `true`이고, 계정 화면의 약관 항목에서 동의하면 이력에 남는다.
+가입 화면을 따로 두고 미리 받는 흐름을 쓰려면 `login.tsx`의 `auth.idp(provider, { redirectUri, agreements })`에
+그 값을 넘긴다(필수 동의는 `terms`·`privacy`를 함께 보낸다). 서버가 로그인 흐름에 보관해 두고 계정을 만드는 것과
+같은 트랜잭션에서 이력을 남긴다. 어느 쪽이든 동의하지 않은 구매자가 동의한 것으로 남지는 않는다.
 
 ## 건드리지 않는 편이 좋은 것
 
@@ -73,3 +82,13 @@ EU 등 분석 쿠키에 사전 동의가 필요한 지역의 구매자를 받는
 - 주문서(`/checkout`)는 들어올 때마다 주문서 세션을 새로 만든다. 조회 API가 없고, 가격과 재고를
   매번 다시 계산해야 하기 때문이다.
 - 비회원 장바구니는 서버가 발급한 토큰으로만 찾는다. 쿠키를 지우면 담은 상품이 사라진다.
+- 배송비는 배송 묶음마다 한 번 붙는다. 같은 출고지 + 같은 배송 정책인 상품이 한 묶음이고, 제주·도서산간 추가
+  배송비는 묶음마다 더하며 무료배송이어도 부과한다. 주문서를 만들 때는 배송지를 몰라 주문서의 `delivery.zipCode`가
+  null이고 추가 배송비가 0이다 — 주문서(`/checkout`)는 우편번호 입력을 마칠 때(blur) `quoteDelivery` 서버 함수로
+  `checkout.quoteDelivery(checkoutId, { zipCode })`를 불러 금액 요약을 갱신한다(주문서를 바꾸지 않는 읽기 계산이다).
+  **최종 금액은 결제 시작 응답의 `amounts`·`delivery`다** — 서버가 결제 시작이 보낸 배송지로 배송비를 다시 계산하므로
+  미리보기와 다를 수 있고, 화면은 그 값으로 덮어쓴다.
+- 취소·반품은 수량 단위다. 주문 상세(`/orders/$orderId`)의 신청 수량 상한은 주문 상품의 `activeQuantity`
+  (남은 수량)이고, 접수 결과의 `expectedRefundAmount`는 수량 비율 상품 금액에서 반품 배송비를 뺀 값이다.
+  배송비 환불은 `deliveryFeeRefundAmount`로 따로 온다. 교환은 희망 옵션(`exchangeOptionId`)이 필요해 이 화면에
+  넣지 않았다.

package/template/src/routes/account.tsx

@@ -26,20 +26,45 @@ const accountSearch = z.object({
 const getAccount = createServerFn({ method: "GET" }).handler(async () => {
   const accessToken = readToken();
   if (!accessToken) throw redirect({ to: "/login", search: { redirectTo: "/account" } });
-  const [me, identities, store] = await Promise.all([
+  const [me, identities, store, consents] = await Promise.all([
     apiFor({ accessToken }).member.me(),
     authFor().identities(accessToken),
     apiFor().store.get(),
+    apiFor({ accessToken }).member.consents(),
   ]);
   // 셀러가 켠 소셜 로그인만 연결할 수 있다
   const providers = store.loginMethods.filter(
     (method): method is SocialProvider => method !== "password",
   );
-  return { me, identities, providers };
+  return { me, identities, providers, consents };
 });
 
 const providerInput = z.object({ provider: z.enum(["kakao", "naver", "google"]) });
 
+const consentInput = z.object({
+  /** 개정된 필수 약관 재동의 */
+  reconsent: z.boolean().optional(),
+  /** 마케팅 수신 동의·철회 */
+  marketing: z.boolean().optional(),
+});
+
+/** 재동의·마케팅 동의 변경 — 구매자 토큰은 서버에만 두므로 서버 함수에서 부른다 */
+const changeConsents = createServerFn({ method: "POST" })
+  .validator(consentInput)
+  .handler(async ({ data }) => {
+    const accessToken = readToken();
+    if (!accessToken) return { error: "다시 로그인해 주세요" };
+    try {
+      await apiFor({ accessToken }).member.updateConsents({
+        ...(data.reconsent ? { terms: true as const, privacy: true as const } : {}),
+        ...(data.marketing === undefined ? {} : { marketing: data.marketing }),
+      });
+      return { error: null };
+    } catch (error) {
+      return { error: accountErrorMessage(error) };
+    }
+  });
+
 /**
  * 소셜 계정 연결 시작 — 로그인과 같은 콜백(`/auth/callback`)으로 돌아오고, 쿠키의 `linkProvider`로 연결임을 안다.
  * 연결은 흐름을 시작한 이 구매자에게만 된다(서버가 확인한다).
@@ -102,7 +127,7 @@ export const Route = createFileRoute("/account")({
 });
 
 function Account() {
-  const { me, identities, providers } = Route.useLoaderData();
+  const { me, identities, providers, consents } = Route.useLoaderData();
   const { linked, error: callbackError } = Route.useSearch();
   const router = useRouter();
   const [pending, setPending] = useState(false);
@@ -113,6 +138,16 @@ function Account() {
       ? (ERROR_MESSAGE[callbackError] ?? "연결하지 못했어요. 다시 시도해 주세요")
       : null);
 
+  const changeConsent = (data: { reconsent?: boolean; marketing?: boolean }) => {
+    setPending(true);
+    setActionError(null);
+    void changeConsents({ data }).then(async (result) => {
+      if (result.error) setActionError(result.error);
+      await router.invalidate();
+      setPending(false);
+    });
+  };
+
   const submit = (event: React.FormEvent<HTMLFormElement>) => {
     event.preventDefault();
     const submitter = (event.nativeEvent as SubmitEvent).submitter as HTMLButtonElement | null;
@@ -208,6 +243,71 @@ function Account() {
           연결한 계정으로도 같은 회원으로 로그인해요. 마지막 로그인 수단은 해제할 수 없어요.
         </p>
       </section>
+
+      <section className="space-y-3">
+        <h2 className="font-bold text-lg">약관 동의</h2>
+        <ul className="divide-y divide-line rounded-lg border border-line">
+          <li className="flex items-center justify-between gap-3 px-4 py-3">
+            <span className="flex flex-col gap-0.5">
+              <span className="font-medium">이용약관 · 개인정보 수집이용</span>
+              <span className="text-muted text-xs">
+                {consents.reconsentRequired
+                  ? "약관이 개정됐어요. 다시 동의해 주세요"
+                  : `동의 완료 · v${consents.terms.agreedVersion ?? "-"}`}
+              </span>
+              {/* 스토어가 약관 주소를 정했으면 열어 볼 수 있게 한다 */}
+              <span className="flex gap-2 text-xs">
+                {consents.terms.currentDocumentUrl ? (
+                  <a
+                    href={consents.terms.currentDocumentUrl}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="text-muted underline"
+                  >
+                    이용약관
+                  </a>
+                ) : null}
+                {consents.privacy.currentDocumentUrl ? (
+                  <a
+                    href={consents.privacy.currentDocumentUrl}
+                    target="_blank"
+                    rel="noreferrer"
+                    className="text-muted underline"
+                  >
+                    개인정보 수집이용
+                  </a>
+                ) : null}
+              </span>
+            </span>
+            {consents.reconsentRequired ? (
+              <button
+                type="button"
+                disabled={pending}
+                onClick={() => changeConsent({ reconsent: true })}
+                className="h-9 rounded-md bg-ink px-3 font-semibold text-sm text-white disabled:opacity-50"
+              >
+                재동의
+              </button>
+            ) : null}
+          </li>
+          <li className="flex items-center justify-between gap-3 px-4 py-3">
+            <span className="flex flex-col gap-0.5">
+              <span className="font-medium">마케팅 수신</span>
+              <span className="text-muted text-xs">
+                {consents.marketing.agreed ? "동의 중" : "받지 않음"}
+              </span>
+            </span>
+            <button
+              type="button"
+              disabled={pending}
+              onClick={() => changeConsent({ marketing: !consents.marketing.agreed })}
+              className="h-9 rounded-md border border-line px-3 text-sm disabled:opacity-50"
+            >
+              {consents.marketing.agreed ? "수신 해제" : "수신 동의"}
+            </button>
+          </li>
+        </ul>
+      </section>
     </div>
   );
 }

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

@@ -1,5 +1,9 @@
 import {
   ApiError,
+  type CheckoutDelivery,
+  cashReceiptAvailable,
+  cashReceiptRequestSchema,
+  type DeliveryQuoteResult,
   paymentOptionKey,
   paymentOptionSchema,
   paymentStartSchema,
@@ -47,6 +51,23 @@ const createCheckout = createServerFn({ method: "POST" })
     return { checkout, member, config };
   });
 
+/**
+ * 배송비 미리보기 — 주문서를 만들 때는 배송지를 몰라 제주·도서산간 추가 배송비가 빠져 있다.
+ * 우편번호를 받으면 다시 계산해 보여 준다(주문서를 바꾸지 않는 읽기 계산이다).
+ * 결제 시작과 마찬가지로 서버 함수로 부른다 — 구매자 토큰이 브라우저 JS에 나가지 않는다.
+ */
+const quoteDelivery = createServerFn({ method: "POST" })
+  .validator(z.object({ checkoutId: z.string(), zipCode: z.string() }))
+  .handler(async ({ data }) => {
+    const api = apiFor({ accessToken: readToken(), cartToken: readCartToken() });
+    try {
+      const quote = await api.checkout.quoteDelivery(data.checkoutId, { zipCode: data.zipCode });
+      return { quote, error: null };
+    } catch {
+      return { quote: null, error: "배송비를 확인하지 못했어요. 우편번호를 다시 확인해주세요." };
+    }
+  });
+
 const paymentForm = z.object({
   checkoutId: z.string(),
   option: paymentOptionSchema,
@@ -61,6 +82,8 @@ const paymentForm = z.object({
   guestName: z.string(),
   email: z.string(),
   orderPassword: z.string(),
+  /** 현금영수증 신청 — 계좌이체·가상계좌에서 구매자가 켰을 때만 */
+  cashReceipt: cashReceiptRequestSchema.optional(),
 });
 
 /** 결제 시작은 서버에서 한다 — 토큰이 브라우저 JS에 노출되지 않는다. 결제창 호출 값(공개 값)만 내려준다 */
@@ -92,6 +115,7 @@ const startPayment = createServerFn({ method: "POST" })
               email: data.email,
               orderPassword: data.orderPassword,
             },
+        cashReceipt: data.cashReceipt,
       });
       // 결제 시작 값은 JSON으로 넘기고 브라우저에서 SDK 스키마로 다시 읽는다 — 서버 함수 직렬화 타입에 맞춘다
       return { start: JSON.stringify(start), error: null };
@@ -109,6 +133,8 @@ function startErrorMessage(error: unknown): string {
       return "결제창을 준비하지 못했어요. 다른 결제수단으로 시도해주세요.";
     case "PAYMENT_NOT_CONFIGURED":
       return "결제 수단을 준비하고 있어요. 잠시 후 다시 시도해주세요.";
+    case "CASH_RECEIPT_NOT_AVAILABLE":
+      return "현금영수증은 계좌이체·가상계좌 결제에서만 신청할 수 있어요.";
     case "RETURN_URL_NOT_ALLOWED":
       return "이 쇼핑몰 주소에서는 결제할 수 없어요. 셀러 콘솔 설정 › 결제에서 결제 도메인을 확인해주세요.";
     default:
@@ -131,6 +157,38 @@ function Checkout() {
   const [submitting, setSubmitting] = useState(false);
   const options = checkout.paymentOptions;
   const [selected, setSelected] = useState(options[0] ? paymentOptionKey(options[0]) : "");
+  /**
+   * 배송지를 반영한 금액. 배송비 미리보기와 결제 시작 응답이 덮어쓴다 — 최종 금액은 결제 시작 응답의 `amounts`다
+   * (서버가 보낸 배송지로 배송비를 다시 계산한다).
+   */
+  const [quote, setQuote] = useState<DeliveryQuoteResult | null>(null);
+  /** 같은 우편번호로 blur가 반복돼도 다시 부르지 않는다 */
+  const [quotedZip, setQuotedZip] = useState<string | null>(null);
+  const amounts = quote?.amounts ?? checkout.amounts;
+  const delivery = quote?.delivery ?? checkout.delivery;
+
+  // 디바운스 타이머 대신 blur에서 부른다 — 우편번호는 5자리를 한 번에 채우는 값이고, FormData 폼에
+  // 입력 상태를 따로 들지 않아도 된다
+  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 {
+          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) => {
     if (result.status === "COMPLETED") {
@@ -168,6 +226,18 @@ function Checkout() {
     }
     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 back = window.location.pathname + window.location.search;
     const payments = paymentsFor(config);
     // 결제창은 클릭 시점에 열어야 팝업 차단에 걸리지 않는다 — 서버 함수를 기다리기 전에 빈 창을 먼저 연다
@@ -188,6 +258,7 @@ function Checkout() {
         guestName: field("guestName"),
         email: field("email"),
         orderPassword: field("orderPassword"),
+        cashReceipt,
       },
     })
       .then(async ({ start, error }) => {
@@ -196,13 +267,11 @@ function Checkout() {
           setNotice(error);
           return;
         }
+        const paymentStart = paymentStartSchema.parse(JSON.parse(start));
+        // 확정 금액 — 서버가 보낸 배송지로 배송비를 다시 계산했다. 화면에 보여 준 금액과 다를 수 있다
+        setQuote({ amounts: paymentStart.amounts, delivery: paymentStart.delivery });
         // 결제 서비스가 결제창을 그린다. 팝업이면 결과를 여기서 받고, 리다이렉트면 이 탭이 떠난다
-        settle(
-          await payments.open(paymentStartSchema.parse(JSON.parse(start)), {
-            window: paymentWindow,
-          }),
-          back,
-        );
+        settle(await payments.open(paymentStart, { window: paymentWindow }), back);
       })
       .catch(() => {
         paymentWindow.close();
@@ -218,7 +287,14 @@ function Checkout() {
           <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 />
+          <Field
+            label="우편번호"
+            name="zipCode"
+            placeholder="04524"
+            required
+            onBlur={handleZipBlur}
+            hint="입력하면 지역 추가 배송비까지 반영한 배송비를 보여 줘요"
+          />
           <Field label="주소" name="address1" required />
           <Field label="상세 주소" name="address2" />
           <Field label="배송 메모" name="deliveryMemo" />
@@ -272,11 +348,52 @@ function Checkout() {
           )}
         </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)}
+              />
+              현금영수증 신청
+            </label>
+            {cashReceiptOn ? (
+              <>
+                <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)
+                    }
+                    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
+                  label={
+                    cashReceiptType === "EXPENSE_PROOF"
+                      ? "사업자등록번호"
+                      : "휴대폰 번호 또는 현금영수증카드 번호"
+                  }
+                  name="cashReceiptNumber"
+                  required
+                />
+              </>
+            ) : null}
+          </fieldset>
+        ) : null}
+
         <SubmitButton
           disabled={submitting || options.length === 0}
           className="h-12 w-full rounded-md bg-ink font-semibold text-white disabled:opacity-50"
         >
-          {formatPrice(checkout.amounts.totalAmount)} 결제하기
+          {formatPrice(amounts.totalAmount)} 결제하기
         </SubmitButton>
       </form>
 
@@ -300,13 +417,25 @@ function Checkout() {
           ))}
         </ul>
         <dl className="space-y-1 border-line border-t pt-3 text-sm">
-          <Row label="상품 금액" value={formatPrice(checkout.amounts.productAmount)} />
-          <Row label="배송비" value={formatPrice(checkout.amounts.deliveryFee)} />
+          <Row label="상품 금액" value={formatPrice(amounts.productAmount)} />
+          {/* 배송비는 배송 묶음(같은 출고지 + 같은 배송 정책)마다 한 번 붙고, 지역 추가 배송비는 묶음마다 더한다 */}
+          <Row label="기본 배송비" value={formatPrice(delivery.baseFee)} />
+          {delivery.remoteSurcharge > 0 ? (
+            <Row
+              label={`${delivery.remoteAreaLabel ?? "지역"} 추가 배송비`}
+              value={formatPrice(delivery.remoteSurcharge)}
+            />
+          ) : null}
           <div className="flex justify-between border-line border-t pt-2 font-bold">
             <dt>총 결제금액</dt>
-            <dd>{formatPrice(checkout.amounts.totalAmount)}</dd>
+            <dd>{formatPrice(amounts.totalAmount)}</dd>
           </div>
         </dl>
+        {deliveryNotes(delivery).map((note) => (
+          <p key={note} className="text-muted text-xs">
+            {note}
+          </p>
+        ))}
         {checkout.testPayment ? (
           <p className="rounded-md bg-chip px-3 py-2 text-xs">
             테스트 결제예요. 실제로 돈이 오가지 않아요.
@@ -318,6 +447,17 @@ function Checkout() {
   );
 }
 
+/** 배송비를 몇 번, 왜 부과했는지 알려 주는 안내 문구 */
+function deliveryNotes(delivery: CheckoutDelivery): string[] {
+  const notes: string[] = [];
+  if (delivery.bundleCount >= 2) {
+    notes.push(`배송 묶음 ${delivery.bundleCount}건 — 묶음마다 배송비가 붙어요.`);
+  }
+  if (delivery.freeByThreshold) notes.push("무료배송 기준 금액을 넘겨 기본 배송비가 빠졌어요.");
+  if (delivery.zipCode === null) notes.push("배송지를 입력하면 배송비가 확정돼요.");
+  return notes;
+}
+
 function Field({
   label,
   name,
@@ -326,6 +466,7 @@ function Field({
   placeholder,
   required,
   hint,
+  onBlur,
 }: {
   label: string;
   name: string;
@@ -334,6 +475,7 @@ function Field({
   placeholder?: string;
   required?: boolean;
   hint?: string;
+  onBlur?: (value: string) => void;
 }) {
   return (
     <label className="block space-y-1">
@@ -348,6 +490,7 @@ function Field({
         defaultValue={defaultValue}
         placeholder={placeholder}
         required={required}
+        onBlur={onBlur ? (event) => onBlur(event.target.value) : undefined}
         className="h-11 w-full rounded-md border border-line px-3"
       />
       {hint ? <span className="text-muted text-xs">{hint}</span> : null}

package/template/src/routes/login.tsx

@@ -26,6 +26,10 @@ const getLoginMethods = createServerFn({ method: "GET" }).handler(async () => {
 /**
  * 소셜 로그인 시작 — state·PKCE verifier를 쿠키에 두고 공급자 로그인 화면 주소를 돌려준다. 돌아오는 곳은
  * `/auth/callback`이고, 이 앱의 주소가 콘솔의 스토어프론트 도메인에 등록돼 있어야 한다.
+ *
+ * 가입 화면에서 약관 동의를 미리 받는다면 `agreements: { terms: true, privacy: true, marketing }`을 함께 넘긴다.
+ * 이 템플릿은 로그인과 가입을 한 화면에서 받아(기존 회원의 로그인까지 막지 않으려고) 넘기지 않고,
+ * 가입된 뒤 계정 화면(`/account`)에서 받는다.
  */
 const startSocial = createServerFn({ method: "POST" })
   .validator(z.object({ provider: z.enum(["kakao", "naver", "google"]), redirectTo: z.unknown() }))

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

@@ -1,8 +1,18 @@
-import { ApiError } from "@sayren/storefront-sdk";
-import { createFileRoute, Link, notFound, redirect } from "@tanstack/react-router";
+import {
+  ApiError,
+  type ClaimReason,
+  type ClaimType,
+  type CreateClaimResult,
+  claimReasonSchema,
+  claimTypeSchema,
+  type MyOrderItem,
+} from "@sayren/storefront-sdk";
+import { createFileRoute, Link, notFound, redirect, useRouter } 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 { readToken } from "../lib/session.server";
@@ -22,14 +32,108 @@ const getOrder = createServerFn({ method: "GET" })
     }
   });
 
+/**
+ * 취소·반품 접수 — 수량을 실으면 그 수량만 접수된다(생략하면 남은 수량 전체).
+ * 상한은 주문 상품의 `activeQuantity`이고 넘기면 서버가 400 `INVALID_QUANTITY`로 거절한다.
+ * 구매자 토큰은 서버에만 두므로 접수도 서버 함수에서 한다.
+ */
+const createClaim = createServerFn({ method: "POST" })
+  .validator(
+    z.object({
+      orderItemId: z.string(),
+      type: claimTypeSchema,
+      reason: claimReasonSchema,
+      quantity: z.number().int().min(1),
+      reasonDetail: z.string().max(1000).optional(),
+    }),
+  )
+  .handler(async ({ data }) => {
+    const accessToken = readToken();
+    if (!accessToken) throw redirect({ to: "/login", search: { redirectTo: "/orders" } });
+    const { orderItemId, ...body } = data;
+    try {
+      return {
+        claim: await apiFor({ accessToken }).myClaims.create(orderItemId, body),
+        error: null,
+      };
+    } catch (error) {
+      return { claim: null, error: claimErrorMessage(error) };
+    }
+  });
+
+function claimErrorMessage(error: unknown): string {
+  if (!(error instanceof ApiError)) return "접수하지 못했어요. 잠시 후 다시 시도해주세요.";
+  switch (error.code) {
+    case "INVALID_QUANTITY":
+      return "남은 수량보다 많이 신청했어요. 수량을 확인해주세요.";
+    case "CLAIM_IN_PROGRESS":
+      return "이미 진행 중인 신청이 있어요.";
+    case "INVALID_STATUS":
+      return "지금은 신청할 수 없는 상태예요. 주문 상태를 확인해주세요.";
+    case "PERIOD_EXPIRED":
+      return "반품·교환 가능 기간이 지났어요.";
+    default:
+      return error.message || "접수하지 못했어요. 잠시 후 다시 시도해주세요.";
+  }
+}
+
 export const Route = createFileRoute("/orders/$orderId")({
   loader: ({ params }) => getOrder({ data: { orderId: params.orderId } }),
   head: ({ params }) => ({ meta: [{ title: `주문 ${params.orderId}` }] }),
   component: OrderDetail,
 });
 
+/**
+ * 상태별로 접수할 수 있는 신청 종류 — **서버 규칙과 같게 둔다.**
+ *
+ * 취소는 발송 전(`PAID`·`CONFIRMED`), 반품은 배송완료(`DELIVERED`) 뒤에만 된다. 발송 중(`DISPATCHED`·
+ * `DELIVERING`)에는 둘 다 안 되므로 버튼을 띄우지 않는다 — 띄우면 구매자가 눌러 봐야 409 `INVALID_STATUS`를 본다.
+ * 교환은 희망 옵션(`exchangeOptionId`)이 필수라 이 화면에서 다루지 않는다.
+ */
+function claimableTypes(status: MyOrderItem["status"]): ClaimType[] {
+  if (status === "PAID" || status === "CONFIRMED") return ["CANCEL"];
+  if (status === "DELIVERED") return ["RETURN"];
+  return [];
+}
+
+const CLAIM_TYPE_LABELS: Record<ClaimType, string> = {
+  CANCEL: "취소",
+  RETURN: "반품",
+  EXCHANGE: "교환",
+};
+
+const CLAIM_REASON_LABELS: Record<ClaimReason, string> = {
+  CHANGE_OF_MIND: "단순 변심",
+  WRONG_ORDER: "주문 실수",
+  DEFECTIVE: "상품 불량",
+  WRONG_DELIVERY: "오배송",
+  DIFFERENT_FROM_PAGE: "상품 정보와 다름",
+  DELAY: "배송 지연",
+};
+
 function OrderDetail() {
   const order = Route.useLoaderData();
+  const router = useRouter();
+  const [openItemId, setOpenItemId] = useState<string | null>(null);
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [result, setResult] = useState<CreateClaimResult | null>(null);
+
+  const submit = (data: Parameters<typeof createClaim>[0]["data"]) => {
+    setPending(true);
+    setError(null);
+    createClaim({ data })
+      .then((response) => {
+        if (response.error) {
+          setError(response.error);
+          return;
+        }
+        setResult(response.claim);
+        setOpenItemId(null);
+        return router.invalidate();
+      })
+      .finally(() => setPending(false));
+  };
 
   return (
     <div className="space-y-6">
@@ -41,23 +145,74 @@ function OrderDetail() {
         <p className="text-muted text-sm">{formatDateTime(order.orderedAt)}</p>
       </div>
 
+      {result ? (
+        <div className="space-y-1 rounded-md bg-chip p-4 text-sm">
+          <p className="font-semibold">신청이 접수됐어요 (수량 {result.quantity}개)</p>
+          {/* 상품 금액 환불은 수량 비율이고, 반품 배송비는 이미 빠져 있다. 배송비 환불은 따로 온다 */}
+          {result.expectedRefundAmount === null ? null : (
+            <p className="text-muted">
+              예상 환불 금액 {formatPrice(result.expectedRefundAmount)}
+              {result.claimDeliveryFee > 0
+                ? ` (반품 배송비 ${formatPrice(result.claimDeliveryFee)} 차감)`
+                : null}
+            </p>
+          )}
+          {result.deliveryFeeRefundAmount > 0 ? (
+            <p className="text-muted">
+              배송비 환불 예상 {formatPrice(result.deliveryFeeRefundAmount)}
+            </p>
+          ) : null}
+        </div>
+      ) : null}
+
       <ul className="divide-y divide-line border-line border-y">
         {order.items.map((item) => (
-          <li key={item.orderItemId} className="flex items-center gap-4 py-4">
-            <ProductThumb
-              src={item.thumbnailUrl}
-              className="size-16 rounded-md bg-chip object-cover"
-            />
-            <span className="flex flex-1 flex-col gap-1 text-sm">
-              <span>{item.productName}</span>
-              {item.optionName ? (
-                <span className="text-muted text-xs">{item.optionName}</span>
-              ) : null}
-              <span className="text-muted text-xs">
-                {item.status} · 수량 {item.quantity}개
+          <li key={item.orderItemId} className="space-y-3 py-4">
+            <div className="flex items-center gap-4">
+              <ProductThumb
+                src={item.thumbnailUrl}
+                className="size-16 rounded-md bg-chip object-cover"
+              />
+              <span className="flex flex-1 flex-col gap-1 text-sm">
+                <span>{item.productName}</span>
+                {item.optionName ? (
+                  <span className="text-muted text-xs">{item.optionName}</span>
+                ) : null}
+                <span className="text-muted text-xs">
+                  {item.status} · 수량 {item.quantity}개
+                  {item.canceledQuantity > 0
+                    ? ` · 취소·반품 ${item.canceledQuantity}개 · 남은 수량 ${item.activeQuantity}개`
+                    : null}
+                </span>
               </span>
-            </span>
-            <span className="text-sm">{formatPrice(item.totalPrice)}</span>
+              <span className="text-sm">{formatPrice(item.totalPrice)}</span>
+            </div>
+
+            {claimableTypes(item.status).length > 0 &&
+            !item.claimStatus &&
+            item.activeQuantity > 0 ? (
+              openItemId === item.orderItemId ? (
+                <ClaimForm
+                  item={item}
+                  pending={pending}
+                  error={error}
+                  onSubmit={submit}
+                  onCancel={() => setOpenItemId(null)}
+                />
+              ) : (
+                <button
+                  type="button"
+                  onClick={() => {
+                    setResult(null);
+                    setError(null);
+                    setOpenItemId(item.orderItemId);
+                  }}
+                  className="text-muted text-xs underline"
+                >
+                  취소·반품 신청
+                </button>
+              )
+            ) : null}
           </li>
         ))}
       </ul>
@@ -86,3 +241,127 @@ function OrderDetail() {
     </div>
   );
 }
+
+/**
+ * 취소·반품 접수 폼. 수량 기본값은 남은 수량 전체이고 입력값은 `activeQuantity`까지다.
+ * 서버 렌더한 마크업에 값이 그대로 남아야 하므로 프리필은 `defaultValue`로 준다.
+ */
+function ClaimForm({
+  item,
+  pending,
+  error,
+  onSubmit,
+  onCancel,
+}: {
+  item: MyOrderItem;
+  pending: boolean;
+  error: string | null;
+  onSubmit: (data: {
+    orderItemId: string;
+    type: ClaimType;
+    reason: ClaimReason;
+    quantity: number;
+    reasonDetail?: string;
+  }) => void;
+  onCancel: () => void;
+}) {
+  const types = claimableTypes(item.status);
+  // 수량은 빈 칸·범위 밖을 폼에서 먼저 잡는다 — `Number("")`는 0이라 그대로 보내면 서버 400을 본다
+  const [quantityText, setQuantityText] = useState(String(item.activeQuantity));
+  const quantity = Number(quantityText);
+  const quantityError =
+    quantityText.trim() === "" || !Number.isInteger(quantity)
+      ? "수량을 입력해주세요."
+      : quantity < 1 || quantity > item.activeQuantity
+        ? `수량은 1개 이상 ${item.activeQuantity}개 이하로 입력해주세요.`
+        : null;
+  return (
+    <form
+      className="space-y-3 rounded-md bg-chip p-4"
+      onSubmit={(event) => {
+        event.preventDefault();
+        if (quantityError) return;
+        const form = new FormData(event.currentTarget);
+        const reasonDetail = String(form.get("reasonDetail") ?? "").trim();
+        onSubmit({
+          orderItemId: item.orderItemId,
+          type: form.get("type") as ClaimType,
+          reason: form.get("reason") as ClaimReason,
+          quantity,
+          reasonDetail: reasonDetail || undefined,
+        });
+      }}
+    >
+      <div className="flex flex-wrap gap-3">
+        <label className="flex flex-col gap-1 text-xs">
+          <span className="text-muted">신청 종류</span>
+          <select
+            name="type"
+            defaultValue={types[0]}
+            className="h-9 rounded-md border border-line bg-white px-2 text-sm"
+          >
+            {types.map((type) => (
+              <option key={type} value={type}>
+                {CLAIM_TYPE_LABELS[type]}
+              </option>
+            ))}
+          </select>
+        </label>
+        <label className="flex flex-col gap-1 text-xs">
+          <span className="text-muted">사유</span>
+          <select
+            name="reason"
+            defaultValue={claimReasonSchema.options[0]}
+            className="h-9 rounded-md border border-line bg-white px-2 text-sm"
+          >
+            {claimReasonSchema.options.map((reason) => (
+              <option key={reason} value={reason}>
+                {CLAIM_REASON_LABELS[reason]}
+              </option>
+            ))}
+          </select>
+        </label>
+        <label className="flex flex-col gap-1 text-xs">
+          <span className="text-muted">수량 (남은 수량 {item.activeQuantity}개)</span>
+          <input
+            type="number"
+            name="quantity"
+            min={1}
+            max={item.activeQuantity}
+            step={1}
+            value={quantityText}
+            onChange={(event) => setQuantityText(event.target.value)}
+            aria-invalid={quantityError !== null}
+            className="h-9 w-24 rounded-md border border-line bg-white px-2 text-sm"
+          />
+        </label>
+      </div>
+
+      {quantityError ? <p className="text-point text-xs">{quantityError}</p> : null}
+
+      <label className="flex flex-col gap-1 text-xs">
+        <span className="text-muted">상세 사유 (선택)</span>
+        <textarea
+          name="reasonDetail"
+          rows={2}
+          maxLength={1000}
+          className="rounded-md border border-line bg-white px-2 py-1 text-sm"
+        />
+      </label>
+
+      {error ? <p className="text-point text-xs">{error}</p> : null}
+
+      <div className="flex items-center gap-3">
+        <SubmitButton
+          disabled={pending || quantityError !== null}
+          className="h-9 rounded-md bg-ink px-4 font-semibold text-sm text-white disabled:opacity-50"
+        >
+          신청하기
+        </SubmitButton>
+        <button type="button" onClick={onCancel} className="text-muted text-xs underline">
+          닫기
+        </button>
+      </div>
+    </form>
+  );
+}