@sayren/mcp 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/mcp",
-  "version": "0.2.2",
+  "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.10.0",
-    "@sayren/storefront-sdk": "^0.10.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.10.0",
-    "@sayren/storefront-sdk": "0.10.0",
+    "@sayren/store-sdk": "0.11.0",
+    "@sayren/storefront-sdk": "0.11.0",
     "@sayren/ui": "0.1.0"
   }
 }

package/template/README.md

@@ -82,6 +82,12 @@ 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/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}