@sayren/store-sdk 0.17.0 → 0.18.0

package/src/schemas/product.ts

@@ -1,9 +1,10 @@
 import { z } from "zod";
 import { type PageParams, pageQueryShape } from "./common";
 import {
-  fulfillmentModeSchema,
   fulfillmentTypeResponseSchema,
-  fulfillmentTypeSchema,
+  productFulfillmentCreateSchema,
+  productFulfillmentResponseSchema,
+  productFulfillmentUpdateSchema,
 } from "./fulfillment";
 import { productRefundPolicyPatchSchema } from "./refund-policy";
 import { UPLOAD_PURPOSE_LIMITS, uploadExtensionOf } from "./upload";
@@ -12,10 +13,6 @@ export const productStatusSchema = z.enum(["SALE", "SUSPENDED", "OUT_OF_STOCK",
 
 export type ProductStatus = z.infer<typeof productStatusSchema>;
 
-export const deliveryTypeSchema = z.enum(["FREE", "PAID", "CONDITIONAL_FREE"]);
-
-export type DeliveryType = z.infer<typeof deliveryTypeSchema>;
-
 export const productSummarySchema = z.object({
   productId: z.string(),
   name: z.string(),
@@ -32,7 +29,11 @@ export const productSummarySchema = z.object({
   thumbnailUrl: z.url().optional(),
   /** optionGroups.length > 0 */
   hasOptions: z.boolean(),
-  fulfillmentType: fulfillmentTypeResponseSchema.optional().default("SHIPPING"),
+  fulfillment: z
+    .object({ type: fulfillmentTypeResponseSchema })
+    .describe(
+      "상품 이행의 유형. 유형별 속성은 단건 조회(`GET /v1/products/{productId}`)의 `fulfillment`에 있다",
+    ),
   updatedAt: z.string(),
 });
 
@@ -90,58 +91,6 @@ export const discountSchema = z.object({
 
 export type Discount = z.infer<typeof discountSchema>;
 
-/**
- * 상품 유형 응답 필드 (이슈 #48) — 이 필드 이전 서버의 응답에는 없으므로 기본값을 둔다. 서버는 항상 싣는다.
- */
-function productFulfillmentResponseShape() {
-  return {
-    fulfillmentType: fulfillmentTypeResponseSchema.optional().default("SHIPPING"),
-    fulfillmentMode: z
-      .string()
-      .nullable()
-      .optional()
-      .default(null)
-      .describe(
-        "제공 방식. `AUTO`(결제 확정과 함께 제공)·`MANUAL`(셀러가 제공 처리). 배송 상품은 null. 값이 추가될 수 있어 문자열로 받는다",
-      ),
-    stockTracking: z
-      .boolean()
-      .optional()
-      .default(true)
-      .describe("재고를 세는가. false면 재고와 무관하게 판다(파일 다운로드 기본)"),
-    downloadLimit: z
-      .number()
-      .int()
-      .nullable()
-      .optional()
-      .default(null)
-      .describe("파일 다운로드 횟수 한도. 파일 다운로드 상품이 아니면 null"),
-    downloadDays: z
-      .number()
-      .int()
-      .nullable()
-      .optional()
-      .default(null)
-      .describe("파일 다운로드 기간(제공일부터 일수). 파일 다운로드 상품이 아니면 null"),
-    withdrawalRestricted: z
-      .boolean()
-      .optional()
-      .default(false)
-      .describe(
-        "청약철회 제한 대상인가. 파일 다운로드·코드 발급 상품만 켤 수 있다(그 밖의 유형은 false로 저장한다). " +
-          "true면 주문서에서 제한 고지에 대한 구매자 동의를 받고, 첫 다운로드·열람 뒤 구매자 취소·반품을 받지 않는다",
-      ),
-    pickupAddressId: z
-      .string()
-      .nullable()
-      .optional()
-      .default(null)
-      .describe(
-        "방문 수령지 주소 id(`seller_addresses`, 유형 PICKUP). 방문 수령 상품이 아니면 null",
-      ),
-  };
-}
-
 export const productSchema = productSummarySchema.extend({
   description: z.string().optional(),
   /**
@@ -155,18 +104,18 @@ export const productSchema = productSummarySchema.extend({
   optionGroups: z.array(optionGroupSchema),
   /** 모든 상품이 최소 1개 variant를 갖는다 (옵션 없으면 default variant 1개) */
   variants: z.array(productVariantSchema),
-  deliveryType: deliveryTypeSchema.optional(),
-  deliveryFee: z.number().int().optional(),
-  conditionalFreeAmount: z.number().int().nullable().optional(),
-  returnFee: z.number().int().optional(),
-  exchangeFee: z.number().int().optional(),
+  fulfillment: productFulfillmentResponseSchema,
+  fulfillmentTypeLocked: z
+    .boolean()
+    .describe(
+      "판매 이력(주문상품)이 있어 상품 유형(`fulfillment.type`)을 바꿀 수 없는가. true면 다른 유형으로 수정하는 요청이 409 `FULFILLMENT_TYPE_LOCKED`다. 같은 유형 안의 속성은 바꿀 수 있다",
+    ),
   refundPolicy: productRefundPolicyPatchSchema
     .nullable()
-    .optional()
-    .describe("상품별 환불 정책 덮어쓰기. null이면 스토어 기본 환불 정책을 쓴다"),
-  shippingAddressId: z.string().nullable().optional(),
-  returnAddressId: z.string().nullable().optional(),
-  ...productFulfillmentResponseShape(),
+    .describe(
+      "상품별 환불 정책 덮어쓰기(상품이 정한 항목만). null이면 스토어 기본 환불 정책을 쓴다. " +
+        "반품·교환 배송비(`returnDeliveryFee`·`exchangeDeliveryFee`)는 배송 상품에만 있다",
+    ),
   /**
    * 설정된 즉시할인. `GET /products/{productId}/discount`의 응답과 같은 형태다(이슈 #51).
    * 할인이 없으면 null이다. 이 필드를 싣기 전 서버의 응답에는 없으므로 optional이다.
@@ -338,170 +287,81 @@ export const variantStockSchema = z.object({
 export type VariantStock = z.infer<typeof variantStockSchema>;
 
 /**
- * 출고지·반품지 지정 문구 — POST·PUT·PATCH가 같은 규칙을 쓰므로 설명도 한 곳이다 (이슈 #30).
+ * 상품 쓰기 요청의 공통 필드 — 등록(POST)과 전체 수정(PUT)이 같다. 이행(`fulfillment`)만 두 요청의 스키마가 다르다.
  *
- * 세 값이 뜻이 다르다. **생략**은 「정하지 않음」이라 서버가 그 시점 스토어 기본 주소를 박아 저장하고,
- * **null**은 「스토어 기본을 따른다」는 명시적 비우기다. 주소록 항목은 상품이 참조 중이면 지울 수 없어
- * (`409 ADDRESS_IN_USE`) 참조를 푸는 수단이 필요한데, 생략을 기본값으로 되채우면 기본 주소는 영원히
- * 풀리지 않는다 — null이 그 경로다. 배송 묶음 판정은 null을 그 시점 스토어 기본 출고지로 정규화하므로
- * 두 표현이 배송비를 갈라놓지 않는다.
+ * 최상위가 `strictObject`다. 모르는 필드는 400이다 — 이슈 #57 이전의 평면 필드(`deliveryFee`·`fulfillmentType`·`returnFee` 등)를
+ * 보낸 요청이 조용히 무시되지 않게 한다. 옛 필드는 `fulfillment.{유형}.…`과 `refundPolicy`로 옮겼다.
  */
-const ADDRESS_DESCRIPTIONS = {
-  shipping:
-    "출고지 주소 id(`GET /v1/seller-addresses?type=SHIPPING`). 생략하면 스토어 기본 출고지를 저장하고, " +
-    "`null`이면 비워 둔다(스토어 기본 출고지를 따른다). 이 스토어의 `SHIPPING` 주소가 아니면 거부한다",
-  return:
-    "반품지 주소 id(`GET /v1/seller-addresses?type=RETURN`). 생략하면 스토어 기본 반품지를 저장하고, " +
-    "`null`이면 비워 둔다(스토어 기본 반품지를 따른다). 이 스토어의 `RETURN` 주소가 아니면 거부한다",
-  patchShipping:
-    "출고지 주소 id. **생략은 바꾸지 않음**이고 `null`은 비우기다(스토어 기본 출고지를 따른다). " +
-    "이 스토어의 `SHIPPING` 주소가 아니면 거부한다",
-  patchReturn:
-    "반품지 주소 id. **생략은 바꾸지 않음**이고 `null`은 비우기다(스토어 기본 반품지를 따른다). " +
-    "이 스토어의 `RETURN` 주소가 아니면 거부한다",
-} as const;
-
-/**
- * 상품 유형 요청 필드 (이슈 #48) — 등록·전체 수정·부분 수정이 같은 필드를 받는다.
- *
- * 생략의 뜻: 등록은 배송 상품(`SHIPPING`)과 유형 기본값이고, 전체 수정(PUT)·부분 수정(PATCH)은 **현재 값을 유지**한다.
- * 이 필드를 모르는 옛 클라이언트가 전체 수정을 보내도 유형이 배송 상품으로 되돌아가지 않게 한다.
- */
-function productFulfillmentRequestShape() {
-  return {
-    fulfillmentType: fulfillmentTypeSchema
-      .optional()
-      .describe(
-        "상품 유형. `SHIPPING` 배송 상품 · `DOWNLOAD` 파일 다운로드 · `CODE` 코드 발급 · `SERVICE` 이용권·서비스 · `PICKUP` 방문 수령. " +
-          "등록에서 생략하면 SHIPPING이고, 수정에서 생략하면 바꾸지 않는다. 판매 이력이 있는 상품의 유형은 바꿀 수 없다" +
-          "(409 `FULFILLMENT_TYPE_LOCKED`). 배송 상품이 아니면 배송비·출고지·반품지·반품비·교환비를 무시하고 0·null로 저장한다",
-      ),
-    fulfillmentMode: fulfillmentModeSchema
-      .nullable()
-      .optional()
-      .describe(
-        "제공 방식. `AUTO` 결제 확정과 함께 제공 · `MANUAL` 셀러가 제공 처리. 생략·null이면 유형 기본값이다" +
-          "(코드 발급 AUTO, 이용권 MANUAL, 파일 다운로드 AUTO만, 방문 수령 MANUAL만). 배송 상품은 무시한다",
-      ),
-    stockTracking: z
-      .boolean()
-      .optional()
-      .describe(
-        "재고를 세는가. 파일 다운로드 상품만 끌 수 있다(기본 false). 그 밖의 유형은 항상 true",
-      ),
-    downloadLimit: z
-      .number()
-      .int()
-      .min(1)
-      .max(100)
-      .nullable()
-      .optional()
-      .describe("파일 다운로드 횟수 한도. 파일 다운로드 상품만 쓰고 생략·null이면 5회"),
-    downloadDays: z
-      .number()
-      .int()
-      .min(1)
-      .max(3650)
-      .nullable()
-      .optional()
-      .describe(
-        "파일 다운로드 기간(제공일부터 일수). 파일 다운로드 상품만 쓰고 생략·null이면 30일",
-      ),
-    withdrawalRestricted: z
-      .boolean()
-      .optional()
-      .describe(
-        "청약철회 제한 대상인가. true면 주문서가 제한 고지를 보여 주고 구매자 동의를 받는다. 배송 상품은 false로 저장한다",
-      ),
-    pickupAddressId: z
-      .string()
-      .nullable()
-      .optional()
-      .describe(
-        "방문 수령지 주소 id(`GET /v1/seller-addresses?type=PICKUP`). 방문 수령 상품만 쓴다. 생략하면 스토어 기본 방문 수령지를 저장한다",
-      ),
-  };
-}
+const productWriteShape = {
+  name: z.string().min(1).max(100),
+  categoryId: z.string().min(1, "카테고리를 선택해주십시오"),
+  salePrice: z
+    .number()
+    .int()
+    .min(10)
+    .multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)")
+    .describe("판매가. 원(KRW) 단위 정수, 최소 10원, 10원 단위"),
+  originalPrice: z.number().int().optional().describe("정가(할인 전 표시 가격). 원 단위"),
+  description: z.string().optional(),
+  /**
+   * 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
+   * 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
+   */
+  descriptionJson: z.string().nullable().optional(),
+  images: z
+    .array(productImageUrlSchema)
+    .min(1)
+    .max(MAX_PRODUCT_IMAGES)
+    .optional()
+    .describe("상품 이미지 주소 목록. 첫 장이 대표 이미지(썸네일)다"),
+  attributes: z.array(z.object({ attributeId: z.string(), value: z.string() })).optional(),
+  refundPolicy: productRefundPolicyPatchSchema
+    .nullish()
+    .describe(
+      "상품별 환불 정책 — 준 항목만 스토어 기본을 덮어쓴다. `null`이나 생략은 스토어 기본을 그대로 쓴다는 뜻이다. " +
+        "반품·교환 배송비(`returnDeliveryFee`·`exchangeDeliveryFee`)는 배송 상품에만 줄 수 있다(다른 유형은 400)",
+    ),
+  ...optionModelRequestSchema.shape,
+};
 
-export const productCreateRequestSchema = z
-  .object({
-    name: z.string().min(1).max(100),
-    categoryId: z.string().min(1, "카테고리를 선택해주십시오"),
-    salePrice: z
-      .number()
-      .int()
-      .min(10)
-      .multipleOf(10, "판매가는 10원 단위여야 합니다 (INVALID_PRICE_UNIT)")
-      .describe("판매가. 원(KRW) 단위 정수, 최소 10원, 10원 단위"),
-    originalPrice: z.number().int().optional().describe("정가(할인 전 표시 가격). 원 단위"),
-    description: z.string().optional(),
-    /**
-     * 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
-     * 표시는 `description`(HTML)이 맡는다 — 소비자는 이 필드를 몰라도 된다.
-     */
-    descriptionJson: z.string().nullable().optional(),
-    images: z
-      .array(productImageUrlSchema)
-      .min(1)
-      .max(MAX_PRODUCT_IMAGES)
-      .optional()
-      .describe("상품 이미지 주소 목록. 첫 장이 대표 이미지(썸네일)다"),
-    attributes: z.array(z.object({ attributeId: z.string(), value: z.string() })).optional(),
-    deliveryType: deliveryTypeSchema
-      .default("PAID")
-      .describe("배송비 유형. FREE 무료, PAID 유료, CONDITIONAL_FREE 조건부 무료"),
-    deliveryFee: z
-      .number()
-      .int()
-      .min(0)
-      .optional()
-      .describe(
-        "배송비. 원 단위. **생략하면 스토어 기본 배송비**(`GET /v1/store`의 `shippingPolicy.baseDeliveryFee`)를 쓴다. " +
-          "`deliveryType`이 FREE면 0으로 저장한다",
-      ),
-    conditionalFreeAmount: z
-      .number()
-      .int()
-      .optional()
-      .describe("CONDITIONAL_FREE일 때 무료 배송이 되는 주문 금액. 원 단위"),
-    returnFee: z
-      .number()
-      .int()
-      .default(0)
-      .describe("반품 배송비. 원 단위. `refundPolicy.returnDeliveryFee`와 같은 값이다"),
-    exchangeFee: z
-      .number()
-      .int()
-      .default(0)
-      .describe("교환 배송비. 원 단위. `refundPolicy.exchangeDeliveryFee`와 같은 값이다"),
-    refundPolicy: productRefundPolicyPatchSchema
-      .nullish()
-      .describe(
-        "상품별 환불 정책 — 준 항목만 스토어 기본을 덮어쓴다. `null`이나 생략은 스토어 기본을 그대로 쓴다는 뜻이다. " +
-          "`returnDeliveryFee`·`exchangeDeliveryFee`를 주면 `returnFee`·`exchangeFee`도 같은 값으로 맞춘다",
-      ),
-    shippingAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.shipping),
-    returnAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.return),
-    ...productFulfillmentRequestShape(),
-  })
-  .extend(optionModelRequestSchema.shape);
+export const productCreateRequestSchema = z.strictObject({
+  ...productWriteShape,
+  fulfillment: productFulfillmentCreateSchema
+    .optional()
+    .describe(
+      "상품 이행. `type`이 유형이고 같은 이름의 키가 유형별 속성이다. 생략하면 배송 상품(기본값)이다. " +
+        "배송 상품이 아닌 유형은 판매가 열린 유형만 등록할 수 있다(409 `FULFILLMENT_TYPE_NOT_AVAILABLE`)",
+    ),
+});
 
 export type ProductCreateRequest = z.infer<typeof productCreateRequestSchema>;
+export type ProductCreateRequestInput = z.input<typeof productCreateRequestSchema>;
+
+const fulfillmentUpdateDescription =
+  "상품 이행. 생략하면 바꾸지 않는다. 주면 유형 안 필드를 모두 담아 통째로 바꾼다(현재 값과 병합하지 않는다). " +
+  "판매 이력이 있으면 유형을 바꿀 수 없다(409 `FULFILLMENT_TYPE_LOCKED`)";
+
+/** 전체 수정(PUT) — 공통 필드는 등록과 같고, 이행은 생략하면 현재 값 유지, 주면 필드가 모두 필수다 */
+export const productReplaceRequestSchema = z.strictObject({
+  ...productWriteShape,
+  fulfillment: productFulfillmentUpdateSchema.optional().describe(fulfillmentUpdateDescription),
+});
+
+export type ProductReplaceRequest = z.infer<typeof productReplaceRequestSchema>;
+export type ProductReplaceRequestInput = z.input<typeof productReplaceRequestSchema>;
 
 export const productPatchRequestSchema = z
-  .object({
+  .strictObject({
     name: z.string().max(100).optional(),
     salePrice: z.number().int().multipleOf(10).optional(),
     status: productStatusSchema.optional(),
-    deliveryFee: z.number().int().optional(),
-    // PATCH의 생략은 「바꾸지 않음」이다 — 기본 주소로 되채우지 않는다. 비우려면 `null`을 준다
-    shippingAddressId: z
-      .string()
+    fulfillment: productFulfillmentUpdateSchema.optional().describe(fulfillmentUpdateDescription),
+    refundPolicy: productRefundPolicyPatchSchema
       .nullable()
       .optional()
-      .describe(ADDRESS_DESCRIPTIONS.patchShipping),
-    returnAddressId: z.string().nullable().optional().describe(ADDRESS_DESCRIPTIONS.patchReturn),
-    ...productFulfillmentRequestShape(),
+      .describe(
+        "상품별 환불 정책. 주면 통째로 바꾼다(준 항목만 스토어 기본을 덮어쓴다). `null`은 덮어쓰기를 지워 스토어 기본을 따른다. 생략하면 바꾸지 않는다",
+      ),
   })
   .refine((value) => Object.values(value).some((v) => v !== undefined), {
     message: "최소 1개 필드가 필요합니다",

package/src/schemas/refund-policy.ts

@@ -16,11 +16,9 @@ const descriptions = {
     "발송 전 취소로 배송 묶음(같은 상품의 주문상품)이 모두 취소되면 그 묶음의 배송비를 환불한다. " +
     "false면 배송비를 환불하지 않는다. 기본 true",
   returnDeliveryFee:
-    "단순 변심(구매자 귀책) 반품의 반품 배송비. 원 단위. 환불액에서 뺀다. 기본 0(무료). " +
-    "상품별 정책에서 이 값을 주면 상품의 `returnFee`도 같은 값으로 맞춘다",
+    "단순 변심(구매자 귀책) 반품의 반품 배송비. 원 단위. 환불액에서 뺀다. 기본 0(무료). 배송 상품에만 있다",
   exchangeDeliveryFee:
-    "단순 변심(구매자 귀책) 교환의 교환 배송비. 원 단위. 구매자에게 청구할 금액을 안내값으로 싣는다. 기본 0(무료). " +
-    "상품별 정책에서 이 값을 주면 상품의 `exchangeFee`도 같은 값으로 맞춘다",
+    "단순 변심(구매자 귀책) 교환의 교환 배송비. 원 단위. 구매자에게 청구할 금액을 안내값으로 싣는다. 기본 0(무료). 배송 상품에만 있다",
   sellerFaultFreeShipping:
     "판매자 귀책(셀러 직권취소, 불량·오배송 반품)이면 배송비를 셀러가 부담한다 — 배송비를 환불하고 반품비를 받지 않는다. " +
     "false면 구매자 귀책과 같은 규칙을 쓴다. 기본 true",
@@ -101,23 +99,17 @@ export const productRefundPolicyPatchSchema = refundPolicyPatchSchema.omit({
   couponShortfallCharge: true,
 });
 
-/** 정책 해석에 쓰는 상품 값 — 상품별 덮어쓰기와 레거시 배송비 필드 */
+/** 정책 해석에 쓰는 상품 값 — 상품별 덮어쓰기 */
 export interface RefundPolicyProductInput {
   /** 상품별 덮어쓰기. 없으면 스토어 기본을 그대로 쓴다 */
   refundPolicy?: RefundPolicyPatch | null;
-  /** @deprecated 레거시 상품 반품비 — `refundPolicy`가 없는 옛 상품의 값이다 */
-  returnFee?: number | null;
-  /** @deprecated 레거시 상품 교환비 — `refundPolicy`가 없는 옛 상품의 값이다 */
-  exchangeFee?: number | null;
 }
 
 /**
  * 유효 정책 해석 — 상품별 덮어쓰기 → 스토어 기본 → `REFUND_POLICY_DEFAULTS` 순이다.
  *
- * 반품비·교환비는 레거시 필드(`products.returnFee`·`exchangeFee`)와 **연결**한다. 상품이
- * `refundPolicy.returnDeliveryFee`를 정하면 그 값이 원천이고(서버가 `returnFee`도 같은 값으로 맞춘다),
- * 정하지 않았으면 레거시 값이 0보다 클 때 그 값을 쓴다. 0이면 스토어 기본을 따른다 —
- * 정책이 생기기 전에 만든 상품(반품비 0)이 스토어 기본을 물려받게 하는 규칙이다.
+ * 반품·교환 배송비의 원천은 정책 하나다(이슈 #57 결정 3). 상품의 레거시 반품비·교환비 필드와의 연결은 없앴고,
+ * 레거시 값은 마이그레이션이 상품별 정책으로 옮겼다.
  */
 export function resolveRefundPolicy(
   storePolicy?: RefundPolicyPatch | null,
@@ -128,29 +120,27 @@ export function resolveRefundPolicy(
 }
 
 /**
- * 상품의 **덮어쓰기 자체** — 레거시 반품비·교환비를 같은 형태로 승격한 값이다. 덮어쓰기가 없으면 null.
+ * 상품의 **덮어쓰기 자체** — 덮어쓰기가 없으면 null.
  *
  * `resolveRefundPolicy`가 합친 결과로는 "상품이 정한 값"과 "스토어 기본을 물려받은 값"을 가를 수 없다.
  * 관리 API 응답의 `refundPolicy`와 콘솔 폼의 덮어쓰기 스위치가 이 함수를 원천으로 쓴다 — 가르지 못하면
- * 스토어 기본을 쓰는 상품을 저장할 때 그 순간의 기본값이 상품에 박히거나, 레거시 값이 조용히 사라진다.
+ * 스토어 기본을 쓰는 상품을 저장할 때 그 순간의 기본값이 상품에 박힌다.
  */
 export function productRefundPolicyOverride(
   product?: RefundPolicyProductInput | null,
 ): RefundPolicyPatch | null {
+  if (product?.refundPolicy == null) return null;
   // 쿠폰 조건 미달 차감은 주문 단위라 스토어만 정한다 — 상품 행에 키가 있어도 덮어쓰기로 읽지 않는다(이슈 #47)
-  const { couponShortfallCharge: _storeOnly, ...override } = dropUndefined(product?.refundPolicy);
-  const legacy: RefundPolicyPatch = {};
-  if (override.returnDeliveryFee === undefined && (product?.returnFee ?? 0) > 0) {
-    legacy.returnDeliveryFee = product?.returnFee ?? 0;
-  }
-  if (override.exchangeDeliveryFee === undefined && (product?.exchangeFee ?? 0) > 0) {
-    legacy.exchangeDeliveryFee = product?.exchangeFee ?? 0;
-  }
-  const merged = { ...legacy, ...override };
-  if (product?.refundPolicy == null && Object.keys(merged).length === 0) return null;
-  return merged;
+  const { couponShortfallCharge: _storeOnly, ...override } = dropUndefined(product.refundPolicy);
+  return override;
 }
 
+/** 반품·교환 배송비 키 — 배송이 없는 상품의 정책에는 두지 않는다 */
+export const REFUND_POLICY_DELIVERY_FEE_KEYS = [
+  "returnDeliveryFee",
+  "exchangeDeliveryFee",
+] as const;
+
 /** `undefined` 값을 빼고 얕게 복사한다 — 전개 순서로 덮어쓸 때 `undefined`가 기본값을 지우지 않게 */
 function dropUndefined(patch?: RefundPolicyPatch | null): RefundPolicyPatch {
   if (!patch) return {};

package/src/schemas/shipping-policy.ts

@@ -1,6 +1,5 @@
 import { z } from "zod";
-import { type FulfillmentType, requiresShipping } from "./fulfillment";
-import type { DeliveryType } from "./product";
+import { type DeliveryType, type FulfillmentType, requiresShipping } from "./fulfillment";
 
 /**
  * 배송비 규칙 (이슈 #29) — 배송비를 **몇 번, 얼마나** 부과하는지를 정한다.

package/src/schemas/webhook-event.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { claimStatusSchema, claimTypeSchema } from "./claim";
 import { orderItemStatusSchema } from "./common";
+import { orderItemFulfillmentSnapshotResponseSchema } from "./fulfillment";
 
 /**
  * 웹훅 발송 형식 (공개 계약). 본문은 얇은 이벤트다. 개인정보를 싣지 않으며
@@ -59,13 +60,11 @@ export const orderWebhookEventDataSchema = z.object({
       "이벤트를 만든 주문상품 ID. 비실물 상품 제공으로 보내는 `ORDER.DELIVERED`에만 실린다. " +
         "택배 배송완료와 그 밖의 주문 이벤트에는 없다",
     ),
-  fulfillmentType: z
-    .string()
+  fulfillmentSnapshot: orderItemFulfillmentSnapshotResponseSchema
     .optional()
     .describe(
-      "이벤트를 만든 주문상품의 상품 유형. 비실물 상품의 제공 완료는 `ORDER.DELIVERED`로도 오고 이 값이 `SHIPPING`이 아니다. " +
-        "현재 값은 `SHIPPING`·`DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`이고 값이 추가될 수 있어 문자열로 받는다. " +
-        "비실물 제공이 아닌 이벤트에는 없고, 없으면 `SHIPPING`으로 읽는다",
+      "이벤트를 만든 주문상품의 주문 시점 이행 스냅샷(주문상품 응답의 `fulfillmentSnapshot`과 같다, 이슈 #57). " +
+        "비실물 상품의 제공 완료는 `ORDER.DELIVERED`로도 오고 `type`이 `SHIPPING`이 아니다. `orderItemId`가 있는 이벤트에만 실린다",
     ),
 });
 export type OrderWebhookEventData = z.infer<typeof orderWebhookEventDataSchema>;
@@ -79,15 +78,18 @@ export const orderFulfilledWebhookEventDataSchema = z.object({
   orderId: z.string().describe("주문 ID"),
   orderItemId: z.string().describe("제공한 주문상품 ID"),
   status: orderItemStatusSchema.describe("이벤트 발생 시점의 주문 대표 상태"),
-  fulfillmentType: z
-    .string()
-    .describe(
-      "상품 유형. 현재 값은 `DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`이고 값이 추가될 수 있어 문자열로 받는다",
-    ),
-  fulfillmentMode: z
-    .string()
-    .nullable()
-    .describe("제공 방식. `AUTO`(결제 확정과 함께)·`MANUAL`(셀러 제공 처리)"),
+  fulfillmentSnapshot: orderItemFulfillmentSnapshotResponseSchema.describe(
+    "제공한 주문상품의 주문 시점 이행 스냅샷(주문상품 응답의 `fulfillmentSnapshot`과 같다, 이슈 #57)",
+  ),
+  fulfillment: z
+    .object({
+      mode: z
+        .string()
+        .describe(
+          "실제 제공 방식. `AUTO`(결제 확정과 함께)·`MANUAL`(셀러 제공 처리). 주문상품 제공 기록의 `mode`와 같다",
+        ),
+    })
+    .describe("제공 기록"),
   fulfilledAt: z.string().describe("제공 시각 (ISO 8601). 주문상품의 `deliveredAt`과 같다"),
   testPayment: z
     .boolean()