@sayren/store-sdk 0.51.0 → 0.52.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sayren/store-sdk",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "main": "./dist/index.mjs",
   "types": "./dist/index.d.mts",
   "exports": {

package/src/schemas/coupon-selection.ts

@@ -1,6 +1,6 @@
 import { KRW_MONEY_RULES } from "./currency";
 import {
-  couponDiscountOf,
+  couponRuleDiscountOf,
   couponStackingOf,
   couponsCombinable,
   type PricingCoupon,
@@ -139,14 +139,19 @@ export function bestCouponSelection(input: CouponSelectionInput): CouponSelectio
   const orders = solo.filter((e) => e.candidate.coupon.rule.kind === "ORDER");
   const deliveries = solo.filter((e) => e.candidate.coupon.rule.kind === "DELIVERY");
   const lineIds = input.lines.map((line) => line.lineId);
-  const lineAmount = new Map(input.lines.map((line) => [line.lineId, line.amount]));
+  const lineById = new Map(input.lines.map((line) => [line.lineId, line]));
 
   /** 상품 쿠폰 한 장의 줄별 할인 — 대상 줄만, 줄 금액 기준 */
   const weightsOf = (entry: (typeof products)[number]) => {
     const eligible = new Set(entry.result?.eligibleLineIds ?? []);
     return lineIds.map((id) =>
       eligible.has(id)
-        ? couponDiscountOf(entry.candidate.coupon.rule.benefit, lineAmount.get(id) ?? 0, rules)
+        ? couponRuleDiscountOf(
+            entry.candidate.coupon.rule,
+            lineById.get(id)?.amount ?? 0,
+            lineById.get(id) ?? null,
+            rules,
+          )
         : 0,
     );
   };

package/src/schemas/coupon.ts

@@ -12,10 +12,12 @@ import {
 import { currencyCodeSchema } from "./currency";
 import {
   COUPON_CONDITIONS_DEFAULTS,
+  COUPON_REWARD_KINDS,
   COUPON_TARGET_LIST_MAX,
   couponBenefitSchema,
   couponConditionsSchema,
   couponKindSchema,
+  couponRewardSchema,
   couponTargetSchema,
 } from "./promotion";
 import { strictRequest } from "./strict";
@@ -103,6 +105,9 @@ const descriptions = {
     "발급 대상 트리(이슈 #222) — 셀러 지급·받기·회원가입 지급에서 누가 받을 수 있는가. 구매자 조건만. 코드 입력형에는 두지 않는다",
   stacking:
     "중복 사용 정책(이슈 #222). 생략하면 종류별 한 장·서로 결합·적립금과 함께. 결합은 양쪽 쿠폰이 모두 허용해야 성립한다",
+  reward:
+    "확장 혜택(구간 할인 `TIERED`·N+1 `BUY_X_GET_Y`·적립금 지급 `POINT`). 주면 `benefit`을 생략하고, 응답의 `benefit`은 가장 가까운 값이다. " +
+    "N+1은 상품 쿠폰만, 적립금 지급은 회원 전용 주문 쿠폰만이다. 수정에서 null이면 확장 혜택을 지운다(`benefit`이 필요하다)",
   issueStartsAt: "받기 시작 시각(받기 쿠폰만, 이슈 #222). 생략하면 사용 시작 시각을 따른다",
   issueEndsAt:
     "받기 종료 시각(받기 쿠폰만, 이 시각부터 못 받는다). 생략하면 사용 종료 시각을 따른다",
@@ -116,6 +121,7 @@ const ruleFields = {
   targetRules: couponTargetRulesSchema.optional().describe(descriptions.targetRules),
   audience: couponConditionTreeSchema.optional().describe(descriptions.audience),
   stacking: couponStackingSchema.optional().describe(descriptions.stacking),
+  reward: couponRewardSchema.nullable().optional().describe(descriptions.reward),
 };
 
 /**
@@ -141,6 +147,8 @@ export function couponRequestRuleIssues(body: {
   targetRules?: CouponRuleTrees["targetRules"];
   audience?: CouponRuleTrees["eligibility"];
   stacking?: { perOrderLimit: number };
+  reward?: { type: "TIERED" | "BUY_X_GET_Y" | "POINT" } | null;
+  benefit?: unknown;
   perMemberUseLimit?: number | null;
   dailyIssueLimit?: number | null;
   issueStartsAt?: string | null;
@@ -179,6 +187,27 @@ export function couponRequestRuleIssues(body: {
       ...(body.audience ? { audience: body.audience } : {}),
     }),
   );
+  if (!body.reward && body.benefit === undefined)
+    issues.push({ path: ["benefit"], message: "혜택(benefit 또는 reward)이 필요합니다" });
+  if (
+    body.reward &&
+    body.kind !== undefined &&
+    !(COUPON_REWARD_KINDS[body.reward.type] as readonly string[]).includes(body.kind)
+  )
+    issues.push({
+      path: ["reward", "type"],
+      message:
+        body.reward.type === "POINT"
+          ? "적립금 지급은 주문 쿠폰만 쓸 수 있습니다"
+          : body.reward.type === "BUY_X_GET_Y"
+            ? "N+1은 상품 쿠폰만 쓸 수 있습니다"
+            : "구간 할인은 배송비 쿠폰에 쓸 수 없습니다",
+    });
+  if (body.reward?.type === "POINT" && !conditions.memberOnly)
+    issues.push({
+      path: ["reward", "type"],
+      message: "적립금 지급은 회원 전용 쿠폰만 쓸 수 있습니다",
+    });
   if (body.stacking && body.stacking.perOrderLimit > 1 && body.kind !== "PRODUCT")
     issues.push({
       path: ["stacking", "perOrderLimit"],
@@ -250,7 +279,7 @@ export const createCouponRequestSchema = strictRequest(
       name: z.string().trim().min(1).max(60).describe(descriptions.name),
       description: z.string().max(300).nullable().optional().describe(descriptions.description),
       kind: couponKindSchema,
-      benefit: couponBenefitSchema,
+      benefit: couponBenefitSchema.optional().describe("혜택. `reward`를 주면 생략한다"),
       conditions: couponConditionsInputSchema
         .optional()
         .describe("사용 조건. 생략한 항목은 기본값(최소 금액 0, 회원 전용, 즉시할인과 중복 가능)"),
@@ -288,6 +317,8 @@ export const createCouponRequestSchema = strictRequest(
         ctx.addIssue({ code: "custom", path: [path], message });
       if (body.issueMethod === "CODE" && !body.code)
         issue("code", "코드 입력형 쿠폰은 코드가 필요합니다");
+      if (body.reward && body.benefit)
+        issue("benefit", "확장 혜택(reward)을 주면 benefit을 생략합니다");
       if (body.issueMethod === "VOUCHER" && !body.voucher)
         issue("voucher", "쿠폰 번호 쿠폰은 번호 설정이 필요합니다");
       if (body.issueMethod !== "VOUCHER" && body.voucher)
@@ -423,6 +454,11 @@ export const couponSchema = z.object({
     .optional()
     .default(COUPON_STACKING_DEFAULTS)
     .describe("중복 사용 정책(이슈 #222). 서버는 항상 싣는다"),
+  reward: couponRewardSchema
+    .nullable()
+    .optional()
+    .default(null)
+    .describe("확장 혜택. 없으면 null이고 `benefit`이 혜택이다. 서버는 항상 싣는다"),
   rulesOnly: z
     .boolean()
     .optional()

package/src/schemas/points.ts

@@ -180,6 +180,7 @@ export const POINT_LOT_SOURCES = [
   "ADJUST",
   "REFUND_RESTORE",
   "OPENING",
+  "COUPON",
 ] as const;
 export type PointLotSource = (typeof POINT_LOT_SOURCES)[number];
 
@@ -194,6 +195,7 @@ export const POINT_ENTRY_TYPES = [
   "EXPIRE",
   "ADJUST",
   "OPENING",
+  "EARN_COUPON",
 ] as const;
 export type PointEntryType = (typeof POINT_ENTRY_TYPES)[number];
 
@@ -257,7 +259,7 @@ export const responsePointEntryTypeSchema = z
   .describe(
     "유형. `EARN_REVIEW` 리뷰 적립 · `REVOKE_REVIEW` 리뷰 삭제 회수 · `EARN_PURCHASE` 구매 적립 · `EXPIRE` 소멸 · `ADJUST` 셀러 지급·차감 · " +
       "`OPENING` 기존 잔액 이전 · `USE_RESERVE` 결제 사용(결제 시작 때 빠짐) · `USE_RELEASE` 결제가 실패·만료되어 되돌림 · " +
-      "`REFUND_RESTORE` 취소·반품 환불로 반환. 값이 추가될 수 있어 문자열로 받는다",
+      "`REFUND_RESTORE` 취소·반품 환불로 반환 · `EARN_COUPON` 적립금 지급 쿠폰. 값이 추가될 수 있어 문자열로 받는다",
   );
 
 /** 원장 항목 — 셀러 조회용(사유·행위자 포함) */
@@ -283,7 +285,7 @@ export const pointLotSchema = z.object({
   lotId: z.string(),
   source: z
     .union([z.enum(POINT_LOT_SOURCES), z.string()])
-    .describe("출처. `REVIEW`·`PURCHASE`·`ADJUST`·`REFUND_RESTORE`·`OPENING` 등"),
+    .describe("출처. `REVIEW`·`PURCHASE`·`ADJUST`·`REFUND_RESTORE`·`OPENING`·`COUPON` 등"),
   amount: z.number().int().describe("적립한 금액"),
   remaining: z.number().int().describe("남은 금액"),
   expiresAt: z.string().nullable().describe("소멸 시각. null이면 소멸 없음"),

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 };