@sayren/store-sdk 0.47.0 → 0.49.0

package/src/schemas/coupon-rules.ts

@@ -0,0 +1,849 @@
+import * as z from "zod";
+import {
+  anyConditionHolds,
+  type ConditionCatalog,
+  type ConditionFieldDef,
+  type ConditionGroup,
+  type ConditionIssue,
+  type ConditionNode,
+  type ConditionRule,
+  type ConditionValue,
+  type ConditionValueType,
+  canonicalizeConditionGroup,
+  canonicalizeConditionRule,
+  conditionCatalog,
+  conditionFields,
+  conditionGroupSchema,
+  conditionIssues,
+  conditionRuleSchema,
+  evaluateCondition,
+  isConditionGroup,
+} from "./condition-tree";
+
+/**
+ * 쿠폰 조건 규칙 (이슈 #222) — 범용 조건 트리(`condition-tree.ts`)를 쿠폰에 쓰는 자리다.
+ *
+ * 쿠폰은 세 트리를 갖는다.
+ * - `eligibility`(사용 조건): 구매자·주문서·시각. 그룹 중첩 3단까지
+ * - `targetRules`(할인 대상): 줄 단위. `{ include, exclude }` 고정 형태 — 포함은 하나라도 맞으면 대상(비면 전 상품), 제외는 하나라도 맞으면 빠지고 포함보다 우선
+ * - `audience`(발급 대상): 누가 받을 수 있는가. 구매자 사실 값만
+ *
+ * 기간·한도·혜택·`memberOnly`·중복 정책은 트리 밖 칸이다. 옛 칸(`conditions`·`target`)은 프리셋 변환(`couponRulesFromLegacy`)으로 같은 트리가 된다 —
+ * 계산은 늘 트리 한 경로다.
+ */
+
+// ─── 사실 값 ──────────────────────────────────────────
+
+/** 요일 — 판정 시각의 Asia/Seoul 달력 요일 */
+export const COUPON_WEEKDAYS = ["MON", "TUE", "WED", "THU", "FRI", "SAT", "SUN"] as const;
+export type CouponWeekday = (typeof COUPON_WEEKDAYS)[number];
+
+/** 쿠폰 조건의 시각 기준 — 상점 시간대 칸이 없어 flow-spec 달력과 같은 Asia/Seoul로 고정한다 */
+export const COUPON_TIME_ZONE = "Asia/Seoul";
+
+/**
+ * 구매자 사실 값 — 평가 시점에 서버가 읽어 넣는다. 결제 시작에서 쓴 값은 주문 스냅샷에 굳혀 환불 정산이 그대로 다시 쓴다.
+ * 모르는 값은 생략한다(그 값을 쓰는 규칙은 거짓).
+ */
+export interface CouponCustomerFacts {
+  /** 가입 뒤 지난 날 수(내림) */
+  daysSinceJoined?: number;
+  marketingAgreed?: boolean;
+  /** 이 상점의 결제 완료 주문 수(취소 포함) */
+  paidOrderCount?: number;
+  /** 마지막 주문 뒤 지난 날 수(내림). 주문이 없으면 생략 */
+  daysSinceLastOrder?: number;
+}
+
+export interface CouponTimeFacts {
+  weekday: CouponWeekday;
+  /** `HH:MM` */
+  timeOfDay: string;
+}
+
+export interface CouponFacts {
+  customer?: CouponCustomerFacts;
+  time?: CouponTimeFacts;
+}
+
+export const couponFactsSchema = z.object({
+  customer: z
+    .object({
+      daysSinceJoined: z.number().int().optional(),
+      marketingAgreed: z.boolean().optional(),
+      paidOrderCount: z.number().int().optional(),
+      daysSinceLastOrder: z.number().int().optional(),
+    })
+    .optional(),
+  time: z.object({ weekday: z.enum(COUPON_WEEKDAYS), timeOfDay: z.string() }).optional(),
+});
+
+const SEOUL = new Intl.DateTimeFormat("en-US", {
+  timeZone: COUPON_TIME_ZONE,
+  weekday: "short",
+  hour: "2-digit",
+  minute: "2-digit",
+  hourCycle: "h23",
+});
+const WEEKDAY_OF: Record<string, CouponWeekday> = {
+  Mon: "MON",
+  Tue: "TUE",
+  Wed: "WED",
+  Thu: "THU",
+  Fri: "FRI",
+  Sat: "SAT",
+  Sun: "SUN",
+};
+
+/** 판정 시각의 요일·시각(Asia/Seoul) */
+export function couponTimeFactsAt(now: Date): CouponTimeFacts {
+  const parts = Object.fromEntries(SEOUL.formatToParts(now).map((p) => [p.type, p.value]));
+  return {
+    weekday: WEEKDAY_OF[parts.weekday ?? ""] ?? "MON",
+    timeOfDay: `${parts.hour ?? "00"}:${parts.minute ?? "00"}`,
+  };
+}
+
+/** 두 시각 사이의 지난 날 수(내림). 읽지 못하면 undefined */
+export function daysBetween(from: string | Date | null | undefined, to: Date): number | undefined {
+  if (!from) return undefined;
+  const start = typeof from === "string" ? Date.parse(from) : from.getTime();
+  if (Number.isNaN(start)) return undefined;
+  return Math.max(0, Math.floor((to.getTime() - start) / 86_400_000));
+}
+
+// ─── 평가 컨텍스트 ────────────────────────────────────
+
+/** 주문서 집계 — 즉시할인 반영, 쿠폰·적립금 전, 배송비 제외 */
+export interface CouponCartFacts {
+  /** 주문서 전체 줄 금액 합 */
+  subtotal: number;
+  /** 할인 대상 줄 금액 합(지금의 최소 주문 금액 기준) */
+  targetSubtotal: number;
+  /** 할인 대상 줄 수량 합 */
+  targetQuantity: number;
+}
+
+export interface CouponOrderContext {
+  facts: CouponFacts;
+  /** 발급 시점처럼 주문서가 없으면 생략 — 주문서 필드는 거짓이 된다 */
+  cart?: CouponCartFacts;
+}
+
+export interface CouponLineContext {
+  productId: string;
+  /** 상품 카테고리와 그 조상 id — 하위 카테고리 상품도 상위 카테고리 대상에 걸린다 */
+  categoryIds: readonly string[];
+  hasInstantDiscount: boolean;
+  /** 즉시할인 반영 단가 */
+  unitPrice: number;
+}
+
+/** 줄 금액에서 줄 컨텍스트를 만든다 — `categoryPath`는 `/조상/…/자신/` */
+export function couponLineContextOf(line: {
+  productId: string;
+  categoryPath?: string | null;
+  quantity: number;
+  baseAmount: number;
+  amount: number;
+}): CouponLineContext {
+  return {
+    productId: line.productId,
+    categoryIds: line.categoryPath ? line.categoryPath.split("/").filter(Boolean) : [],
+    hasInstantDiscount: line.amount < line.baseAmount,
+    unitPrice: line.quantity > 0 ? Math.floor(line.amount / line.quantity) : line.amount,
+  };
+}
+
+// ─── 필드 카탈로그 ────────────────────────────────────
+
+/** 트리 자리 */
+export type CouponConditionSlot = "audience" | "eligibility" | "target";
+
+/** 화면·문서용 필드 목록(직렬화 가능) — 상점 플랫폼 빌더가 이 목록으로 필드·연산자·값 편집기를 고른다 */
+export interface CouponConditionFieldInfo {
+  name: string;
+  type: ConditionValueType;
+  slots: readonly CouponConditionSlot[];
+  /** 값의 단위 — `money`면 쿠폰 통화 최소 단위 */
+  unit?: "day" | "count" | "money" | "quantity";
+  options?: readonly string[];
+}
+
+const MONEY_MAX = 1_000_000_000_000;
+const DAY_MAX = 36_500;
+const COUNT_MAX = 1_000_000;
+
+const ORDER_FIELDS: readonly (ConditionFieldDef<CouponOrderContext> &
+  Omit<CouponConditionFieldInfo, "type">)[] = [
+  {
+    name: "customer.daysSinceJoined",
+    type: "integer",
+    slots: ["audience", "eligibility"],
+    unit: "day",
+    min: 0,
+    max: DAY_MAX,
+    resolve: (ctx) => ctx.facts.customer?.daysSinceJoined,
+  },
+  {
+    name: "customer.marketingAgreed",
+    type: "boolean",
+    slots: ["audience", "eligibility"],
+    resolve: (ctx) => ctx.facts.customer?.marketingAgreed,
+  },
+  {
+    name: "customer.paidOrderCount",
+    type: "integer",
+    slots: ["audience", "eligibility"],
+    unit: "count",
+    min: 0,
+    max: COUNT_MAX,
+    resolve: (ctx) => ctx.facts.customer?.paidOrderCount,
+  },
+  {
+    name: "customer.daysSinceLastOrder",
+    type: "integer",
+    slots: ["audience", "eligibility"],
+    unit: "day",
+    min: 0,
+    max: DAY_MAX,
+    resolve: (ctx) => ctx.facts.customer?.daysSinceLastOrder,
+  },
+  {
+    name: "cart.subtotal",
+    type: "integer",
+    slots: ["eligibility"],
+    unit: "money",
+    operators: [">=", "<=", "between"],
+    min: 0,
+    max: MONEY_MAX,
+    resolve: (ctx) => ctx.cart?.subtotal,
+  },
+  {
+    name: "cart.targetSubtotal",
+    type: "integer",
+    slots: ["eligibility"],
+    unit: "money",
+    operators: [">=", "<=", "between"],
+    min: 0,
+    max: MONEY_MAX,
+    resolve: (ctx) => ctx.cart?.targetSubtotal,
+  },
+  {
+    name: "cart.targetQuantity",
+    type: "integer",
+    slots: ["eligibility"],
+    unit: "quantity",
+    operators: [">=", "<=", "between"],
+    min: 0,
+    max: COUNT_MAX,
+    resolve: (ctx) => ctx.cart?.targetQuantity,
+  },
+  {
+    name: "time.weekday",
+    type: "enumSet",
+    slots: ["eligibility"],
+    options: COUPON_WEEKDAYS,
+    resolve: (ctx) => ctx.facts.time?.weekday,
+  },
+  {
+    name: "time.timeOfDay",
+    type: "timeRange",
+    slots: ["eligibility"],
+    resolve: (ctx) => ctx.facts.time?.timeOfDay,
+  },
+];
+
+const LINE_FIELDS: readonly (ConditionFieldDef<CouponLineContext> &
+  Omit<CouponConditionFieldInfo, "type">)[] = [
+  { name: "line.productId", type: "idSet", slots: ["target"], resolve: (ctx) => ctx.productId },
+  {
+    name: "line.categoryId",
+    type: "idSet",
+    slots: ["target"],
+    resolve: (ctx) => ctx.categoryIds,
+  },
+  {
+    name: "line.hasInstantDiscount",
+    type: "boolean",
+    slots: ["target"],
+    resolve: (ctx) => ctx.hasInstantDiscount,
+  },
+  {
+    name: "line.unitPrice",
+    type: "integer",
+    slots: ["target"],
+    unit: "money",
+    operators: [">=", "<=", "between"],
+    min: 0,
+    max: MONEY_MAX,
+    resolve: (ctx) => ctx.unitPrice,
+  },
+];
+
+export const COUPON_ORDER_CONDITIONS: ConditionCatalog<CouponOrderContext> =
+  conditionCatalog(ORDER_FIELDS);
+export const COUPON_LINE_CONDITIONS: ConditionCatalog<CouponLineContext> =
+  conditionCatalog(LINE_FIELDS);
+
+export const COUPON_CONDITION_FIELDS: readonly CouponConditionFieldInfo[] = [
+  ...ORDER_FIELDS,
+  ...LINE_FIELDS,
+].map(({ name, type, slots, unit, options }) => ({
+  name,
+  type,
+  slots,
+  ...(unit ? { unit } : {}),
+  ...(options ? { options } : {}),
+}));
+
+const FIELD_INFO = new Map(COUPON_CONDITION_FIELDS.map((f) => [f.name, f]));
+
+// ─── 규칙 형식 ────────────────────────────────────────
+
+/** 할인 대상 — 포함·제외 규칙 목록(그룹 없음) */
+export const couponTargetRulesSchema = z.strictObject({
+  include: z
+    .array(conditionRuleSchema)
+    .max(50)
+    .describe("포함 규칙 — 하나라도 맞으면 대상. 비면 전 상품"),
+  exclude: z
+    .array(conditionRuleSchema)
+    .max(50)
+    .describe("제외 규칙 — 하나라도 맞으면 대상에서 빠진다. 포함보다 우선한다"),
+});
+export type CouponTargetRules = z.infer<typeof couponTargetRulesSchema>;
+
+export const COUPON_TARGET_RULES_ALL: CouponTargetRules = { include: [], exclude: [] };
+
+export const EMPTY_CONDITION_GROUP: ConditionGroup = { combinator: "and", rules: [] };
+
+/** 사용 조건·발급 대상 트리 */
+export const couponConditionTreeSchema = conditionGroupSchema;
+
+/** 중복 사용 정책 — 결합은 양쪽 쿠폰이 모두 허용해야 성립한다 */
+export const couponStackingSchema = z.strictObject({
+  combinesWith: z
+    .strictObject({
+      order: z.boolean().describe("주문 쿠폰과 함께 쓸 수 있다"),
+      product: z.boolean().describe("상품 쿠폰과 함께 쓸 수 있다(다른 상품 쿠폰 포함)"),
+      delivery: z.boolean().describe("배송비 쿠폰과 함께 쓸 수 있다"),
+    })
+    .describe("다른 종류 쿠폰과의 결합. 상대 쿠폰도 이 쿠폰의 종류를 허용해야 함께 적용된다"),
+  withPoints: z
+    .boolean()
+    .describe("적립금과 함께 쓸 수 있다. false인 쿠폰이 적용되면 적립금을 쓰지 않는다"),
+  perOrderLimit: z
+    .number()
+    .int()
+    .min(1)
+    .max(100)
+    .describe("한 주문에 쓸 수 있는 이 쿠폰의 장수. 2 이상은 상품 쿠폰만(발급 사본마다 다른 줄)"),
+});
+export type CouponStacking = z.infer<typeof couponStackingSchema>;
+
+/** 지금까지의 동작 — 종류별 한 장, 서로 결합, 적립금과 함께 */
+export const COUPON_STACKING_DEFAULTS: CouponStacking = {
+  combinesWith: { order: true, product: true, delivery: true },
+  withPoints: true,
+  perOrderLimit: 1,
+};
+
+export function canonicalizeCouponTargetRules(rules: CouponTargetRules): CouponTargetRules {
+  return {
+    include: rules.include.map(canonicalizeConditionRule),
+    exclude: rules.exclude.map(canonicalizeConditionRule),
+  };
+}
+
+export function canonicalizeCouponStacking(stacking: CouponStacking): CouponStacking {
+  return {
+    combinesWith: {
+      order: stacking.combinesWith.order,
+      product: stacking.combinesWith.product,
+      delivery: stacking.combinesWith.delivery,
+    },
+    withPoints: stacking.withPoints,
+    perOrderLimit: stacking.perOrderLimit,
+  };
+}
+
+// ─── 프리셋 변환(옛 칸 ⇄ 트리) ────────────────────────
+
+/** 옛 조건 칸 — `promotion.ts`의 `CouponConditions`와 같은 모양(순환 import를 피해 여기 둔다) */
+export interface LegacyCouponConditions {
+  minOrderAmount: number;
+  firstOrderOnly: boolean;
+  memberOnly: boolean;
+  stackWithInstantDiscount: boolean;
+}
+
+export interface LegacyCouponTarget {
+  includeProductIds: string[];
+  includeCategoryIds: string[];
+  excludeProductIds: string[];
+  excludeCategoryIds: string[];
+}
+
+export interface CouponRuleTrees {
+  eligibility: ConditionGroup;
+  targetRules: CouponTargetRules;
+}
+
+const inRule = (field: string, ids: readonly string[]): ConditionRule[] =>
+  ids.length ? [{ field, operator: "in", value: [...new Set(ids)].sort() }] : [];
+
+/**
+ * 옛 칸을 트리로 — 계산이 트리 한 경로를 지나게 하는 변환이다. 뜻이 같다:
+ * 최소 주문 금액 = 대상 상품 금액 이상, 첫 구매 = 결제 완료 주문 수 0, 즉시할인 중복 불가 = 즉시할인 줄 제외,
+ * 포함 목록이 모두 비면 전 상품, 제외가 포함보다 우선. `memberOnly`는 트리 밖이다.
+ */
+export function couponRulesFromLegacy(
+  conditions: LegacyCouponConditions,
+  target: LegacyCouponTarget,
+): CouponRuleTrees {
+  const eligibility: ConditionRule[] = [];
+  if (conditions.firstOrderOnly)
+    eligibility.push({ field: "customer.paidOrderCount", operator: "=", value: 0 });
+  if (conditions.minOrderAmount > 0)
+    eligibility.push({
+      field: "cart.targetSubtotal",
+      operator: ">=",
+      value: conditions.minOrderAmount,
+    });
+  return {
+    eligibility: { combinator: "and", rules: eligibility },
+    targetRules: {
+      include: [
+        ...inRule("line.productId", target.includeProductIds),
+        ...inRule("line.categoryId", target.includeCategoryIds),
+      ],
+      exclude: [
+        ...inRule("line.productId", target.excludeProductIds),
+        ...inRule("line.categoryId", target.excludeCategoryIds),
+        ...(conditions.stackWithInstantDiscount
+          ? []
+          : [{ field: "line.hasInstantDiscount", operator: "=", value: true }]),
+      ],
+    },
+  };
+}
+
+const isMinOrderRule = (node: ConditionNode): boolean =>
+  !isConditionGroup(node) &&
+  node.field === "cart.targetSubtotal" &&
+  node.operator === ">=" &&
+  typeof node.value === "number";
+
+const isFirstOrderRule = (node: ConditionNode): boolean =>
+  !isConditionGroup(node) &&
+  node.field === "customer.paidOrderCount" &&
+  node.operator === "=" &&
+  node.value === 0;
+
+const isInstantExcludeRule = (rule: ConditionRule) =>
+  rule.field === "line.hasInstantDiscount" && rule.operator === "=" && rule.value === true;
+
+const isIdRule = (rule: ConditionRule) =>
+  (rule.field === "line.productId" || rule.field === "line.categoryId") && rule.operator === "in";
+
+/**
+ * 트리를 옛 칸으로 — 옛 응답 필드(`conditions`·`target`)를 채우고 롤링 중 옛 코드가 읽게 한다.
+ * 옛 칸으로 표현되지 않는 규칙이 하나라도 있으면 `rulesOnly: true`다(옛 칸은 가장 가까운 값).
+ */
+export function legacyFromCouponRules(
+  trees: CouponRuleTrees,
+  memberOnly: boolean,
+): { conditions: LegacyCouponConditions; target: LegacyCouponTarget; rulesOnly: boolean } {
+  const top = trees.eligibility.combinator === "and" || trees.eligibility.rules.length <= 1;
+  const nodes = top ? trees.eligibility.rules : [];
+  const minRule = nodes.find(isMinOrderRule) as ConditionRule | undefined;
+  const firstRule = nodes.find(isFirstOrderRule) as ConditionRule | undefined;
+  const ids = (rules: readonly ConditionRule[], field: string) =>
+    [
+      ...new Set(
+        rules
+          .filter((r) => r.field === field && r.operator === "in" && Array.isArray(r.value))
+          .flatMap((r) => r.value as string[]),
+      ),
+    ].sort();
+  const { include, exclude } = trees.targetRules;
+  const mappedEligibility = nodes.filter((n) => n === minRule || n === firstRule).length;
+  const rulesOnly =
+    mappedEligibility !== trees.eligibility.rules.length ||
+    nodes.filter(isMinOrderRule).length > 1 ||
+    include.some((r) => !isIdRule(r)) ||
+    exclude.some((r) => !isIdRule(r) && !isInstantExcludeRule(r));
+  return {
+    conditions: {
+      minOrderAmount: minRule ? (minRule.value as number) : 0,
+      firstOrderOnly: Boolean(firstRule),
+      memberOnly,
+      stackWithInstantDiscount: !exclude.some(isInstantExcludeRule),
+    },
+    target: {
+      includeProductIds: ids(include, "line.productId"),
+      includeCategoryIds: ids(include, "line.categoryId"),
+      excludeProductIds: ids(exclude, "line.productId"),
+      excludeCategoryIds: ids(exclude, "line.categoryId"),
+    },
+    rulesOnly,
+  };
+}
+
+// ─── 평가(쿠폰용) ─────────────────────────────────────
+
+/** 줄이 대상인가 — 제외가 포함보다 우선, 포함이 비면 전 상품 */
+export function couponLineMatches(rules: CouponTargetRules, line: CouponLineContext): boolean {
+  if (anyConditionHolds(rules.exclude, COUPON_LINE_CONDITIONS, line)) return false;
+  if (rules.include.length === 0) return true;
+  return anyConditionHolds(rules.include, COUPON_LINE_CONDITIONS, line);
+}
+
+/** 사용 조건 실패 사유 — 옛 칸으로 옮겨지는 실패는 옛 코드를 그대로 쓴다 */
+export type CouponConditionRejectReason =
+  | "FIRST_ORDER_ONLY"
+  | "MIN_ORDER_AMOUNT"
+  | "CONDITION_NOT_MET";
+
+const usesCart = (node: ConditionNode) =>
+  [...(isConditionGroup(node) ? conditionFields(node) : [node.field])].some((f) =>
+    f.startsWith("cart."),
+  );
+
+/**
+ * 사용 조건 평가 — 두 단계로 부른다.
+ * - `beforeLines`: 대상 줄을 가리기 전 — 최상위 `and`의 주문서 집계를 쓰지 않는 규칙만 본다(옛 판정 순서: 첫 구매가 대상 상품 없음보다 먼저)
+ * - `afterLines`: 주문서 집계를 넣어 나머지 — 최상위 `and`면 주문서 집계 규칙만(앞 단계가 나머지를 통과시켰다), `or`면 트리 전체
+ */
+export function evaluateCouponEligibility(
+  eligibility: ConditionGroup,
+  ctx: CouponOrderContext,
+  phase: "beforeLines" | "afterLines",
+): CouponConditionRejectReason | null {
+  const topAnd = eligibility.combinator === "and" || eligibility.rules.length <= 1;
+  if (topAnd) {
+    const part: ConditionGroup = {
+      combinator: "and",
+      rules: eligibility.rules.filter((node) =>
+        phase === "beforeLines" ? !usesCart(node) : usesCart(node),
+      ),
+    };
+    return reasonOf(evaluateCondition(part, COUPON_ORDER_CONDITIONS, ctx).failed, true);
+  }
+  if (phase === "beforeLines") return null;
+  return evaluateCondition(eligibility, COUPON_ORDER_CONDITIONS, ctx).passed
+    ? null
+    : "CONDITION_NOT_MET";
+}
+
+/**
+ * 사실 값이 없는 구매자·시각 규칙을 참으로 바꾼 트리 — 환불 정산 전용이다. 결제 시작에서 그 규칙을 통과했으므로(스냅샷이 없는 옛 주문 포함)
+ * 주문서 집계 규칙만 남은 금액으로 다시 판정하게 한다. 참은 빈 `and` 그룹이다
+ */
+export function assumeCouponFactRules(group: ConditionGroup, facts: CouponFacts): ConditionGroup {
+  const known = (field: string) => {
+    if (field.startsWith("customer."))
+      return (
+        facts.customer?.[field.slice("customer.".length) as keyof CouponCustomerFacts] !== undefined
+      );
+    if (field.startsWith("time.")) return facts.time !== undefined;
+    return true;
+  };
+  return {
+    combinator: group.combinator,
+    rules: group.rules.map((node) =>
+      isConditionGroup(node)
+        ? assumeCouponFactRules(node, facts)
+        : known(node.field)
+          ? node
+          : EMPTY_CONDITION_GROUP,
+    ),
+  };
+}
+
+function reasonOf(
+  failed: readonly ConditionNode[],
+  topAnd: boolean,
+): CouponConditionRejectReason | null {
+  const first = failed[0];
+  if (!first) return null;
+  if (!topAnd) return "CONDITION_NOT_MET";
+  if (isFirstOrderRule(first)) return "FIRST_ORDER_ONLY";
+  if (isMinOrderRule(first)) return "MIN_ORDER_AMOUNT";
+  return "CONDITION_NOT_MET";
+}
+
+/** 발급 대상 평가 — 구매자 사실 값만 본다. 빈 트리는 모두 대상 */
+export function couponAudienceMatches(audience: ConditionGroup, facts: CouponFacts): boolean {
+  return evaluateCondition(audience, COUPON_ORDER_CONDITIONS, { facts }).passed;
+}
+
+/** 트리들에 나온 구매자 사실 값 이름(`daysSinceJoined` 등) — 서버가 필요한 값만 읽는다 */
+export function couponCustomerFactNames(
+  ...groups: readonly ConditionGroup[]
+): Set<keyof CouponCustomerFacts> {
+  const names = new Set<keyof CouponCustomerFacts>();
+  for (const group of groups) {
+    for (const field of conditionFields(group)) {
+      if (field.startsWith("customer."))
+        names.add(field.slice("customer.".length) as keyof CouponCustomerFacts);
+    }
+  }
+  return names;
+}
+
+/** 사실 값 중 트리가 쓰는 것만 남긴다 — 스냅샷에 굳히는 값 */
+export function pickCouponFacts(facts: CouponFacts, eligibility: ConditionGroup): CouponFacts {
+  const fields = conditionFields(eligibility);
+  const customer: CouponCustomerFacts = {};
+  for (const name of couponCustomerFactNames(eligibility)) {
+    const value = facts.customer?.[name];
+    if (value !== undefined) (customer as Record<string, unknown>)[name] = value;
+  }
+  const out: CouponFacts = {};
+  if (Object.keys(customer).length) out.customer = customer;
+  if (facts.time && [...fields].some((f) => f.startsWith("time."))) out.time = facts.time;
+  return out;
+}
+
+// ─── 검증 ─────────────────────────────────────────────
+
+export interface CouponRuleIssue {
+  path: (string | number)[];
+  message: string;
+}
+
+const ISSUE_MESSAGES: Record<ConditionIssue["code"], string> = {
+  DEPTH: "조건 그룹은 3단까지 둘 수 있습니다",
+  TOO_MANY_RULES: "조건은 50개까지 둘 수 있습니다",
+  UNKNOWN_FIELD: "알 수 없는 조건 필드입니다",
+  FIELD_NOT_ALLOWED: "이 자리에 쓸 수 없는 조건 필드입니다",
+  OPERATOR: "이 필드에 쓸 수 없는 연산자입니다",
+  VALUE: "조건 값이 올바르지 않습니다",
+};
+
+const allowedIn = (slot: CouponConditionSlot) => (field: string) =>
+  FIELD_INFO.get(field)?.slots.includes(slot) ?? false;
+
+/**
+ * 쿠폰 규칙 검증 — 관리 API 요청 스키마의 `superRefine`이 부른다(검증 원천 하나).
+ * 트리 형식·필드 자리에 더해 쿠폰 칸과 엮인 규칙을 본다.
+ * - 비회원에게 여는 쿠폰은 구매자 조건(`customer.*`)을 쓸 수 없다(비회원은 사실 값이 없다)
+ * - 코드형 쿠폰이 결제 완료 주문 수를 쓰면 1인 사용 한도가 필요하다(동시 결제는 1인 한도 조건부 UPDATE가 막는다)
+ * - 회원가입 쿠폰의 발급 대상에는 가입 경과 일수를 쓸 수 없다(가입 순간 늘 0)
+ */
+export function couponRuleIssues(input: {
+  memberOnly: boolean;
+  issueMethod: string;
+  perMemberUseLimit?: number | null;
+  eligibility?: ConditionGroup;
+  targetRules?: CouponTargetRules;
+  audience?: ConditionGroup;
+}): CouponRuleIssue[] {
+  const issues: CouponRuleIssue[] = [];
+  const push = (base: string[], list: ConditionIssue[]) => {
+    for (const issue of list) {
+      // 다른 자리의 필드(줄 필드를 사용 조건에)는 「모르는 필드」가 아니라 「이 자리에 못 쓰는 필드」다
+      const code =
+        issue.code === "UNKNOWN_FIELD" && issue.field && FIELD_INFO.has(issue.field)
+          ? "FIELD_NOT_ALLOWED"
+          : issue.code;
+      issues.push({ path: [...base, ...issue.path], message: ISSUE_MESSAGES[code] });
+    }
+  };
+  if (input.eligibility)
+    push(
+      ["eligibility"],
+      conditionIssues(input.eligibility, COUPON_ORDER_CONDITIONS, {
+        allowed: allowedIn("eligibility"),
+      }),
+    );
+  if (input.audience) {
+    if (input.issueMethod === "CODE" && input.audience.rules.length > 0)
+      issues.push({
+        path: ["audience"],
+        message: "코드 입력형 쿠폰에는 발급 대상을 둘 수 없습니다",
+      });
+    push(
+      ["audience"],
+      conditionIssues(input.audience, COUPON_ORDER_CONDITIONS, {
+        allowed: allowedIn("audience"),
+      }),
+    );
+  }
+  if (input.targetRules) {
+    for (const key of ["include", "exclude"] as const) {
+      push(
+        ["targetRules", key],
+        conditionIssues(
+          { combinator: "or", rules: input.targetRules[key] },
+          COUPON_LINE_CONDITIONS,
+          { allowed: allowedIn("target") },
+        ),
+      );
+    }
+  }
+  if (!input.memberOnly) {
+    for (const slot of ["eligibility", "audience"] as const) {
+      if (couponCustomerFactNames(input[slot] ?? EMPTY_CONDITION_GROUP).size > 0)
+        issues.push({
+          path: [slot],
+          message: "비회원에게 여는 쿠폰에는 구매자 조건을 둘 수 없습니다",
+        });
+    }
+  }
+  if (
+    input.issueMethod === "CODE" &&
+    couponCustomerFactNames(input.eligibility ?? EMPTY_CONDITION_GROUP).has("paidOrderCount") &&
+    input.perMemberUseLimit == null
+  )
+    issues.push({
+      path: ["perMemberUseLimit"],
+      message: "결제 완료 주문 수 조건이 있는 코드 입력형 쿠폰은 1인 사용 한도가 필요합니다",
+    });
+  if (
+    input.issueMethod === "SIGNUP" &&
+    couponCustomerFactNames(input.audience ?? EMPTY_CONDITION_GROUP).has("daysSinceJoined")
+  )
+    issues.push({
+      path: ["audience"],
+      message: "회원가입 쿠폰의 발급 대상에는 가입 경과 일수를 둘 수 없습니다",
+    });
+  return issues;
+}
+
+/** 정규형 트리 묶음 */
+export function canonicalizeCouponTrees(trees: CouponRuleTrees): CouponRuleTrees {
+  return {
+    eligibility: canonicalizeConditionGroup(trees.eligibility),
+    targetRules: canonicalizeCouponTargetRules(trees.targetRules),
+  };
+}
+
+// ─── 구매자 문구 ──────────────────────────────────────
+
+/** 스토어프론트에 싣는 조건 한 줄 — 구조화 값 + 문구. 그룹은 `field: "group"`이고 문구만 있다 */
+export interface CouponRequirement {
+  field: string;
+  operator?: string;
+  value?: ConditionValue;
+  label: string;
+}
+
+const WEEKDAY_LABELS: Record<CouponWeekday, string> = {
+  MON: "월",
+  TUE: "화",
+  WED: "수",
+  THU: "목",
+  FRI: "금",
+  SAT: "토",
+  SUN: "일",
+};
+
+const FIELD_LABELS: Record<string, string> = {
+  "customer.daysSinceJoined": "가입",
+  "customer.paidOrderCount": "구매",
+  "customer.daysSinceLastOrder": "마지막 구매",
+  "cart.subtotal": "주문 금액",
+  "cart.targetSubtotal": "대상 상품",
+  "cart.targetQuantity": "대상 상품",
+  "line.unitPrice": "판매가",
+};
+
+const number = new Intl.NumberFormat("ko-KR");
+
+function amountText(field: string, value: unknown, formatMoney: (minor: number) => string) {
+  const n = typeof value === "number" ? value : Number(value);
+  const unit = FIELD_INFO.get(field)?.unit;
+  if (unit === "money") return formatMoney(n);
+  if (unit === "day") return `${number.format(n)}일`;
+  if (unit === "count") return `${number.format(n)}회`;
+  if (unit === "quantity") return `${number.format(n)}개`;
+  return number.format(n);
+}
+
+/** 규칙 한 개의 문구 — 「가입 30일 이상」 「대상 상품 50,000원 이상」 「첫 구매」 */
+export function describeCouponRule(
+  rule: ConditionRule,
+  formatMoney: (minor: number) => string = (n) => `${number.format(n)}원`,
+): string {
+  if (isFirstOrderRule(rule)) return "첫 구매";
+  const label = FIELD_LABELS[rule.field] ?? rule.field;
+  switch (rule.field) {
+    case "customer.marketingAgreed":
+      return rule.value ? "마케팅 수신 동의" : "마케팅 수신 미동의";
+    case "line.productId":
+      return `상품 ${number.format((rule.value as unknown[]).length)}개`;
+    case "line.categoryId":
+      return `카테고리 ${number.format((rule.value as unknown[]).length)}개`;
+    case "line.hasInstantDiscount":
+      return rule.value ? "즉시할인 상품" : "즉시할인 없는 상품";
+    case "time.weekday":
+      return `${(rule.value as CouponWeekday[]).map((d) => WEEKDAY_LABELS[d] ?? d).join("·")}요일`;
+    case "time.timeOfDay": {
+      const [from, to] = rule.value as [string, string];
+      return `${from}~${to}`;
+    }
+  }
+  const text = (v: unknown) => amountText(rule.field, v, formatMoney);
+  if (rule.operator === "between") {
+    const [from, to] = rule.value as [unknown, unknown];
+    return `${label} ${text(from)}~${text(to)}`;
+  }
+  const suffix = rule.operator === ">=" ? " 이상" : rule.operator === "<=" ? " 이하" : "";
+  if (rule.field === "customer.paidOrderCount" && rule.operator === "=")
+    return `${label} ${text(rule.value)}`;
+  return `${label} ${text(rule.value)}${suffix}`;
+}
+
+export function describeCouponGroup(
+  group: ConditionGroup,
+  formatMoney?: (minor: number) => string,
+): string {
+  const joint = group.combinator === "and" ? " 그리고 " : " 또는 ";
+  return group.rules
+    .map((node) =>
+      isConditionGroup(node)
+        ? `(${describeCouponGroup(node, formatMoney)})`
+        : describeCouponRule(node, formatMoney),
+    )
+    .join(joint);
+}
+
+/** 할인 대상 문구 — 「아우터 카테고리 1개 · 상품 1개, 즉시할인 상품 제외」. 포함이 비면 「전 상품」 */
+export function describeCouponTargetRules(
+  rules: CouponTargetRules,
+  formatMoney?: (minor: number) => string,
+): string {
+  const include = rules.include.length
+    ? rules.include.map((r) => describeCouponRule(r, formatMoney)).join(" 또는 ")
+    : "전 상품";
+  if (rules.exclude.length === 0) return include;
+  const exclude = rules.exclude.map((r) => describeCouponRule(r, formatMoney)).join(", ");
+  return `${include} (${exclude} 제외)`;
+}
+
+/**
+ * 스토어프론트 `requirements` — 최상위 `and`면 노드마다 한 줄(그룹은 문구 한 줄), 최상위 `or`면 트리 전체를 한 줄로.
+ * `minOrderAmount`(옛 필드)와 같은 원천에서 나온다.
+ */
+export function couponRequirementsOf(
+  eligibility: ConditionGroup,
+  formatMoney?: (minor: number) => string,
+): CouponRequirement[] {
+  const canonical = canonicalizeConditionGroup(eligibility);
+  if (canonical.rules.length === 0) return [];
+  const topAnd = canonical.combinator === "and" || canonical.rules.length <= 1;
+  if (!topAnd) return [{ field: "group", label: describeCouponGroup(canonical, formatMoney) }];
+  return canonical.rules.map((node) =>
+    isConditionGroup(node)
+      ? { field: "group", label: describeCouponGroup(node, formatMoney) }
+      : {
+          field: node.field,
+          operator: node.operator,
+          value: node.value,
+          label: describeCouponRule(node, formatMoney),
+        },
+  );
+}