@sayren/store-sdk 0.48.0 → 0.50.0

package/src/schemas/promotion.ts

@@ -1,4 +1,21 @@
 import * as z from "zod";
+import { type ConditionGroup, conditionGroupSchema } from "./condition-tree";
+import {
+  assumeCouponFactRules,
+  COUPON_STACKING_DEFAULTS,
+  type CouponFacts,
+  type CouponRuleTrees,
+  type CouponStacking,
+  type CouponTargetRules,
+  couponLineContextOf,
+  couponLineMatches,
+  couponRulesFromLegacy,
+  couponStackingSchema,
+  couponTargetRulesSchema,
+  couponTimeFactsAt,
+  evaluateCouponEligibility,
+  pickCouponFacts,
+} from "./coupon-rules";
 import { CURRENCIES, KRW_MONEY_RULES, type MoneyRules } from "./currency";
 import { proratedRefundBase } from "./refund-policy";
 
@@ -144,9 +161,61 @@ export const couponRuleSchema = z.object({
     .datetime({ offset: true })
     .nullable()
     .describe("사용 종료 시각(ISO 8601, 시간대 포함, 이 시각부터 못 쓴다). null이면 제한이 없다"),
+  eligibility: (conditionGroupSchema as z.ZodType<ConditionGroup>)
+    .optional()
+    .describe(
+      "사용 조건 트리(이슈 #222). 없으면 `conditions`에서 만든다. 있으면 이것이 원천이고 `conditions`는 가장 가까운 옛 값이다",
+    ),
+  targetRules: couponTargetRulesSchema
+    .optional()
+    .describe(
+      "할인 대상 규칙(이슈 #222). 없으면 `target`·`conditions.stackWithInstantDiscount`에서 만든다",
+    ),
+  stacking: couponStackingSchema
+    .optional()
+    .describe("중복 사용 정책(이슈 #222). 없으면 종류별 한 장·서로 결합·적립금과 함께"),
 });
 export type CouponRule = z.infer<typeof couponRuleSchema>;
 
+/** 규칙의 트리 — 트리 칸이 없으면 옛 칸에서 만든다(계산은 늘 이 한 경로) */
+export function couponTreesOf(
+  rule: Pick<CouponRule, "conditions" | "target"> & {
+    eligibility?: ConditionGroup;
+    targetRules?: CouponTargetRules;
+  },
+): CouponRuleTrees {
+  const legacy = couponRulesFromLegacy(rule.conditions, rule.target);
+  return {
+    eligibility: rule.eligibility ?? legacy.eligibility,
+    targetRules: rule.targetRules ?? legacy.targetRules,
+  };
+}
+
+export function couponStackingOf(rule: { stacking?: CouponStacking }): CouponStacking {
+  return rule.stacking ?? COUPON_STACKING_DEFAULTS;
+}
+
+const STACKING_KEY: Record<CouponKind, keyof CouponStacking["combinesWith"]> = {
+  ORDER: "order",
+  PRODUCT: "product",
+  DELIVERY: "delivery",
+};
+
+/**
+ * 두 쿠폰을 함께 쓸 수 있는가 — 서로가 상대 종류를 허용해야 한다. 같은 쿠폰 정의의 사본끼리는 장수 규칙(`perOrderLimit`)이 보므로 늘 참이다.
+ * `quotePricing`과 최대 조합(`bestCouponSelection`)이 같은 함수를 쓴다
+ */
+export function couponsCombinable(
+  a: { rule: Pick<CouponRule, "couponId" | "kind"> & { stacking?: CouponStacking } },
+  b: { rule: Pick<CouponRule, "couponId" | "kind"> & { stacking?: CouponStacking } },
+): boolean {
+  if (a.rule.couponId === b.rule.couponId) return true;
+  return (
+    couponStackingOf(a.rule).combinesWith[STACKING_KEY[b.rule.kind]] &&
+    couponStackingOf(b.rule).combinesWith[STACKING_KEY[a.rule.kind]]
+  );
+}
+
 /** 쿠폰을 적용하지 못한 사유 */
 export const couponRejectReasonSchema = z
   .enum([
@@ -161,6 +230,8 @@ export const couponRejectReasonSchema = z
     "LINE_NOT_ELIGIBLE",
     "LINE_AMBIGUOUS",
     "NO_DISCOUNT",
+    "CONDITION_NOT_MET",
+    "NOT_COMBINABLE",
   ])
   .describe(
     "쿠폰을 적용하지 못한 사유. `DUPLICATE_COUPON`=같은 쿠폰을 두 번 넣음, " +
@@ -168,7 +239,8 @@ export const couponRejectReasonSchema = z
       "`NOT_STARTED`=사용 기간 전, `EXPIRED`=사용 기간 지남, `MEMBER_ONLY`=회원 전용, `FIRST_ORDER_ONLY`=첫 구매 전용, " +
       "`NO_ELIGIBLE_ITEMS`=대상 상품이 주문에 없음, `MIN_ORDER_AMOUNT`=최소 주문 금액 미달, " +
       "`LINE_NOT_ELIGIBLE`=지정한 주문상품이 대상이 아니거나 이미 상품 쿠폰이 있음, " +
-      "`LINE_AMBIGUOUS`=지정한 `optionId`의 줄이 여럿이라 줄을 정할 수 없음(`lineId`로 지목한다), `NO_DISCOUNT`=할인할 금액이 없음",
+      "`LINE_AMBIGUOUS`=지정한 `optionId`의 줄이 여럿이라 줄을 정할 수 없음(`lineId`로 지목한다), `NO_DISCOUNT`=할인할 금액이 없음, " +
+      "`CONDITION_NOT_MET`=사용 조건(이슈 #222)을 채우지 못함, `NOT_COMBINABLE`=이미 적용된 쿠폰과 함께 쓸 수 없음",
   );
 export type CouponRejectReason = z.infer<typeof couponRejectReasonSchema>;
 
@@ -210,6 +282,11 @@ export interface PricingCoupon {
   /** 발급 쿠폰의 유효 시작·종료 — 쿠폰 사용 기간과 둘 중 좁은 쪽이 적용된다 */
   validFrom?: string | null;
   validUntil?: string | null;
+  /**
+   * 이 쿠폰을 판정할 사실 값 — 주문 스냅샷의 값(환불 정산). 주어지면 입력의 `facts`보다 우선한다.
+   * 결제 시작에서 쓴 구매자·시각 값을 그대로 다시 쓰므로 주문 뒤 바뀐 가입 일수·요일이 결과를 바꾸지 않는다
+   */
+  facts?: CouponFacts | null;
 }
 
 /**
@@ -239,7 +316,7 @@ export interface PricingPoints {
 }
 
 /** 적립금을 쓰지 못한 이유 */
-export type PointRejectReason = "MIN_BALANCE" | "MIN_AMOUNT" | "NOT_PAYABLE";
+export type PointRejectReason = "MIN_BALANCE" | "MIN_AMOUNT" | "NOT_PAYABLE" | "COUPON_EXCLUSIVE";
 
 export interface PricingInput {
   lines: readonly PricingLine[];
@@ -248,16 +325,22 @@ export interface PricingInput {
   coupons: readonly PricingCoupon[];
   /** 배송비 견적. 없으면 배송비 0으로 계산하고 배송비 쿠폰은 할인할 금액이 없다 */
   delivery?: PricingDelivery | null;
-  /** 이 상점에서 결제 완료 주문이 없는 회원인가 */
-  firstOrder: boolean;
+  /**
+   * 이 상점에서 결제 완료 주문이 없는 회원인가 — 옛 입력이다. `facts.customer.paidOrderCount`가 없을 때 true면 0으로 읽는다
+   * (false는 값을 모르는 것으로 둔다 — 「결제 완료 주문 수 = 0」 규칙은 거짓)
+   */
+  firstOrder?: boolean;
   /** 회원 주문인가 */
   isMember: boolean;
-  /** 사용 기간 판정 시각 */
+  /** 사용 기간 판정 시각 — 시각 사실 값(요일·시각)도 여기서 나온다 */
   now: Date;
+  /** 구매자 사실 값(이슈 #222) — 사용 조건 트리가 읽는다. 시각 값을 주지 않으면 `now`에서 만든다 */
+  facts?: CouponFacts | null;
   /**
-   * 사용 기간·회원·첫 구매 조건을 다시 보지 않는다 — **환불 정산의 재계산 전용이다.** 그 조건은 결제 시작에서
+   * 사용 기간·회원 전용을 다시 보지 않는다 — **환불 정산의 재계산 전용이다.** 그 조건은 결제 시작에서
    * 이미 통과했다. 주문 시각(승인 시각)으로 기간을 다시 보면 결제 시작과 승인 사이에 끝난 쿠폰이 조건을 잃은
-   * 것처럼 보이고, 탈퇴한 회원의 반품이 회원 전용 조건에 떨어진다. 대상과 최소 금액만 본다.
+   * 것처럼 보이고, 탈퇴한 회원의 반품이 회원 전용 조건에 떨어진다. 사용 조건 트리는 쿠폰의 스냅샷 사실 값(`PricingCoupon.facts`)으로
+   * 남은 금액과 함께 다시 평가한다(트리 일부만 건너뛰면 `or` 트리의 결과가 틀린다).
    */
   ignoreEligibility?: boolean;
   /**
@@ -296,6 +379,8 @@ export interface PricingCouponResult {
   lineId: string | null;
   /** 이 쿠폰의 대상 줄 — 판정에 쓴 순서 그대로다. 환불 정산이 주문 시점 대상을 되살리는 데 쓴다 */
   eligibleLineIds: string[];
+  /** 판정에 쓴 사실 값 중 이 쿠폰의 사용 조건이 읽은 것 — 주문 스냅샷에 굳힌다. 읽은 값이 없으면 빈 객체 */
+  facts: CouponFacts;
 }
 
 export interface PricingBundleResult {
@@ -380,26 +465,19 @@ export function allocateByWeight(total: number, weights: readonly number[]): num
 }
 
 /** 카테고리 경로(`/a/b/c/`)가 그 카테고리 또는 하위를 가리키는가 */
-function inCategory(categoryPath: string | null | undefined, categoryIds: readonly string[]) {
-  if (!categoryPath || categoryIds.length === 0) return false;
-  const chain = categoryPath.split("/").filter(Boolean);
-  return categoryIds.some((id) => chain.includes(id));
-}
-
-/** 줄이 쿠폰 대상인가 — 제외가 포함보다 우선하고, 포함 목록이 모두 비면 전 상품이다 */
+/**
+ * 줄이 쿠폰 대상인가 — 제외가 포함보다 우선하고, 포함이 비면 전 상품이다. 트리(`targetRules`)가 없으면 옛 칸에서 만든 트리로 본다.
+ * `quantity`를 생략하면 1로 본다(단가 조건은 금액 ÷ 수량).
+ */
 export function isCouponTargetLine(
-  rule: Pick<CouponRule, "target" | "conditions">,
-  line: Pick<PricingLine, "productId" | "categoryPath" | "baseAmount" | "amount">,
+  rule: Pick<CouponRule, "target" | "conditions"> & { targetRules?: CouponTargetRules },
+  line: Pick<PricingLine, "productId" | "categoryPath" | "baseAmount" | "amount"> & {
+    quantity?: number;
+  },
 ): boolean {
-  const { target, conditions } = rule;
-  if (!conditions.stackWithInstantDiscount && line.amount < line.baseAmount) return false;
-  if (target.excludeProductIds.includes(line.productId)) return false;
-  if (inCategory(line.categoryPath, target.excludeCategoryIds)) return false;
-  const noInclude = target.includeProductIds.length === 0 && target.includeCategoryIds.length === 0;
-  if (noInclude) return true;
-  return (
-    target.includeProductIds.includes(line.productId) ||
-    inCategory(line.categoryPath, target.includeCategoryIds)
+  return couponLineMatches(
+    couponTreesOf(rule).targetRules,
+    couponLineContextOf({ ...line, quantity: line.quantity ?? 1 }),
   );
 }
 
@@ -456,9 +534,28 @@ export function quotePricing(input: PricingInput): PricingResult {
     rejectReason: null,
     lineId: null,
     eligibleLineIds: [],
+    facts: {},
   }));
 
-  // 1) 쿠폰마다 공통 조건 — 기간·회원·첫 구매·대상·최소 금액
+  const subtotal = lines.reduce((sum, entry) => sum + entry.line.amount, 0);
+  const inputTime = input.facts?.time ?? couponTimeFactsAt(input.now);
+  /**
+   * 쿠폰 하나의 사실 값 — 스냅샷 값 → 입력 값 순. 트리가 없는 옛 쿠폰(첫 구매 = 옛 칸)만 옛 입력 `firstOrder: true`를
+   * 결제 완료 주문 0으로 읽는다. 트리 쿠폰은 호출부가 실제 사실 값을 넘긴다(옛 입력은 첫 구매 칸이 있을 때만 계산된 값이다)
+   */
+  const factsOf = (coupon: PricingCoupon): CouponFacts => {
+    const own = coupon.facts ?? null;
+    const customer = { ...(input.facts?.customer ?? {}), ...(own?.customer ?? {}) };
+    if (
+      customer.paidOrderCount === undefined &&
+      input.firstOrder === true &&
+      coupon.rule.eligibility === undefined
+    )
+      customer.paidOrderCount = 0;
+    return { customer, time: own?.time ?? inputTime };
+  };
+
+  // 1) 쿠폰마다 공통 조건 — 기간·회원 → 구매자·시각 조건 → 대상 줄 → 주문서 집계 조건(옛 판정 순서와 같다)
   const commonRejectOf = (
     coupon: PricingCoupon,
     result: PricingCouponResult,
@@ -467,17 +564,26 @@ export function quotePricing(input: PricingInput): PricingResult {
       const period = periodRejectOf(coupon, input.now);
       if (period) return period;
       if (coupon.rule.conditions.memberOnly && !input.isMember) return "MEMBER_ONLY";
-      if (coupon.rule.conditions.firstOrderOnly && !input.firstOrder) return "FIRST_ORDER_ONLY";
     }
+    const trees = couponTreesOf(coupon.rule);
+    const facts = factsOf(coupon);
+    result.facts = pickCouponFacts(facts, trees.eligibility);
+    const early = evaluateCouponEligibility(trees.eligibility, { facts }, "beforeLines");
+    if (early) return early;
     const pinned = coupon.eligibleLineIds ? new Set(coupon.eligibleLineIds) : null;
     const eligible = lines.filter((entry) =>
-      pinned ? pinned.has(entry.line.lineId) : isCouponTargetLine(coupon.rule, entry.line),
+      pinned
+        ? pinned.has(entry.line.lineId)
+        : couponLineMatches(trees.targetRules, couponLineContextOf(entry.line)),
     );
     result.eligibleLineIds = eligible.map((entry) => entry.line.lineId);
     if (eligible.length === 0) return "NO_ELIGIBLE_ITEMS";
-    const targetAmount = eligible.reduce((sum, entry) => sum + entry.line.amount, 0);
-    if (targetAmount < coupon.rule.conditions.minOrderAmount) return "MIN_ORDER_AMOUNT";
-    return null;
+    const cart = {
+      subtotal,
+      targetSubtotal: eligible.reduce((sum, entry) => sum + entry.line.amount, 0),
+      targetQuantity: eligible.reduce((sum, entry) => sum + entry.line.quantity, 0),
+    };
+    return evaluateCouponEligibility(trees.eligibility, { facts, cart }, "afterLines");
   };
   const passed: number[] = [];
   input.coupons.forEach((coupon, index) => {
@@ -487,21 +593,34 @@ export function quotePricing(input: PricingInput): PricingResult {
     else passed.push(index);
   });
 
-  /** 적용된 쿠폰 id — 같은 쿠폰 정의는 주문에 한 장 */
-  const appliedCouponIds = new Set<string>();
+  /** 적용된 쿠폰 — 같은 쿠폰 정의의 장수(`perOrderLimit`)와 결합 판정에 쓴다 */
+  const appliedCount = new Map<string, number>();
+  const applied: PricingCoupon[] = [];
   const apply = (index: number, discount: number, lineId: string | null) => {
     const result = results[index] as PricingCouponResult;
+    const coupon = input.coupons[index] as PricingCoupon;
     result.applied = true;
     result.discount = discount;
     result.lineId = lineId;
-    appliedCouponIds.add(result.couponId);
+    appliedCount.set(result.couponId, (appliedCount.get(result.couponId) ?? 0) + 1);
+    applied.push(coupon);
   };
+  /** 같은 쿠폰 정의의 장수 — 상품 쿠폰만 `perOrderLimit`까지, 나머지는 한 장 */
   const duplicate = (index: number) => {
     const result = results[index] as PricingCouponResult;
-    if (!appliedCouponIds.has(result.couponId)) return false;
+    const coupon = input.coupons[index] as PricingCoupon;
+    const limit = coupon.rule.kind === "PRODUCT" ? couponStackingOf(coupon.rule).perOrderLimit : 1;
+    if ((appliedCount.get(result.couponId) ?? 0) < limit) return false;
     result.rejectReason = "DUPLICATE_COUPON";
     return true;
   };
+  /** 결합 — 이미 적용된 쿠폰과 이 쿠폰이 서로의 종류를 허용해야 한다(같은 쿠폰 정의의 사본끼리는 장수 규칙이 본다) */
+  const notCombinable = (index: number) => {
+    const coupon = input.coupons[index] as PricingCoupon;
+    const blocked = applied.some((other) => !couponsCombinable(coupon, other));
+    if (blocked) (results[index] as PricingCouponResult).rejectReason = "NOT_COMBINABLE";
+    return blocked;
+  };
 
   // 2) 상품 쿠폰 — 한 줄에 한 장. 줄을 지정한 쿠폰을 먼저 걸고, 나머지는 대상 줄이 적은 쿠폰부터
   //    할인이 가장 큰 남은 줄(같으면 앞 줄)에 건다. 대상이 넓은 쿠폰이 좁은 쿠폰의 유일한 줄을 먼저 가져가지 않게 한다
@@ -519,6 +638,7 @@ export function quotePricing(input: PricingInput): PricingResult {
     const coupon = input.coupons[index] as PricingCoupon;
     const result = results[index] as PricingCouponResult;
     if (duplicate(index)) continue;
+    if (notCombinable(index)) continue;
     const candidates = result.eligibleLineIds.filter((id) => !takenLines.has(id));
     let chosen: string | null = null;
     let best = 0;
@@ -566,6 +686,7 @@ export function quotePricing(input: PricingInput): PricingResult {
       result.rejectReason = "STACK_LIMIT";
       continue;
     }
+    if (notCombinable(index)) continue;
     const targets = result.eligibleLineIds
       .map((id) => lineOf(id))
       .filter((entry): entry is (typeof lines)[number] => entry !== undefined);
@@ -603,6 +724,7 @@ export function quotePricing(input: PricingInput): PricingResult {
       result.rejectReason = "STACK_LIMIT";
       continue;
     }
+    if (notCombinable(index)) continue;
     const weights = deliveryBundles.map((bundle) => Math.max(0, bundle.fee));
     const base = weights.reduce((sum, w) => sum + w, 0);
     const discount = couponDiscountOf(coupon.rule.benefit, base, rules);
@@ -639,15 +761,24 @@ export function quotePricing(input: PricingInput): PricingResult {
   const bundleWeights = deliveryBundles.map((bundle, index) =>
     Math.max(0, bundle.fee + bundle.remoteSurcharge - (bundles[index]?.couponDiscount ?? 0)),
   );
-  const points = pointUseOf(
-    input.points ?? null,
-    {
-      productPaid: productWeights.reduce((sum, w) => sum + w, 0),
-      deliveryPaid: bundleWeights.reduce((sum, w) => sum + w, 0),
-      total: beforePoints,
-    },
-    rules,
-  );
+  // 적립금과 함께 쓸 수 없는 쿠폰이 적용됐으면 적립금을 쓰지 않는다(쿠폰 우선, 이슈 #222)
+  const pointsBlocked = applied.some((entry) => !couponStackingOf(entry.rule).withPoints);
+  const points = pointsBlocked
+    ? {
+        amount: 0,
+        maxUsable: 0,
+        adjustReason: null,
+        rejectReason: (input.points?.requested ?? 0) > 0 ? ("COUPON_EXCLUSIVE" as const) : null,
+      }
+    : pointUseOf(
+        input.points ?? null,
+        {
+          productPaid: productWeights.reduce((sum, w) => sum + w, 0),
+          deliveryPaid: bundleWeights.reduce((sum, w) => sum + w, 0),
+          total: beforePoints,
+        },
+        rules,
+      );
   if (points.amount > 0) {
     const productPaid = productWeights.reduce((sum, w) => sum + w, 0);
     const toLines = Math.min(points.amount, productPaid);
@@ -750,6 +881,8 @@ export interface AppliedCouponSnapshot {
   eligibleLineIds: string[];
   /** 주문 시점 할인액 */
   discount: number;
+  /** 주문 시점 사실 값(이슈 #222) — 사용 조건 트리가 읽은 구매자·시각 값. 없으면 빈 값(옛 주문) */
+  facts?: CouponFacts | null;
 }
 
 /** 정산이 보는 주문상품 한 줄 — 이번 취소를 **반영한 뒤**의 활성 수량이다 */
@@ -852,17 +985,22 @@ export function settleCouponShortfall(input: CouponSettlementInput): CouponSettl
   });
   const recomputed = quotePricing({
     lines: pricingLines,
-    coupons: coupons.map((coupon) => ({
-      rule: coupon.rule,
-      couponKey: coupon.couponKey,
-      lineId: coupon.lineId,
-      eligibleLineIds: coupon.eligibleLineIds,
-    })),
+    coupons: coupons.map((coupon) => {
+      // 기간·회원 전용은 결제 시작에서 이미 통과했다. 사용 조건 트리는 주문 시점 사실 값 + 남은 금액으로 다시 본다.
+      // 스냅샷에 없는 구매자·시각 값(옛 주문)은 결제 시작에서 통과한 것으로 둔다 — 주문서 집계(`cart.*`)만 남은 금액으로 다시 판정한다
+      const facts = coupon.facts ?? {};
+      const eligibility = assumeCouponFactRules(couponTreesOf(coupon.rule).eligibility, facts);
+      return {
+        rule: { ...coupon.rule, eligibility },
+        couponKey: coupon.couponKey,
+        lineId: coupon.lineId,
+        eligibleLineIds: coupon.eligibleLineIds,
+        facts,
+      };
+    }),
     delivery: null,
-    // 기간·회원·첫 구매 조건은 결제 시작에서 이미 통과했다 — 대상과 최소 금액만 남은 금액으로 다시 본다
-    firstOrder: true,
     isMember: true,
-    now: new Date(0), // ignoreEligibility라 기간을 보지 않는다
+    now: new Date(0), // ignoreEligibility라 기간을 보지 않는다. 시각 조건은 스냅샷 값이거나 통과로 둔다
     ignoreEligibility: true,
   });