@sayren/store-sdk 0.48.0 → 0.50.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,
@@ -61,12 +70,143 @@ const descriptions = {
   totalIssueLimit:
     "총 발급 수 한도. 생략하면 무제한. 다운로드·회원가입 쿠폰은 한도에 닿으면 더 발급하지 않는다",
   totalUseLimit: "총 사용 수 한도. 결제 중인 예약도 센다. 생략하면 무제한",
+  dailyIssueLimit:
+    "하루 발급 수 한도(이슈 #222) — 한국 시간 0시 기준 하루마다 이 장수까지 발급한다(받기·회원가입·셀러 지급). 생략하면 없다. 코드 입력형에는 두지 않는다",
   perMemberIssueLimit:
     "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;
+  dailyIssueLimit?: 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 === "CODE" && body.dailyIssueLimit != null)
+    issues.push({
+      path: ["dailyIssueLimit"],
+      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(),
@@ -111,6 +251,7 @@ export const createCouponRequestSchema = strictRequest(
         .optional()
         .describe(descriptions.validDaysAfterIssue),
       totalIssueLimit: limitField(descriptions.totalIssueLimit),
+      dailyIssueLimit: limitField(descriptions.dailyIssueLimit),
       totalUseLimit: limitField(descriptions.totalUseLimit),
       perMemberIssueLimit: limitField(descriptions.perMemberIssueLimit),
       perMemberUseLimit: limitField(descriptions.perMemberUseLimit),
@@ -119,6 +260,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 +301,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>;
@@ -176,9 +324,14 @@ export const updateCouponRequestSchema = strictRequest(
     endsAt: couponTimeField(descriptions.endsAt),
     validDaysAfterIssue: z.number().int().min(1).max(3650).nullable().optional(),
     totalIssueLimit: limitField(descriptions.totalIssueLimit),
+    dailyIssueLimit: limitField(descriptions.dailyIssueLimit),
     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>;
@@ -202,6 +355,13 @@ export const couponSchema = z.object({
   endsAt: z.string().nullable(),
   validDaysAfterIssue: z.number().int().nullable(),
   totalIssueLimit: z.number().int().nullable(),
+  dailyIssueLimit: z
+    .number()
+    .int()
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("하루 발급 수 한도(한국 시간 0시 기준). 없으면 null. 서버는 항상 싣는다"),
   totalUseLimit: z.number().int().nullable(),
   perMemberIssueLimit: z.number().int().nullable(),
   perMemberUseLimit: z.number().int().nullable(),
@@ -218,6 +378,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 +480,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/product-import.ts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+import {
+  productCreateRequestSchema,
+  productReplaceRequestSchema,
+  productStatusSchema,
+} from "./product";
+import { strictRequest } from "./strict";
+
+/**
+ * 상품 일괄 반영(이슈 #211) — 엑셀로 만든 상품 등록·전체 수정을 작업 하나로 반영한다.
+ * 작업을 만들고(`DRAFT`) 항목을 나눠 붙인 뒤 시작하면(202) 서버가 트랜잭션 하나로 처리한다.
+ * **항목 하나라도 실패하면 아무것도 반영하지 않는다.** 상점 플랫폼 전용 표면이다.
+ */
+
+/** 작업 하나의 항목 수 상한 — 쓰기 트랜잭션 하나에 담기는 양을 묶는 방어선이다 */
+export const MAX_PRODUCT_IMPORT_ITEMS = 1000;
+
+/** 항목 붙이기 한 번의 항목 수 상한 */
+export const MAX_PRODUCT_IMPORT_ITEMS_PER_REQUEST = 100;
+
+export const productImportStatusSchema = z.enum([
+  "DRAFT",
+  "QUEUED",
+  "RUNNING",
+  "SUCCEEDED",
+  "FAILED",
+]);
+
+export type ProductImportStatus = z.infer<typeof productImportStatusSchema>;
+
+const itemKeySchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(100)
+  .describe(
+    "항목 키 — 호출자가 정한다(엑셀의 상품 키 등). 오류·결과를 이 키로 돌려준다. 작업 안에서 유일하다",
+  );
+
+export const productImportItemSchema = z.discriminatedUnion("action", [
+  z.object({
+    key: itemKeySchema,
+    action: z.literal("CREATE"),
+    product: productCreateRequestSchema,
+    status: productStatusSchema.optional().describe("판매 상태. 생략하면 판매중(`SALE`)"),
+  }),
+  z.object({
+    key: itemKeySchema,
+    action: z.literal("UPDATE"),
+    productId: z.string().min(1),
+    expectedUpdatedAt: z
+      .string()
+      .min(1)
+      .describe("내려받을 때의 상품 `updatedAt`. 그 뒤 상품이 바뀌었으면 409 `PRODUCT_CHANGED`"),
+    product: productReplaceRequestSchema.describe(
+      "전체 수정(`PUT /v1/products/{productId}`)과 같은 본문",
+    ),
+    status: productStatusSchema.optional().describe("판매 상태. 생략하면 바꾸지 않는다"),
+    expectedStock: z
+      .record(z.string().min(1), z.number().int().min(0))
+      .optional()
+      .describe(
+        "재고를 바꾸는 조합의 내려받을 때 재고(조합 id → 수량). 반영 시점 재고가 다르면 409 `STOCK_CHANGED`. " +
+          "`product.variants[].stockQuantity`를 준 기존 조합마다 하나씩 있어야 하고 다른 조합은 넣지 않는다(400 `PRODUCT_IMPORT_STOCK_EXPECTATION_MISMATCH`)",
+      ),
+  }),
+]);
+
+export type ProductImportItem = z.infer<typeof productImportItemSchema>;
+export type ProductImportItemInput = z.input<typeof productImportItemSchema>;
+
+export const productImportItemsRequestSchema = strictRequest(
+  z.object({
+    items: z.array(productImportItemSchema).min(1).max(MAX_PRODUCT_IMPORT_ITEMS_PER_REQUEST),
+  }),
+);
+
+export type ProductImportItemsRequest = z.infer<typeof productImportItemsRequestSchema>;
+
+/** 상품 상세 묶음 조회 한 번의 상한(id·상품번호 합) */
+export const MAX_PRODUCT_LOOKUP = 100;
+
+/** 상품 상세 묶음 조회 — 엑셀 내려받기와 올린 파일 대조가 쓴다. 이 상점에 없는 값은 결과에서 빠진다 */
+export const productLookupRequestSchema = strictRequest(
+  z
+    .object({
+      productIds: z.array(z.string().min(1)).max(MAX_PRODUCT_LOOKUP).optional(),
+      productNos: z.array(z.number().int().positive()).max(MAX_PRODUCT_LOOKUP).optional(),
+    })
+    .refine(
+      (value) =>
+        (value.productIds?.length ?? 0) + (value.productNos?.length ?? 0) <= MAX_PRODUCT_LOOKUP,
+      { message: `상품 id·상품번호는 합쳐 ${MAX_PRODUCT_LOOKUP}개까지입니다` },
+    ),
+);
+
+export type ProductLookupRequest = z.infer<typeof productLookupRequestSchema>;
+
+export const productImportErrorSchema = z.object({
+  key: z.string(),
+  code: z.string(),
+  message: z.string(),
+  fieldErrors: z
+    .array(z.object({ field: z.string(), code: z.string(), message: z.string() }))
+    .optional()
+    .describe("요청 본문 경로별 오류(항목의 `product` 기준). 없으면 생략"),
+});
+
+export type ProductImportError = z.infer<typeof productImportErrorSchema>;
+
+export const productImportSchema = z.object({
+  importId: z.string(),
+  status: z
+    .string()
+    .describe("`DRAFT`·`QUEUED`·`RUNNING`·`SUCCEEDED`·`FAILED`. 값이 늘 수 있어 문자열이다"),
+  itemCount: z.number().int(),
+  errors: z
+    .array(productImportErrorSchema)
+    .describe("`FAILED`의 항목별 오류. 하나라도 있으면 아무것도 반영하지 않았다"),
+  results: z
+    .array(
+      z.object({
+        key: z.string(),
+        action: z.string().describe("`CREATE`·`UPDATE`"),
+        productId: z.string(),
+      }),
+    )
+    .describe("`SUCCEEDED`의 항목별 결과"),
+  createdAt: z.string(),
+  startedAt: z.string().nullable(),
+  finishedAt: z.string().nullable(),
+});
+
+export type ProductImport = z.infer<typeof productImportSchema>;