@sayren/store-sdk 0.29.2 → 0.29.4

package/src/schemas/collection.ts

@@ -28,7 +28,7 @@ export const COLLECTION_TYPES = ["MANUAL", "AUTOMATIC"] as const;
 export type CollectionType = (typeof COLLECTION_TYPES)[number];
 
 /**
- * 상품 정렬 — `MANUAL`은 직접 정한 순서(직접 선택 컬렉션만)다. `BEST_SELLING`(판매량순)은 판매량 집계가 열릴 때 받는다.
+ * 상품 정렬 — `MANUAL`은 직접 정한 순서(직접 선택 컬렉션만)다. `BEST_SELLING`(판매량순)은 판매 수량이 많은 순이다(M3).
  * 저장 값 전체 목록이고, 쓰기에서 받는 값은 `collectionProductSortRequestSchema`다.
  */
 export const COLLECTION_PRODUCT_SORTS = [
@@ -44,9 +44,19 @@ export const COLLECTION_PRODUCT_SORTS = [
 export type CollectionProductSort = (typeof COLLECTION_PRODUCT_SORTS)[number];
 
 export const collectionProductSortRequestSchema = z
-  .enum(["MANUAL", "LATEST", "PRICE_ASC", "PRICE_DESC", "REVIEW_COUNT", "RATING_DESC", "RECOMMEND"])
+  .enum([
+    "MANUAL",
+    "LATEST",
+    "BEST_SELLING",
+    "PRICE_ASC",
+    "PRICE_DESC",
+    "REVIEW_COUNT",
+    "RATING_DESC",
+    "RECOMMEND",
+  ])
   .describe(
-    "스토어프론트 상품 기본 정렬. `MANUAL`(직접 정한 순서)·`LATEST`(최신순)·`PRICE_ASC`·`PRICE_DESC`·`REVIEW_COUNT`·`RATING_DESC`·`RECOMMEND`(추천순)",
+    "스토어프론트 상품 기본 정렬. `MANUAL`(직접 정한 순서)·`LATEST`(최신순)·`BEST_SELLING`(판매량순)·`PRICE_ASC`·`PRICE_DESC`·`REVIEW_COUNT`·`RATING_DESC`·`RECOMMEND`(추천순). " +
+      "판매량순의 기간은 판매량 상위 조건의 기간이고, 조건이 없으면 최근 30일이다",
   );
 
 /** 노출 상태 — 노출 여부와 기간에서 나온 값이다. 숨김이 기간보다 앞선다 */
@@ -73,6 +83,13 @@ export const MAX_COLLECTION_RULE_CATEGORIES = 20;
 export const MAX_COLLECTION_CREATED_WITHIN_DAYS = 365;
 /** 미리보기(`POST /v1/collections/preview`)가 싣는 상품 최대 개수 */
 export const COLLECTION_PREVIEW_SIZE = 20;
+/** 판매량 상위 조건의 기간 선택지(일, 오늘 포함 한국 날짜) */
+export const COLLECTION_BEST_SELLING_DAYS = [7, 30, 90] as const;
+export type CollectionBestSellingDays = (typeof COLLECTION_BEST_SELLING_DAYS)[number];
+/** 판매량 상위 조건이 담는 상품 최대 개수 */
+export const MAX_COLLECTION_BEST_SELLING_TOP = 100;
+/** 판매량순(`BEST_SELLING`) 정렬의 기간 — 판매량 상위 조건이 없을 때 쓴다 */
+export const COLLECTION_SALES_SORT_DEFAULT_DAYS: CollectionBestSellingDays = 30;
 
 const createdWithinDaysRuleSchema = z.object({
   field: z.literal("createdWithinDays"),
@@ -106,9 +123,23 @@ const discountedRuleSchema = z.object({
   value: z.literal(true).describe("즉시할인이 지금 적용되는 상품"),
 });
 
+const bestSellingRuleSchema = z.object({
+  field: z.literal("bestSelling"),
+  days: z
+    .union([z.literal(7), z.literal(30), z.literal(90)])
+    .describe("판매량을 세는 기간(일). 7·30·90 중 하나이고 오늘을 포함한 한국 날짜 기준이다"),
+  top: z
+    .number()
+    .int()
+    .min(1)
+    .max(MAX_COLLECTION_BEST_SELLING_TOP)
+    .describe("담을 상품 수(1~100). 다른 조건을 만족하는 상품 중 판매 수량 상위 N개다"),
+});
+
 /**
  * 조건 하나 — `field`로 가른다. 가격은 즉시할인을 반영한 판매가(`discountedPrice ?? salePrice`)다.
- * 판매량 상위(`bestSelling`)는 판매량 집계가 열릴 때 더한다.
+ * 판매량 상위(`bestSelling`)는 술어가 아니라 순위 자르기다. 다른 조건을 모두 만족한 상품 중 판매 수량 상위 N개만 남긴다(`rankBestSelling`).
+ * 판매 수량은 실결제 주문의 결제 수량에서 취소·반품 수량을 뺀 값이고, 날짜는 주문 시각의 한국 날짜다. 집계는 최대 10분 늦다.
  */
 export const collectionRuleSchema = z
   .discriminatedUnion("field", [
@@ -116,6 +147,7 @@ export const collectionRuleSchema = z
     categoryRuleSchema,
     priceRuleSchema,
     discountedRuleSchema,
+    bestSellingRuleSchema,
   ])
   .superRefine((rule, ctx) => {
     if (rule.field !== "price") return;
@@ -163,6 +195,7 @@ export const collectionRuleViewSchema = z.union([
   categoryRuleSchema,
   priceRuleSchema,
   discountedRuleSchema,
+  bestSellingRuleSchema,
   z.looseObject({ field: z.string() }),
 ]);
 
@@ -213,6 +246,7 @@ export function descendantCategoryIdsOf(
 /**
  * 조건 판정 함수를 만든다 — 모든 조건을 만족해야 true다(AND). 카테고리 트리는 여기서 한 번만 푼다.
  * 알 수 없는 조건(`field`)은 만족하지 않는 것으로 본다. 모르는 조건을 건너뛰면 상품이 예고 없이 늘어난다.
+ * 판매량 상위(`bestSelling`)는 여기서 모두 통과시킨다. 순위 자르기는 판매량을 아는 호출부가 `rankBestSelling`으로 한다.
  * 판매 상태는 보지 않는다. 판매 중만 거르는 것은 호출부다.
  */
 export function collectionRulesPredicate(
@@ -243,6 +277,8 @@ export function collectionRulesPredicate(
       case "discounted":
         return (product) =>
           product.discountedPrice !== null && product.discountedPrice < product.salePrice;
+      case "bestSelling":
+        return () => true;
       default:
         return () => false;
     }
@@ -259,6 +295,45 @@ export function matchesCollectionRules(
   return collectionRulesPredicate(rules, context)(product);
 }
 
+/** 판매량 상위 조건 — 없으면 null. 같은 조건은 한 번만 쓰므로 첫 번째다 */
+export function bestSellingRuleOf(
+  rules: readonly CollectionRuleView[],
+): { days: CollectionBestSellingDays; top: number } | null {
+  for (const rule of rules) {
+    const parsed = bestSellingRuleSchema.safeParse(rule);
+    if (parsed.success) return { days: parsed.data.days, top: parsed.data.top };
+  }
+  return null;
+}
+
+/**
+ * 판매량 비교 — 판매 수량이 많은 순, 같으면 최근 등록 순, 그것도 같으면 상품 id 순이다. 결과가 입력 순서에 기대지 않는다.
+ * `sales`에 없는 상품은 0개다.
+ */
+export function compareBySales<T extends { productId: string; createdAt: string }>(
+  sales: ReadonlyMap<string, number>,
+): (a: T, b: T) => number {
+  return (a, b) =>
+    (sales.get(b.productId) ?? 0) - (sales.get(a.productId) ?? 0) ||
+    Date.parse(b.createdAt) - Date.parse(a.createdAt) ||
+    (a.productId < b.productId ? -1 : a.productId > b.productId ? 1 : 0);
+}
+
+/**
+ * 판매량 상위 자르기 — 다른 조건을 통과한 상품 중 판매 수량이 1개 이상인 상품을 `compareBySales` 순으로 `top`개 남긴다.
+ * 판매가 없는 상품은 넣지 않는다.
+ */
+export function rankBestSelling<T extends { productId: string; createdAt: string }>(
+  products: readonly T[],
+  sales: ReadonlyMap<string, number>,
+  top: number,
+): T[] {
+  return products
+    .filter((product) => (sales.get(product.productId) ?? 0) > 0)
+    .sort(compareBySales(sales))
+    .slice(0, Math.max(0, top));
+}
+
 /** 조건이 참조하는 카테고리 id — 카테고리 삭제의 참조 검사에 쓴다 */
 export function collectionRuleCategoryIds(rules: readonly CollectionRuleView[]): string[] {
   const ids: string[] = [];
@@ -288,6 +363,14 @@ export const collectionSchema = z.object({
   metaTitle: z.string().nullable(),
   metaDescription: z.string().nullable(),
   state: collectionStateSchema.describe("지금 노출 상태"),
+  salesComputedAt: z
+    .string()
+    .nullable()
+    .default(null)
+    .describe(
+      "판매량 기준 시각. 판매량 상위 조건이나 판매량순 정렬을 쓰는 컬렉션은 이 시각까지의 주문을 센다(최대 10분 늦다). " +
+        "판매량을 쓰지 않거나 아직 집계 전이면 null",
+    ),
   productCount: z
     .number()
     .int()
@@ -347,7 +430,7 @@ const periodRefine = (
 /**
  * `POST /v1/collections` — 컬렉션을 만든다. `slug`를 생략하면 `c-{id 뒤 8자}`로 만든다.
  * 직접 선택(`MANUAL`)은 `productIds`가 처음 담을 상품과 순서다. 조건 자동(`AUTOMATIC`)은 `rules`가 있어야 하고 `productIds`를 받지 않는다.
- * `productSort`를 생략하면 직접 선택은 `MANUAL`, 조건 자동은 `LATEST`다. 조건 자동은 `MANUAL`을 쓸 수 없다.
+ * `productSort`를 생략하면 직접 선택은 `MANUAL`, 조건 자동은 `LATEST`(판매량 상위 조건이 있으면 `BEST_SELLING`)다. 조건 자동은 `MANUAL`을 쓸 수 없다.
  */
 export const collectionCreateRequestSchema = z
   .object({
@@ -365,7 +448,7 @@ export const collectionCreateRequestSchema = z
     productSort: commonFields.productSort
       .optional()
       .describe(
-        "스토어프론트 상품 기본 정렬. 생략하면 직접 선택은 `MANUAL`, 조건 자동은 `LATEST`다. 조건 자동은 `MANUAL`을 쓸 수 없다",
+        "스토어프론트 상품 기본 정렬. 생략하면 직접 선택은 `MANUAL`, 조건 자동은 `LATEST`(판매량 상위 조건이 있으면 `BEST_SELLING`)다. 조건 자동은 `MANUAL`을 쓸 수 없다",
       ),
     visible: commonFields.visible.default(true),
     startsAt: commonFields.startsAt,
@@ -483,7 +566,9 @@ export const collectionPreviewRequestSchema = z.object({
   rules: collectionRulesSchema,
   productSort: collectionProductSortRequestSchema
     .optional()
-    .describe("미리보기 순서. 생략하거나 `MANUAL`이면 `LATEST`다"),
+    .describe(
+      "미리보기 순서. 생략하면 `LATEST`(판매량 상위 조건이 있으면 `BEST_SELLING`)이고, `MANUAL`이면 `LATEST`다",
+    ),
 });
 
 export type CollectionPreviewRequest = z.infer<typeof collectionPreviewRequestSchema>;
@@ -492,6 +577,13 @@ export type CollectionPreviewRequest = z.infer<typeof collectionPreviewRequestSc
 export const collectionPreviewSchema = z.object({
   count: z.number().int().describe("조건을 만족하는 판매 중 상품 수(조회 시각 기준)"),
   products: z.array(collectionProductSchema).describe("앞 20개(정렬 순)"),
+  salesComputedAt: z
+    .string()
+    .nullable()
+    .default(null)
+    .describe(
+      "판매량 기준 시각. 판매량 상위 조건이나 판매량순 정렬을 쓰면 이 시각까지의 주문을 센다. 판매량을 쓰지 않거나 집계 전이면 null",
+    ),
 });
 
 export type CollectionPreview = z.infer<typeof collectionPreviewSchema>;

package/src/schemas/order.ts

@@ -103,6 +103,15 @@ export const orderItemSchema = z.object({
       "이 주문상품에 배분된 쿠폰 할인 — 상품 쿠폰 + 주문 쿠폰 배분. 실결제 금액은 `totalPrice − couponDiscountAmount`이고 " +
         "취소·반품 환불은 실결제 금액을 수량 비율로 나눈다. 쿠폰이 없으면 0. 서버는 항상 싣는다",
     ),
+  pointAllocation: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "이 주문상품에 배분된 사용 적립금 (원, #93). 현금 실결제는 `totalPrice − couponDiscountAmount − pointAllocation`이고 " +
+        "취소·반품은 현금과 적립금을 따로 수량 비율로 돌려준다. 적립금을 쓰지 않았으면 0. 서버는 항상 싣는다",
+    ),
   hold: z.object({ reason: z.string(), expectedDispatchDate: z.string() }).nullable(),
   fulfillment: orderItemFulfillmentSchema
     .nullable()
@@ -202,6 +211,14 @@ export const orderSchema = z.object({
       .optional()
       .default(0)
       .describe("배송비 쿠폰 할인. 쿠폰이 없으면 0. 서버는 항상 싣는다"),
+    pointAmount: z
+      .number()
+      .int()
+      .optional()
+      .default(0)
+      .describe(
+        "사용 적립금 (원, #93) — 쿠폰 뒤 금액에서 뺐다. `totalAmount`는 적립금을 뺀 결제(현금) 금액이다. 적립금을 쓰지 않았으면 0. 서버는 항상 싣는다",
+      ),
     discounts: z
       .array(orderDiscountSchema)
       .optional()
@@ -518,6 +535,15 @@ export const cancelBySellerResultSchema = z.object({
     .optional()
     .default(0)
     .describe("환불액에 더한, 앞선 환불에서 뺀 쿠폰 차감을 되돌린 몫. 서버는 항상 싣는다"),
+  pointRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "돌려준 적립금 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 현금 환불(`refundAmount`)과 별개다. " +
+        "차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다",
+    ),
   refundedAt: z.string(),
 });
 

package/src/schemas/payment.ts

@@ -677,7 +677,13 @@ export type PaymentAttemptRecord = z.infer<typeof paymentAttemptRecordSchema>;
 
 export const paymentRefundRecordSchema = z.object({
   refundId: z.string(),
-  amount: z.number().int(),
+  amount: z.number().int().describe("PG로 돌려준 현금"),
+  pointRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe("같은 환불에서 돌려준 적립금 (#93). 적립금을 쓰지 않은 결제는 0"),
   reason: z.string().describe("환불 사유 코드"),
   kind: z
     .string()

package/src/schemas/points.ts

@@ -44,6 +44,40 @@ export const purchaseEarnPolicySchema = z.object({
 });
 export type PurchaseEarnPolicy = z.infer<typeof purchaseEarnPolicySchema>;
 
+/** 사용 단위 — 1·10·100원 */
+export const POINT_USE_UNITS = [1, 10, 100] as const;
+
+/**
+ * 적립금 사용 규칙(P3) — 주문서에서 결제 금액을 줄인다. 적용 순서는 즉시할인 → 쿠폰 → 적립금이고, 상품 금액(쿠폰 뒤)에 먼저 쓰고
+ * 남으면 배송비에 쓴다(`includeDeliveryFee`). 결제 금액이 100원 아래로 내려가지 않게 적립금을 줄인다.
+ */
+export const pointUsePolicySchema = z.object({
+  enabled: z.boolean().describe("적립금 사용 여부. 꺼도 잔액은 남는다"),
+  minBalance: z
+    .number()
+    .int()
+    .min(0)
+    .max(10_000_000)
+    .describe("이 잔액 이상이어야 쓸 수 있다(원). 0이면 제한 없음"),
+  minAmount: z
+    .number()
+    .int()
+    .min(0)
+    .max(10_000_000)
+    .describe("한 번에 쓰는 최소 금액(원). 0이면 제한 없음"),
+  unit: z
+    .union([z.literal(1), z.literal(10), z.literal(100)])
+    .describe("사용 단위(원). 요청 금액을 이 단위로 내린다"),
+  maxRatioBp: z
+    .number()
+    .int()
+    .min(1)
+    .max(10_000)
+    .describe("결제 기준 금액(쿠폰 뒤) 대비 최대 사용 비율(만분율, 10000 = 100%)"),
+  includeDeliveryFee: z.boolean().describe("배송비에도 쓰는가. 끄면 상품 금액(쿠폰 뒤)에만 쓴다"),
+});
+export type PointUsePolicy = z.infer<typeof pointUsePolicySchema>;
+
 const expiryDays = z
   .number()
   .int()
@@ -58,6 +92,7 @@ const expiryDays = z
 export const pointPolicySchema = z.object({
   reviewReward: reviewRewardPolicySchema,
   purchaseEarn: purchaseEarnPolicySchema,
+  use: pointUsePolicySchema,
   expiryDays: expiryDays.nullable().describe("적립금 유효 기간(일). 정하지 않았으면 null"),
 });
 export type PointPolicy = z.infer<typeof pointPolicySchema>;
@@ -66,6 +101,14 @@ export type PointPolicy = z.infer<typeof pointPolicySchema>;
 export const POINT_POLICY_DEFAULTS: PointPolicy = {
   reviewReward: { enabled: false, textPoint: 0, photoPoint: 0 },
   purchaseEarn: { enabled: false, rateBp: 0 },
+  use: {
+    enabled: false,
+    minBalance: 0,
+    minAmount: 0,
+    unit: 10,
+    maxRatioBp: 10_000,
+    includeDeliveryFee: true,
+  },
   expiryDays: null,
 };
 
@@ -78,10 +121,12 @@ export function resolvePointPolicy(stored: unknown): PointPolicy {
   const raw = stored as Record<string, unknown>;
   const review = reviewRewardPolicySchema.safeParse(raw.reviewReward);
   const purchase = purchaseEarnPolicySchema.safeParse(raw.purchaseEarn);
+  const use = pointUsePolicySchema.safeParse(raw.use);
   const expiry = expiryDays.nullable().safeParse(raw.expiryDays ?? null);
   return {
     reviewReward: review.success ? review.data : POINT_POLICY_DEFAULTS.reviewReward,
     purchaseEarn: purchase.success ? purchase.data : POINT_POLICY_DEFAULTS.purchaseEarn,
+    use: use.success ? use.data : POINT_POLICY_DEFAULTS.use,
     expiryDays: expiry.success ? expiry.data : null,
   };
 }
@@ -137,7 +182,7 @@ export const POINT_LOT_SOURCES = [
 ] as const;
 export type PointLotSource = (typeof POINT_LOT_SOURCES)[number];
 
-/** 원장 항목 유형. 지금 쓰는 것은 리뷰 적립·회수이고 나머지는 다음 단계 자리다 */
+/** 원장 항목 유형 */
 export const POINT_ENTRY_TYPES = [
   "EARN_REVIEW",
   "REVOKE_REVIEW",
@@ -173,6 +218,20 @@ export const storePointPolicySchema = z.object({
   purchaseEarn: purchaseEarnPolicySchema.describe(
     "구매 적립. 구매확정 때 주문상품 실결제 금액(배송비 제외) × 적립률을 준다. 정하지 않았으면 끔·0",
   ),
+  useAvailable: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      "적립금 사용(결제에 쓰기)을 켤 수 있는가 (#93). false면 준비 중이라 `use.enabled`를 켜는 저장이 409 `POINTS_UNAVAILABLE`이다. " +
+        "필드가 없는 이전 응답은 false로 읽는다",
+    ),
+  use: pointUsePolicySchema
+    .optional()
+    .default(POINT_POLICY_DEFAULTS.use)
+    .describe(
+      "적립금 사용 규칙. 적용 순서는 즉시할인 → 쿠폰 → 적립금이다. 정하지 않았으면 끔. 필드가 없는 이전 응답은 끔으로 읽는다",
+    ),
   expiryDays: pointPolicySchema.shape.expiryDays,
   notice: pointPolicyNoticeSchema,
 });
@@ -185,6 +244,7 @@ export type StorePointPolicy = z.infer<typeof storePointPolicySchema>;
 export const updatePointPolicyRequestSchema = z.object({
   reviewReward: reviewRewardPolicySchema.optional(),
   purchaseEarn: purchaseEarnPolicySchema.optional(),
+  use: pointUsePolicySchema.optional(),
   expiryDays: expiryDays.optional(),
 });
 export type UpdatePointPolicyRequest = z.infer<typeof updatePointPolicyRequestSchema>;
@@ -196,7 +256,8 @@ export const responsePointEntryTypeSchema = z
   .union([z.enum(POINT_ENTRY_TYPES), z.string()])
   .describe(
     "유형. `EARN_REVIEW` 리뷰 적립 · `REVOKE_REVIEW` 리뷰 삭제 회수 · `EARN_PURCHASE` 구매 적립 · `EXPIRE` 소멸 · `ADJUST` 셀러 지급·차감 · " +
-      "`OPENING` 기존 잔액 이전. 값이 추가될 수 있어 문자열로 받는다",
+      "`OPENING` 기존 잔액 이전 · `USE_RESERVE` 결제 사용(결제 시작 때 빠짐) · `USE_RELEASE` 결제가 실패·만료되어 되돌림 · " +
+      "`REFUND_RESTORE` 취소·반품 환불로 반환. 값이 추가될 수 있어 문자열로 받는다",
   );
 
 /** 원장 항목 — 셀러 조회용(사유·행위자 포함) */
@@ -222,7 +283,7 @@ export const pointLotSchema = z.object({
   lotId: z.string(),
   source: z
     .union([z.enum(POINT_LOT_SOURCES), z.string()])
-    .describe("출처. `REVIEW`·`PURCHASE`·`ADJUST`·`OPENING` 등"),
+    .describe("출처. `REVIEW`·`PURCHASE`·`ADJUST`·`REFUND_RESTORE`·`OPENING` 등"),
   amount: z.number().int().describe("적립한 금액"),
   remaining: z.number().int().describe("남은 금액"),
   expiresAt: z.string().nullable().describe("소멸 시각. null이면 소멸 없음"),
@@ -283,3 +344,50 @@ export const pointAdjustmentResultSchema = z.object({
   balance: z.number().int().describe("조정 뒤 잔액"),
 });
 export type PointAdjustmentResult = z.infer<typeof pointAdjustmentResultSchema>;
+
+// ── 사용·환불 (P3) ─────────────────────────────────────
+
+/** 결제 시작에 쓴 적립 묶음 — 해제·환불 반환이 이 값으로 되돌리고 반환 적립금의 만료를 정한다 */
+export interface PointLotUsage {
+  lotId: string;
+  amount: number;
+  expiresAt: string | null;
+}
+
+const RESTORE_GRACE_MS = 30 * DAY_MS;
+
+/**
+ * 환불로 돌려주는 적립금의 만료 — 결제에 쓴 묶음 중 가장 늦은 만료이고, 그 시각이 이미 지났으면 지금 + 30일(KST 날짜 끝)이다.
+ * 쓴 묶음 중 만료 없는 묶음(기존 잔액 등)이 있으면 만료 없음(null)이다. 쓴 기록이 없으면 지금 + 30일이다(사용자 결정 2026-10-02).
+ */
+export function pointRestoreExpiresAtOf(usages: readonly PointLotUsage[], now: Date): Date | null {
+  if (usages.some((usage) => usage.expiresAt === null)) return null;
+  const latest = usages.reduce<number | null>((max, usage) => {
+    const at = Date.parse(usage.expiresAt as string);
+    return Number.isFinite(at) && (max === null || at > max) ? at : max;
+  }, null);
+  if (latest !== null && latest > now.getTime()) return new Date(latest);
+  return pointExpiresAtOf(new Date(now.getTime() + RESTORE_GRACE_MS), 0);
+}
+
+/**
+ * 환불 금액 나누기 — 현금 몫·적립금 몫에서 차감(반품 배송비·쿠폰 조건 미달·추가 차감)을 **현금에서 먼저** 빼고 모자란 몫만 적립금에서 뺀다.
+ * 둘 다 모자라면 0에서 멈추고 못 받은 차감액(`uncollected`)을 돌려준다(호출부가 감사 로그에 남긴다).
+ */
+export function splitRefund(input: { cash: number; points: number; charges: number }): {
+  cashRefund: number;
+  pointRefund: number;
+  uncollected: number;
+} {
+  const cash = Math.max(0, input.cash);
+  const points = Math.max(0, input.points);
+  const charges = Math.max(0, input.charges);
+  const fromCash = Math.min(cash, charges);
+  const rest = charges - fromCash;
+  const fromPoints = Math.min(points, rest);
+  return {
+    cashRefund: cash - fromCash,
+    pointRefund: points - fromPoints,
+    uncollected: rest - fromPoints,
+  };
+}

package/src/schemas/promotion.ts

@@ -219,8 +219,31 @@ export interface PricingDelivery {
   bundles: ReadonlyArray<{ bundleKey: string; fee: number; remoteSurcharge: number }>;
 }
 
+/**
+ * 적립금 사용 입력(#93 P3) — 쿠폰 뒤 금액에 쓴다. 규칙은 상점 정책 `use`(`PointUsePolicy`)의 값이다.
+ * 금액은 요청·잔액·최대 비율 중 작은 값을 `unit`으로 내리고, 남는 결제 금액이 100원 아래로 내려가지 않게 줄인다(적립금 전액 결제는 아직 받지 않는다).
+ */
+export interface PricingPoints {
+  /** 구매자가 쓰겠다는 금액 */
+  requested: number;
+  /** 지금 잔액 */
+  balance: number;
+  rules: {
+    minBalance: number;
+    minAmount: number;
+    unit: number;
+    maxRatioBp: number;
+    includeDeliveryFee: boolean;
+  };
+}
+
+/** 적립금을 쓰지 못한 이유 */
+export type PointRejectReason = "MIN_BALANCE" | "MIN_AMOUNT" | "NOT_PAYABLE";
+
 export interface PricingInput {
   lines: readonly PricingLine[];
+  /** 적립금 사용(#93 P3). 없으면 쓰지 않는다 — 결과는 적립금 이전과 같다 */
+  points?: PricingPoints | null;
   coupons: readonly PricingCoupon[];
   /** 배송비 견적. 없으면 배송비 0으로 계산하고 배송비 쿠폰은 할인할 금액이 없다 */
   delivery?: PricingDelivery | null;
@@ -251,6 +274,8 @@ export interface PricingLineResult {
   /** 이 줄에 들어간 쿠폰 할인 합계 — 상품 쿠폰 + 주문 쿠폰 배분 */
   couponDiscount: number;
   allocations: CouponAllocation[];
+  /** 이 줄에 배분한 사용 적립금(#93 P3). 적립금을 쓰지 않으면 0 */
+  pointAllocation: number;
 }
 
 export interface PricingCouponResult {
@@ -270,6 +295,8 @@ export interface PricingCouponResult {
 export interface PricingBundleResult {
   bundleKey: string;
   couponDiscount: number;
+  /** 이 배송 묶음에 배분한 사용 적립금(#93 P3) */
+  pointAllocation: number;
 }
 
 export interface PricingResult {
@@ -285,7 +312,15 @@ export interface PricingResult {
   deliveryFee: number;
   /** 배송비 쿠폰 할인 */
   deliveryDiscountAmount: number;
-  /** 결제 금액 = productAmount − couponDiscountAmount + deliveryFee − deliveryDiscountAmount */
+  /** 사용 적립금(#93 P3). 쓰지 않으면 0 */
+  pointAmount: number;
+  /** 지금 쓸 수 있는 최대 적립금 — 주문서 안내값(잔액을 모두 요청했을 때의 금액). 적립금 입력이 없으면 0 */
+  pointMaxUsable: number;
+  /** 요청보다 적게 썼다면 그 이유 — `MIN_PAYMENT`: 결제 금액 100원을 남기려고 줄였다 */
+  pointAdjustReason: "MIN_PAYMENT" | null;
+  /** 요청했지만 쓰지 못했다면 그 이유 */
+  pointRejectReason: PointRejectReason | null;
+  /** 결제 금액 = productAmount − couponDiscountAmount + deliveryFee − deliveryDiscountAmount − pointAmount */
   totalAmount: number;
 }
 
@@ -541,6 +576,7 @@ export function quotePricing(input: PricingInput): PricingResult {
   const bundles: PricingBundleResult[] = deliveryBundles.map((bundle) => ({
     bundleKey: bundle.bundleKey,
     couponDiscount: 0,
+    pointAllocation: 0,
   }));
   let deliverySlot = false;
   let deliveryDiscountAmount = 0;
@@ -574,6 +610,7 @@ export function quotePricing(input: PricingInput): PricingResult {
     amount: entry.line.amount,
     couponDiscount: entry.allocations.reduce((sum, a) => sum + a.amount, 0),
     allocations: entry.allocations,
+    pointAllocation: 0,
   }));
   const productAmount = lines.reduce((sum, entry) => sum + entry.line.amount, 0);
   const couponDiscountAmount = lineResults.reduce((sum, line) => sum + line.couponDiscount, 0);
@@ -581,6 +618,33 @@ export function quotePricing(input: PricingInput): PricingResult {
     (sum, bundle) => sum + bundle.fee + bundle.remoteSurcharge,
     0,
   );
+  const beforePoints = productAmount - couponDiscountAmount + deliveryFee - deliveryDiscountAmount;
+
+  // 5) 적립금(#93 P3) — 쿠폰 뒤 금액에 쓴다. 상품 줄에 먼저(줄 실결제 비율), 남으면 배송 묶음에(묶음 실배송비 비율) 배분한다
+  const productWeights = lineResults.map((line) => Math.max(0, line.amount - line.couponDiscount));
+  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,
+  });
+  if (points.amount > 0) {
+    const productPaid = productWeights.reduce((sum, w) => sum + w, 0);
+    const toLines = Math.min(points.amount, productPaid);
+    allocateByWeight(toLines, productWeights).forEach((share, i) => {
+      const line = lineResults[i];
+      if (line) line.pointAllocation = share;
+    });
+    const toBundles = points.amount - toLines;
+    if (toBundles > 0) {
+      allocateByWeight(toBundles, bundleWeights).forEach((share, i) => {
+        const bundle = bundles[i];
+        if (bundle) bundle.pointAllocation = share;
+      });
+    }
+  }
   return {
     lines: lineResults,
     coupons: results,
@@ -589,10 +653,56 @@ export function quotePricing(input: PricingInput): PricingResult {
     couponDiscountAmount,
     deliveryFee,
     deliveryDiscountAmount,
-    totalAmount: productAmount - couponDiscountAmount + deliveryFee - deliveryDiscountAmount,
+    pointAmount: points.amount,
+    pointMaxUsable: points.maxUsable,
+    pointAdjustReason: points.adjustReason,
+    pointRejectReason: points.rejectReason,
+    totalAmount: beforePoints - points.amount,
   };
 }
 
+/**
+ * 사용 적립금 금액(순수) — 요청·잔액·최대 비율·「결제 금액 100원 남기기」 중 작은 값을 단위로 내린다.
+ * 최소 보유액·최소 사용액에 못 미치면 0이다. 결제 금액이 0원이 되는 사용(적립금 전액 결제)은 아직 받지 않는다(P4).
+ */
+export function pointUseOf(
+  points: PricingPoints | null,
+  amounts: { productPaid: number; deliveryPaid: number; total: number },
+): {
+  amount: number;
+  maxUsable: number;
+  adjustReason: "MIN_PAYMENT" | null;
+  rejectReason: PointRejectReason | null;
+} {
+  const none = { amount: 0, maxUsable: 0, adjustReason: null, rejectReason: null };
+  if (!points) return none;
+  const { rules } = points;
+  const unit = Math.max(1, Math.floor(rules.unit));
+  const base = amounts.productPaid + (rules.includeDeliveryFee ? amounts.deliveryPaid : 0);
+  const byRatio = Math.floor((base * rules.maxRatioBp) / 10_000);
+  // 결제 금액은 0원 또는 100원 이상이어야 하고, 지금은 0원 결제를 받지 않으므로 100원을 남긴다
+  const byPayment = Math.max(0, amounts.total - MIN_PAYMENT_AMOUNT);
+  const balance = Math.max(0, points.balance);
+  const floorUnit = (value: number) => Math.floor(Math.max(0, value) / unit) * unit;
+  const eligible = balance >= rules.minBalance;
+  const ceiling = Math.min(balance, byRatio, byPayment);
+  const maxUsable = eligible && floorUnit(ceiling) >= rules.minAmount ? floorUnit(ceiling) : 0;
+  const requested = Math.max(0, Math.floor(points.requested));
+  if (requested === 0) return { ...none, maxUsable };
+  if (!eligible) return { amount: 0, maxUsable, adjustReason: null, rejectReason: "MIN_BALANCE" };
+  const amount = floorUnit(Math.min(requested, balance, byRatio, byPayment));
+  if (amount <= 0) {
+    return { amount: 0, maxUsable, adjustReason: null, rejectReason: "NOT_PAYABLE" };
+  }
+  if (amount < rules.minAmount) {
+    return { amount: 0, maxUsable, adjustReason: null, rejectReason: "MIN_AMOUNT" };
+  }
+  // 요청이 결제 금액 100원 남기기에 걸려 줄었다
+  const adjustReason =
+    floorUnit(Math.min(requested, balance, byRatio)) > amount ? "MIN_PAYMENT" : null;
+  return { amount, maxUsable, adjustReason, rejectReason: null };
+}
+
 // ─── 환불 정산: 조건 미달 차감 ─────────────────────────────
 
 /**
@@ -799,10 +909,36 @@ export function settleCouponShortfall(input: CouponSettlementInput): CouponSettl
  * 바로 나누면 몫이 항상 0 이상이고 전량 취소의 합이 실결제 금액과 정확히 같다.
  */
 export function proratedPaidRefundBase(
-  item: { totalPrice: number; couponDiscountAmount?: number | null; quantity: number },
+  item: {
+    totalPrice: number;
+    couponDiscountAmount?: number | null;
+    /** 주문상품에 배분된 사용 적립금(#93 P3) — 현금 환불 기준에서 뺀다. 없으면 0 */
+    pointAllocation?: number | null;
+    quantity: number;
+  },
   settledQuantity: number,
   cancelQuantity: number,
 ): number {
-  const paid = Math.max(0, item.totalPrice - (item.couponDiscountAmount ?? 0));
+  const paid = Math.max(
+    0,
+    item.totalPrice - (item.couponDiscountAmount ?? 0) - (item.pointAllocation ?? 0),
+  );
   return proratedRefundBase(paid, item.quantity, settledQuantity, cancelQuantity);
 }
+
+/**
+ * 주문상품의 사용 적립금 중 이번 취소 수량의 몫(#93 P3) — 누적 내림의 차분이라 나눠 취소해도 합이 배분액과 같다.
+ * 현금 환불(`proratedPaidRefundBase`)과 따로 돌려준다(`pointRefundAmount`).
+ */
+export function proratedPointRefund(
+  item: { pointAllocation?: number | null; quantity: number },
+  settledQuantity: number,
+  cancelQuantity: number,
+): number {
+  return proratedRefundBase(
+    item.pointAllocation ?? 0,
+    item.quantity,
+    settledQuantity,
+    cancelQuantity,
+  );
+}