@sayren/store-sdk 0.29.7 → 0.30.0

package/src/schemas/fulfillment.ts

@@ -69,9 +69,86 @@ export function fulfillmentRuleOf(type: string | null | undefined): FulfillmentR
   return FULFILLMENT_RULES[fulfillmentTypeOf(type)];
 }
 
-/** 택배 배송이 필요한가 — 배송비 묶음·배송지·발송 흐름의 판정은 이 함수 하나를 지난다 */
-export function requiresShipping(type: string | null | undefined): boolean {
-  return fulfillmentRuleOf(type).requiresShipping;
+// ─── 이행 방식 (이슈 #115 결정 28) ─────────────────────────────
+//
+// 유형(`SHIPPING`·`MANUAL`)은 그대로 두고 그 안의 **이행 방식**을 고른다. 상품이 허용 방식(`fulfillment.methods`)을 두고 구매자가
+// 주문서에서 하나를 고른다(생략하면 허용 목록의 첫 방식). 배송지·배송비 판정은 방식 규칙을 지난다 — 배송 상품도 방문 수령이면
+// 배송지·배송비가 없다.
+
+/**
+ * 이행 방식.
+ * - `CARRIER` 택배(송장·배송 추적)
+ * - `DIRECT` 직접 배달(배송지 있음, 송장 없음)
+ * - `PICKUP` 방문 수령(배송지·배송비 없음)
+ * - `PROVIDED` 제공 처리(배송 없는 상품)
+ */
+export const FULFILLMENT_METHODS = ["CARRIER", "DIRECT", "PICKUP", "PROVIDED"] as const;
+
+export const fulfillmentMethodSchema = z.enum(FULFILLMENT_METHODS);
+
+export type FulfillmentMethod = z.infer<typeof fulfillmentMethodSchema>;
+
+/** 방식 하나의 규칙 */
+export interface FulfillmentMethodRule {
+  /** 배송지를 받는가 — 배송비 묶음·배송지 필수 판정의 대상인가 */
+  requiresAddress: boolean;
+  /** 송장 등록·배송 추적으로 배송완료가 되는가 */
+  carrierTracking: boolean;
+  /** 구매자가 픽업 장소를 고르는가 */
+  pickupLocation: boolean;
+}
+
+/** 방식별 규칙표 — **유일한 원천이다.** */
+export const FULFILLMENT_METHOD_RULES: Readonly<Record<FulfillmentMethod, FulfillmentMethodRule>> =
+  {
+    CARRIER: { requiresAddress: true, carrierTracking: true, pickupLocation: false },
+    DIRECT: { requiresAddress: true, carrierTracking: false, pickupLocation: false },
+    PICKUP: { requiresAddress: false, carrierTracking: false, pickupLocation: true },
+    PROVIDED: { requiresAddress: false, carrierTracking: false, pickupLocation: false },
+  };
+
+/** 유형별 허용 방식 — 첫 값이 유형 기본이다 */
+export const FULFILLMENT_METHODS_BY_TYPE: Readonly<
+  Record<FulfillmentType, readonly FulfillmentMethod[]>
+> = {
+  SHIPPING: ["CARRIER", "DIRECT", "PICKUP"],
+  MANUAL: ["PROVIDED", "PICKUP"],
+};
+
+/** 유형의 기본 방식 — 허용 방식을 두지 않은 상품·이 필드 이전 주문상품 */
+export function defaultFulfillmentMethodOf(type: string | null | undefined): FulfillmentMethod {
+  return FULFILLMENT_METHODS_BY_TYPE[fulfillmentTypeOf(type)][0] as FulfillmentMethod;
+}
+
+/** 상품의 허용 방식 — 두지 않았으면 유형 기본 하나다 */
+export function fulfillmentMethodsOf(fulfillment: {
+  type: string;
+  methods?: readonly string[] | null;
+}): FulfillmentMethod[] {
+  const methods = (fulfillment.methods ?? []).filter((m): m is FulfillmentMethod =>
+    (FULFILLMENT_METHODS as readonly string[]).includes(m),
+  );
+  return methods.length > 0 ? methods : [defaultFulfillmentMethodOf(fulfillment.type)];
+}
+
+/** 저장된 방식 → 방식. null·모르는 값은 유형 기본이다 */
+export function fulfillmentMethodOf(
+  type: string | null | undefined,
+  method: string | null | undefined,
+): FulfillmentMethod {
+  const parsed = fulfillmentMethodSchema.safeParse(method);
+  return parsed.success ? parsed.data : defaultFulfillmentMethodOf(type);
+}
+
+/**
+ * 택배 배송이 필요한가 — 배송비 묶음·배송지·발송 흐름의 판정은 이 함수 하나를 지난다.
+ * 방식을 주면 방식 규칙도 본다(배송 상품의 방문 수령은 배송이 없다). 방식을 모르면 유형 규칙만 본다.
+ */
+export function requiresShipping(type: string | null | undefined, method?: string | null): boolean {
+  if (!fulfillmentRuleOf(type).requiresShipping) return false;
+  return (
+    method == null || FULFILLMENT_METHOD_RULES[fulfillmentMethodOf(type, method)].requiresAddress
+  );
 }
 
 /** 반품에 수거가 필요한가 — 비실물 반품은 수거 등록·수거 완료 없이 승인한다 */
@@ -150,6 +227,28 @@ function refineShippingConsistency(
 const deliveryTypeDescription =
   "배송비 유형. `FREE` 무료, `PAID` 유료, `CONDITIONAL_FREE` 조건부 무료";
 
+// ── 이행 방식(#115) ──
+
+/** 요청의 허용 방식 — 유형마다 받는 값이 다르다. 겹치면 400 */
+function methodsRequestSchema(type: FulfillmentType) {
+  return z
+    .array(z.enum(FULFILLMENT_METHODS_BY_TYPE[type] as [FulfillmentMethod, ...FulfillmentMethod[]]))
+    .min(1)
+    .refine((methods) => new Set(methods).size === methods.length, {
+      message: "이행 방식이 겹칩니다",
+    })
+    .describe(
+      `허용 이행 방식(이슈 #115). ${type === "SHIPPING" ? "`CARRIER`·`DIRECT`·`PICKUP`" : "`PROVIDED`·`PICKUP`"} 중 1개 이상, 첫 값이 주문서 기본이다. 생략하면 등록은 유형 기본(${type === "SHIPPING" ? "`CARRIER`" : "`PROVIDED`"}), 수정은 지금 값 유지(유형을 바꾸면 유형 기본)`,
+    );
+}
+
+const storedMethodsSchema = z
+  .array(z.string())
+  .optional()
+  .describe(
+    "허용 이행 방식(이슈 #115). 현재 값은 `CARRIER`·`DIRECT`·`PICKUP`·`PROVIDED`이고 값이 추가될 수 있어 문자열로 받는다. 셀러가 두지 않았으면 생략되고 유형 기본(`SHIPPING`은 `CARRIER`, `MANUAL`은 `PROVIDED`)이다",
+  );
+
 // ── 등록 요청 ──
 
 const shippingCreateSchema = z
@@ -179,8 +278,12 @@ const shippingCreateSchema = z
  * 상품 이행 — 등록(POST). 배송 상품의 `shipping`을 생략하면 기본값(유료 배송·상점 기본 배송비·기본 출고지·반품지)이다.
  */
 export const productFulfillmentCreateSchema = z.discriminatedUnion("type", [
-  z.strictObject({ type: z.literal("SHIPPING"), shipping: shippingCreateSchema.optional() }),
-  z.strictObject({ type: z.literal("MANUAL") }),
+  z.strictObject({
+    type: z.literal("SHIPPING"),
+    shipping: shippingCreateSchema.optional(),
+    methods: methodsRequestSchema("SHIPPING").optional(),
+  }),
+  z.strictObject({ type: z.literal("MANUAL"), methods: methodsRequestSchema("MANUAL").optional() }),
 ]);
 
 export type ProductFulfillmentCreate = z.infer<typeof productFulfillmentCreateSchema>;
@@ -209,8 +312,12 @@ const shippingUpdateSchema = z
  * `fulfillment` 자체를 생략하면 이행을 바꾸지 않는다.
  */
 export const productFulfillmentUpdateSchema = z.discriminatedUnion("type", [
-  z.strictObject({ type: z.literal("SHIPPING"), shipping: shippingUpdateSchema }),
-  z.strictObject({ type: z.literal("MANUAL") }),
+  z.strictObject({
+    type: z.literal("SHIPPING"),
+    shipping: shippingUpdateSchema,
+    methods: methodsRequestSchema("SHIPPING").optional(),
+  }),
+  z.strictObject({ type: z.literal("MANUAL"), methods: methodsRequestSchema("MANUAL").optional() }),
 ]);
 
 export type ProductFulfillmentUpdate = z.infer<typeof productFulfillmentUpdateSchema>;
@@ -241,8 +348,9 @@ export const productFulfillmentSchema = z.discriminatedUnion("type", [
         .nullable()
         .describe("반품지 주소 id. null이면 상점 기본 반품지를 따른다"),
     }),
+    methods: storedMethodsSchema,
   }),
-  z.object({ type: z.literal("MANUAL") }),
+  z.object({ type: z.literal("MANUAL"), methods: storedMethodsSchema }),
 ]);
 
 export type ProductFulfillment = z.infer<typeof productFulfillmentSchema>;
@@ -289,6 +397,30 @@ export type ProductFulfillmentView = z.infer<typeof productFulfillmentResponseSc
 
 // ─── 주문상품 이행 스냅샷 (이슈 #57) ─────────────────────────────
 
+const snapshotMethodSchema = z
+  .string()
+  .optional()
+  .describe(
+    "주문 시점 이행 방식(이슈 #115). 현재 값은 `CARRIER`·`DIRECT`·`PICKUP`·`PROVIDED`이고 값이 추가될 수 있어 문자열로 받는다. 없으면 유형 기본",
+  );
+
+/** 주문상품의 주문 시점 픽업 장소 — 장소를 고치거나 지워도 이 주문의 안내는 바뀌지 않는다 */
+export const pickupLocationSnapshotSchema = z.object({
+  locationId: z.string(),
+  name: z.string(),
+  address: z.string(),
+  phone: z.string().nullable(),
+  hours: z.string().nullable(),
+});
+
+export type PickupLocationSnapshot = z.infer<typeof pickupLocationSnapshotSchema>;
+
+const snapshotPickupSchema = pickupLocationSnapshotSchema
+  .optional()
+  .describe(
+    "방문 수령(`PICKUP`)에서 고른 장소(주문 시점 값). 픽업 장소를 두지 않은 상점이거나 다른 방식이면 생략",
+  );
+
 /**
  * 주문상품의 주문 시점 이행 — 결제 확정이 주문서 줄에서 굳힌다. 상품의 현재 값이 아니다. 서버는 주문상품 컬럼
  * (`fulfillment_type`·`delivery_bundle_key`)과 jsonb(`fulfillment_snapshot`)를 합쳐 이 모양을 만든다.
@@ -308,8 +440,14 @@ export const orderItemFulfillmentSnapshotSchema = z.discriminatedUnion("type", [
         .nullable()
         .describe("주문 시점 반품지 주소 id. null이거나 지워진 주소면 상점 기본 반품지로 안내한다"),
     }),
+    method: snapshotMethodSchema,
+    pickupLocation: snapshotPickupSchema,
+  }),
+  z.object({
+    type: z.literal("MANUAL"),
+    method: snapshotMethodSchema,
+    pickupLocation: snapshotPickupSchema,
   }),
-  z.object({ type: z.literal("MANUAL") }),
 ]);
 
 export type OrderItemFulfillmentSnapshot = z.infer<typeof orderItemFulfillmentSnapshotSchema>;
@@ -323,3 +461,33 @@ export const orderItemFulfillmentSnapshotResponseSchema = openFulfillmentUnion(
 export type OrderItemFulfillmentSnapshotView = z.infer<
   typeof orderItemFulfillmentSnapshotResponseSchema
 >;
+
+// ─── 픽업 장소 (이슈 #115 결정 28) ─────────────────────────────
+
+/** 상점당 픽업 장소 상한 */
+export const MAX_PICKUP_LOCATIONS = 20;
+
+/** 방문 수령(`PICKUP`) 장소 — 상점 설정이다. 구매자가 주문서에서 고르고 주문상품에 주문 시점 값이 남는다 */
+export const pickupLocationSchema = z.object({
+  locationId: z.string(),
+  name: z.string().describe("장소 이름(예: 본점)"),
+  address: z.string().describe("주소"),
+  phone: z.string().nullable().describe("연락처. 없으면 null"),
+  hours: z.string().nullable().describe("수령 가능 시간 안내. 없으면 null"),
+  usable: z.boolean().describe("사용 여부. false면 구매자에게 보이지 않고 주문서에서 고를 수 없다"),
+  sortOrder: z.number().int(),
+  createdAt: z.string(),
+});
+
+export type PickupLocation = z.infer<typeof pickupLocationSchema>;
+
+export const pickupLocationRequestSchema = z.strictObject({
+  name: z.string().trim().min(1).max(50),
+  address: z.string().trim().min(1).max(200),
+  phone: z.string().trim().max(30).nullish(),
+  hours: z.string().trim().max(100).nullish(),
+  usable: z.boolean().default(true),
+});
+
+export type PickupLocationRequest = z.infer<typeof pickupLocationRequestSchema>;
+export type PickupLocationRequestInput = z.input<typeof pickupLocationRequestSchema>;

package/src/schemas/misc.ts

@@ -158,6 +158,8 @@ export const eventTypeSchema = z
     "INQUIRY.CREATED",
     "REVIEW.CREATED",
     "PRODUCT.OUT_OF_STOCK",
+    // 커머스 플로우 알림 블록(이슈 #115). 플로우에 알림 블록을 둔 상점의 구독자에게만 간다
+    "ORDER.FLOW_NOTIFICATION",
   ])
   .describe(
     "웹훅 이벤트 타입. `ORDER.ADDRESS_CHANGE_REQUESTED`는 현재 발송하지 않음(호환을 위해 값만 남았고, 구독해도 이벤트가 오지 않는다)",

package/src/schemas/order.ts

@@ -4,6 +4,7 @@ import { changeTypeSchema, orderItemStatusSchema, type PageParams, pageSchema }
 import { orderItemFulfillmentSnapshotResponseSchema } from "./fulfillment";
 import { cashReceiptSchema, easyPayProviderResponseSchema } from "./payment";
 import { customInputValueSchema, optionSelectionSchema } from "./product";
+import { staySnapshotSchema } from "./stay";
 
 export const orderSummarySchema = z.object({
   orderId: z.string(),
@@ -81,6 +82,9 @@ export const orderItemSchema = z.object({
     .describe(
       "구매자가 적은 직접 입력값(주문 시점 항목명과 값, 이슈 #59). 없으면 빈 배열. 서버는 항상 싣는다",
     ),
+  stay: staySnapshotSchema
+    .optional()
+    .describe("숙박 기간과 박별 가격(날짜별 재고 상품만, 이슈 #118). 없으면 생략"),
   sellerCode: z.string().nullable(),
   fulfillmentSnapshot: orderItemFulfillmentSnapshotResponseSchema.describe(
     "주문 시점 이행 스냅샷(이슈 #57). `type`이 주문 시점 상품 유형이다. 배송 상품이 아니면 발송·배송완료 대신 제공 처리를 하고, " +

package/src/schemas/product.ts

@@ -8,6 +8,7 @@ import {
 } from "./fulfillment";
 import { pointEarnRateBpSchema } from "./points";
 import { productRefundPolicyPatchSchema } from "./refund-policy";
+import { inventoryModeSchema } from "./stay";
 import { UPLOAD_PURPOSE_LIMITS, uploadExtensionOf } from "./upload";
 
 export const productStatusSchema = z.enum(["SALE", "SUSPENDED", "OUT_OF_STOCK", "CLOSED"]);
@@ -101,6 +102,12 @@ export const productVariantSchema = z.object({
   weightGram: z.number().int().nullable(),
   sellerCode: z.string().nullable(),
   usable: z.boolean(),
+  attributes: z
+    .record(z.string(), z.string())
+    .optional()
+    .describe(
+      "조합 속성(이슈 #115) — 키 → 값 문자열(예: 회차 일시 `showAt`). 플로우가 `item.option.<키>`로 읽고 타입(날짜·숫자 등)은 플로우가 선언한다. 없으면 생략",
+    ),
   hasOrders: z
     .boolean()
     .optional()
@@ -163,6 +170,28 @@ export const addonGroupSchema = z.object({
 
 export type AddonGroup = z.infer<typeof addonGroupSchema>;
 
+/**
+ * 직접 입력 타입(이슈 #115 결정 24) — 값은 늘 문자열로 오가고 서버가 타입대로 검사·정규화한다.
+ * `number`는 정수, `select`는 `options` 중 하나, `date`는 `YYYY-MM-DD`, `datetime`은 오프셋 있는 ISO 8601이다.
+ * `image`는 구매자 업로드(`POST /storefront/v1/uploads/order-inputs`) 주소 목록이고 `maxLength`가 최대 장수(1~5)다
+ */
+export const CUSTOM_INPUT_TYPES = [
+  "text",
+  "number",
+  "select",
+  "date",
+  "datetime",
+  "image",
+] as const;
+
+/** 직접 입력 키 — 플로우 식이 `item.inputs.<key>`로 읽는다. 영문 소문자로 시작하는 영숫자·밑줄 */
+const customInputKeySchema = z
+  .string()
+  .regex(/^[a-z][a-zA-Z0-9_]{0,39}$/)
+  .describe(
+    "고정 키(영문 소문자로 시작, 영숫자·밑줄 40자). 플로우 식이 `item.inputs.<key>`로 읽는다",
+  );
+
 /** 직접 입력 항목 — 예: 각인 문구 */
 export const customInputSchema = z.object({
   inputId: z.string(),
@@ -172,6 +201,18 @@ export const customInputSchema = z.object({
   required: z.boolean(),
   usable: z.boolean().describe("사용 여부. false면 구매자에게 보이지 않는다"),
   sortOrder: z.number().int(),
+  key: z.string().nullable().optional().describe("고정 키. 없으면 null(플로우 식이 읽지 않는다)"),
+  type: z
+    .string()
+    .optional()
+    .describe(
+      "입력 타입. 현재 값은 `text`·`number`·`select`·`date`·`datetime`이고 값이 추가될 수 있어 문자열로 받는다. 없으면 `text`",
+    ),
+  options: z
+    .array(z.string())
+    .nullable()
+    .optional()
+    .describe("`select`의 선택지. 그 밖의 타입은 null"),
 });
 
 export type CustomInput = z.infer<typeof customInputSchema>;
@@ -254,6 +295,18 @@ export const customInputRequestSchema = z.object({
   maxLength: z.number().int().min(1).max(MAX_CUSTOM_INPUT_LENGTH),
   required: z.boolean().default(false),
   usable: z.boolean().default(true),
+  /** 아래 셋은 생략하면 지금 값을 유지한다(새 항목은 키 없음·`text`) — 옛 클라이언트의 저장이 타입을 지우지 않는다 */
+  key: customInputKeySchema.nullish(),
+  type: z
+    .enum(CUSTOM_INPUT_TYPES)
+    .optional()
+    .describe("입력 타입. 생략하면 지금 값 유지(새 항목은 `text`)"),
+  options: z
+    .array(z.string().trim().min(1).max(50))
+    .min(1)
+    .max(30)
+    .nullish()
+    .describe("`select`의 선택지(1~30개). `select`가 아니면 생략하거나 null"),
 });
 
 export type CustomInputRequest = z.infer<typeof customInputRequestSchema>;
@@ -279,6 +332,8 @@ export type OptionSelection = z.infer<typeof optionSelectionSchema>;
 export const customInputValueSchema = z.object({
   label: z.string(),
   value: z.string(),
+  key: z.string().nullable().optional().describe("항목의 고정 키(주문 시점). 없으면 null"),
+  type: z.string().optional().describe("항목의 입력 타입(주문 시점). 없으면 `text`"),
 });
 
 export type CustomInputValue = z.infer<typeof customInputValueSchema>;
@@ -338,6 +393,17 @@ export const productSchema = productSummarySchema.extend({
     .default("REGISTERED")
     .describe("옵션 값 정렬 순서(이슈 #59). 서버는 항상 싣는다"),
   fulfillment: productFulfillmentResponseSchema,
+  inventoryMode: z
+    .string()
+    .optional()
+    .describe("재고 방식(이슈 #118). 날짜별 재고 상품만 `DATED`를 싣는다. 없으면 `STANDARD`"),
+  flowId: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "주문 흐름(이슈 #115) — 상품에 지정한 흐름. null이면 카테고리의 흐름, 그것도 없으면 기본 흐름",
+    ),
   fulfillmentTypeLocked: z
     .boolean()
     .describe(
@@ -462,6 +528,13 @@ export const productVariantRequestSchema = z.object({
   weightGram: z.number().int().min(0).optional(),
   sellerCode: codeSchema.optional(),
   usable: z.boolean().default(true),
+  attributes: z
+    .record(z.string().regex(/^[a-z][a-zA-Z0-9_]{0,39}$/), z.string().max(100))
+    .refine((value) => Object.keys(value).length <= 10, { message: "조합 속성은 10개까지입니다" })
+    .optional()
+    .describe(
+      "조합 속성(이슈 #115) — 키 → 값 문자열(예: 회차 일시 `showAt`). 플로우가 `item.option.<키>`로 읽고 타입(날짜·숫자 등)은 플로우가 선언한다. 생략하면 지금 값 유지(새 조합은 없음), `{}`면 비운다",
+    ),
 });
 
 export type ProductVariantRequest = z.infer<typeof productVariantRequestSchema>;
@@ -601,6 +674,18 @@ const productWriteShape = {
     .describe(
       "쓰기 전용(이슈 #59) — 이 저장으로 옵션을 불러온 저장 옵션 id. 상품 저장과 같은 트랜잭션에서 불러오기 기록을 남겨 저장 옵션의 `importedProductCount`를 센다. 없는 id는 무시한다",
     ),
+  inventoryMode: inventoryModeSchema
+    .optional()
+    .describe(
+      "재고 방식(이슈 #118). `DATED`면 날짜별 달력(`PUT /products/{id}/calendar`)이 재고·가격이고 주문서 줄은 숙박 기간(`stay`)을 받는다. 생략하면 등록은 `STANDARD`, 수정은 지금 값. 판매 이력이 있으면 바꿀 수 없다(409 `INVENTORY_MODE_LOCKED`)",
+    ),
+  flowId: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "주문 흐름(이슈 #115) — 게시한 흐름 id. null이면 카테고리의 흐름(없으면 기본 흐름)을 쓴다. 생략하면 등록은 null, 수정은 지금 값. 게시하지 않은 흐름은 409 `FLOW_NOT_PUBLISHED`. 이미 결제된 주문은 결제 때 붙은 흐름을 그대로 따른다",
+    ),
 };
 
 export const productCreateRequestSchema = z.strictObject({
@@ -634,6 +719,13 @@ export const productPatchRequestSchema = z
     name: z.string().max(100).optional(),
     salePrice: z.number().int().multipleOf(10).optional(),
     status: productStatusSchema.optional(),
+    flowId: z
+      .string()
+      .nullable()
+      .optional()
+      .describe(
+        "주문 흐름(이슈 #115) — 게시한 흐름 id, null이면 카테고리의 흐름(없으면 기본 흐름). 생략하면 바꾸지 않는다",
+      ),
     images: productImagesRequestSchema
       .optional()
       .describe(

package/src/schemas/saved-option-set.ts

@@ -1,6 +1,7 @@
 import { z } from "zod";
 import { type PageParams, pageQueryShape } from "./common";
 import {
+  customInputRequestSchema,
   MAX_ADDON_GROUPS,
   MAX_CUSTOM_INPUT_LENGTH,
   MAX_CUSTOM_INPUTS,
@@ -51,6 +52,9 @@ export const savedCustomInputSchema = z.object({
   placeholder: z.string().nullable(),
   maxLength: z.number().int(),
   required: z.boolean(),
+  key: z.string().nullable().optional().describe("고정 키(#115). 없으면 생략"),
+  type: z.string().optional().describe("입력 타입(#115). 없으면 `text`"),
+  options: z.array(z.string()).nullable().optional().describe("`select`의 선택지"),
 });
 
 export type SavedCustomInput = z.infer<typeof savedCustomInputSchema>;
@@ -93,6 +97,10 @@ export const savedCustomInputRequestSchema = z.object({
   placeholder: z.string().trim().max(100).nullish(),
   maxLength: z.number().int().min(1).max(MAX_CUSTOM_INPUT_LENGTH),
   required: z.boolean().default(false),
+  /** 타입 있는 주문 입력(#115) — 상품 직접 입력과 같은 규칙. 생략하면 키 없음·`text` */
+  key: customInputRequestSchema.shape.key,
+  type: customInputRequestSchema.shape.type,
+  options: customInputRequestSchema.shape.options,
 });
 
 /**

package/src/schemas/scope.ts

@@ -31,6 +31,8 @@ export const STORE_SCOPE_RESOURCES = {
   audit: ["r"],
   promotion: ["r", "rw"],
   storefront: ["r", "rw"],
+  // 커머스 플로우 정의·할당(이슈 #115) — 주문 처리 행동은 order 스코프다
+  flow: ["r", "rw"],
 } as const satisfies Record<string, readonly ScopeAccess[]>;
 
 export type StoreScopeResource = keyof typeof STORE_SCOPE_RESOURCES;
@@ -68,6 +70,7 @@ export const STORE_ROLE_SCOPES = {
     "audit:r",
     "promotion:rw",
     "storefront:rw",
+    "flow:rw",
   ],
   ADMIN: [
     "product:rw",
@@ -84,6 +87,7 @@ export const STORE_ROLE_SCOPES = {
     "audit:r",
     "promotion:rw",
     "storefront:rw",
+    "flow:rw",
   ],
   STAFF: [
     "product:rw",
@@ -94,5 +98,6 @@ export const STORE_ROLE_SCOPES = {
     "review:rw",
     "customer:r",
     "promotion:r",
+    "flow:r",
   ],
 } as const satisfies Record<StoreRole, readonly string[]>;

package/src/schemas/shipping-policy.ts

@@ -259,6 +259,8 @@ export interface DeliveryFeeLine {
    * 유형을 바꿔도 결제 시작의 견적과 주문상품 스냅샷이 같은 유형을 보게 한다. 생략하면 상품 값을 쓴다.
    */
   fulfillmentType?: FulfillmentType | null;
+  /** 이 줄의 이행 방식(이슈 #115) — 배송지가 없는 방식(방문 수령)은 묶음을 만들지 않는다. 생략하면 유형 규칙만 본다 */
+  fulfillmentMethod?: string | null;
 }
 
 /**
@@ -344,7 +346,8 @@ export function quoteDelivery(input: DeliveryQuoteInput): DeliveryQuote {
     const product = input.productOf(line.productId);
     if (!product) continue;
     // 비실물은 묶음도 무료 기준 판정 금액도 만들지 않는다 — 디지털 금액이 실물 배송비를 면제시키지 않게 한다
-    if (!requiresShipping(line.fulfillmentType ?? product.fulfillmentType)) continue;
+    if (!requiresShipping(line.fulfillmentType ?? product.fulfillmentType, line.fulfillmentMethod))
+      continue;
     shippableAmount += line.amount;
     const key = deliveryBundleKeyOf(product);
     const group = groups.get(key) ?? { product, ids: new Set<string>(), sum: 0 };

package/src/schemas/stay.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+
+/**
+ * 날짜별 재고·가격(이슈 #118) — 숙박·회차처럼 날짜마다 재고와 가격이 다른 상품. 상품 `inventoryMode: "DATED"`이면 조합(객실) × 날짜
+ * 달력이 재고·가격의 원천이고, 주문서 줄은 기간(`stay`)을 받는다. 날짜는 한국 날짜 `YYYY-MM-DD`다.
+ */
+
+/** 한국 날짜 */
+export const calendarDateSchema = z
+  .string()
+  .regex(/^\d{4}-\d{2}-\d{2}$/)
+  .refine((value) => {
+    const date = new Date(`${value}T00:00:00Z`);
+    return !Number.isNaN(date.getTime()) && date.toISOString().slice(0, 10) === value;
+  }, "날짜 형식이 아닙니다")
+  .describe("한국 날짜(YYYY-MM-DD)");
+
+/** 한 번에 받는 최대 박수 */
+export const MAX_STAY_NIGHTS = 30;
+/** 달력 한 번 조회·설정 최대 일수 */
+export const MAX_CALENDAR_DAYS = 400;
+
+export const inventoryModeSchema = z
+  .enum(["STANDARD", "DATED"])
+  .describe("재고 방식. `STANDARD` 조합 재고 수량 · `DATED` 날짜별 재고·가격(숙박·회차)");
+export type InventoryMode = z.infer<typeof inventoryModeSchema>;
+
+/** 숙박 기간 — 체크인 날부터 체크아웃 전날까지가 박이다 */
+export const stayRangeSchema = z
+  .object({
+    checkIn: calendarDateSchema,
+    checkOut: calendarDateSchema,
+  })
+  .describe("숙박 기간. 체크인 날부터 체크아웃 전날까지 박마다 재고·가격을 본다");
+export type StayRange = z.infer<typeof stayRangeSchema>;
+
+/** 주문 시점 숙박 — 박마다 그때 가격 */
+export const staySnapshotSchema = z.object({
+  checkIn: z.string(),
+  checkOut: z.string(),
+  nights: z
+    .array(z.object({ date: z.string(), price: z.number().int() }))
+    .describe("박마다 날짜·가격(객실 1개 기준)"),
+});
+export type StaySnapshot = z.infer<typeof staySnapshotSchema>;
+
+/** 체크인~체크아웃 전날 날짜 목록. 형식이 틀리거나 체크아웃이 체크인 이하면 빈 목록 */
+export function nightsOf(range: StayRange): string[] {
+  const start = Date.parse(`${range.checkIn}T00:00:00Z`);
+  const end = Date.parse(`${range.checkOut}T00:00:00Z`);
+  if (Number.isNaN(start) || Number.isNaN(end) || end <= start) return [];
+  const nights: string[] = [];
+  for (let at = start; at < end; at += 86_400_000) {
+    nights.push(new Date(at).toISOString().slice(0, 10));
+  }
+  return nights;
+}
+
+/** 관리 달력 한 칸 */
+export const calendarDaySchema = z.object({
+  variantId: z.string(),
+  date: z.string(),
+  stock: z.number().int().describe("그날 남은 재고"),
+  price: z.number().int().nullable().describe("그날 가격(원). null이면 조합 가격"),
+});
+export type CalendarDay = z.infer<typeof calendarDaySchema>;
+
+export const calendarQuerySchema = z.object({
+  variantId: z.string().optional().describe("조합. 생략하면 모든 조합"),
+  from: calendarDateSchema,
+  to: calendarDateSchema.describe("끝 날짜(포함)"),
+});
+
+/**
+ * 달력 설정 — 기간의 날짜마다 재고·가격을 덮어쓴다(없는 날은 만든다). `stock`·`price`는 준 것만 바꾸고, `price: null`은 조합 가격으로
+ * 되돌린다. `daysOfWeek`(0=일~6=토)를 주면 그 요일만 바꾼다
+ */
+export const setCalendarRequestSchema = z
+  .object({
+    variantIds: z.array(z.string()).min(1).max(50),
+    from: calendarDateSchema,
+    to: calendarDateSchema,
+    stock: z.number().int().min(0).max(100_000).optional(),
+    price: z.number().int().min(0).multipleOf(10).nullable().optional(),
+    daysOfWeek: z.array(z.number().int().min(0).max(6)).min(1).max(7).optional(),
+  })
+  .refine((value) => value.stock !== undefined || value.price !== undefined, {
+    message: "stock이나 price 중 하나는 있어야 합니다",
+  });
+export type SetCalendarRequest = z.input<typeof setCalendarRequestSchema>;

package/src/schemas/upload.ts

@@ -5,8 +5,9 @@ import { z } from "zod";
  *
  * - `product-image`: 상품 목록·상세의 상품 이미지. 목록 썸네일로 쓰이므로 정지 이미지만 받는다.
  * - `description`: 상세설명 본문에 삽입하는 미디어. 동영상과 svg도 받는다.
+ * - `flow-attachment`: 주문 흐름 행동의 첨부(시안 등, 이슈 #115). 구매자에게 보이므로 정지 이미지와 PDF만 받는다.
  */
-export const uploadPurposeSchema = z.enum(["product-image", "description"]);
+export const uploadPurposeSchema = z.enum(["product-image", "description", "flow-attachment"]);
 
 export type UploadPurpose = z.infer<typeof uploadPurposeSchema>;
 
@@ -34,6 +35,10 @@ export const UPLOAD_PURPOSE_LIMITS: Record<UploadPurpose, UploadPurposeLimit> =
     extensions: ["jpg", "jpeg", "png", "gif", "webp", "avif", "svg", "mp4", "webm", "mov"],
     maxBytes: 50 * MB,
   },
+  "flow-attachment": {
+    extensions: ["jpg", "jpeg", "png", "webp", "avif", "gif", "pdf"],
+    maxBytes: 20 * MB,
+  },
 };
 
 /** 파일명의 소문자 확장자. 확장자가 없으면 `""` */