@sayren/store-sdk 0.1.0

package/src/schemas/order.ts

@@ -0,0 +1,233 @@
+import { z } from "zod";
+import { changeTypeSchema, orderItemStatusSchema, type PageParams, pageSchema } from "./common";
+
+export const orderSummarySchema = z.object({
+  orderId: z.string(),
+  ordererName: z.string(),
+  itemCount: z.number().int(),
+  totalAmount: z.number().int(),
+  representativeStatus: orderItemStatusSchema,
+  orderedAt: z.string(),
+  testPayment: z
+    .boolean()
+    .describe(
+      "테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았어요. 상품을 발송하지 않도록 주의하세요",
+    ),
+});
+
+export type OrderSummary = z.infer<typeof orderSummarySchema>;
+
+export const shippingAddressSchema = z.object({
+  receiverName: z.string(),
+  phone: z.string(),
+  zipCode: z.string(),
+  address1: z.string(),
+  address2: z.string().nullish(),
+  deliveryMemo: z.string().nullish(),
+  entranceCode: z.string().nullish(),
+});
+
+export type ShippingAddress = z.infer<typeof shippingAddressSchema>;
+
+export const orderItemSchema = z.object({
+  orderItemId: z.string(),
+  orderId: z.string(),
+  status: orderItemStatusSchema,
+  claimStatus: z.enum(["CANCEL_REQUESTED", "RETURN_REQUESTED", "EXCHANGE_REQUESTED"]).nullable(),
+  productId: z.string(),
+  productName: z.string(),
+  optionId: z.string().nullable(),
+  optionName: z.string().nullable(),
+  sellerCode: z.string().nullable(),
+  quantity: z.number().int(),
+  unitPrice: z.number().int(),
+  discountAmount: z.number().int(),
+  totalPrice: z.number().int(),
+  hold: z.object({ reason: z.string(), expectedDispatchDate: z.string() }).nullable(),
+  autoDecisionDate: z.string().nullable(),
+  sellerMemo: z.string().nullable(),
+  orderedAt: z.string(),
+  lastChangedAt: z.string(),
+  lastChangedType: changeTypeSchema,
+  testPayment: z
+    .boolean()
+    .describe(
+      "소속 주문이 테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았어요",
+    ),
+});
+
+export type OrderItem = z.infer<typeof orderItemSchema>;
+
+export const orderSchema = z.object({
+  orderId: z.string(),
+  orderedAt: z.string(),
+  orderer: z.object({
+    name: z.string(),
+    phone: z.string(),
+    email: z.email().optional(),
+  }),
+  shippingAddress: shippingAddressSchema,
+  payment: z.object({
+    method: z
+      .enum(["CARD", "BANK_TRANSFER", "VIRTUAL_ACCOUNT", "MOBILE", "POINT", "MIXED"])
+      .describe(
+        "method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다",
+      ),
+    approvedMethod: z
+      .string()
+      .nullable()
+      .optional()
+      .default(null)
+      .describe(
+        "실제 결제수단. method는 호환용이며 간편결제를 CARD로 표시한다. 실제 수단은 approvedMethod를 본다. " +
+          "현재 값은 `pgPaymentMethodSchema`(`PgPaymentMethod`: CARD·BANK_TRANSFER·VIRTUAL_ACCOUNT·MOBILE·EASY_PAY)이고 " +
+          "매출 리포트·스토어프론트·환불 원장과 같은 값이다. 값이 추가될 수 있어 문자열로 받는다. PG가 알려 주지 않았으면 요청 수단, " +
+          "시도 기록이 없는 오래된 주문은 null. 서버는 항상 싣는다",
+      ),
+    productAmount: z.number().int(),
+    deliveryFee: z.number().int(),
+    discountAmount: z.number().int(),
+    totalAmount: z.number().int(),
+    paidAt: z.string().nullable(),
+  }),
+  testPayment: z
+    .boolean()
+    .describe(
+      "테스트 결제(샌드박스 결제) 주문인가. true면 실제로 돈이 오가지 않았어요. 상품을 발송하지 않도록 주의하세요",
+    ),
+  items: z.array(orderItemSchema),
+});
+
+export type Order = z.infer<typeof orderSchema>;
+
+/** 주문 목록 응답 — `GET /v1/orders` */
+export const orderSummaryPageSchema = pageSchema(orderSummarySchema);
+export type OrderSummaryPage = z.infer<typeof orderSummaryPageSchema>;
+
+/** 주문상품 변경 목록 응답 — `GET /v1/order-items` */
+export const orderItemPageSchema = pageSchema(orderItemSchema);
+export type OrderItemPage = z.infer<typeof orderItemPageSchema>;
+
+const testPaymentQuery = z
+  .enum(["true", "false"])
+  .optional()
+  .describe(
+    "테스트 결제(샌드박스 결제) 필터. `true`면 테스트 결제만, `false`면 실결제만, 생략하면 전부예요",
+  );
+
+const pageQuery = {
+  page: z.string().optional().describe("페이지 번호 (1부터, 기본 1)"),
+};
+
+/**
+ * `GET /v1/orders` 쿼리 — OpenAPI 문서용 형태(값은 쿼리 문자열). 검증 규칙은 서버가 적용한다:
+ * `orderedFrom` 누락 400 `MISSING_PARAMETER`, 날짜 형식 오류 400 `INVALID_PARAMETER`, 31일 초과 400 `RANGE_TOO_WIDE`,
+ * `testPayment`가 `true`·`false`가 아니면 400 `INVALID_PARAMETER`
+ */
+export const orderListQuerySchema = z.object({
+  orderedFrom: z.string().describe("조회 시작 시각 (ISO 8601 날짜 또는 일시, 포함). 필수"),
+  orderedTo: z
+    .string()
+    .optional()
+    .describe("조회 끝 시각 (ISO 8601, 포함). 생략하면 orderedFrom부터 31일. 기간은 최대 31일"),
+  status: orderItemStatusSchema
+    .optional()
+    .describe("주문상품 상태 필터 — 이 상태의 주문상품이 하나라도 있는 주문"),
+  keyword: z.string().optional().describe("주문번호(일치)·주문자명·수령인명(포함) 검색"),
+  testPayment: testPaymentQuery,
+  ...pageQuery,
+  size: z.string().optional().describe("페이지 크기 (기본 20, 최대 100)"),
+});
+
+/**
+ * `GET /v1/order-items` 쿼리 — OpenAPI 문서용 형태. `lastChangedFrom` 누락 400 `MISSING_PARAMETER`, 형식 오류 400
+ * `INVALID_PARAMETER`, 24시간 초과 400 `RANGE_TOO_WIDE`, `testPayment` 값 오류 400 `INVALID_PARAMETER`
+ */
+export const orderItemListQuerySchema = z.object({
+  lastChangedFrom: z.string().describe("마지막 변경 시각 조회 시작 (ISO 8601, 포함). 필수"),
+  lastChangedTo: z
+    .string()
+    .optional()
+    .describe(
+      "마지막 변경 시각 조회 끝 (ISO 8601, 포함). 생략하면 시작부터 24시간. 기간은 최대 24시간",
+    ),
+  lastChangedType: changeTypeSchema.optional().describe("마지막 변경 유형 필터"),
+  testPayment: testPaymentQuery,
+  ...pageQuery,
+  size: z.string().optional().describe("페이지 크기 (기본 100, 최대 300)"),
+});
+
+export interface OrderListParams extends PageParams {
+  orderedFrom: string;
+  orderedTo?: string;
+  status?: z.infer<typeof orderItemStatusSchema>;
+  keyword?: string;
+  /** 테스트 결제 필터 — `"true"` 테스트 결제만, `"false"` 실결제만, 생략하면 전부 */
+  testPayment?: "true" | "false";
+}
+
+export interface OrderItemListParams extends PageParams {
+  lastChangedFrom: string;
+  lastChangedTo?: string;
+  lastChangedType?: z.infer<typeof changeTypeSchema>;
+  /** 테스트 결제 필터 — `"true"` 테스트 결제 주문만, `"false"` 실결제만, 생략하면 전부 */
+  testPayment?: "true" | "false";
+}
+
+export const deliveryMethodSchema = z.enum(["COURIER", "DIRECT", "QUICK", "NOTHING"]);
+
+export type DeliveryMethod = z.infer<typeof deliveryMethodSchema>;
+
+export const dispatchRequestSchema = z
+  .object({
+    deliveryMethod: deliveryMethodSchema,
+    carrierCode: z.string().optional(),
+    trackingNumber: z.string().optional(),
+    dispatchedAt: z.string().optional(),
+  })
+  .refine(
+    (value) =>
+      value.deliveryMethod === "DIRECT" || value.deliveryMethod === "NOTHING"
+        ? true
+        : !!value.carrierCode && !!value.trackingNumber,
+    { message: "COURIER/QUICK 발송은 carrierCode와 trackingNumber가 필수입니다" },
+  );
+
+export type DispatchRequest = z.infer<typeof dispatchRequestSchema>;
+
+export const deliveryInfoSchema = z.object({
+  orderItemId: z.string(),
+  deliveryMethod: deliveryMethodSchema,
+  carrierCode: z.string().nullable(),
+  carrierName: z.string().nullable(),
+  trackingNumber: z.string().nullable(),
+  trackingUrl: z.url().nullable(),
+  status: z.enum(["DISPATCHED", "DELIVERING", "DELIVERED"]),
+  dispatchedAt: z.string(),
+  deliveredAt: z.string().nullable(),
+});
+
+export type DeliveryInfo = z.infer<typeof deliveryInfoSchema>;
+
+export const carrierSchema = z.object({
+  carrierCode: z.string(),
+  name: z.string(),
+  trackingUrlTemplate: z.string(),
+});
+
+export type Carrier = z.infer<typeof carrierSchema>;
+
+export const holdOrderItemRequestSchema = z.object({
+  reason: z.enum(["OUT_OF_STOCK", "CUSTOMER_REQUEST", "CUSTOMS", "ETC"]),
+  detail: z.string().max(500).optional(),
+  expectedDispatchDate: z.string(),
+});
+
+export type HoldOrderItemRequest = z.infer<typeof holdOrderItemRequestSchema>;
+
+export const cancelBySellerRequestSchema = z.object({
+  reason: z.enum(["OUT_OF_STOCK", "PRICE_ERROR", "DELIVERY_IMPOSSIBLE", "ETC"]),
+  detail: z.string().max(500).optional(),
+});
+
+export type CancelBySellerRequest = z.infer<typeof cancelBySellerRequestSchema>;