@sayren/store-sdk 0.47.0 → 0.49.0

package/src/schemas/coupon-selection.ts

@@ -0,0 +1,266 @@
+import { KRW_MONEY_RULES } from "./currency";
+import {
+  couponDiscountOf,
+  couponStackingOf,
+  couponsCombinable,
+  type PricingCoupon,
+  type PricingInput,
+  type PricingResult,
+  quotePricing,
+} from "./promotion";
+
+/**
+ * 최대 할인 쿠폰 조합 (이슈 #222) — 후보 쿠폰 중 할인 합이 가장 큰 조합을 고르는 **순수 함수**다.
+ * 금액은 고른 조합을 `quotePricing`에 다시 넣어 계산한다(원천 함수 하나). 상품 상세의 최대 할인·주문서 추천이 이 함수를 지난다.
+ *
+ * 방법
+ * 1. 후보를 하나씩 `quotePricing`으로 돌려 혼자서도 적용되는 쿠폰만 남긴다
+ * 2. 주문 쿠폰·배송비 쿠폰은 자리마다 하나(없음 포함)를 고르는 경우를 모두 본다(서로 결합할 수 있는 것만)
+ * 3. 그 경우마다 상품 쿠폰을 줄에 배정한다 — 줄 하나에 한 장이고 할인은 줄 금액만 보므로 최대 가중 매칭이다.
+ *    다른 상품 쿠폰과 함께 쓸 수 없는 상품 쿠폰(`combinesWith.product: false`)은 매칭 밖이라 혼자 쓰는 경우로 따로 본다
+ * 4. 경우마다 `quotePricing`으로 계산하고 할인 합이 가장 큰 것을 고른다. 결제 금액이 1원 이상 최소 결제 금액 미만이 되는 조합은 결제를
+ *    시작할 수 없으므로, 할인이 작은 상품 쿠폰부터 하나씩 빼며 다시 본다
+ *
+ * 주문 쿠폰의 기준은 「상품 쿠폰 차감 뒤 대상 합계」라 상품 쿠폰 할인을 키워도 총 할인은 줄지 않는다 — 그래서 3의 매칭이 그 경우의 최적이다.
+ * 다만 정률 할인의 판매가 단위 내림 때문에 단위(KRW 10원) 안쪽의 차이는 남을 수 있다.
+ * 적립금은 목표에 넣지 않는다(`points` 입력은 무시한다). 고른 쿠폰에 적립금과 함께 쓸 수 없는 쿠폰이 있으면 결과의 `withPoints`가 false다.
+ * 동률이면 장수가 적은 조합, 그다음 먼저 끝나는 쿠폰을 쓰는 조합, 그다음 쿠폰 키 순이다.
+ */
+
+export interface CouponSelectionInput extends Omit<PricingInput, "coupons" | "points"> {
+  /** 후보 — 쿠폰 키(`couponKey`)가 서로 달라야 한다(발급 쿠폰이면 발급 id). `lineId`는 무시한다 */
+  candidates: readonly PricingCoupon[];
+}
+
+export interface CouponSelection {
+  /** 고른 쿠폰 — 상품 쿠폰은 줄(`lineId`)이 정해져 있다. 그대로 결제 시작에 넣으면 같은 금액이다 */
+  coupons: PricingCoupon[];
+  /** 고른 조합의 계산 결과 */
+  result: PricingResult;
+  /** 쿠폰 할인 합(상품·주문 + 배송비) */
+  discountAmount: number;
+  /** 고른 조합이 적립금과 함께 쓸 수 있는가 */
+  withPoints: boolean;
+}
+
+type Candidate = { coupon: PricingCoupon; key: string; until: number };
+
+const keyOf = (coupon: PricingCoupon) => coupon.couponKey ?? coupon.rule.couponId;
+const untilOf = (coupon: PricingCoupon) => {
+  const times = [coupon.rule.endsAt, coupon.validUntil]
+    .filter((t): t is string => Boolean(t))
+    .map((t) => Date.parse(t))
+    .filter((t) => !Number.isNaN(t));
+  return times.length ? Math.min(...times) : Number.POSITIVE_INFINITY;
+};
+
+const combinable = couponsCombinable;
+
+/**
+ * 최대 가중 매칭(헝가리안, 행 = 쿠폰, 열 = 줄). `weights[i][j]`가 0이면 배정하지 않는 것과 같다.
+ * 결과는 행마다 열 번호 또는 -1이다. 크기는 보유 쿠폰 × 주문서 줄이라 작다.
+ */
+export function maxWeightAssignment(weights: readonly (readonly number[])[]): number[] {
+  const rows = weights.length;
+  const cols = rows ? Math.max(...weights.map((r) => r.length)) : 0;
+  if (!rows || !cols) return Array.from({ length: rows }, () => -1);
+  const n = Math.max(rows, cols);
+  const max = Math.max(0, ...weights.flat());
+  // 비용 = max − 가중치(정사각 행렬로 채운다). 1부터 세는 고전 구현
+  const cost = (i: number, j: number) => max - (weights[i]?.[j] ?? 0);
+  const u = new Array<number>(n + 1).fill(0);
+  const v = new Array<number>(n + 1).fill(0);
+  const p = new Array<number>(n + 1).fill(0);
+  const way = new Array<number>(n + 1).fill(0);
+  for (let i = 1; i <= n; i++) {
+    p[0] = i;
+    let j0 = 0;
+    const minv = new Array<number>(n + 1).fill(Number.POSITIVE_INFINITY);
+    const used = new Array<boolean>(n + 1).fill(false);
+    do {
+      used[j0] = true;
+      const i0 = p[j0] as number;
+      let delta = Number.POSITIVE_INFINITY;
+      let j1 = 0;
+      for (let j = 1; j <= n; j++) {
+        if (used[j]) continue;
+        const cur = cost(i0 - 1, j - 1) - (u[i0] as number) - (v[j] as number);
+        if (cur < (minv[j] as number)) {
+          minv[j] = cur;
+          way[j] = j0;
+        }
+        if ((minv[j] as number) < delta) {
+          delta = minv[j] as number;
+          j1 = j;
+        }
+      }
+      for (let j = 0; j <= n; j++) {
+        if (used[j]) {
+          u[p[j] as number] = (u[p[j] as number] as number) + delta;
+          v[j] = (v[j] as number) - delta;
+        } else {
+          minv[j] = (minv[j] as number) - delta;
+        }
+      }
+      j0 = j1;
+    } while (p[j0] !== 0);
+    do {
+      const j1 = way[j0] as number;
+      p[j0] = p[j1] as number;
+      j0 = j1;
+    } while (j0 !== 0);
+  }
+  const assignment = Array.from({ length: rows }, () => -1);
+  for (let j = 1; j <= n; j++) {
+    const i = (p[j] as number) - 1;
+    if (i >= 0 && i < rows && j - 1 < cols && (weights[i]?.[j - 1] ?? 0) > 0) assignment[i] = j - 1;
+  }
+  return assignment;
+}
+
+export function bestCouponSelection(input: CouponSelectionInput): CouponSelection {
+  const rules = input.moneyRules ?? KRW_MONEY_RULES;
+  const base: Omit<PricingInput, "coupons"> = { ...input, points: null };
+  const price = (coupons: PricingCoupon[]) => quotePricing({ ...base, coupons });
+
+  // 1) 혼자서도 적용되는 후보 — 먼저 끝나는 쿠폰, 쿠폰 키 순으로 줄 세워 결과가 결정적이다
+  const ordered: Candidate[] = input.candidates
+    .map((coupon) => ({
+      coupon: { ...coupon, lineId: null },
+      key: keyOf(coupon),
+      until: untilOf(coupon),
+    }))
+    .sort((a, b) => a.until - b.until || (a.key < b.key ? -1 : a.key > b.key ? 1 : 0));
+  const solo = ordered
+    .map((candidate) => ({ candidate, result: price([candidate.coupon]).coupons[0] }))
+    .filter((entry) => entry.result?.applied);
+
+  const products = solo.filter((e) => e.candidate.coupon.rule.kind === "PRODUCT");
+  const orders = solo.filter((e) => e.candidate.coupon.rule.kind === "ORDER");
+  const deliveries = solo.filter((e) => e.candidate.coupon.rule.kind === "DELIVERY");
+  const lineIds = input.lines.map((line) => line.lineId);
+  const lineAmount = new Map(input.lines.map((line) => [line.lineId, line.amount]));
+
+  /** 상품 쿠폰 한 장의 줄별 할인 — 대상 줄만, 줄 금액 기준 */
+  const weightsOf = (entry: (typeof products)[number]) => {
+    const eligible = new Set(entry.result?.eligibleLineIds ?? []);
+    return lineIds.map((id) =>
+      eligible.has(id)
+        ? couponDiscountOf(entry.candidate.coupon.rule.benefit, lineAmount.get(id) ?? 0, rules)
+        : 0,
+    );
+  };
+
+  /** 같은 쿠폰 정의는 `perOrderLimit` 장까지만 후보로 둔다(사본끼리는 규칙이 같아 앞 장이면 된다) */
+  const withinLimit = (entries: typeof products) => {
+    const seen = new Map<string, number>();
+    return entries.filter((entry) => {
+      const rule = entry.candidate.coupon.rule;
+      const count = seen.get(rule.couponId) ?? 0;
+      if (count >= couponStackingOf(rule).perOrderLimit) return false;
+      seen.set(rule.couponId, count + 1);
+      return true;
+    });
+  };
+
+  const planCache = new Map<string, PricingCoupon[][]>();
+  /** 상품 쿠폰 배정안 — 함께 쓰는 쿠폰들의 최대 매칭 하나 + 혼자 쓰는 쿠폰마다 하나 */
+  const productPlans = (allowed: typeof products): PricingCoupon[][] => {
+    const signature = allowed.map((e) => e.candidate.key).join("\n");
+    const cached = planCache.get(signature);
+    if (cached) return cached;
+    const plans: PricingCoupon[][] = [];
+    const sociable = withinLimit(
+      allowed.filter((e) => couponStackingOf(e.candidate.coupon.rule).combinesWith.product),
+    );
+    const assignment = maxWeightAssignment(sociable.map(weightsOf));
+    plans.push(
+      sociable.flatMap((entry, i) => {
+        const col = assignment[i] ?? -1;
+        return col >= 0 ? [{ ...entry.candidate.coupon, lineId: lineIds[col] ?? null }] : [];
+      }),
+    );
+    for (const entry of allowed) {
+      if (couponStackingOf(entry.candidate.coupon.rule).combinesWith.product) continue;
+      const weights = weightsOf(entry);
+      const best = weights.reduce((bi, w, i) => (w > (weights[bi] ?? 0) ? i : bi), 0);
+      if ((weights[best] ?? 0) > 0)
+        plans.push([{ ...entry.candidate.coupon, lineId: lineIds[best] ?? null }]);
+    }
+    planCache.set(signature, plans);
+    return plans;
+  };
+
+  type Scored = {
+    coupons: PricingCoupon[];
+    result: PricingResult;
+    discount: number;
+    /** 동률 비교 — 쿠폰마다 (끝나는 시각, 키)를 오름차순으로 */
+    tie: [number, string][];
+  };
+  /** 동률 비교 — 먼저 끝나는 쿠폰을 쓰는 쪽이 앞선다(만료 없음은 가장 뒤). 숫자는 숫자로 비교한다 */
+  const tieLess = (a: [number, string][], b: [number, string][]) => {
+    for (let i = 0; i < Math.min(a.length, b.length); i++) {
+      const [ua, ka] = a[i] as [number, string];
+      const [ub, kb] = b[i] as [number, string];
+      if (ua !== ub) return ua < ub;
+      if (ka !== kb) return ka < kb;
+    }
+    return a.length < b.length;
+  };
+  let best: Scored | null = null;
+  const consider = (coupons: PricingCoupon[]) => {
+    const result = price(coupons);
+    if (!result.coupons.every((c) => c.applied)) return;
+    if (result.totalAmount > 0 && result.totalAmount < rules.minPayment) {
+      // 결제를 시작할 수 없는 금액 — 할인이 가장 작은 상품 쿠폰을 빼고 다시 본다
+      const productCoupons = result.coupons
+        .map((c, i) => ({ c, i }))
+        .filter(({ c }) => c.kind === "PRODUCT")
+        .sort((a, b) => a.c.discount - b.c.discount || b.i - a.i);
+      const drop = productCoupons[0];
+      if (drop) consider(coupons.filter((_, i) => i !== drop.i));
+      return;
+    }
+    const discount = result.couponDiscountAmount + result.deliveryDiscountAmount;
+    const tie = coupons
+      .map((c): [number, string] => [untilOf(c), keyOf(c)])
+      .sort((a, b) => a[0] - b[0] || (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0));
+    const current = best as Scored | null;
+    if (
+      !current ||
+      discount > current.discount ||
+      (discount === current.discount &&
+        (coupons.length < current.coupons.length ||
+          (coupons.length === current.coupons.length && tieLess(tie, current.tie))))
+    )
+      best = { coupons, result, discount, tie };
+  };
+
+  for (const order of [null, ...orders]) {
+    for (const delivery of [null, ...deliveries]) {
+      const o = order?.candidate.coupon ?? null;
+      const d = delivery?.candidate.coupon ?? null;
+      if (o && d && !combinable(o, d)) continue;
+      const allowed = products.filter(
+        (e) =>
+          (!o || combinable(e.candidate.coupon, o)) && (!d || combinable(e.candidate.coupon, d)),
+      );
+      for (const plan of productPlans(allowed)) {
+        consider([...plan, ...(o ? [o] : []), ...(d ? [d] : [])]);
+      }
+    }
+  }
+
+  const chosen = best as Scored | null;
+  if (!chosen) {
+    const result = price([]);
+    return { coupons: [], result, discountAmount: 0, withPoints: true };
+  }
+  return {
+    coupons: chosen.coupons,
+    result: chosen.result,
+    discountAmount: chosen.discount,
+    withPoints: chosen.coupons.every((c) => couponStackingOf(c.rule).withPoints),
+  };
+}

package/src/schemas/coupon.ts

@@ -1,5 +1,14 @@
 import * as z from "zod";
 import { pageQueryShape } from "./common";
+import {
+  COUPON_STACKING_DEFAULTS,
+  type CouponRuleTrees,
+  couponConditionTreeSchema,
+  couponRuleIssues,
+  couponRulesFromLegacy,
+  couponStackingSchema,
+  couponTargetRulesSchema,
+} from "./coupon-rules";
 import { currencyCodeSchema } from "./currency";
 import {
   COUPON_CONDITIONS_DEFAULTS,
@@ -65,8 +74,131 @@ const descriptions = {
     "1인 발급 수 한도(셀러 지급·다운로드). 생략하면 1인 1장. 회원가입 쿠폰은 1장 고정이라 1만 받는다",
   perMemberUseLimit:
     "1인 사용 수 한도(코드 입력형). 생략하면 무제한. 비회원에게 여는 쿠폰은 둘 수 없다",
+  eligibility:
+    "사용 조건 트리(이슈 #222) — `{ combinator: and|or, rules: [{ field, operator, value } | 그룹] }`, 그룹 3단·규칙 50개까지. " +
+    "주면 `conditions`의 최소 주문 금액·첫 구매를 쓰지 않는다(`conditions`에는 `memberOnly`만 둔다). 필드 목록은 `COUPON_CONDITION_FIELDS`",
+  targetRules:
+    "할인 대상 규칙(이슈 #222) — `include`(하나라도 맞으면 대상, 비면 전 상품)·`exclude`(하나라도 맞으면 제외, 포함보다 우선). " +
+    "주면 `target`과 `conditions.stackWithInstantDiscount`를 쓰지 않는다(즉시할인 제외는 `line.hasInstantDiscount` 규칙)",
+  audience:
+    "발급 대상 트리(이슈 #222) — 셀러 지급·받기·회원가입 지급에서 누가 받을 수 있는가. 구매자 조건만. 코드 입력형에는 두지 않는다",
+  stacking:
+    "중복 사용 정책(이슈 #222). 생략하면 종류별 한 장·서로 결합·적립금과 함께. 결합은 양쪽 쿠폰이 모두 허용해야 성립한다",
+  issueStartsAt: "받기 시작 시각(받기 쿠폰만, 이슈 #222). 생략하면 사용 시작 시각을 따른다",
+  issueEndsAt:
+    "받기 종료 시각(받기 쿠폰만, 이 시각부터 못 받는다). 생략하면 사용 종료 시각을 따른다",
+  visibleFrom:
+    "쿠폰 목록 노출 시작(받기 쿠폰만). 이 시각부터 받기 시작 전까지 목록에 보이고 받기는 「시작 전」이다. 생략하면 받기 시작부터 보인다",
 } as const;
 
+/** 조건 트리 칸 — 생성·수정 요청이 같이 쓴다 */
+const ruleFields = {
+  eligibility: couponConditionTreeSchema.optional().describe(descriptions.eligibility),
+  targetRules: couponTargetRulesSchema.optional().describe(descriptions.targetRules),
+  audience: couponConditionTreeSchema.optional().describe(descriptions.audience),
+  stacking: couponStackingSchema.optional().describe(descriptions.stacking),
+};
+
+/**
+ * 트리와 옛 칸을 한 번에 검사한다 — 트리를 주면 그 트리, 아니면 옛 칸에서 만든 트리로 같은 규칙을 본다(검증 원천 `couponRuleIssues`).
+ * 생성 요청과 수정 뒤 합친 결과(`CouponsService.update`)가 이 함수를 지난다.
+ */
+export function couponRequestRuleIssues(body: {
+  kind?: string;
+  issueMethod: string;
+  conditions?: Partial<{
+    minOrderAmount: number;
+    firstOrderOnly: boolean;
+    memberOnly: boolean;
+    stackWithInstantDiscount: boolean;
+  }>;
+  target?: Partial<
+    Record<
+      "includeProductIds" | "includeCategoryIds" | "excludeProductIds" | "excludeCategoryIds",
+      string[]
+    >
+  >;
+  eligibility?: CouponRuleTrees["eligibility"];
+  targetRules?: CouponRuleTrees["targetRules"];
+  audience?: CouponRuleTrees["eligibility"];
+  stacking?: { perOrderLimit: number };
+  perMemberUseLimit?: number | null;
+  issueStartsAt?: string | null;
+  issueEndsAt?: string | null;
+  visibleFrom?: string | null;
+  endsAt?: string | null;
+}): { path: (string | number)[]; message: string }[] {
+  const issues: { path: (string | number)[]; message: string }[] = [];
+  const conditions = { ...COUPON_CONDITIONS_DEFAULTS, ...(body.conditions ?? {}) };
+  if (
+    body.eligibility &&
+    (body.conditions?.minOrderAmount !== undefined || body.conditions?.firstOrderOnly !== undefined)
+  )
+    issues.push({
+      path: ["conditions"],
+      message: "사용 조건 트리를 주면 최소 주문 금액·첫 구매는 트리로 둡니다",
+    });
+  if (body.targetRules && (body.target || body.conditions?.stackWithInstantDiscount !== undefined))
+    issues.push({
+      path: ["target"],
+      message: "할인 대상 규칙을 주면 대상 상품·즉시할인 제외는 규칙으로 둡니다",
+    });
+  const legacy = couponRulesFromLegacy(conditions, {
+    includeProductIds: body.target?.includeProductIds ?? [],
+    includeCategoryIds: body.target?.includeCategoryIds ?? [],
+    excludeProductIds: body.target?.excludeProductIds ?? [],
+    excludeCategoryIds: body.target?.excludeCategoryIds ?? [],
+  });
+  issues.push(
+    ...couponRuleIssues({
+      memberOnly: conditions.memberOnly,
+      issueMethod: body.issueMethod,
+      perMemberUseLimit: body.perMemberUseLimit ?? null,
+      eligibility: body.eligibility ?? legacy.eligibility,
+      targetRules: body.targetRules ?? legacy.targetRules,
+      ...(body.audience ? { audience: body.audience } : {}),
+    }),
+  );
+  if (body.stacking && body.stacking.perOrderLimit > 1 && body.kind !== "PRODUCT")
+    issues.push({
+      path: ["stacking", "perOrderLimit"],
+      message: "한 주문에 두 장 이상은 상품 쿠폰만 쓸 수 있습니다",
+    });
+  if (
+    body.issueMethod !== "DOWNLOAD" &&
+    (body.issueStartsAt != null || body.issueEndsAt != null || body.visibleFrom != null)
+  )
+    issues.push({
+      path: ["issueStartsAt"],
+      message: "받기 기간·노출 시작은 받기 쿠폰에만 둡니다",
+    });
+  if (
+    body.issueStartsAt &&
+    body.issueEndsAt &&
+    Date.parse(body.issueEndsAt) <= Date.parse(body.issueStartsAt)
+  )
+    issues.push({
+      path: ["issueEndsAt"],
+      message: "받기 종료 시각은 받기 시작 시각보다 뒤여야 합니다",
+    });
+  // 받기 기간은 사용 기간 안이다 — 넘으면 받는 순간 유효 기간이 지난 쿠폰을 준다
+  if (body.endsAt && body.issueEndsAt && Date.parse(body.issueEndsAt) > Date.parse(body.endsAt))
+    issues.push({
+      path: ["issueEndsAt"],
+      message: "받기 종료 시각은 사용 종료 시각보다 늦을 수 없습니다",
+    });
+  if (
+    body.endsAt &&
+    body.issueStartsAt &&
+    Date.parse(body.issueStartsAt) >= Date.parse(body.endsAt)
+  )
+    issues.push({
+      path: ["issueStartsAt"],
+      message: "받기 시작 시각은 사용 종료 시각보다 앞이어야 합니다",
+    });
+  return issues;
+}
+
 /** 조건 입력 — 생략한 항목은 기본값(`COUPON_CONDITIONS_DEFAULTS`)이다 */
 export const couponConditionsInputSchema = z.strictObject({
   minOrderAmount: z.number().int().min(0).optional(),
@@ -119,6 +251,10 @@ export const createCouponRequestSchema = strictRequest(
         .describe(
           "쿠폰 통화(이슈 #130). 정액·최대 할인액·최소 주문 금액이 이 통화 값이고 같은 통화 주문서에만 적용된다. 생략하면 기본 통화(KRW). 판매 통화여야 하고 만든 뒤에는 바꿀 수 없다",
         ),
+      ...ruleFields,
+      issueStartsAt: couponTimeField(descriptions.issueStartsAt),
+      issueEndsAt: couponTimeField(descriptions.issueEndsAt),
+      visibleFrom: couponTimeField(descriptions.visibleFrom),
     })
     .superRefine((body, ctx) => {
       const issue = (path: string, message: string) =>
@@ -156,6 +292,9 @@ export const createCouponRequestSchema = strictRequest(
       if (body.startsAt && body.endsAt && Date.parse(body.endsAt) <= Date.parse(body.startsAt)) {
         issue("endsAt", "종료 시각은 시작 시각보다 뒤여야 합니다");
       }
+      for (const found of couponRequestRuleIssues(body)) {
+        ctx.addIssue({ code: "custom", path: found.path, message: found.message });
+      }
     }),
 );
 export type CreateCouponRequest = z.infer<typeof createCouponRequestSchema>;
@@ -179,6 +318,10 @@ export const updateCouponRequestSchema = strictRequest(
     totalUseLimit: limitField(descriptions.totalUseLimit),
     perMemberIssueLimit: limitField(descriptions.perMemberIssueLimit),
     perMemberUseLimit: limitField(descriptions.perMemberUseLimit),
+    ...ruleFields,
+    issueStartsAt: couponTimeField(descriptions.issueStartsAt),
+    issueEndsAt: couponTimeField(descriptions.issueEndsAt),
+    visibleFrom: couponTimeField(descriptions.visibleFrom),
   }),
 );
 export type UpdateCouponRequest = z.infer<typeof updateCouponRequestSchema>;
@@ -218,6 +361,38 @@ export const couponSchema = z.object({
     .describe(
       "쿠폰 통화(이슈 #130). 금액 필드는 이 통화의 최소 단위다. 옛 서버 응답은 KRW로 읽는다",
     ),
+  eligibility: couponConditionTreeSchema
+    .optional()
+    .describe(
+      "사용 조건 트리(이슈 #222). 옛 쿠폰은 `conditions`에서 만든 트리다. 서버는 항상 싣는다",
+    ),
+  targetRules: couponTargetRulesSchema
+    .optional()
+    .describe(
+      "할인 대상 규칙(이슈 #222). 옛 쿠폰은 `target`에서 만든 규칙이다. 서버는 항상 싣는다",
+    ),
+  audience: couponConditionTreeSchema
+    .optional()
+    .describe("발급 대상 트리(이슈 #222). 없으면 빈 트리(모두 대상). 서버는 항상 싣는다"),
+  stacking: couponStackingSchema
+    .optional()
+    .default(COUPON_STACKING_DEFAULTS)
+    .describe("중복 사용 정책(이슈 #222). 서버는 항상 싣는다"),
+  rulesOnly: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      "트리로만 표현되는 규칙이 있는가(이슈 #222). true면 `conditions`·`target`은 가장 가까운 옛 값이고 원천은 트리다",
+    ),
+  issueStartsAt: z
+    .string()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe(descriptions.issueStartsAt),
+  issueEndsAt: z.string().nullable().optional().default(null).describe(descriptions.issueEndsAt),
+  visibleFrom: z.string().nullable().optional().default(null).describe(descriptions.visibleFrom),
   status: couponStatusSchema,
   locked: z.boolean().describe("발급·사용이 시작돼 혜택·조건·대상·사용 시작일을 바꿀 수 없는가"),
   lockedAt: z.string().nullable(),
@@ -288,7 +463,7 @@ export const issueCouponResultSchema = z.object({
         .string()
         .describe(
           "실패 사유. `CUSTOMER_NOT_FOUND`(이 상점 구매자가 아님)·`COUPON_LIMIT_REACHED`(1인 발급 한도)·" +
-            "`COUPON_EXHAUSTED`(총 발급 한도)",
+            "`COUPON_EXHAUSTED`(총 발급 한도)·`AUDIENCE_NOT_MATCHED`(발급 대상 조건에 맞지 않음, 이슈 #222)",
         ),
       message: z.string(),
     }),

package/src/schemas/order.ts

@@ -1,7 +1,13 @@
 import * as z from "zod";
 import { sellerCheckoutSchema } from "./checkout";
 import { commerceNumberField } from "./commerce-number";
-import { changeTypeSchema, orderItemStatusSchema, type PageParams, pageSchema } from "./common";
+import {
+  changeTypeSchema,
+  type OrderItemStatus,
+  orderItemStatusSchema,
+  type PageParams,
+  pageSchema,
+} from "./common";
 import { orderItemFulfillmentSnapshotResponseSchema } from "./fulfillment";
 import { cashReceiptSchema, easyPayProviderResponseSchema } from "./payment";
 import { customInputValueSchema, optionSelectionSchema } from "./product";
@@ -473,6 +479,67 @@ export const deliveryInfoSchema = z.object({
 
 export type DeliveryInfo = z.infer<typeof deliveryInfoSchema>;
 
+/**
+ * 배송 주문상품 한 줄 — `GET /v1/order-items/shipping`(이슈 #208·#209). 발송 작업용으로 주문상품에 주문번호·주문자·배송지·발송 정보를 붙였다.
+ * 배송지가 필요한 줄(택배·직접 배달)만 나온다
+ */
+export const shippingOrderItemSchema = orderItemSchema.extend({
+  orderNo: z.string().nullable().describe("주문번호(숫자 14자리). 이 필드 이전 주문은 null"),
+  ordererName: z.string(),
+  ordererPhone: z.string(),
+  shippingAddress: shippingAddressSchema,
+  delivery: deliveryInfoSchema.nullable().describe("발송 정보. 발송 전이면 null"),
+});
+
+export type ShippingOrderItem = z.infer<typeof shippingOrderItemSchema>;
+
+export const shippingOrderItemPageSchema = pageSchema(shippingOrderItemSchema);
+export type ShippingOrderItemPage = z.infer<typeof shippingOrderItemPageSchema>;
+
+/**
+ * `GET /v1/order-items/shipping` 쿼리 — OpenAPI 문서용 형태. `orderedFrom` 누락 400 `MISSING_PARAMETER`, 형식 오류 400
+ * `INVALID_PARAMETER`, 366일 초과 400 `RANGE_TOO_WIDE`, `testPayment` 값 오류 400 `INVALID_PARAMETER`
+ */
+export const shippingOrderItemListQuerySchema = z.object({
+  orderedFrom: z
+    .string()
+    .optional()
+    .describe("주문 시각 조회 시작 (ISO 8601 날짜 또는 일시, 포함). `orderItemNos`가 없으면 필수"),
+  orderedTo: z
+    .string()
+    .optional()
+    .describe(
+      "주문 시각 조회 끝 (ISO 8601, 포함). 생략하면 orderedFrom부터 31일. 기간은 최대 366일",
+    ),
+  status: z
+    .string()
+    .optional()
+    .describe("주문상품 상태 필터. 쉼표로 여러 상태를 받는다(예: `PAID,CONFIRMED`)"),
+  orderItemNos: z
+    .string()
+    .optional()
+    .describe("상품주문번호(하이픈 허용)를 쉼표로 이어 최대 100개. 이 번호의 주문상품만 조회한다"),
+  keyword: z
+    .string()
+    .optional()
+    .describe("주문번호·상품주문번호(일치, 하이픈 허용)·주문자명·수령인명·상품명(포함) 검색"),
+  testPayment: testPaymentQuery,
+  ...pageQuery,
+  size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)"),
+});
+
+export type ShippingOrderItemListParams = PageParams & {
+  orderedTo?: string;
+  /** 하나 또는 여러 상태 */
+  status?: OrderItemStatus | OrderItemStatus[];
+  keyword?: string;
+  /** 테스트 결제 필터 — `"true"` 테스트 결제 주문만, `"false"` 실결제만, 생략하면 전부 */
+  testPayment?: "true" | "false";
+} & (
+    | { orderedFrom: string; orderItemNos?: string[] }
+    | { orderedFrom?: string; orderItemNos: string[] }
+  );
+
 /**
  * 택배 추적 단계. 응답에서는 문자열로 받는다(값이 추가될 수 있다) — 현재 값은 `ACCEPTED`(접수)·`IN_TRANSIT`(이동 중)·
  * `OUT_FOR_DELIVERY`(배송 출발)·`DELIVERED`(배송완료)다.