@sayren/store-sdk 0.31.0 → 0.32.0

package/src/schemas/inventory.ts

@@ -0,0 +1,230 @@
+import { z } from "zod";
+
+/**
+ * 위치별 재고 (이슈 #132) — 재고 위치(창고·상설 매장·팝업 매장)마다 조합의 가용 재고를 따로 센다. 출고지·반품지·픽업 장소가 위치를
+ * 가리키고, 배송 주문은 출고지 위치에서, 방문 수령 주문은 그 매장 위치에서 뺀다. 위치를 하나만 쓰는 상점은 기본 위치 하나다.
+ *
+ * - 가용 재고(`available`)는 지금 팔 수 있는 수량이다(팔린 미출고분이 이미 빠진 수). 저장하는 값이다.
+ * - 출고 대기(`pendingFulfillment`)는 그 위치에 할당됐고 아직 출고 전(주문상품 `PAID`·`CONFIRMED`)인 수량이다.
+ * - 실재고(`onHand`)는 가용 재고 + 출고 대기다. 위치에 실제로 있어야 하는 수량이다.
+ * - 상품·옵션 API의 `stockQuantity`는 그 상품 기준 위치의 가용 재고다(이름·뜻 유지).
+ */
+
+/** 재고 조정 사유 — `COUNT`는 실사 줄(`counted`)이 쓴다 */
+export const inventoryAdjustmentReasonSchema = z
+  .enum(["RECEIVED", "DAMAGED", "LOST", "FOUND", "RETURN_RESTOCK", "CORRECTION", "COUNT"])
+  .describe(
+    "조정 사유 — 입고 `RECEIVED`, 파손 `DAMAGED`, 분실 `LOST`, 재발견 `FOUND`, 반품 재입고 `RETURN_RESTOCK`, 정정 `CORRECTION`, 실사 `COUNT`",
+  );
+export type InventoryAdjustmentReason = z.infer<typeof inventoryAdjustmentReasonSchema>;
+
+export const inventoryLocationSchema = z.object({
+  inventoryLocationId: z.string(),
+  name: z.string().describe("위치 이름(예: 본사 창고, 성수 팝업)"),
+  isDefault: z
+    .boolean()
+    .describe("기본 위치인가 — 상점마다 하나이고 삭제할 수 없다. 기존 재고가 있는 곳이다"),
+  sortOrder: z.number().int(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type InventoryLocation = z.infer<typeof inventoryLocationSchema>;
+
+export const inventoryLocationRequestSchema = z.strictObject({
+  name: z.string().trim().min(1).max(50),
+  sortOrder: z.number().int().min(0).max(10_000).optional(),
+});
+export type InventoryLocationRequest = z.infer<typeof inventoryLocationRequestSchema>;
+
+export const inventoryLevelSchema = z.object({
+  productId: z.string(),
+  variantId: z
+    .string()
+    .describe("판매 단위(variant) ID. 주문 상품의 `optionId`와 같은 값 공간이다"),
+  inventoryLocationId: z.string(),
+  available: z.number().int().describe("가용 재고"),
+  pendingFulfillment: z.number().int().describe("출고 대기 — 할당됐고 아직 출고 전인 수량"),
+  onHand: z.number().int().describe("실재고 — 가용 재고 + 출고 대기"),
+  version: z
+    .number()
+    .int()
+    .describe("쓰기마다 1씩 오르는 버전(`INVENTORY.CHANGED`의 `levelVersion`)"),
+  updatedAt: z.string(),
+});
+export type InventoryLevel = z.infer<typeof inventoryLevelSchema>;
+
+export const inventoryLevelListQuerySchema = z.object({
+  inventoryLocationId: z.string().optional(),
+  productId: z.string().optional(),
+  variantId: z.string().optional(),
+  cursor: z.string().optional().describe("이전 응답의 `nextCursor`. 생략하면 처음부터"),
+  limit: z.coerce.number().int().min(1).max(200).optional().describe("한 쪽 크기(기본 100)"),
+});
+export type InventoryLevelListQuery = z.infer<typeof inventoryLevelListQuerySchema>;
+
+export const inventoryLevelPageSchema = z.object({
+  contents: z.array(inventoryLevelSchema),
+  nextCursor: z.string().nullable().describe("다음 페이지 커서. 마지막 페이지면 null"),
+});
+export type InventoryLevelPage = z.infer<typeof inventoryLevelPageSchema>;
+
+export const inventoryMovementKindSchema = z
+  .enum([
+    "OPENING",
+    "SALE",
+    "RESTORE",
+    "REVERT",
+    "EXCHANGE_OUT",
+    "ADJUST",
+    "COUNT",
+    "TRANSFER_OUT",
+    "TRANSFER_IN",
+    "REMOVED",
+  ])
+  .describe(
+    "변동 종류 — 시작 `OPENING`, 판매 `SALE`, 복원 `RESTORE`, 복원 되돌리기 `REVERT`, 교환 출고 `EXCHANGE_OUT`, 조정 `ADJUST`, 실사 `COUNT`, 이동 출고 `TRANSFER_OUT`, 이동 입고 `TRANSFER_IN`, 조합 삭제 `REMOVED`",
+  );
+export type InventoryMovementKind = z.infer<typeof inventoryMovementKindSchema>;
+
+export const inventoryMovementSchema = z.object({
+  movementId: z.string(),
+  seq: z
+    .number()
+    .int()
+    .describe("상점별 순번 — 커밋 순서와 같고 빈 번호가 없다. `after` 커서에 쓴다"),
+  productId: z.string(),
+  variantId: z.string(),
+  inventoryLocationId: z.string(),
+  kind: z.string().describe("변동 종류(`inventoryMovementKindSchema`). 값이 늘 수 있다"),
+  delta: z.number().int().describe("가용 재고 변화량"),
+  available: z.number().int().describe("변화 뒤 가용 재고"),
+  levelVersion: z.number().int(),
+  reason: z.string().nullable(),
+  note: z.string().nullable(),
+  refType: z.string().nullable().describe("출처 유형 — `order_item`·`claim`·`operation`"),
+  refId: z.string().nullable(),
+  operationId: z.string().nullable().describe("재고 조정·이동 요청 ID"),
+  actorType: z.string().describe("행위자 유형 — `seller`·`app`·`agent`·`system`"),
+  actorId: z.string().nullable(),
+  createdAt: z.string(),
+});
+export type InventoryMovement = z.infer<typeof inventoryMovementSchema>;
+
+export const inventoryMovementListQuerySchema = z.object({
+  inventoryLocationId: z.string().optional(),
+  productId: z.string().optional(),
+  variantId: z.string().optional(),
+  kind: inventoryMovementKindSchema.optional(),
+  after: z.coerce
+    .number()
+    .int()
+    .min(0)
+    .optional()
+    .describe("이 순번 다음부터(오름차순). 생략하면 처음부터"),
+  from: z.string().optional().describe("이 시각 이후(ISO 8601)"),
+  to: z.string().optional().describe("이 시각 이전(ISO 8601)"),
+  limit: z.coerce.number().int().min(1).max(200).optional().describe("한 쪽 크기(기본 100)"),
+});
+export type InventoryMovementListQuery = z.infer<typeof inventoryMovementListQuerySchema>;
+
+export const inventoryMovementPageSchema = z.object({
+  contents: z.array(inventoryMovementSchema),
+  nextAfter: z
+    .number()
+    .int()
+    .nullable()
+    .describe(
+      "다음 쪽의 `after` 값. 더 없으면 null(새 변동을 기다릴 때는 마지막 `seq`를 그대로 쓴다)",
+    ),
+});
+export type InventoryMovementPage = z.infer<typeof inventoryMovementPageSchema>;
+
+/** 한 요청의 줄 상한 — 30초 타임아웃·바인드 한도 */
+export const MAX_INVENTORY_OPERATION_LINES = 200;
+
+export const inventoryAdjustmentLineSchema = z
+  .strictObject({
+    variantId: z.string().min(1),
+    inventoryLocationId: z.string().min(1).optional().describe("생략하면 기본 위치"),
+    delta: z
+      .number()
+      .int()
+      .refine((value) => value !== 0, { message: "delta는 0이 아니어야 합니다" })
+      .optional()
+      .describe("가용 재고 증감. 감소는 가용 재고를 넘지 않는다"),
+    counted: z
+      .number()
+      .int()
+      .min(0)
+      .optional()
+      .describe(
+        "실사 — 센 실물 수량. 실재고가 이 값이 되도록 가용 재고를 맞춘다(센 값 − 출고 대기)",
+      ),
+  })
+  .refine((line) => (line.delta === undefined) !== (line.counted === undefined), {
+    message: "줄마다 delta와 counted 중 하나만 줍니다",
+  });
+
+export const inventoryAdjustmentRequestSchema = z.strictObject({
+  lines: z.array(inventoryAdjustmentLineSchema).min(1).max(MAX_INVENTORY_OPERATION_LINES),
+  reason: inventoryAdjustmentReasonSchema
+    .optional()
+    .describe("증감 줄(`delta`)의 사유. 실사 줄은 늘 `COUNT`다. 증감 줄이 있으면 필수"),
+  note: z.string().trim().max(500).optional(),
+  reference: z.string().trim().max(100).optional().describe("외부 참조(입고서 번호 등)"),
+});
+export type InventoryAdjustmentRequest = z.infer<typeof inventoryAdjustmentRequestSchema>;
+
+export const inventoryTransferRequestSchema = z.strictObject({
+  fromInventoryLocationId: z.string().min(1),
+  toInventoryLocationId: z.string().min(1),
+  lines: z
+    .array(z.strictObject({ variantId: z.string().min(1), quantity: z.number().int().min(1) }))
+    .min(1)
+    .max(MAX_INVENTORY_OPERATION_LINES),
+  note: z.string().trim().max(500).optional(),
+});
+export type InventoryTransferRequest = z.infer<typeof inventoryTransferRequestSchema>;
+
+export const inventoryOperationResultSchema = z.object({
+  operationId: z.string(),
+  kind: z.enum(["ADJUSTMENT", "TRANSFER"]),
+  lines: z.array(
+    z.object({
+      variantId: z.string(),
+      inventoryLocationId: z.string(),
+      delta: z.number().int().describe("적용한 가용 재고 변화량(실사는 맞춘 차이, 같으면 0)"),
+      available: z.number().int().describe("적용 뒤 가용 재고"),
+    }),
+  ),
+  createdAt: z.string(),
+});
+export type InventoryOperationResult = z.infer<typeof inventoryOperationResultSchema>;
+
+/** 수거 완료의 재입고 지정(Q3) — 생략하면 조합은 할당 순서(교환 → 판매), 위치는 반품지에 연결된 위치 → 할당 위치다 */
+export const claimCollectCompleteRequestSchema = z.object({
+  restock: z
+    .object({
+      optionId: z
+        .string()
+        .min(1)
+        .optional()
+        .describe(
+          "돌아온 조합 — 그 주문상품의 할당 조합이어야 한다(아니면 400 `INVALID_RESTOCK_OPTION`)",
+        ),
+      inventoryLocationId: z.string().min(1).optional().describe("재입고할 재고 위치"),
+    })
+    .optional(),
+});
+export type ClaimCollectCompleteRequest = z.infer<typeof claimCollectCompleteRequestSchema>;
+
+export const claimRedeliveryRequestSchema = z.object({
+  carrierCode: z.string().min(1),
+  trackingNumber: z.string().min(1),
+  inventoryLocationId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("교환품을 보낼 재고 위치. 생략하면 그 상품의 기준 위치"),
+});
+export type ClaimRedeliveryRequest = z.infer<typeof claimRedeliveryRequestSchema>;

package/src/schemas/misc.ts

@@ -162,6 +162,8 @@ export const eventTypeSchema = z
     "ORDER.FLOW_NOTIFICATION",
     // 커머스 플로우 상태 변경(이슈 #115). 흐름 단계가 바뀔 때마다 간다
     "ORDER.FLOW_STATE_CHANGED",
+    // 위치별 재고 변화(이슈 #132). 재고 변동 내역 한 행마다 간다
+    "INVENTORY.CHANGED",
   ])
   .describe(
     "웹훅 이벤트 타입. `ORDER.ADDRESS_CHANGE_REQUESTED`는 현재 발송하지 않음(호환을 위해 값만 남았고, 구독해도 이벤트가 오지 않는다)",

package/src/schemas/scope-descriptions.ts

@@ -21,6 +21,10 @@ export const SCOPE_DESCRIPTIONS: Record<StoreScopeResource, { r: string; rw: str
   promotion: { r: "쿠폰·적립금 설정을 읽습니다", rw: "쿠폰을 발급하고 적립금을 지급합니다" },
   storefront: { r: "스토어프론트 설정을 읽습니다", rw: "스토어프론트를 편집하고 발행합니다" },
   flow: { r: "주문 흐름 설정을 읽습니다", rw: "주문 흐름을 만들고 수정합니다" },
+  inventory: {
+    r: "위치별 재고와 재고 변동 내역을 읽습니다",
+    rw: "재고를 조정·실사하고 위치 사이에서 이동합니다",
+  },
 };
 
 /** `{resource}:{r|rw}` → 문장. 카탈로그에 없는 스코프는 null */

package/src/schemas/scope.ts

@@ -33,6 +33,8 @@ export const STORE_SCOPE_RESOURCES = {
   storefront: ["r", "rw"],
   // 커머스 플로우 정의·할당(이슈 #115) — 주문 처리 행동은 order 스코프다
   flow: ["r", "rw"],
+  // 위치별 재고·재고 조정·이동·변동 내역(이슈 #132) — 기존 재고 표면(조합 재고 수정, 상품·옵션의 `stockQuantity`)은 product 스코프다
+  inventory: ["r", "rw"],
 } as const satisfies Record<string, readonly ScopeAccess[]>;
 
 export type StoreScopeResource = keyof typeof STORE_SCOPE_RESOURCES;
@@ -71,6 +73,7 @@ export const STORE_ROLE_SCOPES = {
     "promotion:rw",
     "storefront:rw",
     "flow:rw",
+    "inventory:rw",
   ],
   ADMIN: [
     "product:rw",
@@ -88,6 +91,7 @@ export const STORE_ROLE_SCOPES = {
     "promotion:rw",
     "storefront:rw",
     "flow:rw",
+    "inventory:rw",
   ],
   STAFF: [
     "product:rw",
@@ -99,5 +103,6 @@ export const STORE_ROLE_SCOPES = {
     "customer:r",
     "promotion:r",
     "flow:r",
+    "inventory:rw",
   ],
 } as const satisfies Record<StoreRole, readonly string[]>;

package/src/schemas/store.ts

@@ -461,6 +461,13 @@ export const sellerAddressSchema = z.object({
   zipCode: z.string(),
   address1: z.string(),
   address2: z.string().optional(),
+  inventoryLocationId: z
+    .string()
+    .nullable()
+    .optional()
+    .describe(
+      "이 주소의 재고 위치 ID — 출고지면 배송 주문을 이 위치 재고로 팔고, 반품지면 반품을 이 위치로 들인다. 위치를 하나만 쓰는 상점은 기본 위치다",
+    ),
   createdAt: z.string(),
 });
 
@@ -474,6 +481,11 @@ export const sellerAddressRequestSchema = z.object({
   zipCode: z.string().regex(/^[0-9]{5}$/),
   address1: z.string().min(1),
   address2: z.string().optional(),
+  inventoryLocationId: z
+    .string()
+    .min(1)
+    .optional()
+    .describe("재고 위치 ID. 등록에서 생략하면 기본 위치, 수정에서 생략하면 지금 연결을 유지한다"),
 });
 
 export type SellerAddressRequest = z.infer<typeof sellerAddressRequestSchema>;

package/src/schemas/webhook-event.ts

@@ -320,11 +320,55 @@ export const productOutOfStockWebhookEventDataSchema = z.object({
   variantId: z
     .string()
     .describe("재고가 0이 된 판매 단위(variant) ID. 주문 상품의 `optionId`와 같은 값 공간이다"),
+  inventoryLocationId: z
+    .string()
+    .optional()
+    .describe(
+      "재고가 0이 된 재고 위치 ID. 품절은 위치별 가용 재고의 0 전이다. 위치를 하나만 쓰는 상점은 기본 위치다(옛 이벤트에는 없다)",
+    ),
 });
 export type ProductOutOfStockWebhookEventData = z.infer<
   typeof productOutOfStockWebhookEventDataSchema
 >;
 
+/**
+ * 위치별 재고 변화(이슈 #132) — 재고 변동 내역 한 행마다 한 건이다. 같은 위치·조합의 순서는 `levelVersion`(빈 번호 없음)으로 맞추고,
+ * 상점 전체 순서는 `movementSeq`(재고 변동 내역 조회의 `after` 커서와 같은 값)다. 자기가 한 조정의 반향은 `actorType`·`actorId`·`operationId`로 거른다.
+ * 출고 대기·실재고(상태 전이) 변화는 이벤트를 내지 않는다 — 필요하면 위치별 재고 조회를 다시 읽는다
+ */
+export const inventoryChangedWebhookEventDataSchema = z.object({
+  productId: z.string().describe("상품 ID"),
+  variantId: z
+    .string()
+    .describe("판매 단위(variant) ID. 주문 상품의 `optionId`와 같은 값 공간이다"),
+  inventoryLocationId: z.string().describe("재고 위치 ID"),
+  available: z.number().int().describe("변화 뒤 가용 재고"),
+  delta: z.number().int().describe("가용 재고 변화량(0이 아니다)"),
+  kind: z
+    .string()
+    .describe(
+      "변동 종류 — `OPENING`·`SALE`·`RESTORE`·`REVERT`·`EXCHANGE_OUT`·`ADJUST`·`COUNT`·`TRANSFER_OUT`·`TRANSFER_IN`·`REMOVED`. 값이 늘 수 있다",
+    ),
+  reason: z.string().nullable().describe("조정·실사 사유 코드. 없으면 null"),
+  levelVersion: z
+    .number()
+    .int()
+    .describe("위치별 재고 행의 버전 — 같은 위치·조합 안에서 빈 번호 없이 오른다"),
+  movementSeq: z.number().int().describe("상점별 재고 변동 내역 순번"),
+  actorType: z.string().describe("행위자 유형 — `seller`·`app`·`agent`·`system`"),
+  actorId: z.string().nullable().describe("행위자 ID. 시스템이면 null"),
+  refType: z
+    .string()
+    .nullable()
+    .describe("출처 유형 — `order_item`·`claim`·`operation`. 없으면 null"),
+  refId: z.string().nullable().describe("출처 ID"),
+  operationId: z.string().nullable().describe("재고 조정·이동 요청 ID. 조정·이동이 아니면 null"),
+  occurredAt: z.string().describe("변화 시각"),
+});
+export type InventoryChangedWebhookEventData = z.infer<
+  typeof inventoryChangedWebhookEventDataSchema
+>;
+
 export const orderWebhookEventSchema = z.object({
   ...envelopeFields,
   type: z.enum([
@@ -380,6 +424,12 @@ export const productOutOfStockWebhookEventSchema = z.object({
   data: productOutOfStockWebhookEventDataSchema,
 });
 
+export const inventoryChangedWebhookEventSchema = z.object({
+  ...envelopeFields,
+  type: z.literal("INVENTORY.CHANGED"),
+  data: inventoryChangedWebhookEventDataSchema,
+});
+
 /**
  * 플로우 알림(이슈 #115) — 상점이 플로우에 둔 알림 블록(`core.notify`, 채널 `webhook`)이 보낸다. 구매자 알림(알림톡·메일)은 이 이벤트를 받아
  * 상점이 보낸다(플랫폼은 구매자에게 직접 보내지 않는다). 개인정보는 싣지 않는다
@@ -436,6 +486,7 @@ export const webhookEventSchema = z
     productOutOfStockWebhookEventSchema,
     flowNotificationWebhookEventSchema,
     flowStateChangedWebhookEventSchema,
+    inventoryChangedWebhookEventSchema,
   ])
   .describe(
     "웹훅 요청 본문 (얇은 이벤트). 개인정보를 싣지 않으며 `data`의 id로 관리 API를 조회한다",