@sayren/store-sdk 0.50.0 → 0.52.0

package/src/schemas/promotion.ts

@@ -94,6 +94,142 @@ export const couponBenefitSchema = z
   });
 export type CouponBenefit = z.infer<typeof couponBenefitSchema>;
 
+/** 구간 할인의 구간 수 상한 */
+export const COUPON_REWARD_TIER_MAX = 5;
+
+const rewardShortfallChargeSchema = z
+  .boolean()
+  .describe(
+    "부분 취소로 할인액이 줄면 그 차액을 환불에서 뺀다. 상점 환불 정책 `couponShortfallCharge`가 꺼져 있거나 판매자 귀책이면 빼지 않는다",
+  );
+
+/**
+ * 확장 혜택(이슈 #222 혜택 확장) — 있으면 계산의 원천이고 `benefit`은 가장 가까운 값이다.
+ * - `TIERED`: 기준 금액(주문 쿠폰은 상품 쿠폰 차감 뒤 대상 합계, 상품 쿠폰은 그 줄 금액)이 넘은 가장 높은 구간의 할인. 첫 구간 미만이면 `MIN_ORDER_AMOUNT`
+ * - `BUY_X_GET_Y`: 상품 쿠폰만. 걸린 줄 수량을 `buy + get`개 묶음으로 세어 묶음마다 `get`개를 `rate`% 할인
+ * - `POINT`: 주문 쿠폰만. 할인 대신 대상 줄 실결제(쿠폰·적립금 뒤)에 `benefit`을 적용한 적립금을 구매확정 때 준다
+ */
+export const couponRewardSchema = z
+  .discriminatedUnion("type", [
+    z.object({
+      type: z.literal("TIERED"),
+      tiers: z
+        .array(
+          z.object({
+            minAmount: z.number().int().min(0).describe("이 구간의 기준 금액 하한(원)"),
+            benefit: couponBenefitSchema,
+          }),
+        )
+        .min(2)
+        .max(COUPON_REWARD_TIER_MAX)
+        .describe("구간. 기준 금액 하한 오름차순"),
+      shortfallCharge: rewardShortfallChargeSchema,
+    }),
+    z.object({
+      type: z.literal("BUY_X_GET_Y"),
+      buy: z.number().int().min(1).max(99).describe("구매 수량(N+1의 N)"),
+      get: z.number().int().min(1).max(99).describe("할인 수량(N+1의 1)"),
+      rate: z.number().int().min(1).max(100).describe("할인 수량의 할인율(%). 100이면 무료"),
+      shortfallCharge: rewardShortfallChargeSchema,
+    }),
+    z.object({
+      type: z.literal("POINT"),
+      benefit: couponBenefitSchema.describe(
+        "적립 방식. `RATE`=대상 실결제의 %(최대 `maxDiscountAmount`), `AMOUNT`=고정 적립금",
+      ),
+    }),
+  ])
+  .superRefine((reward, ctx) => {
+    if (reward.type !== "TIERED") return;
+    reward.tiers.forEach((tier, index) => {
+      const prev = reward.tiers[index - 1];
+      if (prev && tier.minAmount <= prev.minAmount) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["tiers", index, "minAmount"],
+          message: "구간 하한은 앞 구간보다 커야 합니다",
+        });
+      }
+    });
+  })
+  .describe("확장 혜택(구간 할인·N+1·적립금 지급). 없으면 `benefit`이 혜택이다");
+export type CouponReward = z.infer<typeof couponRewardSchema>;
+
+/** 확장 혜택을 쓸 수 있는 쿠폰 종류 */
+export const COUPON_REWARD_KINDS: Record<CouponReward["type"], readonly CouponKind[]> = {
+  TIERED: ["ORDER", "PRODUCT"],
+  BUY_X_GET_Y: ["PRODUCT"],
+  POINT: ["ORDER"],
+};
+
+/** 응답·옛 칸의 `benefit` — 확장 혜택에서 가장 가까운 값(구간은 첫 구간, N+1은 묶음 평균 할인율, 적립금은 할인 0원에 가까운 1원) */
+export function couponBenefitOfReward(reward: CouponReward): CouponBenefit {
+  if (reward.type === "TIERED") return (reward.tiers[0] as { benefit: CouponBenefit }).benefit;
+  if (reward.type === "BUY_X_GET_Y") {
+    // 묶음 평균 할인율(1+1 무료 → 50%) — 확장 혜택을 모르는 소비자에게 「100% 할인」으로 보이지 않게
+    const value = Math.max(1, Math.floor((reward.rate * reward.get) / (reward.buy + reward.get)));
+    return { type: "RATE", value, maxDiscountAmount: null };
+  }
+  return { type: "AMOUNT", value: 1, maxDiscountAmount: null };
+}
+
+/** 구간 할인의 적용 구간 — 기준 금액이 넘은 가장 높은 구간. 없으면 null */
+export function couponTierOf(
+  reward: Extract<CouponReward, { type: "TIERED" }>,
+  base: number,
+): { index: number; benefit: CouponBenefit } | null {
+  for (let index = reward.tiers.length - 1; index >= 0; index--) {
+    const tier = reward.tiers[index];
+    if (tier && base >= tier.minAmount) return { index, benefit: tier.benefit };
+  }
+  return null;
+}
+
+/**
+ * 쿠폰 한 장의 할인액 — 확장 혜택까지 보는 원천이다(`quotePricing`·최대 조합이 같이 쓴다).
+ * `line`은 상품 쿠폰이 걸린 줄의 금액·수량이고 N+1만 수량을 읽는다. 적립금 지급은 할인이 0이다.
+ */
+export function couponRuleDiscountOf(
+  rule: Pick<CouponRule, "benefit" | "reward">,
+  base: number,
+  line: { quantity: number } | null,
+  rules: MoneyRules = KRW_MONEY_RULES,
+): number {
+  const reward = rule.reward;
+  if (!reward) return couponDiscountOf(rule.benefit, base, rules);
+  if (reward.type === "POINT") return 0;
+  if (reward.type === "TIERED") {
+    const tier = couponTierOf(reward, base);
+    return tier ? couponDiscountOf(tier.benefit, base, rules) : 0;
+  }
+  const quantity = line?.quantity ?? 0;
+  if (base <= 0 || quantity <= 0) return 0;
+  const units = Math.floor(quantity / (reward.buy + reward.get)) * reward.get;
+  // 같은 줄은 단가가 같다 — 할인 수량의 금액은 줄 금액의 수량 비율(내림)이다
+  const unitsAmount = Math.floor((base * units) / quantity);
+  if (reward.rate === 100) return unitsAmount;
+  return couponDiscountOf(
+    { type: "RATE", value: reward.rate, maxDiscountAmount: null },
+    unitsAmount,
+    rules,
+  );
+}
+
+/**
+ * 적립금 지급 쿠폰의 적립금 — 대상 줄 실결제(쿠폰·적립금 뒤)에 혜택을 적용하고 줄에 실결제 비율로 나눈다.
+ * 결제 시작(`quotePricing`)과 구매확정 지급이 같은 함수다(구매확정은 주문상품의 실결제를 넣는다).
+ */
+export function couponPointRewardOf(
+  reward: Extract<CouponReward, { type: "POINT" }>,
+  paidByLine: readonly number[],
+  rules: MoneyRules = KRW_MONEY_RULES,
+): { total: number; shares: number[] } {
+  const weights = paidByLine.map((paid) => Math.max(0, paid));
+  const base = weights.reduce((sum, w) => sum + w, 0);
+  const total = couponDiscountOf(reward.benefit, base, rules);
+  return { total, shares: total > 0 ? allocateByWeight(total, weights) : weights.map(() => 0) };
+}
+
 /** 쿠폰 사용 조건 */
 export const couponConditionsSchema = z.object({
   minOrderAmount: z.number().int().min(0).describe(descriptions.minOrderAmount),
@@ -174,6 +310,7 @@ export const couponRuleSchema = z.object({
   stacking: couponStackingSchema
     .optional()
     .describe("중복 사용 정책(이슈 #222). 없으면 종류별 한 장·서로 결합·적립금과 함께"),
+  reward: couponRewardSchema.optional(),
 });
 export type CouponRule = z.infer<typeof couponRuleSchema>;
 
@@ -381,6 +518,10 @@ export interface PricingCouponResult {
   eligibleLineIds: string[];
   /** 판정에 쓴 사실 값 중 이 쿠폰의 사용 조건이 읽은 것 — 주문 스냅샷에 굳힌다. 읽은 값이 없으면 빈 객체 */
   facts: CouponFacts;
+  /** 적립금 지급 쿠폰이 구매확정 때 줄 적립금(지금 수량 기준). 그 밖은 0 */
+  rewardPoint: number;
+  /** 구간 할인이 적용한 구간 순번. 그 밖은 null — 환불 정산이 구간이 내려갔는지 본다 */
+  tierIndex: number | null;
 }
 
 export interface PricingBundleResult {
@@ -395,6 +536,8 @@ export interface PricingResult {
   coupons: PricingCouponResult[];
   /** 배송비 쿠폰의 묶음별 배분 */
   bundles: PricingBundleResult[];
+  /** 적립금 지급 쿠폰의 적립 예정 합계 — 결제 금액에 영향이 없다 */
+  rewardPointAmount: number;
   /** 상품 금액 합 (즉시할인 반영, 쿠폰 전) */
   productAmount: number;
   /** 상품·주문 쿠폰 할인 합계 */
@@ -535,6 +678,8 @@ export function quotePricing(input: PricingInput): PricingResult {
     lineId: null,
     eligibleLineIds: [],
     facts: {},
+    rewardPoint: 0,
+    tierIndex: null,
   }));
 
   const subtotal = lines.reduce((sum, entry) => sum + entry.line.amount, 0);
@@ -596,9 +741,11 @@ export function quotePricing(input: PricingInput): PricingResult {
   /** 적용된 쿠폰 — 같은 쿠폰 정의의 장수(`perOrderLimit`)와 결합 판정에 쓴다 */
   const appliedCount = new Map<string, number>();
   const applied: PricingCoupon[] = [];
-  const apply = (index: number, discount: number, lineId: string | null) => {
+  const apply = (index: number, discount: number, lineId: string | null, base = 0) => {
     const result = results[index] as PricingCouponResult;
     const coupon = input.coupons[index] as PricingCoupon;
+    const reward = coupon.rule.reward;
+    if (reward?.type === "TIERED") result.tierIndex = couponTierOf(reward, base)?.index ?? null;
     result.applied = true;
     result.discount = discount;
     result.lineId = lineId;
@@ -622,6 +769,17 @@ export function quotePricing(input: PricingInput): PricingResult {
     return blocked;
   };
 
+  /** 상품 쿠폰을 줄 하나에 걸었을 때의 할인 — N+1은 그 줄 수량을 센다 */
+  const productDiscountOn = (coupon: PricingCoupon, lineId: string) => {
+    const line = lineOf(lineId)?.line;
+    return couponRuleDiscountOf(coupon.rule, line?.amount ?? 0, line ?? null, rules);
+  };
+  /** 할인이 0일 때의 사유 — 구간 할인이 첫 구간에 못 미치면 최소 금액 미달이다 */
+  const zeroReasonOf = (coupon: PricingCoupon, base: number): CouponRejectReason =>
+    coupon.rule.reward?.type === "TIERED" && couponTierOf(coupon.rule.reward, base) === null
+      ? "MIN_ORDER_AMOUNT"
+      : "NO_DISCOUNT";
+
   // 2) 상품 쿠폰 — 한 줄에 한 장. 줄을 지정한 쿠폰을 먼저 걸고, 나머지는 대상 줄이 적은 쿠폰부터
   //    할인이 가장 큰 남은 줄(같으면 앞 줄)에 건다. 대상이 넓은 쿠폰이 좁은 쿠폰의 유일한 줄을 먼저 가져가지 않게 한다
   const productIndexes = passed.filter((index) => input.coupons[index]?.rule.kind === "PRODUCT");
@@ -650,14 +808,14 @@ export function quotePricing(input: PricingInput): PricingResult {
         continue;
       }
       chosen = coupon.lineId;
-      best = couponDiscountOf(coupon.rule.benefit, lineOf(chosen)?.line.amount ?? 0, rules);
+      best = productDiscountOn(coupon, chosen);
     } 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, rules);
+        const discount = productDiscountOn(coupon, id);
         if (chosen === null || discount > best) {
           chosen = id;
           best = discount;
@@ -666,13 +824,13 @@ export function quotePricing(input: PricingInput): PricingResult {
     }
     const entry = chosen === null ? undefined : lineOf(chosen);
     if (!entry || chosen === null || best <= 0) {
-      result.rejectReason = "NO_DISCOUNT";
+      result.rejectReason = zeroReasonOf(coupon, entry?.line.amount ?? 0);
       continue;
     }
     takenLines.add(chosen);
     entry.productDiscount += best;
     entry.allocations.push({ couponKey: result.couponKey, amount: best });
-    apply(index, best, chosen);
+    apply(index, best, chosen, entry.line.amount);
   }
 
   // 3) 주문 쿠폰 — 상품 쿠폰 차감 뒤 금액 기준, 대상 줄에 금액 비율로 배분
@@ -692,9 +850,19 @@ export function quotePricing(input: PricingInput): PricingResult {
       .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, rules);
+    // 적립금 지급은 할인 없이 자리를 차지하고, 적립금은 실결제가 정해진 뒤(5 뒤) 계산한다
+    if (coupon.rule.reward?.type === "POINT") {
+      if (base <= 0) {
+        result.rejectReason = "NO_DISCOUNT";
+        continue;
+      }
+      orderSlot = true;
+      apply(index, 0, null);
+      continue;
+    }
+    const discount = couponRuleDiscountOf(coupon.rule, base, null, rules);
     if (discount <= 0) {
-      result.rejectReason = "NO_DISCOUNT";
+      result.rejectReason = zeroReasonOf(coupon, base);
       continue;
     }
     const shares = allocateByWeight(discount, weights);
@@ -703,7 +871,7 @@ export function quotePricing(input: PricingInput): PricingResult {
       if (share > 0) entry.allocations.push({ couponKey: result.couponKey, amount: share });
     });
     orderSlot = true;
-    apply(index, discount, null);
+    apply(index, discount, null, base);
   }
 
   // 4) 배송비 쿠폰 — 기본 배송비(지역 추가 제외) 기준, 묶음에 기본 배송비 비율로 배분
@@ -727,7 +895,7 @@ export function quotePricing(input: PricingInput): PricingResult {
     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);
+    const discount = couponRuleDiscountOf(coupon.rule, base, null, rules);
     if (discount <= 0) {
       result.rejectReason = "NO_DISCOUNT";
       continue;
@@ -794,10 +962,24 @@ export function quotePricing(input: PricingInput): PricingResult {
       });
     }
   }
+  // 6) 적립금 지급 쿠폰 — 대상 줄의 실결제(쿠폰·사용 적립금 뒤)로 계산한다. 구매확정 지급도 같은 함수다
+  let rewardPointAmount = 0;
+  input.coupons.forEach((coupon, index) => {
+    const result = results[index] as PricingCouponResult;
+    const reward = coupon.rule.reward;
+    if (!result.applied || reward?.type !== "POINT") return;
+    const paid = result.eligibleLineIds.map((id) => {
+      const line = lineResults[lineIndex.get(id) ?? -1];
+      return line ? line.amount - line.couponDiscount - line.pointAllocation : 0;
+    });
+    result.rewardPoint = couponPointRewardOf(reward, paid, rules).total;
+    rewardPointAmount += result.rewardPoint;
+  });
   return {
     lines: lineResults,
     coupons: results,
     bundles,
+    rewardPointAmount,
     productAmount,
     couponDiscountAmount,
     deliveryFee,
@@ -927,7 +1109,7 @@ export interface CouponSettlementEntry {
   allocatedRemaining: number;
   /** 남은 주문상품으로 다시 계산한 할인 — 쿠폰 조건을 잃었으면 0 */
   recomputed: number;
-  /** 누적 미달분 목표 = 조건을 잃었으면 `allocatedRemaining`, 아니면 0 */
+  /** 누적 미달분 목표 = 조건을 잃었으면 `allocatedRemaining`, 차액 정산 쿠폰은 `allocatedRemaining − recomputed`(음수면 더 돌려준다), 아니면 0 */
   target: number;
   charge: number;
   refund: number;
@@ -949,6 +1131,47 @@ export const NO_COUPON_SETTLEMENT: CouponSettlementResult = {
   entries: [],
 };
 
+/**
+ * 주문이 받은 쿠폰을 수량 `quantityOf(줄)`로 다시 계산한다 — 환불 정산(`settleCouponShortfall`)과 적립금 지급 쿠폰의 구매확정 적립이 같이 쓴다.
+ * 기간·회원 전용은 결제 시작에서 이미 통과했다. 사용 조건 트리는 주문 시점 사실 값 + 남은 금액으로 다시 보고,
+ * 스냅샷에 없는 구매자·시각 값(옛 주문)은 통과한 것으로 둔다 — 주문서 집계(`cart.*`)만 남은 금액으로 다시 판정한다
+ */
+export function recomputeOrderCoupons(
+  coupons: readonly AppliedCouponSnapshot[],
+  lines: readonly CouponSettlementLine[],
+  quantityOf: (line: CouponSettlementLine) => number = (line) => line.activeQuantity,
+): PricingResult {
+  return quotePricing({
+    lines: lines.map((line) => {
+      const quantity = quantityOf(line);
+      const amount = proratedRefundBase(line.totalPrice, line.quantity, 0, quantity);
+      // 대상은 주문 시점 목록으로 고정하므로 즉시할인 판정에 쓰는 정가는 금액과 같게 둔다
+      return {
+        lineId: line.lineId,
+        productId: line.productId,
+        quantity,
+        baseAmount: amount,
+        amount,
+      };
+    }),
+    coupons: coupons.map((coupon) => {
+      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,
+    isMember: true,
+    now: new Date(0), // ignoreEligibility라 기간을 보지 않는다. 시각 조건은 스냅샷 값이거나 통과로 둔다
+    ignoreEligibility: true,
+  });
+}
+
 /**
  * 쿠폰 조건 미달 차감 — **순수 함수다.** 부분 취소·반품으로 남은 주문상품이 쿠폰 조건을 잃으면,
  * 남은 주문상품이 받던 할인만큼을 이번 환불에서 뺀다.
@@ -959,6 +1182,9 @@ export const NO_COUPON_SETTLEMENT: CouponSettlementResult = {
  * - 쿠폰이 **여전히 적용되면 목표 0**, 조건을 잃었으면 목표 = `allocatedRemaining`이다. 적용되는 쿠폰의
  *   정률 10원 내림 차이까지 차감하면 조건을 지킨 구매자가 몇 원씩 잃는다 — 조건을 잃은 경우만 본다.
  *   재계산 할인이 더 커지는 경우(정률 최대 할인액)도 차감하지 않고 더 돌려주지도 않는다.
+ * - 확장 혜택(구간 할인·N+1)에서 셀러가 차액 정산(`reward.shortfallCharge`)을 켰으면 적용이 유지돼도 목표가
+ *   `allocatedRemaining − recomputed`다. 구간 할인은 구간이 내려갔을 때만 보고 0 아래로 내리지 않는다. N+1만 음수 목표를 허용한다
+ *   (남은 수량의 할인 개수가 배분보다 많으면 그만큼 더 돌려주고 누적 차감이 음수로 남는다). 뒤의 환불이 그 몫을 되찾을 때는 판매자 귀책·정책 꺼짐이어도 면제하지 않는다.
  * - `delta` = 목표 − (이미 차감 + 이미 면제). 양수면 청구하고(판매자 귀책·정책 꺼짐이면 면제로 기록),
  *   음수면 앞서 뺀 차감부터 돌려준다. 마지막 활성 수량까지 취소되면 목표가 0이라 누적 차감이 모두 되돌아가고,
  *   전량 취소의 환불 합계가 결제액과 같아진다.
@@ -972,37 +1198,13 @@ export function settleCouponShortfall(input: CouponSettlementInput): CouponSettl
   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) => {
-      // 기간·회원 전용은 결제 시작에서 이미 통과했다. 사용 조건 트리는 주문 시점 사실 값 + 남은 금액으로 다시 본다.
-      // 스냅샷에 없는 구매자·시각 값(옛 주문)은 결제 시작에서 통과한 것으로 둔다 — 주문서 집계(`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,
-    isMember: true,
-    now: new Date(0), // ignoreEligibility라 기간을 보지 않는다. 시각 조건은 스냅샷 값이거나 통과로 둔다
-    ignoreEligibility: true,
-  });
+  const recompute = (quantityOf: (line: CouponSettlementLine) => number) =>
+    recomputeOrderCoupons(coupons, input.lines, quantityOf);
+  const recomputed = recompute((line) => line.activeQuantity);
+  // 차액 차감(확장 혜택) — 구간 할인은 구간이 내려갔을 때만 본다(같은 구간의 정률 내림 차이로 몇 원씩 빼지 않는다)
+  const original = coupons.some((coupon) => coupon.rule.reward?.type === "TIERED")
+    ? recompute((line) => line.quantity)
+    : null;
 
   const base = coupons.map((coupon, index) => {
     const allocatedRemaining = input.lines.reduce((sum, line) => {
@@ -1013,13 +1215,30 @@ export function settleCouponShortfall(input: CouponSettlementInput): CouponSettl
     }, 0);
     const result = recomputed.coupons[index];
     const stillApplied = result?.applied === true;
+    const recomputedDiscount = stillApplied ? (result?.discount ?? 0) : 0;
     const state = input.settlements[coupon.couponKey] ?? {};
+    const reward = coupon.rule.reward;
+    // 차액 정산 쿠폰은 목표가 음수일 수 있다(남은 수량의 할인이 배분보다 크면 그만큼 더 돌려준다 — N+1 홀수 잔량)
+    // 차액 정산 — 구간 할인은 구간이 내려갔을 때만, 0 아래로는 내리지 않는다(구간이 내려가 더 돌려주는 일은 없다).
+    // N+1은 할인 개수가 정수라 남은 수량의 할인이 배분보다 클 수 있다 — 그 차이만 음수 목표(더 돌려줌)다
+    const tiered =
+      reward?.type === "TIERED" &&
+      reward.shortfallCharge &&
+      (result?.tierIndex ?? -1) < (original?.coupons[index]?.tierIndex ?? -1);
+    const signed = reward?.type === "BUY_X_GET_Y" && reward.shortfallCharge;
     return {
       couponKey: coupon.couponKey,
       allocatedRemaining,
-      recomputed: stillApplied ? (result?.discount ?? 0) : 0,
-      target: stillApplied ? 0 : allocatedRemaining,
-      charged: Math.max(0, state.charged ?? 0),
+      recomputed: recomputedDiscount,
+      target: !stillApplied
+        ? allocatedRemaining
+        : signed
+          ? allocatedRemaining - recomputedDiscount
+          : tiered
+            ? Math.max(0, allocatedRemaining - recomputedDiscount)
+            : 0,
+      signed,
+      charged: signed ? (state.charged ?? 0) : Math.max(0, state.charged ?? 0),
       waived: Math.max(0, state.waived ?? 0),
     };
   });
@@ -1032,9 +1251,13 @@ export function settleCouponShortfall(input: CouponSettlementInput): CouponSettl
     let refund = 0;
     let waived = item.waived;
     if (delta < 0) {
-      // 구매자에게 유리하게 앞서 뺀 차감부터 돌려주고, 남은 초과분은 면제 기록에서 지운다
-      refund = Math.min(item.charged, -delta);
-      waived = Math.max(0, waived - (-delta - refund));
+      // 구매자에게 유리하게 앞서 뺀 차감부터 돌려주고, 남은 초과분은 면제 기록에서 지운다.
+      // 차액 정산 쿠폰은 그래도 남으면 더 돌려준다(누적 차감이 음수가 되고, 뒤의 환불이 목표로 돌아오며 다시 맞춘다)
+      refund = Math.min(Math.max(0, item.charged), -delta);
+      const rest = -delta - refund;
+      const unwaived = Math.min(waived, rest);
+      waived -= unwaived;
+      if (item.signed) refund += rest - unwaived;
     }
     refundAmount += refund;
     entries.push({
@@ -1053,8 +1276,22 @@ export function settleCouponShortfall(input: CouponSettlementInput): CouponSettl
   let chargeAmount = 0;
   const chargeAllowed = input.shortfallCharge && !input.sellerFault;
   for (const entry of entries) {
-    const delta = entry.target - (entry.next.charged + entry.next.waived);
+    let delta = entry.target - (entry.next.charged + entry.next.waived);
     if (delta <= 0) continue;
+    // 앞서 더 돌려준 몫(음수 누적)을 되찾는 것은 차감이 아니다 — 판매자 귀책·정책 꺼짐에도 면제하지 않는다.
+    // 면제로 적으면 환불 합계가 결제액을 넘는다
+    const owed = Math.max(0, -entry.next.charged);
+    if (owed > 0) {
+      const reclaim = Math.min(delta, owed, capacity);
+      if (reclaim > 0) {
+        capacity -= reclaim;
+        chargeAmount += reclaim;
+        entry.charge += reclaim;
+        entry.next = { ...entry.next, charged: entry.next.charged + reclaim };
+      }
+      delta -= Math.min(delta, owed);
+      if (delta <= 0) continue;
+    }
     if (!chargeAllowed) {
       entry.waive = delta;
       entry.next = { ...entry.next, waived: entry.next.waived + delta };
@@ -1064,7 +1301,7 @@ export function settleCouponShortfall(input: CouponSettlementInput): CouponSettl
     if (charge <= 0) continue;
     capacity -= charge;
     chargeAmount += charge;
-    entry.charge = charge;
+    entry.charge += charge;
     entry.next = { ...entry.next, charged: entry.next.charged + charge };
   }
   return { chargeAmount, refundAmount, entries };

package/src/schemas/userinfo.ts

@@ -0,0 +1,118 @@
+import * as z from "zod";
+
+/**
+ * 구매자 정보의 OIDC userinfo 표준 클레임(OpenID Connect Core 1.0 5.1, 이슈 #264). 이름은 표준 그대로 snake_case다.
+ * 값이 없는 클레임은 응답에서 빠진다. 같은 형식이 스토어프론트 API(storefront-sdk `userinfoSchema`)에도 있다.
+ */
+
+/** 생일 — `YYYY-MM-DD`, 연도를 모르면 `0000-MM-DD`(표준 형식) */
+export const CUSTOMER_BIRTHDATE_PATTERN = /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/;
+
+export const customerUserinfoAddressSchema = z.object({
+  formatted: z.string().optional(),
+  street_address: z.string().optional(),
+  locality: z.string().optional(),
+  region: z.string().optional(),
+  postal_code: z.string().optional(),
+  country: z.string().optional().describe("ISO 3166-1 alpha-2"),
+});
+
+export const customerUserinfoSchema = z
+  .object({
+    sub: z.string().describe("구매자 id(상점 안에서 유일)"),
+    name: z.string().optional(),
+    given_name: z.string().optional(),
+    family_name: z.string().optional(),
+    middle_name: z.string().optional(),
+    nickname: z.string().optional(),
+    preferred_username: z.string().optional(),
+    profile: z.string().optional(),
+    picture: z.string().optional(),
+    website: z.string().optional(),
+    email: z.string().optional(),
+    email_verified: z
+      .boolean()
+      .optional()
+      .describe("이메일 확인 여부 — 인증된 소셜 가입·셀러 위임만 true다. 비밀번호 가입은 false"),
+    gender: z.string().optional().describe("표준 값은 `female`·`male`이고 다른 값도 온다"),
+    birthdate: z.string().optional().describe("`YYYY-MM-DD`, 연도를 모르면 `0000-MM-DD`"),
+    zoneinfo: z.string().optional().describe("IANA 시간대(예: `Asia/Seoul`)"),
+    locale: z.string().optional().describe("BCP 47 언어 태그(예: `ko-KR`)"),
+    phone_number: z.string().optional().describe("E.164(예: `+821012345678`)"),
+    phone_number_verified: z.boolean().optional(),
+    address: customerUserinfoAddressSchema.optional().describe("기본 배송지에서 만든다"),
+    updated_at: z.number().int().optional().describe("프로필을 바꾼 시각(epoch 초)"),
+  })
+  .describe("OIDC userinfo 표준 클레임(이슈 #264)");
+export type CustomerUserinfo = z.infer<typeof customerUserinfoSchema>;
+
+const text = (max: number) => z.string().trim().min(1).max(max).nullable().optional();
+const httpsUrl = z
+  .url({ protocol: /^https$/ })
+  .max(2048)
+  .nullable()
+  .optional()
+  .describe("https 주소");
+
+/** 시간대·언어 태그 검사 — 런타임(Intl)이 아는 값만 받는다 */
+const zoneinfo = z
+  .string()
+  .max(64)
+  .refine((value) => {
+    try {
+      new Intl.DateTimeFormat("en", { timeZone: value });
+      return true;
+    } catch {
+      return false;
+    }
+  }, "IANA 시간대가 아닙니다")
+  .nullable()
+  .optional();
+const locale = z
+  .string()
+  .max(35)
+  .refine((value) => {
+    try {
+      return Intl.getCanonicalLocales(value).length === 1;
+    } catch {
+      return false;
+    }
+  }, "BCP 47 언어 태그가 아닙니다")
+  .nullable()
+  .optional();
+const birthdate = z
+  .string()
+  .regex(CUSTOMER_BIRTHDATE_PATTERN, "생일은 YYYY-MM-DD(연도를 모르면 0000-MM-DD)입니다")
+  .refine((value) => {
+    const [y, m, d] = value.split("-").map(Number) as [number, number, number];
+    // 연도를 모르면 윤년(2000)으로 날짜만 본다
+    const day = new Date(Date.UTC(y === 0 ? 2000 : y, m - 1, d));
+    return day.getUTCMonth() === m - 1 && day.getUTCDate() === d;
+  }, "없는 날짜입니다")
+  .nullable()
+  .optional();
+
+/**
+ * 셀러가 위임으로 바꿀 수 있는 클레임 — 준 클레임만 바뀌고 null은 지운다. `sub`·`email`·`phone_number`·`updated_at`·`address`는 받지 않는다. 확인 여부(`*_verified`)는 셀러가 확인한 값을 받는다
+ * (이메일·휴대폰은 각자의 칸, 주소는 배송지가 원천이다)
+ */
+export const customerUserinfoInputSchema = z
+  .strictObject({
+    /** 셀러가 확인한 값 그대로 받는다 — 셀러 서비스가 인증한 회원이다 */
+    email_verified: z.boolean().optional(),
+    phone_number_verified: z.boolean().optional(),
+    given_name: text(50),
+    family_name: text(50),
+    middle_name: text(50),
+    nickname: text(50),
+    preferred_username: text(50),
+    profile: httpsUrl,
+    picture: httpsUrl,
+    website: httpsUrl,
+    gender: text(30),
+    birthdate,
+    zoneinfo,
+    locale,
+  })
+  .describe("바꿀 OIDC 클레임 — 준 것만 바뀌고 null은 지운다");
+export type CustomerUserinfoInput = z.infer<typeof customerUserinfoInputSchema>;

package/dist/webhook-headers-D6QmPdEJ.d.mts

@@ -1,22 +0,0 @@
-//#region src/webhook-headers.d.ts
-/** 웹훅 발송 요청 헤더 상수 (공개 계약). zod 의존 없이 서버 엔트리포인트에서도 가볍게 쓴다 */
-/** 서명 헤더. 형식: `t=<unix초>,v1=<hex>[,v1=<hex>]` */
-declare const WEBHOOK_SIGNATURE_HEADER = "Sayren-Signature";
-/** 이벤트 ID 헤더. 본문 `id`와 같다. 중복 제거 키 */
-declare const WEBHOOK_EVENT_ID_HEADER = "Sayren-Event-Id";
-/** 이벤트 타입 헤더. 본문 `type`과 같다 */
-declare const WEBHOOK_EVENT_TYPE_HEADER = "Sayren-Event-Type";
-/** 전송 기록 ID 헤더. 전송 기록의 `deliveryId`와 같다 */
-declare const WEBHOOK_DELIVERY_ID_HEADER = "Sayren-Delivery-Id";
-/** 발송 요청의 `User-Agent` 값 */
-declare const WEBHOOK_USER_AGENT = "Sayren-Webhooks/1.0";
-/** 수신 측 권장 타임스탬프 허용 오차(초) */
-declare const WEBHOOK_DEFAULT_TOLERANCE_SEC = 300;
-declare const WEBHOOK_HEADERS: {
-  readonly signature: "Sayren-Signature";
-  readonly eventId: "Sayren-Event-Id";
-  readonly eventType: "Sayren-Event-Type";
-  readonly deliveryId: "Sayren-Delivery-Id";
-};
-//#endregion
-export { WEBHOOK_HEADERS as a, WEBHOOK_EVENT_TYPE_HEADER as i, WEBHOOK_DELIVERY_ID_HEADER as n, WEBHOOK_SIGNATURE_HEADER as o, WEBHOOK_EVENT_ID_HEADER as r, WEBHOOK_USER_AGENT as s, WEBHOOK_DEFAULT_TOLERANCE_SEC as t };