@sayren/store-sdk 0.16.0 → 0.18.0

package/src/schemas/order.ts

@@ -1,5 +1,8 @@
 import { z } from "zod";
 import { changeTypeSchema, orderItemStatusSchema, type PageParams, pageSchema } from "./common";
+import { orderItemDownloadSchema } from "./digital-asset";
+import { orderItemFulfillmentSnapshotResponseSchema } from "./fulfillment";
+import { MAX_CODE_LENGTH, orderItemCodeSchema } from "./fulfillment-code";
 import { cashReceiptSchema, easyPayProviderResponseSchema } from "./payment";
 
 export const orderSummarySchema = z.object({
@@ -30,6 +33,57 @@ export const shippingAddressSchema = z.object({
 
 export type ShippingAddress = z.infer<typeof shippingAddressSchema>;
 
+/** 비실물 주문상품의 제공 정보 (이슈 #48) */
+export const orderItemFulfillmentSchema = z.object({
+  status: z
+    .string()
+    .describe(
+      "제공 상태. `FULFILLED`(제공함)·`REVOKED`(환불 등으로 회수함). 값이 추가될 수 있어 문자열로 받는다",
+    ),
+  mode: z.string().nullable().describe("제공 방식. `AUTO`·`MANUAL`"),
+  fulfilledAt: z.string().describe("제공 시각 (ISO 8601)"),
+  note: z.string().nullable().describe("셀러가 남긴 이용 안내. 없으면 null"),
+  codes: z
+    .array(orderItemCodeSchema)
+    .optional()
+    .default([])
+    .describe(
+      "코드 발급 상품에 배정한 코드의 가린 값. 평문은 싣지 않는다. 코드 상품이 아니면 빈 배열. 서버는 항상 싣는다",
+    ),
+  download: orderItemDownloadSchema
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "파일 다운로드 상품의 횟수·기한·파일 목록. 파일 주소는 싣지 않는다. 다른 유형은 null. 서버는 항상 싣는다",
+    ),
+  mail: z
+    .object({
+      status: z
+        .string()
+        .describe(
+          "제공 안내 메일 상태. 현재 값은 `PENDING`(보낼 예정)·`SENDING`·`SENT`·`FAILED`·`SKIPPED`(보내지 않음: 스토어 설정 꺼짐·받을 주소 없음)이고 값이 추가될 수 있다",
+        ),
+      sentAt: z.string().nullable(),
+      errorCode: z.string().nullable().describe("실패·건너뜀 사유 코드"),
+    })
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("구매자에게 보낸 제공 안내 메일(이슈 #48). 기록이 없으면 null. 서버는 항상 싣는다"),
+});
+
+/** 제공 안내 메일 재발송 결과 */
+export const fulfillmentMailResendSchema = z.object({
+  mailStatus: z
+    .string()
+    .describe("재발송 뒤 메일 상태 — `SENT`·`PENDING`(곧 다시 보낸다)·`FAILED`·`SKIPPED`"),
+});
+
+export type FulfillmentMailResend = z.infer<typeof fulfillmentMailResendSchema>;
+
+export type OrderItemFulfillment = z.infer<typeof orderItemFulfillmentSchema>;
+
 export const orderItemSchema = z.object({
   orderItemId: z.string(),
   orderId: z.string(),
@@ -40,6 +94,10 @@ export const orderItemSchema = z.object({
   optionId: z.string().nullable(),
   optionName: z.string().nullable(),
   sellerCode: z.string().nullable(),
+  fulfillmentSnapshot: orderItemFulfillmentSnapshotResponseSchema.describe(
+    "주문 시점 이행 스냅샷(이슈 #57). `type`이 주문 시점 상품 유형이다. 배송 상품이 아니면 발송·배송완료 대신 제공 처리를 하고, " +
+      "`DELIVERED`는 제공 완료(방문 수령은 수령 완료)다. 상품을 나중에 고쳐도 바뀌지 않는다. 실제 제공 기록은 `fulfillment`에 있다",
+  ),
   quantity: z.number().int().describe("주문 수량"),
   canceledQuantity: z
     .number()
@@ -51,8 +109,27 @@ export const orderItemSchema = z.object({
     .describe("살아 있는 수량 (`quantity` − `canceledQuantity`). 0이면 주문상품이 전량 취소됐다"),
   unitPrice: z.number().int(),
   discountAmount: z.number().int(),
-  totalPrice: z.number().int().describe("주문상품 금액 (할인 반영 단가 × 주문 수량)"),
+  totalPrice: z
+    .number()
+    .int()
+    .describe("주문상품 금액 (즉시할인 반영 단가 × 주문 수량). 쿠폰 할인 전 금액이다"),
+  couponDiscountAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "이 주문상품에 배분된 쿠폰 할인 — 상품 쿠폰 + 주문 쿠폰 배분. 실결제 금액은 `totalPrice − couponDiscountAmount`이고 " +
+        "취소·반품 환불은 실결제 금액을 수량 비율로 나눈다. 쿠폰이 없으면 0. 서버는 항상 싣는다",
+    ),
   hold: z.object({ reason: z.string(), expectedDispatchDate: z.string() }).nullable(),
+  fulfillment: orderItemFulfillmentSchema
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "비실물 상품의 제공 정보(이슈 #48). 제공 전이거나 배송 상품이면 null이다. 코드 평문·파일 주소는 싣지 않는다. 서버는 항상 싣는다",
+    ),
   autoDecisionDate: z.string().nullable(),
   sellerMemo: z.string().nullable(),
   orderedAt: z.string(),
@@ -67,6 +144,21 @@ export const orderItemSchema = z.object({
 
 export type OrderItem = z.infer<typeof orderItemSchema>;
 
+/** 주문이 받은 쿠폰 한 장 (이슈 #47) */
+export const orderDiscountSchema = z.object({
+  couponId: z.string().describe("쿠폰 id"),
+  name: z.string().describe("주문 시점 쿠폰 이름"),
+  kind: z
+    .string()
+    .describe(
+      "쿠폰 종류. 현재 값은 `ORDER`(주문 쿠폰)·`PRODUCT`(상품 쿠폰)·`DELIVERY`(배송비 쿠폰)이고 값이 추가될 수 있어 문자열로 받는다",
+    ),
+  discountAmount: z.number().int().describe("이 쿠폰의 할인액 (원)"),
+  issueId: z.string().nullable().describe("발급 쿠폰 id. 코드 입력형은 null"),
+});
+
+export type OrderDiscount = z.infer<typeof orderDiscountSchema>;
+
 export const orderSchema = z.object({
   orderId: z.string(),
   orderedAt: z.string(),
@@ -75,6 +167,13 @@ export const orderSchema = z.object({
     phone: z.string(),
     email: z.email().optional(),
   }),
+  requiresShipping: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe(
+      "택배 배송이 필요한 주문상품이 있는가. false면 `shippingAddress`는 주문자 이름·연락처만 있고 주소는 빈 문자열이다. 서버는 항상 싣는다",
+    ),
   shippingAddress: shippingAddressSchema,
   payment: z.object({
     method: z
@@ -102,10 +201,38 @@ export const orderSchema = z.object({
           "그 밖의 결제수단과 간편결제 이전 주문은 null. 서버는 항상 싣는다. " +
           "현재 값은 `NAVERPAY`·`KAKAOPAY`·`TOSSPAY`·`PAYCO`이고 값이 추가될 수 있어 문자열로 받는다",
       ),
-    productAmount: z.number().int(),
-    deliveryFee: z.number().int(),
-    discountAmount: z.number().int(),
-    totalAmount: z.number().int(),
+    productAmount: z.number().int().describe("상품 금액 합 (즉시할인 반영, 쿠폰 전)"),
+    deliveryFee: z.number().int().describe("배송비 (쿠폰 전)"),
+    discountAmount: z
+      .number()
+      .int()
+      .describe(
+        "즉시할인 합 (정가 − 할인 단가) × 수량. 쿠폰 할인은 `couponDiscountAmount`로 따로 온다",
+      ),
+    couponDiscountAmount: z
+      .number()
+      .int()
+      .optional()
+      .default(0)
+      .describe("상품·주문 쿠폰 할인 합계. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
+    deliveryDiscountAmount: z
+      .number()
+      .int()
+      .optional()
+      .default(0)
+      .describe("배송비 쿠폰 할인. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
+    discounts: z
+      .array(orderDiscountSchema)
+      .optional()
+      .default([])
+      .describe("주문이 받은 쿠폰. 쿠폰이 없으면 빈 배열. 서버는 항상 싣는다"),
+    totalAmount: z
+      .number()
+      .int()
+      .describe(
+        "결제 금액 = productAmount + deliveryFee − couponDiscountAmount − deliveryDiscountAmount. " +
+          "쿠폰이 없는 주문은 productAmount + deliveryFee다",
+      ),
     paidAt: z.string().nullable(),
     cashReceipt: cashReceiptSchema
       .nullable()
@@ -115,6 +242,14 @@ export const orderSchema = z.object({
         "현금영수증. 구매자가 계좌이체·가상계좌 결제에서 신청했을 때만 있고 그 밖에는 null. 서버는 항상 싣는다",
       ),
   }),
+  withdrawalAgreedAt: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(
+      "청약철회 제한 안내에 동의한 시각(이슈 #48). 제한 상품이 없던 주문은 null. 서버는 항상 싣는다",
+    ),
   testPayment: z
     .boolean()
     .describe(
@@ -159,6 +294,12 @@ export const orderListQuerySchema = z.object({
     .optional()
     .describe("주문상품 상태 필터 — 이 상태의 주문상품이 하나라도 있는 주문"),
   keyword: z.string().optional().describe("주문번호(일치)·주문자명·수령인명(포함) 검색"),
+  fulfillmentType: z
+    .string()
+    .optional()
+    .describe(
+      "상품 유형 필터(이슈 #48) — 이 유형(`SHIPPING`·`DOWNLOAD`·`CODE`·`SERVICE`·`PICKUP`)의 주문상품이 하나라도 있는 주문",
+    ),
   testPayment: testPaymentQuery,
   ...pageQuery,
   size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)"),
@@ -187,6 +328,8 @@ export interface OrderListParams extends PageParams {
   orderedTo?: string;
   status?: z.infer<typeof orderItemStatusSchema>;
   keyword?: string;
+  /** 상품 유형 필터 — 이 유형의 주문상품이 하나라도 있는 주문(이슈 #48) */
+  fulfillmentType?: string;
   /** 테스트 결제 필터 — `"true"` 테스트 결제만, `"false"` 실결제만, 생략하면 전부 */
   testPayment?: "true" | "false";
 }
@@ -345,13 +488,48 @@ export const cancelBySellerRequestSchema = z.object({
 
 export type CancelBySellerRequest = z.infer<typeof cancelBySellerRequestSchema>;
 
+/**
+ * 제공 처리 요청 (이슈 #48) — `POST /v1/order-items/{orderItemId}/fulfill`. 수동 제공 비실물 주문상품(이용권·방문 수령 등)을
+ * 제공 완료(`DELIVERED`)로 바꾼다.
+ */
+export const fulfillRequestSchema = z.object({
+  note: z
+    .string()
+    .trim()
+    .max(1000)
+    .optional()
+    .describe("구매자에게 보일 이용 안내(예: 예약 방법, 수령 장소). 주문 상세에 실린다"),
+  codes: z
+    .array(z.string().trim().min(1).max(MAX_CODE_LENGTH))
+    .min(1)
+    .max(100)
+    .optional()
+    .describe(
+      "수동 제공 코드 발급 상품의 코드 — 셀러 시스템이 발급한 코드를 넘긴다. 남은 수량만큼 보낸다(`CODE_COUNT_MISMATCH`). " +
+        "암호화해 저장하고 구매자가 열람할 때만 평문으로 나간다. 다른 유형은 보내지 않는다",
+    ),
+});
+
+export type FulfillRequest = z.infer<typeof fulfillRequestSchema>;
+
+/** 제공 처리 일괄 요청 — `POST /v1/order-items/fulfill` */
+export const fulfillBulkRequestSchema = z.object({
+  orderItemIds: z.array(z.string()).min(1).max(100),
+  note: fulfillRequestSchema.shape.note,
+});
+
+export type FulfillBulkRequest = z.infer<typeof fulfillBulkRequestSchema>;
+
 /** `POST /v1/order-items/{orderItemId}/cancel` 응답 — 셀러 직권취소 환불 결과 */
 export const cancelBySellerResultSchema = z.object({
   orderItemId: z.string(),
   refundAmount: z
     .number()
     .int()
-    .describe("실제 환불한 금액 — 수량 비율 상품 금액 + 배송비 환불 − 조건부 무료배송 미달 차감"),
+    .describe(
+      "실제 환불한 금액 — 수량 비율 상품 실결제 금액(쿠폰 배분을 뺀 금액) + 배송비 환불 − 조건부 무료배송 미달 차감 " +
+        "+ 되돌린 쿠폰 차감(`couponChargeRefundAmount`)",
+    ),
   quantity: z.number().int().describe("취소한 수량"),
   canceledQuantity: z.number().int().describe("취소 후 누적 취소 수량"),
   deliveryFeeRefundAmount: z
@@ -364,6 +542,18 @@ export const cancelBySellerResultSchema = z.object({
     .number()
     .int()
     .describe("조건부 무료배송 기준 미달로 환불액에서 뺀 배송비. 정책이 꺼져 있으면 항상 0이다"),
+  couponChargeAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe("쿠폰 조건 미달 차감. 판매자 취소는 차감하지 않으므로 늘 0이다. 서버는 항상 싣는다"),
+  couponChargeRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe("환불액에 더한, 앞선 환불에서 뺀 쿠폰 차감을 되돌린 몫. 서버는 항상 싣는다"),
   refundedAt: z.string(),
 });
 

package/src/schemas/product.ts

@@ -1,16 +1,18 @@
 import { z } from "zod";
 import { type PageParams, pageQueryShape } from "./common";
-import { refundPolicyPatchSchema } from "./refund-policy";
+import {
+  fulfillmentTypeResponseSchema,
+  productFulfillmentCreateSchema,
+  productFulfillmentResponseSchema,
+  productFulfillmentUpdateSchema,
+} from "./fulfillment";
+import { productRefundPolicyPatchSchema } from "./refund-policy";
 import { UPLOAD_PURPOSE_LIMITS, uploadExtensionOf } from "./upload";
 
 export const productStatusSchema = z.enum(["SALE", "SUSPENDED", "OUT_OF_STOCK", "CLOSED"]);
 
 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(),
@@ -27,6 +29,11 @@ export const productSummarySchema = z.object({
   thumbnailUrl: z.url().optional(),
   /** optionGroups.length > 0 */
   hasOptions: z.boolean(),
+  fulfillment: z
+    .object({ type: fulfillmentTypeResponseSchema })
+    .describe(
+      "상품 이행의 유형. 유형별 속성은 단건 조회(`GET /v1/products/{productId}`)의 `fulfillment`에 있다",
+    ),
   updatedAt: z.string(),
 });
 
@@ -73,6 +80,17 @@ export const productVariantSchema = z.object({
 
 export type ProductVariant = z.infer<typeof productVariantSchema>;
 
+export const discountSchema = z.object({
+  productId: z.string(),
+  discountType: z.enum(["RATE", "AMOUNT"]),
+  discountValue: z.number().int(),
+  discountedPrice: z.number().int(),
+  startAt: z.string().nullable(),
+  endAt: z.string().nullable(),
+});
+
+export type Discount = z.infer<typeof discountSchema>;
+
 export const productSchema = productSummarySchema.extend({
   description: z.string().optional(),
   /**
@@ -86,17 +104,28 @@ 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(),
-  refundPolicy: refundPolicyPatchSchema
+  fulfillment: productFulfillmentResponseSchema,
+  fulfillmentTypeLocked: z
+    .boolean()
+    .describe(
+      "판매 이력(주문상품)이 있어 상품 유형(`fulfillment.type`)을 바꿀 수 없는가. true면 다른 유형으로 수정하는 요청이 409 `FULFILLMENT_TYPE_LOCKED`다. 같은 유형 안의 속성은 바꿀 수 있다",
+    ),
+  refundPolicy: productRefundPolicyPatchSchema
+    .nullable()
+    .describe(
+      "상품별 환불 정책 덮어쓰기(상품이 정한 항목만). null이면 스토어 기본 환불 정책을 쓴다. " +
+        "반품·교환 배송비(`returnDeliveryFee`·`exchangeDeliveryFee`)는 배송 상품에만 있다",
+    ),
+  /**
+   * 설정된 즉시할인. `GET /products/{productId}/discount`의 응답과 같은 형태다(이슈 #51).
+   * 할인이 없으면 null이다. 이 필드를 싣기 전 서버의 응답에는 없으므로 optional이다.
+   */
+  discount: discountSchema
     .nullable()
     .optional()
-    .describe("상품별 환불 정책 덮어쓰기. null이면 스토어 기본 환불 정책을 쓴다"),
-  shippingAddressId: z.string().nullable().optional(),
-  returnAddressId: z.string().nullable().optional(),
+    .describe(
+      "설정된 즉시할인. GET /v1/products/{productId}/discount 응답과 같은 형태다. 할인이 없으면 null",
+    ),
   createdAt: z.string().optional(),
 });
 
@@ -258,106 +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;
-
-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: refundPolicyPatchSchema
-      .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),
-  })
-  .extend(optionModelRequestSchema.shape);
+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.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),
+      .describe(
+        "상품별 환불 정책. 주면 통째로 바꾼다(준 항목만 스토어 기본을 덮어쓴다). `null`은 덮어쓰기를 지워 스토어 기본을 따른다. 생략하면 바꾸지 않는다",
+      ),
   })
   .refine((value) => Object.values(value).some((v) => v !== undefined), {
     message: "최소 1개 필드가 필요합니다",
@@ -396,17 +400,6 @@ export const productListQuerySchema = z.object({
   ...pageQueryShape(),
 });
 
-export const discountSchema = z.object({
-  productId: z.string(),
-  discountType: z.enum(["RATE", "AMOUNT"]),
-  discountValue: z.number().int(),
-  discountedPrice: z.number().int(),
-  startAt: z.string().nullable(),
-  endAt: z.string().nullable(),
-});
-
-export type Discount = z.infer<typeof discountSchema>;
-
 export const discountRequestSchema = z.object({
   discountType: z.enum(["RATE", "AMOUNT"]),
   discountValue: z.number().int().min(1),