@sayren/store-sdk 0.29.1 → 0.29.3

package/package.json

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

package/src/client.ts

@@ -56,11 +56,14 @@ import {
   type CollectionCreateRequestInput,
   type CollectionListParams,
   type CollectionPatchRequest,
+  type CollectionPreviewRequest,
   type CollectionProductsAddRequest,
   type CollectionProductsReplaceRequest,
   collectionCreateRequestSchema,
   collectionPageSchema,
   collectionPatchRequestSchema,
+  collectionPreviewRequestSchema,
+  collectionPreviewSchema,
   collectionProductSchema,
   collectionProductsAddRequestSchema,
   collectionProductsReplaceRequestSchema,
@@ -560,7 +563,7 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       remove: (collectionId: string) =>
         storeHttp.requestVoid("DELETE", path`/collections/${collectionId}`),
-      /** 담긴 상품 — 직접 정한 순서 */
+      /** 담긴 상품 — 직접 선택은 정한 순서, 조건 자동은 지금 조건을 만족하는 판매 중 상품(기본 정렬 순) */
       listProducts: (collectionId: string, params?: { page?: number; size?: number }) =>
         storeHttp.request(
           "GET",
@@ -580,6 +583,11 @@ export function createStoreClient(options: StoreClientOptions) {
         }),
       removeProduct: (collectionId: string, productId: string) =>
         storeHttp.requestVoid("DELETE", path`/collections/${collectionId}/products/${productId}`),
+      /** 조건 자동 미리보기 — 저장하지 않고 조건을 만족하는 판매 중 상품 수와 앞 20개를 본다 */
+      preview: (body: CollectionPreviewRequest) =>
+        storeHttp.request("POST", "/collections/preview", collectionPreviewSchema, {
+          body: collectionPreviewRequestSchema.parse(body),
+        }),
     },
 
     categories: {

package/src/schemas/claim.ts

@@ -77,6 +77,15 @@ export const claimSchema = z.object({
       "접수 시점에 계산한 예상 배송비 환불액. 배송 묶음(같은 상품의 주문상품)이 모두 취소되거나 " +
         "판매자 귀책일 때만 0보다 크다. 이 필드가 생기기 전에 접수된 클레임은 null이다",
     ),
+  expectedPointRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "예상 반환 적립금 (원, #93) — 결제에 쓴 적립금 중 이 수량의 몫이다. 예상 환불액(현금)과 별개이고, 차감은 현금에서 먼저 뺀다. " +
+        "교환·적립금을 쓰지 않은 주문은 0이다. 서버는 항상 싣는다",
+    ),
   exchangeOption: z.object({ optionId: z.string(), optionName: z.string() }).nullable(),
   collect: z
     .object({
@@ -201,6 +210,15 @@ export const approveClaimResultSchema = z.object({
     .optional()
     .default(0)
     .describe("환불액에 더한, 앞선 환불에서 뺀 쿠폰 차감을 되돌린 몫. 서버는 항상 싣는다"),
+  pointRefundAmount: z
+    .number()
+    .int()
+    .optional()
+    .default(0)
+    .describe(
+      "돌려준 적립금 (원, #93) — 결제에 쓴 적립금 중 이번 취소·반품 수량의 몫이다. 현금 환불(`refundAmount`)과 별개다. " +
+        "차감은 현금에서 먼저 빼고 모자란 몫만 여기서 뺀다. 적립금을 쓰지 않은 주문과 이 필드가 없는 이전 응답·이벤트는 0으로 읽는다",
+    ),
   refundedAt: z.string(),
 });
 

package/src/schemas/collection.ts

@@ -6,8 +6,8 @@ import { productImageUrlSchema } from "./product";
  * 컬렉션 (이슈 #83) — 상품을 어디에 보여 줄지 정하는 묶음이다. 카테고리는 상품이 무엇인지를 정하고 상품당 하나지만, 컬렉션은
  * 다대다다. 이벤트·기획전은 기간이 있는 직접 선택 컬렉션이다. 권한은 카테고리와 같다(`category:r`·`category:rw`).
  *
- * 유형은 만들 때 정하고 바꿀 수 없다. 지금은 직접 선택(`MANUAL`)만 만들 수 있다. 조건 자동(`AUTOMATIC`)은 다음 단계에서 열리고,
- * 응답의 `type`은 값이 늘 수 있어 문자열이다.
+ * 유형은 만들 때 정하고 바꿀 수 없다. 직접 선택(`MANUAL`)은 셀러가 상품을 담고 순서를 정하고, 조건 자동(`AUTOMATIC`)은 조건(`rules`)을
+ * 모두 만족하는 판매 중 상품을 조회할 때마다 계산한다(결과를 저장하지 않는다). 응답의 `type`은 값이 늘 수 있어 문자열이다.
  */
 
 /** 상점당 컬렉션 최대 개수 — 넘으면 409 `COLLECTION_LIMIT_EXCEEDED` */
@@ -23,7 +23,7 @@ export const MAX_COLLECTION_DESCRIPTION = 500;
 /** 주소(slug) 형식 — 영문 소문자·숫자·하이픈, 첫 글자는 영문 소문자나 숫자, 64자까지 */
 export const COLLECTION_SLUG_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
 
-/** 유형 — `MANUAL`(직접 선택)·`AUTOMATIC`(조건 자동, 아직 만들 수 없다) */
+/** 유형 — `MANUAL`(직접 선택)·`AUTOMATIC`(조건 자동) */
 export const COLLECTION_TYPES = ["MANUAL", "AUTOMATIC"] as const;
 export type CollectionType = (typeof COLLECTION_TYPES)[number];
 
@@ -65,6 +65,210 @@ export function collectionStateOf(
   return "ACTIVE";
 }
 
+/** 조건 자동 컬렉션의 조건 최대 개수 */
+export const MAX_COLLECTION_RULES = 10;
+/** 카테고리 조건 하나에 넣는 카테고리 최대 개수 */
+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;
+
+const createdWithinDaysRuleSchema = z.object({
+  field: z.literal("createdWithinDays"),
+  value: z
+    .number()
+    .int()
+    .min(1)
+    .max(MAX_COLLECTION_CREATED_WITHIN_DAYS)
+    .describe("등록한 지 N일 안의 상품(1~365). 조회 시각에서 N일을 뺀 시각 이후에 등록한 상품이다"),
+});
+
+const categoryRuleSchema = z.object({
+  field: z.literal("category"),
+  categoryIds: z
+    .array(z.string().min(1))
+    .min(1)
+    .max(MAX_COLLECTION_RULE_CATEGORIES)
+    .describe(
+      "카테고리 id(1~20개). 하위 카테고리의 상품도 포함한다. 상점에 없는 id는 400 `COLLECTION_CATEGORY_NOT_FOUND`다",
+    ),
+});
+
+const priceRuleSchema = z.object({
+  field: z.literal("price"),
+  min: z.number().int().min(0).optional().describe("최저가(포함, 원)"),
+  max: z.number().int().min(0).optional().describe("최고가(포함, 원)"),
+});
+
+const discountedRuleSchema = z.object({
+  field: z.literal("discounted"),
+  value: z.literal(true).describe("즉시할인이 지금 적용되는 상품"),
+});
+
+/**
+ * 조건 하나 — `field`로 가른다. 가격은 즉시할인을 반영한 판매가(`discountedPrice ?? salePrice`)다.
+ * 판매량 상위(`bestSelling`)는 판매량 집계가 열릴 때 더한다.
+ */
+export const collectionRuleSchema = z
+  .discriminatedUnion("field", [
+    createdWithinDaysRuleSchema,
+    categoryRuleSchema,
+    priceRuleSchema,
+    discountedRuleSchema,
+  ])
+  .superRefine((rule, ctx) => {
+    if (rule.field !== "price") return;
+    if (rule.min === undefined && rule.max === undefined) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["min"],
+        message: "최저가나 최고가 중 하나는 있어야 합니다",
+      });
+    } else if (rule.min !== undefined && rule.max !== undefined && rule.min > rule.max) {
+      ctx.addIssue({ code: "custom", path: ["max"], message: "최고가는 최저가 이상이어야 합니다" });
+    }
+  });
+
+export type CollectionRule = z.infer<typeof collectionRuleSchema>;
+export type CollectionRuleField = CollectionRule["field"];
+
+/** 조건 목록 — 모두 만족해야 한다(AND). 같은 `field`는 한 번만 쓴다 */
+export const collectionRulesSchema = z
+  .array(collectionRuleSchema)
+  .min(1)
+  .max(MAX_COLLECTION_RULES)
+  .superRefine((rules, ctx) => {
+    const seen = new Set<string>();
+    rules.forEach((rule, index) => {
+      if (seen.has(rule.field)) {
+        ctx.addIssue({
+          code: "custom",
+          path: [index, "field"],
+          message: "같은 조건을 두 번 쓸 수 없습니다",
+        });
+      }
+      seen.add(rule.field);
+    });
+  })
+  .describe(
+    "조건 목록. 모두 만족하는 판매 중 상품이 컬렉션 상품이다(AND). 같은 조건(`field`)은 한 번만 쓴다",
+  );
+
+/**
+ * 응답의 조건 — 이 SDK가 아는 조건이거나 뒤에 더해질 조건(`field`만 확인한다)이다. 새 조건이 생겨도 옛 SDK의 응답 검증이 깨지지 않는다.
+ */
+export const collectionRuleViewSchema = z.union([
+  createdWithinDaysRuleSchema,
+  categoryRuleSchema,
+  priceRuleSchema,
+  discountedRuleSchema,
+  z.looseObject({ field: z.string() }),
+]);
+
+export type CollectionRuleView = z.infer<typeof collectionRuleViewSchema>;
+
+/** 조건 판정에 쓰는 상품 값 — 즉시할인가는 호출부가 계산해 넘긴다 */
+export interface CollectionRuleProduct {
+  createdAt: string;
+  categoryId: string | null;
+  salePrice: number;
+  /** 지금 적용되는 즉시할인가. 할인이 없으면 null */
+  discountedPrice: number | null;
+}
+
+export interface CollectionRuleContext {
+  /** 판정 시각 — 등록일 조건의 기준이다 */
+  now: Date;
+  /** 상점 카테고리(부모 관계) — 카테고리 조건의 하위 포함 판정에 쓴다 */
+  categories: ReadonlyArray<{ categoryId: string; parentId: string | null }>;
+}
+
+const DAY_MS = 86_400_000;
+
+/** 카테고리 자신 + 모든 하위 카테고리 id */
+export function descendantCategoryIdsOf(
+  roots: readonly string[],
+  categories: CollectionRuleContext["categories"],
+): Set<string> {
+  const ids = new Set(roots);
+  const children = new Map<string, string[]>();
+  for (const category of categories) {
+    if (!category.parentId) continue;
+    const list = children.get(category.parentId);
+    if (list) list.push(category.categoryId);
+    else children.set(category.parentId, [category.categoryId]);
+  }
+  const queue = [...roots];
+  for (let next = queue.shift(); next !== undefined; next = queue.shift()) {
+    for (const child of children.get(next) ?? []) {
+      if (ids.has(child)) continue;
+      ids.add(child);
+      queue.push(child);
+    }
+  }
+  return ids;
+}
+
+/**
+ * 조건 판정 함수를 만든다 — 모든 조건을 만족해야 true다(AND). 카테고리 트리는 여기서 한 번만 푼다.
+ * 알 수 없는 조건(`field`)은 만족하지 않는 것으로 본다. 모르는 조건을 건너뛰면 상품이 예고 없이 늘어난다.
+ * 판매 상태는 보지 않는다. 판매 중만 거르는 것은 호출부다.
+ */
+export function collectionRulesPredicate(
+  rules: readonly CollectionRuleView[],
+  context: CollectionRuleContext,
+): (product: CollectionRuleProduct) => boolean {
+  const checks = rules.map((rule): ((product: CollectionRuleProduct) => boolean) => {
+    const known = collectionRuleSchema.safeParse(rule);
+    if (!known.success) return () => false;
+    const parsed = known.data;
+    switch (parsed.field) {
+      case "createdWithinDays": {
+        const since = context.now.getTime() - parsed.value * DAY_MS;
+        return (product) => Date.parse(product.createdAt) >= since;
+      }
+      case "category": {
+        const ids = descendantCategoryIdsOf(parsed.categoryIds, context.categories);
+        return (product) => product.categoryId !== null && ids.has(product.categoryId);
+      }
+      case "price":
+        return (product) => {
+          const price = product.discountedPrice ?? product.salePrice;
+          return (
+            (parsed.min === undefined || price >= parsed.min) &&
+            (parsed.max === undefined || price <= parsed.max)
+          );
+        };
+      case "discounted":
+        return (product) =>
+          product.discountedPrice !== null && product.discountedPrice < product.salePrice;
+      default:
+        return () => false;
+    }
+  });
+  return (product) => checks.length > 0 && checks.every((check) => check(product));
+}
+
+/** 상품 하나가 조건을 모두 만족하는가 — 여러 상품을 판정할 때는 `collectionRulesPredicate`를 한 번 만들어 쓴다 */
+export function matchesCollectionRules(
+  product: CollectionRuleProduct,
+  rules: readonly CollectionRuleView[],
+  context: CollectionRuleContext,
+): boolean {
+  return collectionRulesPredicate(rules, context)(product);
+}
+
+/** 조건이 참조하는 카테고리 id — 카테고리 삭제의 참조 검사에 쓴다 */
+export function collectionRuleCategoryIds(rules: readonly CollectionRuleView[]): string[] {
+  const ids: string[] = [];
+  for (const rule of rules) {
+    const parsed = categoryRuleSchema.safeParse(rule);
+    if (parsed.success) ids.push(...parsed.data.categoryIds);
+  }
+  return ids;
+}
+
 export const collectionSchema = z.object({
   collectionId: z.string(),
   type: z.string().describe("유형. 현재 값은 `MANUAL`·`AUTOMATIC`이고 값이 늘 수 있어 문자열이다"),
@@ -73,6 +277,10 @@ export const collectionSchema = z.object({
   description: z.string(),
   imageUrl: z.string().nullable().describe("대표 이미지 주소"),
   productSort: z.string().describe("스토어프론트 상품 기본 정렬"),
+  rules: z
+    .array(collectionRuleViewSchema)
+    .nullable()
+    .describe("조건 자동 컬렉션의 조건(AND). 직접 선택 컬렉션은 null"),
   visible: z.boolean().describe("노출 여부. false면 기간과 무관하게 스토어프론트에 보이지 않는다"),
   startsAt: z.string().nullable().describe("노출 시작 시각. null이면 바로 노출한다"),
   endsAt: z.string().nullable().describe("노출 종료 시각. null이면 끝나지 않는다"),
@@ -80,7 +288,12 @@ export const collectionSchema = z.object({
   metaTitle: z.string().nullable(),
   metaDescription: z.string().nullable(),
   state: collectionStateSchema.describe("지금 노출 상태"),
-  productCount: z.number().int().describe("담긴 상품 수(판매 상태 무관)"),
+  productCount: z
+    .number()
+    .int()
+    .describe(
+      "상품 수. 직접 선택은 담긴 상품 수(판매 상태 무관), 조건 자동은 지금 조건을 만족하는 판매 중 상품 수",
+    ),
   revision: z
     .number()
     .int()
@@ -132,20 +345,28 @@ const periodRefine = (
 };
 
 /**
- * `POST /v1/collections` — 직접 선택 컬렉션을 만든다. `slug`를 생략하면 `c-{id 뒤 8자}`로 만든다.
- * `productIds`는 처음 담을 상품과 순서다.
+ * `POST /v1/collections` — 컬렉션을 만든다. `slug`를 생략하면 `c-{id 뒤 8자}`로 만든다.
+ * 직접 선택(`MANUAL`)은 `productIds`가 처음 담을 상품과 순서다. 조건 자동(`AUTOMATIC`)은 `rules`가 있어야 하고 `productIds`를 받지 않는다.
+ * `productSort`를 생략하면 직접 선택은 `MANUAL`, 조건 자동은 `LATEST`다. 조건 자동은 `MANUAL`을 쓸 수 없다.
  */
 export const collectionCreateRequestSchema = z
   .object({
     title: z.string().trim().min(1).max(MAX_COLLECTION_TITLE).describe("제목"),
     slug: slugField.optional(),
     type: z
-      .enum(["MANUAL"])
+      .enum(COLLECTION_TYPES)
       .default("MANUAL")
-      .describe("유형. 지금은 `MANUAL`(직접 선택)만 받는다. 만든 뒤 바꿀 수 없다"),
+      .describe("유형. `MANUAL`(직접 선택)·`AUTOMATIC`(조건 자동). 만든 뒤 바꿀 수 없다"),
+    rules: collectionRulesSchema
+      .optional()
+      .describe("조건 자동 컬렉션의 조건(AND). 조건 자동이면 필수, 직접 선택이면 줄 수 없다"),
     description: commonFields.description.default(""),
     imageUrl: commonFields.imageUrl.optional(),
-    productSort: commonFields.productSort.default("MANUAL"),
+    productSort: commonFields.productSort
+      .optional()
+      .describe(
+        "스토어프론트 상품 기본 정렬. 생략하면 직접 선택은 `MANUAL`, 조건 자동은 `LATEST`다. 조건 자동은 `MANUAL`을 쓸 수 없다",
+      ),
     visible: commonFields.visible.default(true),
     startsAt: commonFields.startsAt,
     endsAt: commonFields.endsAt,
@@ -168,6 +389,11 @@ export const collectionPatchRequestSchema = z
     title: z.string().trim().min(1).max(MAX_COLLECTION_TITLE).optional(),
     slug: slugField.optional(),
     type: z.string().optional().describe("바꿀 수 없다. 주면 400 `COLLECTION_TYPE_IMMUTABLE`"),
+    rules: collectionRulesSchema
+      .optional()
+      .describe(
+        "조건 자동 컬렉션의 조건을 통째로 바꾼다. 직접 선택 컬렉션에 주면 400 `COLLECTION_RULES_NOT_ALLOWED`",
+      ),
     description: commonFields.description.optional(),
     imageUrl: commonFields.imageUrl.optional(),
     productSort: commonFields.productSort.optional(),
@@ -207,8 +433,11 @@ export const collectionProductSchema = z.object({
   thumbnailUrl: z.string().nullable(),
   status: z.string().describe("판매 상태. 스토어프론트에는 `SALE`만 보인다"),
   salePrice: z.number().int(),
-  position: z.number().int().describe("직접 정한 순서(1부터)"),
-  addedAt: z.string(),
+  position: z
+    .number()
+    .int()
+    .describe("순서(1부터). 직접 선택은 셀러가 정한 순서, 조건 자동은 컬렉션 기본 정렬의 순위"),
+  addedAt: z.string().describe("담은 시각. 조건 자동은 상품 등록 시각"),
 });
 
 export type CollectionProduct = z.infer<typeof collectionProductSchema>;
@@ -248,3 +477,21 @@ export const collectionListQuerySchema = z.object({
 export const collectionProductListQuerySchema = z.object({
   ...pageQueryShape({ defaultSize: 100, maxSize: MAX_COLLECTION_PRODUCTS }),
 });
+
+/** `POST /v1/collections/preview` — 저장하지 않고 조건으로 나오는 상품을 본다 */
+export const collectionPreviewRequestSchema = z.object({
+  rules: collectionRulesSchema,
+  productSort: collectionProductSortRequestSchema
+    .optional()
+    .describe("미리보기 순서. 생략하거나 `MANUAL`이면 `LATEST`다"),
+});
+
+export type CollectionPreviewRequest = z.infer<typeof collectionPreviewRequestSchema>;
+
+/** 미리보기 응답 — 조건을 만족하는 판매 중 상품 수와 앞 20개 */
+export const collectionPreviewSchema = z.object({
+  count: z.number().int().describe("조건을 만족하는 판매 중 상품 수(조회 시각 기준)"),
+  products: z.array(collectionProductSchema).describe("앞 20개(정렬 순)"),
+});
+
+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,
+  };
+}