@sayren/store-sdk 0.29.0 → 0.29.2

package/src/schemas/points.ts

@@ -0,0 +1,285 @@
+import { z } from "zod";
+
+/**
+ * 적립금 (이슈 #93) — 상점 정책·원장 유형·순수 계산. 정책 해석은 `resolvePointPolicy`, 리뷰 적립 금액은
+ * `reviewRewardPointOf`, 적립 묶음(lot) 만료 시각은 `pointExpiresAtOf` 한 곳이다. 서버·상점 플랫폼이 같은 함수를 쓴다.
+ *
+ * 정책이 없으면(null) 모든 적립이 꺼져 있다(사용자 결정 2026-10-02). 셀러가 켜야 적립이 시작된다.
+ * 구매 적립 금액은 `pointEarnOf`, 적용 적립률은 `purchaseEarnRateOf`(상품 덮어쓰기 우선)다. 사용 규칙은 다음 단계(P3)에서 가산한다.
+ */
+
+/** 리뷰 적립·회수 금액 상한 — 한 리뷰에 주는 금액 */
+export const POINT_REVIEW_REWARD_MAX = 100_000;
+/** 유효 기간 범위(일) — 「소멸 없음」 선택지는 두지 않는다(사용자 결정 2026-10-02) */
+export const POINT_EXPIRY_DAYS_MIN = 30;
+export const POINT_EXPIRY_DAYS_MAX = 1825;
+
+/** 구매 적립률 상한(만분율) — 3000 = 30% */
+export const POINT_EARN_RATE_BP_MAX = 3000;
+
+const rewardAmount = z.number().int().min(0).max(POINT_REVIEW_REWARD_MAX);
+
+/** 구매 적립률(만분율, 100 = 1%). 상품별 덮어쓰기도 같은 범위다 */
+export const pointEarnRateBpSchema = z
+  .number()
+  .int()
+  .min(0)
+  .max(POINT_EARN_RATE_BP_MAX)
+  .describe("구매 적립률(만분율, 100 = 1%). 0~3000");
+
+export const reviewRewardPolicySchema = z.object({
+  enabled: z.boolean().describe("리뷰 적립 사용 여부"),
+  textPoint: rewardAmount.describe("리뷰를 작성하면 주는 적립금(원). 0~100,000"),
+  photoPoint: rewardAmount.describe(
+    "사진이 있는 리뷰에 **더** 주는 적립금(원). 0~100,000. 사진 리뷰는 `textPoint + photoPoint`를 받는다",
+  ),
+});
+export type ReviewRewardPolicy = z.infer<typeof reviewRewardPolicySchema>;
+
+export const purchaseEarnPolicySchema = z.object({
+  enabled: z.boolean().describe("구매 적립 사용 여부"),
+  rateBp: pointEarnRateBpSchema.describe(
+    "상점 기본 구매 적립률(만분율, 100 = 1%). 0~3000. 상품의 `pointEarnRateBp`가 있으면 그 값이 우선한다",
+  ),
+});
+export type PurchaseEarnPolicy = z.infer<typeof purchaseEarnPolicySchema>;
+
+const expiryDays = z
+  .number()
+  .int()
+  .min(POINT_EXPIRY_DAYS_MIN)
+  .max(POINT_EXPIRY_DAYS_MAX)
+  .describe(
+    "적립금 유효 기간(일, 30~1825). 적립한 날로부터 이 기간이 지난 날의 끝(한국 시간 23:59:59)에 소멸한다. " +
+      "바꿔도 이미 적립된 적립금의 유효 기간은 바뀌지 않는다",
+  );
+
+/** 저장된 상점 정책(`stores.point_policy`) — 해석은 `resolvePointPolicy` */
+export const pointPolicySchema = z.object({
+  reviewReward: reviewRewardPolicySchema,
+  purchaseEarn: purchaseEarnPolicySchema,
+  expiryDays: expiryDays.nullable().describe("적립금 유효 기간(일). 정하지 않았으면 null"),
+});
+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 },
+  expiryDays: null,
+};
+
+/**
+ * 저장된 정책 → 유효 정책. null·형식이 틀린 값은 기본(모두 끔)이다. 키 하나가 틀려도 그 묶음만 기본으로 읽는다
+ * (정책 형식이 바뀌어 옛 행이 남아 있을 때 적립을 잘못 켜지 않게 한다).
+ */
+export function resolvePointPolicy(stored: unknown): PointPolicy {
+  if (!stored || typeof stored !== "object") return POINT_POLICY_DEFAULTS;
+  const raw = stored as Record<string, unknown>;
+  const review = reviewRewardPolicySchema.safeParse(raw.reviewReward);
+  const purchase = purchaseEarnPolicySchema.safeParse(raw.purchaseEarn);
+  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,
+    expiryDays: expiry.success ? expiry.data : null,
+  };
+}
+
+/** 적립을 하나라도 켰는가 — 켜면 유효 기간이 필수다 */
+export function pointEarningEnabled(policy: PointPolicy): boolean {
+  return policy.reviewReward.enabled || policy.purchaseEarn.enabled;
+}
+
+/**
+ * 주문상품에 적용할 구매 적립률 — 구매 적립이 꺼져 있으면 0, 상품 덮어쓰기(`products.point_earn_rate_bp`)가 있으면 그 값
+ * (0 = 적립 안 함), 없으면 상점 기본이다. 결제 확정 때 주문상품에 스냅샷한다.
+ */
+export function purchaseEarnRateOf(policy: PointPolicy, productRateBp: number | null): number {
+  if (!policy.purchaseEarn.enabled) return 0;
+  return productRateBp ?? policy.purchaseEarn.rateBp;
+}
+
+/** 구매 적립 금액 — 적립 기준 금액 × 적립률, 1원 미만은 내린다 */
+export function pointEarnOf(input: { paidBase: number; rateBp: number }): number {
+  if (input.paidBase <= 0 || input.rateBp <= 0) return 0;
+  return Math.floor((input.paidBase * input.rateBp) / 10_000);
+}
+
+/** 리뷰 하나의 적립 금액 — 정책이 꺼져 있으면 0이다. 사진은 추가분이다 */
+export function reviewRewardPointOf(policy: PointPolicy, hasPhoto: boolean): number {
+  const { reviewReward } = policy;
+  if (!reviewReward.enabled) return 0;
+  return reviewReward.textPoint + (hasPhoto ? reviewReward.photoPoint : 0);
+}
+
+const DAY_MS = 86_400_000;
+const KST_OFFSET_MS = 9 * 3_600_000;
+
+/**
+ * 적립 묶음의 만료 시각 — 적립 시각 + `days`일이 속한 한국 시간 날짜의 끝(23:59:59.999 KST). 구매자 안내가 날짜 단위라
+ * 시각을 날짜 끝에 맞춘다. `days`가 null이면 만료 없음(null)이다.
+ */
+export function pointExpiresAtOf(earnedAt: Date, days: number | null): Date | null {
+  if (days === null) return null;
+  const shifted = earnedAt.getTime() + days * DAY_MS + KST_OFFSET_MS;
+  const endOfDay = Math.floor(shifted / DAY_MS) * DAY_MS + DAY_MS - 1;
+  return new Date(endOfDay - KST_OFFSET_MS);
+}
+
+/** 적립 묶음 출처 — 같은 출처 id에는 묶음이 하나뿐이다(DB 부분 유니크) */
+export const POINT_LOT_SOURCES = [
+  "REVIEW",
+  "PURCHASE",
+  "ADJUST",
+  "REFUND_RESTORE",
+  "OPENING",
+] as const;
+export type PointLotSource = (typeof POINT_LOT_SOURCES)[number];
+
+/** 원장 항목 유형. 지금 쓰는 것은 리뷰 적립·회수이고 나머지는 다음 단계 자리다 */
+export const POINT_ENTRY_TYPES = [
+  "EARN_REVIEW",
+  "REVOKE_REVIEW",
+  "EARN_PURCHASE",
+  "USE_RESERVE",
+  "USE_RELEASE",
+  "REFUND_RESTORE",
+  "EXPIRE",
+  "ADJUST",
+  "OPENING",
+] as const;
+export type PointEntryType = (typeof POINT_ENTRY_TYPES)[number];
+
+/** 상점 플랫폼 알림 — `REVIEW_REWARD_PAUSED` 리뷰 자동 적립이 멈춤 · `POINTS_AVAILABLE` 적립금 설정을 쓸 수 있음 */
+export const pointPolicyNoticeSchema = z
+  .enum(["REVIEW_REWARD_PAUSED", "POINTS_AVAILABLE"])
+  .nullable()
+  .describe(
+    "상점에 보일 안내. `REVIEW_REWARD_PAUSED`: 지난 90일에 리뷰 적립이 있었는데 적립금 기본값이 끔으로 바뀌어 리뷰 자동 적립(500원 + 사진 500원)이 멈췄다. " +
+      "`POINTS_AVAILABLE`: 적립금 설정을 열었으니 다시 켤 수 있다. 안내할 것이 없으면 null",
+  );
+export type PointPolicyNotice = z.infer<typeof pointPolicyNoticeSchema>;
+
+/** `GET /v1/store/point-policy` 응답 */
+export const storePointPolicySchema = z.object({
+  available: z
+    .boolean()
+    .describe(
+      "적립금 설정을 바꿀 수 있는가. false면 준비 중이라 정책 저장이 409 `POINTS_UNAVAILABLE`이고 모든 적립이 멈춰 있다",
+    ),
+  configured: z.boolean().describe("셀러가 정책을 저장한 적이 있는가. false면 기본(모두 끔)이다"),
+  reviewReward: reviewRewardPolicySchema.describe("리뷰 적립. 정하지 않았으면 끔·0원"),
+  purchaseEarn: purchaseEarnPolicySchema.describe(
+    "구매 적립. 구매확정 때 주문상품 실결제 금액(배송비 제외) × 적립률을 준다. 정하지 않았으면 끔·0",
+  ),
+  expiryDays: pointPolicySchema.shape.expiryDays,
+  notice: pointPolicyNoticeSchema,
+});
+export type StorePointPolicy = z.infer<typeof storePointPolicySchema>;
+
+/**
+ * `PUT /v1/store/point-policy` 본문 — 준 항목만 바꾼다(생략 = 저장된 값 유지). 리뷰 적립·구매 적립 중 하나라도 켜면 유효 기간이 있어야 한다
+ * (본문이나 저장된 값, 없으면 400 `POINT_EXPIRY_REQUIRED`).
+ */
+export const updatePointPolicyRequestSchema = z.object({
+  reviewReward: reviewRewardPolicySchema.optional(),
+  purchaseEarn: purchaseEarnPolicySchema.optional(),
+  expiryDays: expiryDays.optional(),
+});
+export type UpdatePointPolicyRequest = z.infer<typeof updatePointPolicyRequestSchema>;
+
+// ── 잔액·원장 조회와 셀러 조정 ─────────────────────────────
+
+/** 응답의 원장 유형 — 값이 추가될 수 있어 문자열로 받는다 */
+export const responsePointEntryTypeSchema = z
+  .union([z.enum(POINT_ENTRY_TYPES), z.string()])
+  .describe(
+    "유형. `EARN_REVIEW` 리뷰 적립 · `REVOKE_REVIEW` 리뷰 삭제 회수 · `EARN_PURCHASE` 구매 적립 · `EXPIRE` 소멸 · `ADJUST` 셀러 지급·차감 · " +
+      "`OPENING` 기존 잔액 이전. 값이 추가될 수 있어 문자열로 받는다",
+  );
+
+/** 원장 항목 — 셀러 조회용(사유·행위자 포함) */
+export const pointEntrySchema = z.object({
+  entryId: z.string(),
+  memberId: z.string(),
+  type: responsePointEntryTypeSchema,
+  amount: z.number().int().describe("변동액. 적립 +, 회수·차감·소멸 −"),
+  balanceAfter: z.number().int().describe("이 변동 직후 잔액"),
+  refType: z
+    .string()
+    .nullable()
+    .describe("가리키는 대상 종류(`REVIEW`·`ORDER_ITEM`·`LOT`·`ADJUSTMENT`)"),
+  refId: z.string().nullable(),
+  memo: z.string().nullable().describe("셀러 조정 사유. 그 밖에는 null"),
+  actor: z.string().nullable().describe("셀러 조정을 한 행위자. 그 밖에는 null"),
+  createdAt: z.string(),
+});
+export type PointEntry = z.infer<typeof pointEntrySchema>;
+
+/** 적립 묶음 요약 — 남은 금액이 있는 묶음 */
+export const pointLotSchema = z.object({
+  lotId: z.string(),
+  source: z
+    .union([z.enum(POINT_LOT_SOURCES), z.string()])
+    .describe("출처. `REVIEW`·`PURCHASE`·`ADJUST`·`OPENING` 등"),
+  amount: z.number().int().describe("적립한 금액"),
+  remaining: z.number().int().describe("남은 금액"),
+  expiresAt: z.string().nullable().describe("소멸 시각. null이면 소멸 없음"),
+  createdAt: z.string(),
+});
+export type PointLot = z.infer<typeof pointLotSchema>;
+
+/** `GET /v1/customers/{customerId}/points` */
+export const customerPointsSchema = z.object({
+  balance: z.number().int().describe("잔액"),
+  expiringSoon: z.number().int().describe("30일 안에 소멸할 금액"),
+  lots: z.array(pointLotSchema).describe("남은 금액이 있는 묶음(소멸이 이른 순, 최대 100개)"),
+});
+export type CustomerPoints = z.infer<typeof customerPointsSchema>;
+
+/** 원장 조회 쿼리 — 상점 전체(`GET /v1/points/history`)는 회원·유형·기간으로 거른다 */
+export const pointHistoryQuerySchema = z.object({
+  page: z.coerce.number().int().min(1).optional(),
+  size: z.coerce.number().int().min(1).max(100).optional(),
+  type: z.string().optional().describe("유형(`EARN_PURCHASE` 등)"),
+  memberId: z.string().optional().describe("회원(구매자) id"),
+  from: z.iso.datetime({ offset: true }).optional().describe("이 시각 이후(포함)"),
+  to: z.iso.datetime({ offset: true }).optional().describe("이 시각 이전(미포함)"),
+});
+export type PointHistoryQuery = z.infer<typeof pointHistoryQuerySchema>;
+
+/** 셀러 조정 금액 한도 — 한 번에 천만 원 */
+export const POINT_ADJUSTMENT_MAX = 10_000_000;
+
+/**
+ * `POST /v1/customers/{customerId}/points/adjustments` — 셀러 지급(+)·차감(−). 헤더 `Idempotency-Key`가 필수다.
+ * 지급의 소멸 시각은 `expiresAt`(생략하면 정책 유효 기간, 정책이 없으면 400 `POINT_EXPIRY_REQUIRED`), 차감은 소멸이 이른 적립금부터 뺀다
+ * (잔액보다 많으면 409 `POINT_BALANCE_INSUFFICIENT`).
+ */
+export const pointAdjustmentRequestSchema = z
+  .object({
+    amount: z
+      .number()
+      .int()
+      .min(-POINT_ADJUSTMENT_MAX)
+      .max(POINT_ADJUSTMENT_MAX)
+      .refine((value) => value !== 0, "0원은 조정할 수 없습니다")
+      .describe("지급은 양수, 차감은 음수(원)"),
+    reason: z.string().trim().min(1).max(200).describe("사유(필수). 구매자에게는 보이지 않는다"),
+    expiresAt: z.iso
+      .datetime({ offset: true })
+      .optional()
+      .describe("지급분의 소멸 시각. 생략하면 정책 유효 기간으로 정한다. 차감에는 주지 않는다"),
+  })
+  .refine((value) => !(value.amount < 0 && value.expiresAt), {
+    message: "차감에는 소멸 시각을 줄 수 없습니다",
+    path: ["expiresAt"],
+  });
+export type PointAdjustmentRequest = z.infer<typeof pointAdjustmentRequestSchema>;
+
+export const pointAdjustmentResultSchema = z.object({
+  entry: pointEntrySchema,
+  balance: z.number().int().describe("조정 뒤 잔액"),
+});
+export type PointAdjustmentResult = z.infer<typeof pointAdjustmentResultSchema>;

package/src/schemas/product.ts

@@ -6,6 +6,7 @@ import {
   productFulfillmentResponseSchema,
   productFulfillmentUpdateSchema,
 } from "./fulfillment";
+import { pointEarnRateBpSchema } from "./points";
 import { productRefundPolicyPatchSchema } from "./refund-policy";
 import { UPLOAD_PURPOSE_LIMITS, uploadExtensionOf } from "./upload";
 
@@ -292,6 +293,12 @@ export const productSchema = productSummarySchema.extend({
       "정가(할인 전 표시 가격). 원 단위. 비교용 표시 값이고 결제 금액 계산에 쓰지 않는다 — 구매자가 내는 가격은 " +
         "즉시할인이 있으면 `discountedPrice`, 없으면 `salePrice`다. 스토어프론트 상품 응답에도 같은 값이 실린다. 정하지 않았으면 null",
     ),
+  pointEarnRateBp: pointEarnRateBpSchema
+    .nullable()
+    .optional()
+    .describe(
+      "구매 적립률 덮어쓰기(만분율, 100 = 1%, 0~3000, 이슈 #93). null이면 상점 기본 적립률, 0이면 이 상품은 적립하지 않는다. 결제 확정 시점 값이 주문상품에 남는다",
+    ),
   images: z.array(z.url()).optional(),
   attributes: z.array(z.object({ attributeId: z.string(), value: z.string() })).optional(),
   optionGroups: z.array(optionGroupSchema),
@@ -547,6 +554,12 @@ const productWriteShape = {
       "정가(할인 전 표시 가격). 원 단위. 비교용 표시 값이고 결제 금액은 판매가(즉시할인이 있으면 할인 적용가)다. " +
         "스토어프론트가 판매가보다 클 때 취소선·할인율로 보인다. 즉시할인은 `PUT /v1/products/{productId}/discount`로 따로 정한다",
     ),
+  pointEarnRateBp: pointEarnRateBpSchema
+    .nullable()
+    .optional()
+    .describe(
+      "구매 적립률 덮어쓰기(만분율, 100 = 1%, 0~3000, 이슈 #93). null이면 상점 기본 적립률, 0이면 이 상품은 적립하지 않는다. 결제 확정 시점 값이 주문상품에 남는다. 전체 수정(PUT)에서 생략하면 지금 값을 유지한다",
+    ),
   description: z.string().optional(),
   /**
    * 상세설명 에디터(@avarlabs/editor)의 직렬화 상태. 재편집 때 이 값으로 문서를 복원한다.
@@ -616,6 +629,12 @@ export const productPatchRequestSchema = z
       .describe(
         "상품별 환불 정책. 주면 통째로 바꾼다(준 항목만 상점 기본을 덮어쓴다). `null`은 덮어쓰기를 지워 상점 기본을 따른다. 생략하면 바꾸지 않는다",
       ),
+    pointEarnRateBp: pointEarnRateBpSchema
+      .nullable()
+      .optional()
+      .describe(
+        "구매 적립률 덮어쓰기(만분율, 100 = 1%, 0~3000, 이슈 #93). null이면 상점 기본 적립률, 0이면 이 상품은 적립하지 않는다. 결제 확정 시점 값이 주문상품에 남는다. 생략하면 바꾸지 않는다",
+      ),
   })
   .refine((value) => Object.values(value).some((v) => v !== undefined), {
     message: "최소 1개 필드가 필요합니다",