@sayren/store-sdk 0.16.0 → 0.17.0

package/src/schemas/promotion.ts

@@ -0,0 +1,806 @@
+import { z } from "zod";
+import { proratedRefundBase } from "./refund-policy";
+
+/**
+ * 쿠폰 금액 계산 (이슈 #47) — 쿠폰 할인을 **얼마나, 어느 주문상품에** 주는지를 정한다.
+ *
+ * 계산은 순수 함수 `quotePricing` 하나다. 장바구니 요약, 주문서 미리보기, 결제 시작의 최종 확정,
+ * 주문 스냅샷, 환불 정산의 조건 미달 판정(`settleCouponShortfall`)이 모두 이 함수를 지난다.
+ * 다섯 경로가 각자 계산하면 화면 금액, 결제 금액, 환불 금액이 갈라진다(`quoteDelivery`와 같은 원칙).
+ *
+ * 계산 순서
+ * 1. 즉시할인(`products.discount`)은 이미 단가에 들어 있다. 입력 `amount`가 즉시할인 반영 금액이다.
+ * 2. 상품 쿠폰(`PRODUCT`) — 주문상품 한 줄에 한 장. 그 줄 금액을 기준으로 할인한다.
+ * 3. 주문 쿠폰(`ORDER`) — 주문에 한 장. **상품 쿠폰 차감 뒤 금액**의 대상 합계를 기준으로 할인하고,
+ *    대상 줄에 금액 비율로 나눈다(누적 내림의 차분).
+ * 4. 배송비 쿠폰(`DELIVERY`) — 주문에 한 장. 기본 배송비(지역 추가 배송비 제외)를 기준으로 할인하고
+ *    배송 묶음에 기본 배송비 비율로 나눈다.
+ *
+ * 무료배송 기준(상품별 조건부 무료·스토어 전체 기준)은 **쿠폰 차감 전 금액**으로 판정한다. 그래서 배송비
+ * 견적(`quoteDelivery`)은 쿠폰과 무관하게 먼저 계산되고, 이 함수는 그 결과만 입력으로 받는다.
+ *
+ * 최소 주문 금액은 대상 상품의 **즉시할인 반영 합계**(쿠폰 차감 전, 배송비 제외)로 판정한다.
+ * 정률 할인은 10원 단위로 내리고(`discountedPriceOf`의 즉시할인과 같은 단위), 최대 할인액과 기준 금액을
+ * 넘지 않는다.
+ */
+
+const descriptions = {
+  kind:
+    "쿠폰 종류. `ORDER`=주문 쿠폰(대상 상품 합계에서 할인), `PRODUCT`=상품 쿠폰(주문상품 한 줄에서 할인), " +
+    "`DELIVERY`=배송비 쿠폰(기본 배송비에서 할인, 지역 추가 배송비 제외)",
+  benefitType: "할인 방식. `RATE`=정률(%), `AMOUNT`=정액(원)",
+  benefitValue: "할인 값. `RATE`면 1~100(%), `AMOUNT`면 원 단위 금액",
+  maxDiscountAmount:
+    "정률 할인의 최대 할인액(원). null이면 상한이 없다. 정액 할인에는 쓰지 않는다(null)",
+  minOrderAmount:
+    "최소 주문 금액(원). 대상 상품의 즉시할인 반영 합계(배송비 제외)가 이 값 이상이어야 쓸 수 있다. 0이면 조건이 없다",
+  firstOrderOnly: "이 스토어에서 결제 완료 주문이 없는 회원만 쓸 수 있다",
+  memberOnly:
+    "회원만 쓸 수 있다. false면 비회원도 쓸 수 있다 — 코드 입력형이면서 1인 한도가 없는 쿠폰만 false로 둘 수 있다",
+  stackWithInstantDiscount:
+    "상품 즉시할인과 함께 쓸 수 있다. false면 즉시할인이 걸린 주문상품은 쿠폰 대상에서 빠진다",
+  includeProductIds: "대상 상품 id. 포함 목록(상품·카테고리)이 모두 비면 전 상품이 대상이다",
+  includeCategoryIds: "대상 카테고리 id. 하위 카테고리의 상품도 대상이다",
+  excludeProductIds: "제외 상품 id. 포함보다 우선한다",
+  excludeCategoryIds: "제외 카테고리 id. 하위 카테고리의 상품도 제외한다. 포함보다 우선한다",
+} as const;
+
+/** 쿠폰 종류 */
+export const couponKindSchema = z
+  .enum(["ORDER", "PRODUCT", "DELIVERY"])
+  .describe(descriptions.kind);
+export type CouponKind = z.infer<typeof couponKindSchema>;
+
+/** 쿠폰 혜택 — 정률은 1~100%, 최대 할인액을 둘 수 있다. 정액은 최대 할인액이 없다 */
+export const couponBenefitSchema = z
+  .object({
+    type: z.enum(["RATE", "AMOUNT"]).describe(descriptions.benefitType),
+    value: z.number().int().min(1).describe(descriptions.benefitValue),
+    maxDiscountAmount: z.number().int().min(1).nullable().describe(descriptions.maxDiscountAmount),
+  })
+  .superRefine((benefit, ctx) => {
+    if (benefit.type === "RATE" && benefit.value > 100) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["value"],
+        message: "정률 할인은 1~100(%)이어야 합니다",
+      });
+    }
+    if (benefit.type === "AMOUNT" && benefit.maxDiscountAmount !== null) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["maxDiscountAmount"],
+        message: "정액 할인에는 최대 할인액을 두지 않습니다",
+      });
+    }
+  });
+export type CouponBenefit = z.infer<typeof couponBenefitSchema>;
+
+/** 쿠폰 사용 조건 */
+export const couponConditionsSchema = z.object({
+  minOrderAmount: z.number().int().min(0).describe(descriptions.minOrderAmount),
+  firstOrderOnly: z.boolean().describe(descriptions.firstOrderOnly),
+  memberOnly: z.boolean().describe(descriptions.memberOnly),
+  stackWithInstantDiscount: z.boolean().describe(descriptions.stackWithInstantDiscount),
+});
+export type CouponConditions = z.infer<typeof couponConditionsSchema>;
+
+/** 조건을 생략했을 때의 값 */
+export const COUPON_CONDITIONS_DEFAULTS: CouponConditions = {
+  minOrderAmount: 0,
+  firstOrderOnly: false,
+  memberOnly: true,
+  stackWithInstantDiscount: true,
+};
+
+/** 상한 — 대상 목록은 규칙 스냅샷에 통째로 복사되므로 크기를 제한한다 */
+export const COUPON_TARGET_LIST_MAX = 500;
+
+/** 쿠폰 대상 — 포함 목록이 모두 비면 전 상품이다. 제외가 포함보다 우선한다 */
+export const couponTargetSchema = z.object({
+  includeProductIds: z
+    .array(z.string().min(1))
+    .max(COUPON_TARGET_LIST_MAX)
+    .describe(descriptions.includeProductIds),
+  includeCategoryIds: z
+    .array(z.string().min(1))
+    .max(COUPON_TARGET_LIST_MAX)
+    .describe(descriptions.includeCategoryIds),
+  excludeProductIds: z
+    .array(z.string().min(1))
+    .max(COUPON_TARGET_LIST_MAX)
+    .describe(descriptions.excludeProductIds),
+  excludeCategoryIds: z
+    .array(z.string().min(1))
+    .max(COUPON_TARGET_LIST_MAX)
+    .describe(descriptions.excludeCategoryIds),
+});
+export type CouponTarget = z.infer<typeof couponTargetSchema>;
+
+export const COUPON_TARGET_ALL: CouponTarget = {
+  includeProductIds: [],
+  includeCategoryIds: [],
+  excludeProductIds: [],
+  excludeCategoryIds: [],
+};
+
+/**
+ * 쿠폰 규칙 스냅샷 — 계산에 필요한 값만 담는다. 결제 시작이 쿠폰을 읽어 이 형태로 결제 세션에 굳히고,
+ * 주문 생성·환불 정산은 이 스냅샷만 읽는다. 결제 도중·주문 뒤 셀러가 쿠폰을 바꿔도 그 주문의 금액은 움직이지 않는다.
+ */
+export const couponRuleSchema = z.object({
+  couponId: z.string().describe("쿠폰 id (`cpn_…`)"),
+  name: z.string().describe("쿠폰 이름"),
+  kind: couponKindSchema,
+  benefit: couponBenefitSchema,
+  conditions: couponConditionsSchema,
+  target: couponTargetSchema,
+  startsAt: z.iso
+    .datetime({ offset: true })
+    .nullable()
+    .describe("사용 시작 시각(ISO 8601, 시간대 포함). null이면 제한이 없다"),
+  endsAt: z.iso
+    .datetime({ offset: true })
+    .nullable()
+    .describe("사용 종료 시각(ISO 8601, 시간대 포함, 이 시각부터 못 쓴다). null이면 제한이 없다"),
+});
+export type CouponRule = z.infer<typeof couponRuleSchema>;
+
+/** 쿠폰을 적용하지 못한 사유 */
+export const couponRejectReasonSchema = z
+  .enum([
+    "DUPLICATE_COUPON",
+    "STACK_LIMIT",
+    "NOT_STARTED",
+    "EXPIRED",
+    "MEMBER_ONLY",
+    "FIRST_ORDER_ONLY",
+    "NO_ELIGIBLE_ITEMS",
+    "MIN_ORDER_AMOUNT",
+    "LINE_NOT_ELIGIBLE",
+    "NO_DISCOUNT",
+  ])
+  .describe(
+    "쿠폰을 적용하지 못한 사유. `DUPLICATE_COUPON`=같은 쿠폰을 두 번 넣음, " +
+      "`STACK_LIMIT`=같은 종류의 쿠폰이 이미 적용됨(주문 쿠폰·배송비 쿠폰은 주문당 1장, 상품 쿠폰은 주문상품 한 줄에 1장), " +
+      "`NOT_STARTED`=사용 기간 전, `EXPIRED`=사용 기간 지남, `MEMBER_ONLY`=회원 전용, `FIRST_ORDER_ONLY`=첫 구매 전용, " +
+      "`NO_ELIGIBLE_ITEMS`=대상 상품이 주문에 없음, `MIN_ORDER_AMOUNT`=최소 주문 금액 미달, " +
+      "`LINE_NOT_ELIGIBLE`=지정한 주문상품이 대상이 아니거나 이미 상품 쿠폰이 있음, `NO_DISCOUNT`=할인할 금액이 없음",
+  );
+export type CouponRejectReason = z.infer<typeof couponRejectReasonSchema>;
+
+/** 쿠폰 적용 뒤 결제 금액의 하한 — 0원 결제 경로가 없어 이보다 작으면 결제를 시작하지 않는다(400 `PAYMENT_AMOUNT_TOO_LOW`) */
+export const MIN_PAYMENT_AMOUNT = 100;
+
+// ─── 계산 ─────────────────────────────────────────────
+
+/** 계산에 넣는 주문상품 한 줄 */
+export interface PricingLine {
+  /** 줄 식별자 — 주문서는 항목 순번, 주문은 주문상품 id. 배분 결과가 이 키로 나온다 */
+  lineId: string;
+  productId: string;
+  /** 상품 카테고리 경로(`/조상/…/자신/`). 없으면 카테고리 대상에 걸리지 않는다 */
+  categoryPath?: string | null;
+  /** 수량 — 계산에는 쓰지 않는다(금액이 이미 수량을 반영한다). 화면·로그용이다 */
+  quantity: number;
+  /** 즉시할인 전 금액 (정가 단가 × 수량) */
+  baseAmount: number;
+  /** 즉시할인 반영 금액 (할인 단가 × 수량) — 쿠폰 계산의 기준이다 */
+  amount: number;
+}
+
+/** 계산에 넣는 쿠폰 한 장 */
+export interface PricingCoupon {
+  rule: CouponRule;
+  /** 결과·배분의 키. 생략하면 `rule.couponId` */
+  couponKey?: string;
+  /**
+   * 상품 쿠폰을 걸 줄. 생략하면 계산이 고른다 — 줄을 지정한 쿠폰을 먼저 걸고, 나머지는 대상 줄이 적은 쿠폰부터
+   * 할인이 가장 큰 남은 줄(같으면 앞 줄)에 건다
+   */
+  lineId?: string | null;
+  /**
+   * 대상 줄을 이미 정했으면 그 목록 — 환불 정산의 재계산이 쓴다. 주어지면 `target`·즉시할인 조건을 다시
+   * 판정하지 않는다(주문 뒤 상품의 카테고리·즉시할인이 바뀌어도 주문 시점 대상이 그대로다).
+   */
+  eligibleLineIds?: readonly string[] | null;
+  /** 발급 쿠폰의 유효 시작·종료 — 쿠폰 사용 기간과 둘 중 좁은 쪽이 적용된다 */
+  validFrom?: string | null;
+  validUntil?: string | null;
+}
+
+/**
+ * 배송비 쿠폰이 보는 배송비 견적 — `quoteDelivery` 결과의 묶음 내역이다. 배송비 총액은 묶음의
+ * `fee + remoteSurcharge` 합으로 계산한다(총액을 따로 받으면 묶음과 어긋날 수 있다).
+ */
+export interface PricingDelivery {
+  bundles: ReadonlyArray<{ bundleKey: string; fee: number; remoteSurcharge: number }>;
+}
+
+export interface PricingInput {
+  lines: readonly PricingLine[];
+  coupons: readonly PricingCoupon[];
+  /** 배송비 견적. 없으면 배송비 0으로 계산하고 배송비 쿠폰은 할인할 금액이 없다 */
+  delivery?: PricingDelivery | null;
+  /** 이 스토어에서 결제 완료 주문이 없는 회원인가 */
+  firstOrder: boolean;
+  /** 회원 주문인가 */
+  isMember: boolean;
+  /** 사용 기간 판정 시각 */
+  now: Date;
+  /**
+   * 사용 기간·회원·첫 구매 조건을 다시 보지 않는다 — **환불 정산의 재계산 전용이다.** 그 조건은 결제 시작에서
+   * 이미 통과했다. 주문 시각(승인 시각)으로 기간을 다시 보면 결제 시작과 승인 사이에 끝난 쿠폰이 조건을 잃은
+   * 것처럼 보이고, 탈퇴한 회원의 반품이 회원 전용 조건에 떨어진다. 대상과 최소 금액만 본다.
+   */
+  ignoreEligibility?: boolean;
+}
+
+/** 줄 하나에 들어간 쿠폰별 할인 */
+export interface CouponAllocation {
+  couponKey: string;
+  amount: number;
+}
+
+export interface PricingLineResult {
+  lineId: string;
+  /** 즉시할인 반영 금액 (쿠폰 전) */
+  amount: number;
+  /** 이 줄에 들어간 쿠폰 할인 합계 — 상품 쿠폰 + 주문 쿠폰 배분 */
+  couponDiscount: number;
+  allocations: CouponAllocation[];
+}
+
+export interface PricingCouponResult {
+  couponKey: string;
+  couponId: string;
+  kind: CouponKind;
+  applied: boolean;
+  /** 이 쿠폰의 할인액. 적용하지 못했으면 0 */
+  discount: number;
+  rejectReason: CouponRejectReason | null;
+  /** 상품 쿠폰이 걸린 줄. 그 밖은 null */
+  lineId: string | null;
+  /** 이 쿠폰의 대상 줄 — 판정에 쓴 순서 그대로다. 환불 정산이 주문 시점 대상을 되살리는 데 쓴다 */
+  eligibleLineIds: string[];
+}
+
+export interface PricingBundleResult {
+  bundleKey: string;
+  couponDiscount: number;
+}
+
+export interface PricingResult {
+  lines: PricingLineResult[];
+  coupons: PricingCouponResult[];
+  /** 배송비 쿠폰의 묶음별 배분 */
+  bundles: PricingBundleResult[];
+  /** 상품 금액 합 (즉시할인 반영, 쿠폰 전) */
+  productAmount: number;
+  /** 상품·주문 쿠폰 할인 합계 */
+  couponDiscountAmount: number;
+  /** 배송비 (쿠폰 전) */
+  deliveryFee: number;
+  /** 배송비 쿠폰 할인 */
+  deliveryDiscountAmount: number;
+  /** 결제 금액 = productAmount − couponDiscountAmount + deliveryFee − deliveryDiscountAmount */
+  totalAmount: number;
+}
+
+/**
+ * 할인액 — 정률은 10원 단위 내림, 최대 할인액과 기준 금액을 넘지 않는다. 기준 금액이 0 이하면 0이다.
+ *
+ * 곱셈을 먼저 하고 나눈다. `base × 율 ÷ 1000`을 내려 10을 곱하면 `floor(base × 율 / 100 / 10) × 10`과 같고
+ * 부동소수 오차가 끼지 않는다.
+ */
+export function couponDiscountOf(benefit: CouponBenefit, base: number): number {
+  if (base <= 0) return 0;
+  let raw =
+    benefit.type === "RATE" ? Math.floor((base * benefit.value) / 1000) * 10 : benefit.value;
+  if (benefit.type === "RATE" && benefit.maxDiscountAmount !== null) {
+    raw = Math.min(raw, benefit.maxDiscountAmount);
+  }
+  return Math.max(0, Math.min(raw, base));
+}
+
+/**
+ * 금액을 가중치 비율로 나눈다 — **누적 내림의 차분**이다.
+ *
+ * `i`번째 몫 = `floor(total × W_i / W) − floor(total × W_{i−1} / W)`(`W_i`는 앞에서부터 누적 가중치).
+ * 합이 `total`과 정확히 같고, 입력 순서가 같으면 결과도 같다. `total ≤ W`이면 몫이 가중치를 넘지 않는다.
+ * 곱이 2^53을 넘을 수 있어 BigInt로 계산한다.
+ */
+export function allocateByWeight(total: number, weights: readonly number[]): number[] {
+  if (!Number.isSafeInteger(total) || !weights.every((w) => Number.isSafeInteger(w))) {
+    throw new RangeError("allocateByWeight: 금액과 가중치는 안전한 정수여야 합니다");
+  }
+  const sum = weights.reduce((acc, w) => acc + Math.max(0, w), 0);
+  if (total <= 0 || sum <= 0) return weights.map(() => 0);
+  const bigTotal = BigInt(total);
+  const bigSum = BigInt(sum);
+  let cumulative = 0n;
+  let previous = 0n;
+  return weights.map((weight) => {
+    cumulative += BigInt(Math.max(0, weight));
+    const upTo = (bigTotal * cumulative) / bigSum;
+    const share = upTo - previous;
+    previous = upTo;
+    return Number(share);
+  });
+}
+
+/** 카테고리 경로(`/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));
+}
+
+/** 줄이 쿠폰 대상인가 — 제외가 포함보다 우선하고, 포함 목록이 모두 비면 전 상품이다 */
+export function isCouponTargetLine(
+  rule: Pick<CouponRule, "target" | "conditions">,
+  line: Pick<PricingLine, "productId" | "categoryPath" | "baseAmount" | "amount">,
+): 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)
+  );
+}
+
+/** 시각 파싱 — 값이 없으면 null(제한 없음), 읽지 못하면 NaN(판정에서 거절한다) */
+function timeOf(value: string | null | undefined): number | null {
+  if (!value) return null;
+  return Date.parse(value);
+}
+
+/**
+ * 사용 기간 판정 — 쿠폰 기간과 발급 쿠폰 유효 기간 중 좁은 쪽. 시작은 포함, 종료는 제외.
+ * 읽지 못하는 시각은 제한 없음이 아니라 거절이다(fail-closed).
+ */
+function periodRejectOf(coupon: PricingCoupon, now: Date): CouponRejectReason | null {
+  const at = now.getTime();
+  const starts = [timeOf(coupon.rule.startsAt), timeOf(coupon.validFrom)].filter(
+    (t): t is number => t !== null,
+  );
+  const ends = [timeOf(coupon.rule.endsAt), timeOf(coupon.validUntil)].filter(
+    (t): t is number => t !== null,
+  );
+  if (starts.some((t) => Number.isNaN(t) || at < t)) return "NOT_STARTED";
+  if (ends.some((t) => Number.isNaN(t) || at >= t)) return "EXPIRED";
+  return null;
+}
+
+/**
+ * 쿠폰 금액 계산 — **순수 함수다.** DB를 읽지 않는다. 규칙 스냅샷을 만드는 조회와 한도·보유 판정
+ * (발급 쿠폰 상태, 1인 한도)은 호출부 몫이다.
+ *
+ * 종류별로 상품 쿠폰 → 주문 쿠폰 → 배송비 쿠폰 순으로 적용한다. 같은 종류의 자리와 같은 쿠폰 id는
+ * **적용된** 쿠폰만 차지한다 — 앞선 주문 쿠폰이 최소 금액 미달이면 뒤의 주문 쿠폰이 쓰이고, 같은 쿠폰의 발급
+ * 사본 중 앞 장이 만료됐으면 뒤 장이 쓰인다. 결과의 `coupons`는 입력 순서 그대로다. 입력이 같으면 결과도 같다.
+ */
+export function quotePricing(input: PricingInput): PricingResult {
+  const lines = input.lines.map((line) => ({
+    line,
+    productDiscount: 0,
+    allocations: [] as CouponAllocation[],
+  }));
+  const lineIndex = new Map(lines.map((entry, index) => [entry.line.lineId, index]));
+  const lineOf = (id: string) => {
+    const index = lineIndex.get(id);
+    return index === undefined ? undefined : lines[index];
+  };
+
+  const results: PricingCouponResult[] = input.coupons.map((coupon) => ({
+    couponKey: coupon.couponKey ?? coupon.rule.couponId,
+    couponId: coupon.rule.couponId,
+    kind: coupon.rule.kind,
+    applied: false,
+    discount: 0,
+    rejectReason: null,
+    lineId: null,
+    eligibleLineIds: [],
+  }));
+
+  // 1) 쿠폰마다 공통 조건 — 기간·회원·첫 구매·대상·최소 금액
+  const commonRejectOf = (
+    coupon: PricingCoupon,
+    result: PricingCouponResult,
+  ): CouponRejectReason | null => {
+    if (!input.ignoreEligibility) {
+      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 pinned = coupon.eligibleLineIds ? new Set(coupon.eligibleLineIds) : null;
+    const eligible = lines.filter((entry) =>
+      pinned ? pinned.has(entry.line.lineId) : isCouponTargetLine(coupon.rule, 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 passed: number[] = [];
+  input.coupons.forEach((coupon, index) => {
+    const result = results[index] as PricingCouponResult;
+    const reason = commonRejectOf(coupon, result);
+    if (reason) result.rejectReason = reason;
+    else passed.push(index);
+  });
+
+  /** 적용된 쿠폰 id — 같은 쿠폰 정의는 주문에 한 장 */
+  const appliedCouponIds = new Set<string>();
+  const apply = (index: number, discount: number, lineId: string | null) => {
+    const result = results[index] as PricingCouponResult;
+    result.applied = true;
+    result.discount = discount;
+    result.lineId = lineId;
+    appliedCouponIds.add(result.couponId);
+  };
+  const duplicate = (index: number) => {
+    const result = results[index] as PricingCouponResult;
+    if (!appliedCouponIds.has(result.couponId)) return false;
+    result.rejectReason = "DUPLICATE_COUPON";
+    return true;
+  };
+
+  // 2) 상품 쿠폰 — 한 줄에 한 장. 줄을 지정한 쿠폰을 먼저 걸고, 나머지는 대상 줄이 적은 쿠폰부터
+  //    할인이 가장 큰 남은 줄(같으면 앞 줄)에 건다. 대상이 넓은 쿠폰이 좁은 쿠폰의 유일한 줄을 먼저 가져가지 않게 한다
+  const productIndexes = passed.filter((index) => input.coupons[index]?.rule.kind === "PRODUCT");
+  const productOrder = [
+    ...productIndexes.filter((index) => input.coupons[index]?.lineId),
+    ...productIndexes
+      .filter((index) => !input.coupons[index]?.lineId)
+      .map((index) => ({ index, width: results[index]?.eligibleLineIds.length ?? 0 }))
+      .sort((a, b) => a.width - b.width || a.index - b.index)
+      .map((entry) => entry.index),
+  ];
+  const takenLines = new Set<string>();
+  for (const index of productOrder) {
+    const coupon = input.coupons[index] as PricingCoupon;
+    const result = results[index] as PricingCouponResult;
+    if (duplicate(index)) continue;
+    const candidates = result.eligibleLineIds.filter((id) => !takenLines.has(id));
+    let chosen: string | null = null;
+    let best = 0;
+    if (coupon.lineId) {
+      if (!candidates.includes(coupon.lineId)) {
+        result.rejectReason = result.eligibleLineIds.includes(coupon.lineId)
+          ? "STACK_LIMIT"
+          : "LINE_NOT_ELIGIBLE";
+        continue;
+      }
+      chosen = coupon.lineId;
+      best = couponDiscountOf(coupon.rule.benefit, lineOf(chosen)?.line.amount ?? 0);
+    } else {
+      if (candidates.length === 0) {
+        result.rejectReason = "STACK_LIMIT";
+        continue;
+      }
+      for (const id of candidates) {
+        const discount = couponDiscountOf(coupon.rule.benefit, lineOf(id)?.line.amount ?? 0);
+        if (chosen === null || discount > best) {
+          chosen = id;
+          best = discount;
+        }
+      }
+    }
+    const entry = chosen === null ? undefined : lineOf(chosen);
+    if (!entry || chosen === null || best <= 0) {
+      result.rejectReason = "NO_DISCOUNT";
+      continue;
+    }
+    takenLines.add(chosen);
+    entry.productDiscount += best;
+    entry.allocations.push({ couponKey: result.couponKey, amount: best });
+    apply(index, best, chosen);
+  }
+
+  // 3) 주문 쿠폰 — 상품 쿠폰 차감 뒤 금액 기준, 대상 줄에 금액 비율로 배분
+  let orderSlot = false;
+  for (const index of passed) {
+    const coupon = input.coupons[index] as PricingCoupon;
+    const result = results[index] as PricingCouponResult;
+    if (coupon.rule.kind !== "ORDER") continue;
+    if (duplicate(index)) continue;
+    if (orderSlot) {
+      result.rejectReason = "STACK_LIMIT";
+      continue;
+    }
+    const targets = result.eligibleLineIds
+      .map((id) => lineOf(id))
+      .filter((entry): entry is (typeof lines)[number] => entry !== undefined);
+    const weights = targets.map((entry) => Math.max(0, entry.line.amount - entry.productDiscount));
+    const base = weights.reduce((sum, w) => sum + w, 0);
+    const discount = couponDiscountOf(coupon.rule.benefit, base);
+    if (discount <= 0) {
+      result.rejectReason = "NO_DISCOUNT";
+      continue;
+    }
+    const shares = allocateByWeight(discount, weights);
+    targets.forEach((entry, i) => {
+      const share = shares[i] ?? 0;
+      if (share > 0) entry.allocations.push({ couponKey: result.couponKey, amount: share });
+    });
+    orderSlot = true;
+    apply(index, discount, null);
+  }
+
+  // 4) 배송비 쿠폰 — 기본 배송비(지역 추가 제외) 기준, 묶음에 기본 배송비 비율로 배분
+  const deliveryBundles = input.delivery?.bundles ?? [];
+  const bundles: PricingBundleResult[] = deliveryBundles.map((bundle) => ({
+    bundleKey: bundle.bundleKey,
+    couponDiscount: 0,
+  }));
+  let deliverySlot = false;
+  let deliveryDiscountAmount = 0;
+  for (const index of passed) {
+    const coupon = input.coupons[index] as PricingCoupon;
+    const result = results[index] as PricingCouponResult;
+    if (coupon.rule.kind !== "DELIVERY") continue;
+    if (duplicate(index)) continue;
+    if (deliverySlot) {
+      result.rejectReason = "STACK_LIMIT";
+      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);
+    if (discount <= 0) {
+      result.rejectReason = "NO_DISCOUNT";
+      continue;
+    }
+    allocateByWeight(discount, weights).forEach((share, i) => {
+      const bundle = bundles[i];
+      if (bundle) bundle.couponDiscount += share;
+    });
+    deliverySlot = true;
+    deliveryDiscountAmount = discount;
+    apply(index, discount, null);
+  }
+
+  const lineResults: PricingLineResult[] = lines.map((entry) => ({
+    lineId: entry.line.lineId,
+    amount: entry.line.amount,
+    couponDiscount: entry.allocations.reduce((sum, a) => sum + a.amount, 0),
+    allocations: entry.allocations,
+  }));
+  const productAmount = lines.reduce((sum, entry) => sum + entry.line.amount, 0);
+  const couponDiscountAmount = lineResults.reduce((sum, line) => sum + line.couponDiscount, 0);
+  const deliveryFee = deliveryBundles.reduce(
+    (sum, bundle) => sum + bundle.fee + bundle.remoteSurcharge,
+    0,
+  );
+  return {
+    lines: lineResults,
+    coupons: results,
+    bundles,
+    productAmount,
+    couponDiscountAmount,
+    deliveryFee,
+    deliveryDiscountAmount,
+    totalAmount: productAmount - couponDiscountAmount + deliveryFee - deliveryDiscountAmount,
+  };
+}
+
+// ─── 환불 정산: 조건 미달 차감 ─────────────────────────────
+
+/**
+ * 주문이 받은 쿠폰 한 장 — 주문 시점 규칙과 대상 줄을 굳힌 값이다(`orders.discounts`의 항목).
+ * 환불 정산은 이 값만 읽는다. 셀러가 쿠폰을 바꾸거나 상품의 카테고리가 바뀌어도 결과가 같다.
+ */
+export interface AppliedCouponSnapshot {
+  couponKey: string;
+  rule: CouponRule;
+  /** 상품 쿠폰이 걸린 주문상품 id. 그 밖은 null */
+  lineId: string | null;
+  /** 주문 시점 대상 주문상품 id — 주문서 항목 순서 그대로다 */
+  eligibleLineIds: string[];
+  /** 주문 시점 할인액 */
+  discount: number;
+}
+
+/** 정산이 보는 주문상품 한 줄 — 이번 취소를 **반영한 뒤**의 활성 수량이다 */
+export interface CouponSettlementLine {
+  lineId: string;
+  productId: string;
+  quantity: number;
+  /** 남은 활성 수량 (이번 취소 반영 뒤) */
+  activeQuantity: number;
+  /** 주문상품 금액 (즉시할인 반영 단가 × 전체 수량, 쿠폰 전) */
+  totalPrice: number;
+  /** 주문 시점 쿠폰별 배분 */
+  allocations: readonly CouponAllocation[];
+}
+
+/** 쿠폰 한 장의 정산 누적 — `orders.coupon_settlements[couponKey]` */
+export interface CouponSettlementState {
+  /** 지금까지 환불에서 뺀 조건 미달 차감 (되돌린 금액을 뺀 값) */
+  charged: number;
+  /** 판매자 귀책·정책 꺼짐으로 받지 않기로 한 미달분 — 뒤의 환불이 다시 청구하지 않게 남긴다 */
+  waived: number;
+}
+
+export interface CouponSettlementInput {
+  coupons: readonly AppliedCouponSnapshot[];
+  lines: readonly CouponSettlementLine[];
+  settlements: Readonly<Record<string, Partial<CouponSettlementState> | undefined>>;
+  /** 스토어 환불 정책 `couponShortfallCharge` */
+  shortfallCharge: boolean;
+  /** 판매자 귀책(직권취소, 불량·오배송 반품) — 미달분을 청구하지 않는다 */
+  sellerFault: boolean;
+  /**
+   * 이번 환불에서 실제로 뺄 수 있는 금액 — 차감의 상한이다. 넘겨 차감하면 환불은 0원으로 잘리는데 기록에는
+   * 전액이 남아, 뒤에 되돌릴 때 받지 않은 돈을 돌려준다(배송비 미달 차감의 `chargeableAmount`와 같은 이유).
+   */
+  chargeableAmount: number;
+}
+
+export interface CouponSettlementEntry {
+  couponKey: string;
+  /** 남은 주문상품에 배분된 할인 */
+  allocatedRemaining: number;
+  /** 남은 주문상품으로 다시 계산한 할인 — 쿠폰 조건을 잃었으면 0 */
+  recomputed: number;
+  /** 누적 미달분 목표 = 조건을 잃었으면 `allocatedRemaining`, 아니면 0 */
+  target: number;
+  charge: number;
+  refund: number;
+  waive: number;
+  next: CouponSettlementState;
+}
+
+export interface CouponSettlementResult {
+  /** 이번 환불에서 뺄 금액 — 조건 미달 차감 */
+  chargeAmount: number;
+  /** 이번 환불에 더할 금액 — 앞선 환불에서 뺀 차감을 되돌린 몫 */
+  refundAmount: number;
+  entries: CouponSettlementEntry[];
+}
+
+export const NO_COUPON_SETTLEMENT: CouponSettlementResult = {
+  chargeAmount: 0,
+  refundAmount: 0,
+  entries: [],
+};
+
+/**
+ * 쿠폰 조건 미달 차감 — **순수 함수다.** 부분 취소·반품으로 남은 주문상품이 쿠폰 조건을 잃으면,
+ * 남은 주문상품이 받던 할인만큼을 이번 환불에서 뺀다.
+ *
+ * 쿠폰마다
+ * - `allocatedRemaining` = 남은 수량에 배분된 할인(`proratedRefundBase`로 수량 비율)
+ * - `recomputed` = 주문 시점 규칙 스냅샷과 주문 시점 대상 줄로, 남은 금액만 넣어 `quotePricing`을 다시 돌린 할인
+ * - 쿠폰이 **여전히 적용되면 목표 0**, 조건을 잃었으면 목표 = `allocatedRemaining`이다. 적용되는 쿠폰의
+ *   정률 10원 내림 차이까지 차감하면 조건을 지킨 구매자가 몇 원씩 잃는다 — 조건을 잃은 경우만 본다.
+ *   재계산 할인이 더 커지는 경우(정률 최대 할인액)도 차감하지 않고 더 돌려주지도 않는다.
+ * - `delta` = 목표 − (이미 차감 + 이미 면제). 양수면 청구하고(판매자 귀책·정책 꺼짐이면 면제로 기록),
+ *   음수면 앞서 뺀 차감부터 돌려준다. 마지막 활성 수량까지 취소되면 목표가 0이라 누적 차감이 모두 되돌아가고,
+ *   전량 취소의 환불 합계가 결제액과 같아진다.
+ * - 청구는 이번 환불에서 실제로 뺄 수 있는 금액(`chargeableAmount` + 이번에 되돌린 금액)을 넘지 않고,
+ *   **실제로 뺀 금액만** 기록한다. 못 뺀 나머지는 기록하지 않아 다음 환불이 다시 본다.
+ *
+ * 배송비 쿠폰은 여기서 다루지 않는다. 배송비 쿠폰을 발급하게 되면(3단계) 묶음 배송비 환불
+ * (`computeDeliveryFeeSettlement`)이 그 묶음의 `couponDiscount`를 빼야 한다 — 빼지 않으면 받지 않은 배송비를 돌려준다.
+ */
+export function settleCouponShortfall(input: CouponSettlementInput): CouponSettlementResult {
+  const coupons = input.coupons.filter((coupon) => coupon.rule.kind !== "DELIVERY");
+  if (coupons.length === 0) return NO_COUPON_SETTLEMENT;
+
+  const pricingLines: PricingLine[] = input.lines.map((line) => {
+    const remaining = proratedRefundBase(line.totalPrice, line.quantity, 0, line.activeQuantity);
+    // 대상은 주문 시점 목록으로 고정하므로 즉시할인 판정에 쓰는 정가는 금액과 같게 둔다
+    return {
+      lineId: line.lineId,
+      productId: line.productId,
+      quantity: line.activeQuantity,
+      baseAmount: remaining,
+      amount: remaining,
+    };
+  });
+  const recomputed = quotePricing({
+    lines: pricingLines,
+    coupons: coupons.map((coupon) => ({
+      rule: coupon.rule,
+      couponKey: coupon.couponKey,
+      lineId: coupon.lineId,
+      eligibleLineIds: coupon.eligibleLineIds,
+    })),
+    delivery: null,
+    // 기간·회원·첫 구매 조건은 결제 시작에서 이미 통과했다 — 대상과 최소 금액만 남은 금액으로 다시 본다
+    firstOrder: true,
+    isMember: true,
+    now: new Date(0), // ignoreEligibility라 기간을 보지 않는다
+    ignoreEligibility: true,
+  });
+
+  const base = coupons.map((coupon, index) => {
+    const allocatedRemaining = input.lines.reduce((sum, line) => {
+      const allocation = line.allocations
+        .filter((a) => a.couponKey === coupon.couponKey)
+        .reduce((acc, a) => acc + a.amount, 0);
+      return sum + proratedRefundBase(allocation, line.quantity, 0, line.activeQuantity);
+    }, 0);
+    const result = recomputed.coupons[index];
+    const stillApplied = result?.applied === true;
+    const state = input.settlements[coupon.couponKey] ?? {};
+    return {
+      couponKey: coupon.couponKey,
+      allocatedRemaining,
+      recomputed: stillApplied ? (result?.discount ?? 0) : 0,
+      target: stillApplied ? 0 : allocatedRemaining,
+      charged: Math.max(0, state.charged ?? 0),
+      waived: Math.max(0, state.waived ?? 0),
+    };
+  });
+
+  // 되돌림을 먼저 정한다 — 되돌린 금액만큼 이번 환불에서 뺄 수 있는 여유가 생긴다
+  const entries: CouponSettlementEntry[] = [];
+  let refundAmount = 0;
+  for (const item of base) {
+    const delta = item.target - (item.charged + item.waived);
+    let refund = 0;
+    let waived = item.waived;
+    if (delta < 0) {
+      // 구매자에게 유리하게 앞서 뺀 차감부터 돌려주고, 남은 초과분은 면제 기록에서 지운다
+      refund = Math.min(item.charged, -delta);
+      waived = Math.max(0, waived - (-delta - refund));
+    }
+    refundAmount += refund;
+    entries.push({
+      couponKey: item.couponKey,
+      allocatedRemaining: item.allocatedRemaining,
+      recomputed: item.recomputed,
+      target: item.target,
+      charge: 0,
+      refund,
+      waive: 0,
+      next: { charged: item.charged - refund, waived },
+    });
+  }
+
+  let capacity = Math.max(0, input.chargeableAmount) + refundAmount;
+  let chargeAmount = 0;
+  const chargeAllowed = input.shortfallCharge && !input.sellerFault;
+  for (const entry of entries) {
+    const delta = entry.target - (entry.next.charged + entry.next.waived);
+    if (delta <= 0) continue;
+    if (!chargeAllowed) {
+      entry.waive = delta;
+      entry.next = { ...entry.next, waived: entry.next.waived + delta };
+      continue;
+    }
+    const charge = Math.min(delta, capacity);
+    if (charge <= 0) continue;
+    capacity -= charge;
+    chargeAmount += charge;
+    entry.charge = charge;
+    entry.next = { ...entry.next, charged: entry.next.charged + charge };
+  }
+  return { chargeAmount, refundAmount, entries };
+}
+
+/**
+ * 주문상품의 실결제 금액 중 이번 취소 수량의 몫 — **실결제 금액(`totalPrice − couponDiscountAmount`)을
+ * 누적 내림의 차분으로 나눈다.**
+ *
+ * 상품 금액과 쿠폰 배분을 따로 나눠 빼면 합은 같지만 한 번의 몫이 −1원이 되는 경우가 있다
+ * (예: 금액 3원·할인 2원·수량 5개에서 셋째 개). 음수를 0으로 자르면 합이 1원 넘친다. 실결제 금액을
+ * 바로 나누면 몫이 항상 0 이상이고 전량 취소의 합이 실결제 금액과 정확히 같다.
+ */
+export function proratedPaidRefundBase(
+  item: { totalPrice: number; couponDiscountAmount?: number | null; quantity: number },
+  settledQuantity: number,
+  cancelQuantity: number,
+): number {
+  const paid = Math.max(0, item.totalPrice - (item.couponDiscountAmount ?? 0));
+  return proratedRefundBase(paid, item.quantity, settledQuantity, cancelQuantity);
+}