@sayren/store-sdk 0.23.0 → 0.28.1

package/src/schemas/payment.ts

@@ -2,9 +2,9 @@ import { z } from "zod";
 import { type PageParams, pageSchema } from "./common";
 
 /**
- * 스토어 결제(PG) 설정과 매출 리포트 계약.
+ * 상점 결제(PG) 설정과 매출 리포트 계약.
  *
- * PG는 셀러가 직접 계약한다. 자격 증명은 스토어별로 저장되고, 비밀 값(시크릿 키·API Secret·
+ * PG는 셀러가 직접 계약한다. 자격 증명은 상점별로 저장되고, 비밀 값(시크릿 키·API Secret·
  * 웹훅 시크릿)은 저장 후 다시 조회할 수 없다. 응답에는 앞 4자리 마스킹만 나온다. 공개 값
  * (클라이언트 키·Store ID·채널 키)은 원래 브라우저 결제창에 노출되는 값이라 그대로 돌려준다.
  */
@@ -53,7 +53,7 @@ const secretInput = () => z.string().trim().min(8).max(512);
 /**
  * 토스페이먼츠 결제위젯 키 접두사. 결제창은 API 개별 연동(`*_ck_`·`*_sk_`)만 쓴다. 위젯 키는 결제창 SDK가
  * `NOT_SUPPORTED_WIDGET_KEY`로, 서버 API가 404 `NOT_FOUND_MERCHANT`로 거부하므로 저장 전에 막는다.
- * 요청 스키마·api 어댑터·콘솔 폼이 같은 상수를 쓴다(원천). `g` 플래그가 없어 `.test()`가 상태를 갖지 않는다.
+ * 요청 스키마·api 어댑터·상점 플랫폼 폼이 같은 상수를 쓴다(원천). `g` 플래그가 없어 `.test()`가 상태를 갖지 않는다.
  */
 export const TOSS_WIDGET_CLIENT_KEY_PATTERN = /^(test|live)_gck_/;
 /** 토스페이먼츠 결제위젯 시크릿 키 접두사. {@link TOSS_WIDGET_CLIENT_KEY_PATTERN} 참고 */
@@ -360,7 +360,7 @@ export const paymentProviderSchema = z.object({
     .optional()
     .default(null)
     .describe(
-      "지금 새 결제의 후보가 아닌 사유. 후보면 null. 판정 원천은 서버 라우팅이다(콘솔이 다시 계산하지 않는다). " +
+      "지금 새 결제의 후보가 아닌 사유. 후보면 null. 판정 원천은 서버 라우팅이다(상점 플랫폼이 다시 계산하지 않는다). " +
         "후보가 아닌 PG에는 항상 사유 코드를 붙인다(연결 안 된 PG 포함) — 모든 PG는 `candidates`에 있거나 이 값이 null이 아니다. 현재 값: " +
         "`NOT_CONNECTED`(연결 안 됨) · `DISABLED`(사용 중지) · `CREDENTIAL_MISSING`(활성 환경 자격 증명 없음) · " +
         "`SANDBOX_IN_LIVE_STORE`(다른 PG가 라이브라 이 샌드박스 PG는 실구매자 결제에 쓰지 않음) · " +
@@ -559,7 +559,9 @@ export const cashReceiptSchema = z.object({
   canceledAt: z.string().nullable().describe("최근 취소 시각 (ISO 8601)"),
   failCode: z.string().nullable().describe("마지막 실패 코드. 성공하면 비운다"),
   failMessage: z.string().nullable().describe("마지막 실패 사유"),
-  reissuable: z.boolean().describe("콘솔 재발급으로 다시 시도할 수 있는가 (`FAILED`·`PENDING`)"),
+  reissuable: z
+    .boolean()
+    .describe("상점 플랫폼 재발급으로 다시 시도할 수 있는가 (`FAILED`·`PENDING`)"),
   requestedAt: z.string().describe("신청 시각 (ISO 8601)"),
   updatedAt: z.string().describe("마지막 변경 시각 (ISO 8601)"),
 });

package/src/schemas/product.ts

@@ -35,6 +35,13 @@ export const productSummarySchema = z.object({
       "상품 이행의 유형. 유형별 속성은 단건 조회(`GET /v1/products/{productId}`)의 `fulfillment`에 있다",
     ),
   updatedAt: z.string(),
+  sample: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe(
+      "상점을 만들 때 넣은 샘플 상품인가(이슈 #70). 상점 플랫폼이 「샘플」 배지를 단다. 스토어프론트에는 싣지 않는다. 서버는 항상 싣는다",
+    ),
 });
 
 export type ProductSummary = z.infer<typeof productSummarySchema>;
@@ -105,7 +112,7 @@ export const MAX_ADDON_GROUPS = 5;
 export const MAX_CUSTOM_INPUTS = 5;
 /** 직접 입력 항목 최대 글자 수의 상한 */
 export const MAX_CUSTOM_INPUT_LENGTH = 200;
-/** 조합 수가 이 값 이상이면 콘솔이 경고한다(상한은 `MAX_VARIANTS`) */
+/** 조합 수가 이 값 이상이면 상점 플랫폼이 경고한다(상한은 `MAX_VARIANTS`) */
 export const VARIANT_COUNT_WARNING = 100;
 
 /**
@@ -152,7 +159,7 @@ export const customInputSchema = z.object({
 export type CustomInput = z.infer<typeof customInputSchema>;
 
 /**
- * 직접 입력 항목명에 쓸 수 없는 개인정보성 단어 — 콘솔 검사와 서버 400(`CUSTOM_INPUT_LABEL_FORBIDDEN`)이 이 목록 하나를 쓴다.
+ * 직접 입력 항목명에 쓸 수 없는 개인정보성 단어 — 상점 플랫폼 검사와 서버 400(`CUSTOM_INPUT_LABEL_FORBIDDEN`)이 이 목록 하나를 쓴다.
  * 구매자 개인정보는 주문 정보로 받는다. 직접 입력 항목으로 받으면 보관·파기 규칙 밖에 남는다.
  */
 export const CUSTOM_INPUT_FORBIDDEN_WORDS = [
@@ -307,7 +314,7 @@ export const productSchema = productSummarySchema.extend({
   refundPolicy: productRefundPolicyPatchSchema
     .nullable()
     .describe(
-      "상품별 환불 정책 덮어쓰기(상품이 정한 항목만). null이면 스토어 기본 환불 정책을 쓴다. " +
+      "상품별 환불 정책 덮어쓰기(상품이 정한 항목만). null이면 상점 기본 환불 정책을 쓴다. " +
         "반품·교환 배송비(`returnDeliveryFee`·`exchangeDeliveryFee`)는 배송 상품에만 있다",
     ),
   /**
@@ -538,7 +545,7 @@ const productWriteShape = {
   refundPolicy: productRefundPolicyPatchSchema
     .nullish()
     .describe(
-      "상품별 환불 정책 — 준 항목만 스토어 기본을 덮어쓴다. `null`이나 생략은 스토어 기본을 그대로 쓴다는 뜻이다. " +
+      "상품별 환불 정책 — 준 항목만 상점 기본을 덮어쓴다. `null`이나 생략은 상점 기본을 그대로 쓴다는 뜻이다. " +
         "반품·교환 배송비(`returnDeliveryFee`·`exchangeDeliveryFee`)는 배송 상품에만 줄 수 있다(다른 유형은 400)",
     ),
   ...optionModelRequestSchema.shape,
@@ -587,7 +594,7 @@ export const productPatchRequestSchema = z
       .nullable()
       .optional()
       .describe(
-        "상품별 환불 정책. 주면 통째로 바꾼다(준 항목만 스토어 기본을 덮어쓴다). `null`은 덮어쓰기를 지워 스토어 기본을 따른다. 생략하면 바꾸지 않는다",
+        "상품별 환불 정책. 주면 통째로 바꾼다(준 항목만 상점 기본을 덮어쓴다). `null`은 덮어쓰기를 지워 상점 기본을 따른다. 생략하면 바꾸지 않는다",
       ),
   })
   .refine((value) => Object.values(value).some((v) => v !== undefined), {

package/src/schemas/promotion.ts

@@ -16,7 +16,7 @@ import { proratedRefundBase } from "./refund-policy";
  * 4. 배송비 쿠폰(`DELIVERY`) — 주문에 한 장. 기본 배송비(지역 추가 배송비 제외)를 기준으로 할인하고
  *    배송 묶음에 기본 배송비 비율로 나눈다.
  *
- * 무료배송 기준(상품별 조건부 무료·스토어 전체 기준)은 **쿠폰 차감 전 금액**으로 판정한다. 그래서 배송비
+ * 무료배송 기준(상품별 조건부 무료·상점 전체 기준)은 **쿠폰 차감 전 금액**으로 판정한다. 그래서 배송비
  * 견적(`quoteDelivery`)은 쿠폰과 무관하게 먼저 계산되고, 이 함수는 그 결과만 입력으로 받는다.
  *
  * 최소 주문 금액은 대상 상품의 **즉시할인 반영 합계**(쿠폰 차감 전, 배송비 제외)로 판정한다.
@@ -34,7 +34,7 @@ const descriptions = {
     "정률 할인의 최대 할인액(원). null이면 상한이 없다. 정액 할인에는 쓰지 않는다(null)",
   minOrderAmount:
     "최소 주문 금액(원). 대상 상품의 즉시할인 반영 합계(배송비 제외)가 이 값 이상이어야 쓸 수 있다. 0이면 조건이 없다",
-  firstOrderOnly: "이 스토어에서 결제 완료 주문이 없는 회원만 쓸 수 있다",
+  firstOrderOnly: "이 상점에서 결제 완료 주문이 없는 회원만 쓸 수 있다",
   memberOnly:
     "회원만 쓸 수 있다. false면 비회원도 쓸 수 있다 — 코드 입력형이면서 1인 한도가 없는 쿠폰만 false로 둘 수 있다",
   stackWithInstantDiscount:
@@ -224,7 +224,7 @@ export interface PricingInput {
   coupons: readonly PricingCoupon[];
   /** 배송비 견적. 없으면 배송비 0으로 계산하고 배송비 쿠폰은 할인할 금액이 없다 */
   delivery?: PricingDelivery | null;
-  /** 이 스토어에서 결제 완료 주문이 없는 회원인가 */
+  /** 이 상점에서 결제 완료 주문이 없는 회원인가 */
   firstOrder: boolean;
   /** 회원 주문인가 */
   isMember: boolean;
@@ -635,7 +635,7 @@ export interface CouponSettlementInput {
   coupons: readonly AppliedCouponSnapshot[];
   lines: readonly CouponSettlementLine[];
   settlements: Readonly<Record<string, Partial<CouponSettlementState> | undefined>>;
-  /** 스토어 환불 정책 `couponShortfallCharge` */
+  /** 상점 환불 정책 `couponShortfallCharge` */
   shortfallCharge: boolean;
   /** 판매자 귀책(직권취소, 불량·오배송 반품) — 미달분을 청구하지 않는다 */
   sellerFault: boolean;

package/src/schemas/refund-policy.ts

@@ -3,9 +3,9 @@ import { z } from "zod";
 /**
  * 환불 정책 (이슈 #25) — 취소·반품·교환에서 **배송비를 누가 부담하는지**를 정한다.
  *
- * 두 층이다. 스토어 설정(`PATCH /v1/store`의 `refundPolicy`)이 기본값이고, 상품별 정책
+ * 두 층이다. 상점 설정(`PATCH /v1/store`의 `refundPolicy`)이 기본값이고, 상품별 정책
  * (`POST/PUT /v1/products`의 `refundPolicy`)이 그 상품에만 덮어쓴다. 상품이 정하지 않은 항목은
- * 스토어 기본을 따르고, 스토어도 정하지 않았으면 `REFUND_POLICY_DEFAULTS`다.
+ * 상점 기본을 따르고, 상점도 정하지 않았으면 `REFUND_POLICY_DEFAULTS`다.
  *
  * 한 주문에 정책이 섞이면 **상품별로 계산한다**. 배송비 묶음도 상품 단위다(주문서·장바구니의
  * 배송비 합산과 같은 규칙: 같은 상품의 주문상품이 한 묶음이고 묶음마다 배송비가 붙는다).
@@ -30,7 +30,7 @@ const descriptions = {
     "판매자 귀책(셀러 직권취소, 불량·오배송 반품)은 빼지 않는다. false면 차감 없이 실결제 금액만 나눠 환불한다. 기본 true",
 } as const;
 
-/** 유효 환불 정책 — 스토어 기본 + 상품별 덮어쓰기를 합친 결과 */
+/** 유효 환불 정책 — 상점 기본 + 상품별 덮어쓰기를 합친 결과 */
 export const refundPolicySchema = z.object({
   preShipmentDeliveryFeeRefund: z.boolean().describe(descriptions.preShipmentDeliveryFeeRefund),
   returnDeliveryFee: z.number().int().min(0).describe(descriptions.returnDeliveryFee),
@@ -49,7 +49,7 @@ export const refundPolicySchema = z.object({
 export type RefundPolicy = z.infer<typeof refundPolicySchema>;
 
 /**
- * 스토어가 정하지 않았을 때 서버가 쓰는 값.
+ * 상점이 정하지 않았을 때 서버가 쓰는 값.
  *
  * `as const`가 아니라 `RefundPolicy`로 타입을 좁힌다 — 리터럴 타입이면 `Partial<typeof …>`로 일부만 바꿀 때
  * `true` 자리에 `false`를 넣을 수 없다.
@@ -64,7 +64,7 @@ export const REFUND_POLICY_DEFAULTS: RefundPolicy = {
 };
 
 /**
- * 부분 정책 — 스토어 설정 요청과 상품별 덮어쓰기가 쓴다. 준 항목만 바뀐다.
+ * 부분 정책 — 상점 설정 요청과 상품별 덮어쓰기가 쓴다. 준 항목만 바뀐다.
  *
  * `strictObject`라 모르는 키는 400이다. 오타(`returnFee` 등)를 조용히 무시하면 셀러는 저장됐다고
  * 믿는데 정책은 기본값으로 남는다.
@@ -93,7 +93,7 @@ export type RefundPolicyPatch = z.infer<typeof refundPolicyPatchSchema>;
 
 /**
  * 상품별 덮어쓰기 — 쿠폰 조건 미달 차감(`couponShortfallCharge`)은 주문 단위 규칙이라 상품이 정하지 않는다.
- * 스토어 정책만 읽는다(이슈 #47).
+ * 상점 정책만 읽는다(이슈 #47).
  */
 export const productRefundPolicyPatchSchema = refundPolicyPatchSchema.omit({
   couponShortfallCharge: true,
@@ -101,12 +101,12 @@ export const productRefundPolicyPatchSchema = refundPolicyPatchSchema.omit({
 
 /** 정책 해석에 쓰는 상품 값 — 상품별 덮어쓰기 */
 export interface RefundPolicyProductInput {
-  /** 상품별 덮어쓰기. 없으면 스토어 기본을 그대로 쓴다 */
+  /** 상품별 덮어쓰기. 없으면 상점 기본을 그대로 쓴다 */
   refundPolicy?: RefundPolicyPatch | null;
 }
 
 /**
- * 유효 정책 해석 — 상품별 덮어쓰기 → 스토어 기본 → `REFUND_POLICY_DEFAULTS` 순이다.
+ * 유효 정책 해석 — 상품별 덮어쓰기 → 상점 기본 → `REFUND_POLICY_DEFAULTS` 순이다.
  *
  * 반품·교환 배송비의 원천은 정책 하나다(이슈 #57 결정 3). 상품의 레거시 반품비·교환비 필드와의 연결은 없앴고,
  * 레거시 값은 마이그레이션이 상품별 정책으로 옮겼다.
@@ -122,15 +122,15 @@ export function resolveRefundPolicy(
 /**
  * 상품의 **덮어쓰기 자체** — 덮어쓰기가 없으면 null.
  *
- * `resolveRefundPolicy`가 합친 결과로는 "상품이 정한 값"과 "스토어 기본을 물려받은 값"을 가를 수 없다.
- * 관리 API 응답의 `refundPolicy`와 콘솔 폼의 덮어쓰기 스위치가 이 함수를 원천으로 쓴다 — 가르지 못하면
- * 스토어 기본을 쓰는 상품을 저장할 때 그 순간의 기본값이 상품에 박힌다.
+ * `resolveRefundPolicy`가 합친 결과로는 "상품이 정한 값"과 "상점 기본을 물려받은 값"을 가를 수 없다.
+ * 관리 API 응답의 `refundPolicy`와 상점 플랫폼 폼의 덮어쓰기 스위치가 이 함수를 원천으로 쓴다 — 가르지 못하면
+ * 상점 기본을 쓰는 상품을 저장할 때 그 순간의 기본값이 상품에 박힌다.
  */
 export function productRefundPolicyOverride(
   product?: RefundPolicyProductInput | null,
 ): RefundPolicyPatch | null {
   if (product?.refundPolicy == null) return null;
-  // 쿠폰 조건 미달 차감은 주문 단위라 스토어만 정한다 — 상품 행에 키가 있어도 덮어쓰기로 읽지 않는다(이슈 #47)
+  // 쿠폰 조건 미달 차감은 주문 단위라 상점만 정한다 — 상품 행에 키가 있어도 덮어쓰기로 읽지 않는다(이슈 #47)
   const { couponShortfallCharge: _storeOnly, ...override } = dropUndefined(product.refundPolicy);
   return override;
 }

package/src/schemas/saved-option-set.ts

@@ -16,7 +16,7 @@ import {
  * 달라 저장하지 않는다. 추가금은 조합별이 아니라 **값별**로 둔다 — 조합 옵션으로 불러오면 조합 추가금은 고른 값 추가금의 합이다.
  */
 
-/** 스토어당 저장 옵션 최대 개수 */
+/** 상점당 저장 옵션 최대 개수 */
 export const MAX_SAVED_OPTION_SETS = 200;
 /** 저장 옵션 이름 최대 글자 수 */
 export const MAX_SAVED_OPTION_SET_NAME = 50;

package/src/schemas/scope.ts

@@ -2,10 +2,10 @@ import { z } from "zod";
 import type { StoreRole } from "./auth";
 
 /**
- * 스토어 스코프 카탈로그 (auth-spec §7) — 형식 `{리소스}:{r|rw}`, rw는 r을 함의한다.
+ * 상점 스코프 카탈로그 (auth-spec §7) — 형식 `{리소스}:{r|rw}`, rw는 r을 함의한다.
  *
  * 관리 API가 요구하는 스코프와 역할별 자동 부여 스코프의 **단일 원천**이다.
- * 서버(apps/api)가 이 상수를 그대로 가져다 역할→스코프를 산출하므로, 콘솔 권한 매트릭스와
+ * 서버(apps/api)가 이 상수를 그대로 가져다 역할→스코프를 산출하므로, 상점 플랫폼 권한 매트릭스와
  * 서버 인가가 갈라지지 않는다.
  */
 
@@ -49,8 +49,7 @@ export function isStoreScope(scope: string): boolean {
 
 /**
  * 역할별 자동 부여 스코프 (auth-spec §7).
- * storeToken(사람)의 스코프는 이 표로 결정된다. PAT·M2M 클라이언트에는 역할이 없고
- * 발급 시 지정한 스코프만 갖는다(발급자 보유 스코프 이내).
+ * 계정 토큰으로 상점을 호출할 때의 스코프는 그 상점에서의 역할로 이 표에서 결정된다.
  */
 export const STORE_ROLE_SCOPES = {
   OWNER: [

package/src/schemas/shipping-policy.ts

@@ -9,7 +9,7 @@ import { type DeliveryType, type FulfillmentType, requiresShipping } from "./ful
  *    (`deliveryBundleKeyOf`). 이슈 #25의 「묶음 = 같은 상품」 규칙을 일반화한 것이다 — 키를 상품 id에서
  *    정책 지문으로 바꿨고, 주문상품이 주문 시점 키를 스냅샷해(`order_items.delivery_bundle_key`)
  *    환불 정산(`refund-settlement.ts`)과 주문 스냅샷(`orders.delivery_fee_settlements`)이 같은 키를 쓴다.
- * 2. **무료 기준**: 상품별 조건부 무료(`CONDITIONAL_FREE`, 묶음 소계 기준)와 스토어 전체 무료 기준
+ * 2. **무료 기준**: 상품별 조건부 무료(`CONDITIONAL_FREE`, 묶음 소계 기준)와 상점 전체 무료 기준
  *    (`freeThreshold`, 주문 상품 금액 합 기준)이 있다. 둘 중 하나라도 충족하면 그 배송비는 0이다.
  * 3. **지역 추가 배송비**: 우편번호가 제주·도서산간이면 **묶음마다** 추가된다. 묶음이 곧 한 번의 발송이라
  *    두 출고지에서 각각 보내면 추가 운임도 두 번 든다.
@@ -20,21 +20,21 @@ import { type DeliveryType, type FulfillmentType, requiresShipping } from "./ful
  * 계산은 `quoteDelivery` 하나다. 장바구니·주문서·결제 시작·환불 정산이 모두 이 함수를 쓴다 —
  * 네 곳이 각자 계산하면 화면 금액과 결제 금액이 갈라진다.
  *
- * **비실물 줄은 배송 계산에서 빠진다**(이슈 #48, `requiresShipping`). 묶음을 만들지 않고, 스토어 전체 무료 기준의
+ * **비실물 줄은 배송 계산에서 빠진다**(이슈 #48, `requiresShipping`). 묶음을 만들지 않고, 상점 전체 무료 기준의
  * 판정 금액(`shippableAmount`)에도 넣지 않는다 — 디지털 상품 금액이 실물 배송비를 면제시키지 않게 한다.
  */
 
 const descriptions = {
   baseDeliveryFee:
-    "스토어 기본 배송비. 원 단위. 상품 등록·수정에서 `deliveryFee`를 생략하면 이 값을 쓴다. 기본 3000",
+    "상점 기본 배송비. 원 단위. 상품 등록·수정에서 `deliveryFee`를 생략하면 이 값을 쓴다. 기본 3000",
   freeThreshold:
-    "스토어 전체 무료배송 기준액. 주문 상품 금액 합이 이 값 이상이면 모든 묶음의 배송비가 0이다. " +
+    "상점 전체 무료배송 기준액. 주문 상품 금액 합이 이 값 이상이면 모든 묶음의 배송비가 0이다. " +
     "null이면 전체 무료배송을 쓰지 않는다(상품별 조건부 무료는 그대로 동작한다). 기본 null",
   jejuSurcharge: "제주 지역 추가 배송비. 원 단위. **배송 묶음마다** 더한다. 기본 0",
   isolatedSurcharge: "도서산간 지역 추가 배송비. 원 단위. **배송 묶음마다** 더한다. 기본 0",
 } as const;
 
-/** 유효 배송비 정책 — 스토어가 정하지 않은 항목은 `SHIPPING_POLICY_DEFAULTS`로 채운 값이다 */
+/** 유효 배송비 정책 — 상점이 정하지 않은 항목은 `SHIPPING_POLICY_DEFAULTS`로 채운 값이다 */
 export const shippingPolicySchema = z.object({
   baseDeliveryFee: z.number().int().min(0).describe(descriptions.baseDeliveryFee),
   freeThreshold: z.number().int().min(1).nullable().describe(descriptions.freeThreshold),
@@ -45,7 +45,7 @@ export const shippingPolicySchema = z.object({
 export type ShippingPolicy = z.infer<typeof shippingPolicySchema>;
 
 /**
- * 스토어가 정하지 않았을 때 서버가 쓰는 값.
+ * 상점이 정하지 않았을 때 서버가 쓰는 값.
  *
  * `as const`가 아니라 `ShippingPolicy`로 좁힌다 — 리터럴 타입이면 `Partial<typeof …>`로 일부만 바꿀 때
  * `null` 자리에 숫자를 넣을 수 없다(`REFUND_POLICY_DEFAULTS`와 같은 이유).
@@ -72,7 +72,7 @@ export const shippingPolicyPatchSchema = z.strictObject({
 
 export type ShippingPolicyPatch = z.infer<typeof shippingPolicyPatchSchema>;
 
-/** 유효 정책 해석 — 스토어가 정한 항목 + `SHIPPING_POLICY_DEFAULTS` */
+/** 유효 정책 해석 — 상점이 정한 항목 + `SHIPPING_POLICY_DEFAULTS` */
 export function resolveShippingPolicy(patch?: ShippingPolicyPatch | null): ShippingPolicy {
   if (!patch) return { ...SHIPPING_POLICY_DEFAULTS };
   const given = Object.fromEntries(
@@ -89,10 +89,10 @@ export const remoteAreaSchema = z.enum(["NONE", "JEJU", "ISOLATED"]);
 export type RemoteArea = z.infer<typeof remoteAreaSchema>;
 
 /**
- * 제주·도서산간 우편번호 범위 — **코드 상수다.** 금액은 스토어가 정하고 범위는 플랫폼이 고정한다.
+ * 제주·도서산간 우편번호 범위 — **코드 상수다.** 금액은 상점이 정하고 범위는 플랫폼이 고정한다.
  *
  * 국내 택배사가 공표하는 제주·도서산간 할증 구간을 5자리 우편번호 범위로 옮긴 표다. 셀러마다
- * 범위가 다르면 같은 주소에 다른 금액이 나가고 CS가 셀러 수만큼 갈라진다. 스토어별 범위 편집은
+ * 범위가 다르면 같은 주소에 다른 금액이 나가고 CS가 셀러 수만큼 갈라진다. 상점별 범위 편집은
  * 후속 과제이고, 지금은 이 표가 유일한 원천이다.
  *
  * ## 근거
@@ -131,7 +131,7 @@ export type RemoteArea = z.infer<typeof remoteAreaSchema>;
  * 도로명주소·건물관리번호 단위 판정은 후속 과제다.
  *
  * 범위는 **닫힌 구간**(`from` ≤ zip ≤ `to`)이고 겹치지 않는다. 앞에서부터 처음 맞는 항목을 쓴다.
- * 순서는 콘솔 「추가 배송비 지역」 표의 행 순서이기도 하다(`remoteAreaGroups`). 제주를 먼저 두고
+ * 순서는 상점 플랫폼 「추가 배송비 지역」 표의 행 순서이기도 하다(`remoteAreaGroups`). 제주를 먼저 두고
  * 도서산간은 우편번호 오름차순으로 둔다.
  */
 export const REMOTE_AREA_ZIP_RANGES: ReadonlyArray<{
@@ -141,7 +141,7 @@ export const REMOTE_AREA_ZIP_RANGES: ReadonlyArray<{
   readonly label: string;
 }> = [
   // 제주 전지역. 추자면·우도는 택배사 표에서 더 높은 운임이지만 공개 계약의 지역 구분은
-  // JEJU 하나이고 금액은 스토어가 정한다.
+  // JEJU 하나이고 금액은 상점이 정한다.
   { area: "JEJU", from: 63_000, to: 63_644, label: "제주특별자치도" },
   // 무의도·실미도·팔미도. 택배사 표는 「인천 중구 섬지역」이지만 2026-07-01 행정체제 개편으로
   // 중구가 나뉘면서 무의동은 영종구 소속이다.
@@ -220,7 +220,7 @@ export interface DeliveryBundleProduct {
   deliveryType: DeliveryType;
   deliveryFee: number;
   conditionalFreeAmount: number | null;
-  /** 출고지 주소 id(`seller_addresses`). null이면 스토어 기본 출고지를 쓰는 상품끼리 한 묶음이다 */
+  /** 출고지 주소 id(`seller_addresses`). null이면 상점 기본 출고지를 쓰는 상품끼리 한 묶음이다 */
   shippingAddressId?: string | null;
   /**
    * 상품 유형 (이슈 #48). 생략·null이면 배송 상품이다. 배송이 필요 없는 유형은 묶음을 만들지 않는다.
@@ -265,7 +265,7 @@ export interface DeliveryFeeLine {
  * 기본 배송비를 면제한 근거 — 면제하지 않았으면 null이다.
  *
  * 환불 정산이 근거를 구분해야 한다. 조건부 무료 기준 미달 차감은 **상품별 조건부 무료(`CONDITIONAL`)로
- * 면제된 묶음만** 대상이다. 스토어 전체 무료 기준(`STORE_THRESHOLD`)이나 무료배송 상품(`FREE`)은 셀러가
+ * 면제된 묶음만** 대상이다. 상점 전체 무료 기준(`STORE_THRESHOLD`)이나 무료배송 상품(`FREE`)은 셀러가
  * 배송비를 받지 않기로 한 것이므로, 일부 취소로 기준이 깨져도 구매자에게 배송비를 물리지 않는다.
  *
  * 세 값이 겹치면 `FREE` → `STORE_THRESHOLD` → `CONDITIONAL` 순으로 센 근거를 남긴다.
@@ -277,7 +277,7 @@ export type DeliveryFeeWaiver = z.infer<typeof deliveryFeeWaiverSchema>;
 /** 묶음 하나의 견적 */
 export interface DeliveryBundleQuote {
   bundleKey: string;
-  /** 이 묶음에 든 상품 id — 스냅샷 검증과 콘솔 안내에 쓴다 */
+  /** 이 묶음에 든 상품 id — 스냅샷 검증과 상점 플랫폼 안내에 쓴다 */
   productIds: string[];
   /** 실제 청구한 기본 배송비 — 무료배송·무료 기준 충족이면 0 */
   fee: number;
@@ -301,10 +301,10 @@ export interface DeliveryQuote {
   /** 청구할 배송비 총액 = `baseFee` + `remoteSurcharge` */
   deliveryFee: number;
   remoteArea: RemoteArea;
-  /** 스토어 전체 무료 기준(`freeThreshold`) 충족으로 기본 배송비를 면제했는가 */
+  /** 상점 전체 무료 기준(`freeThreshold`) 충족으로 기본 배송비를 면제했는가 */
   freeByThreshold: boolean;
   /**
-   * 배송이 필요한 줄의 상품 금액 합 — 스토어 전체 무료 기준의 판정 금액이다(이슈 #48). 비실물 줄은 빠진다.
+   * 배송이 필요한 줄의 상품 금액 합 — 상점 전체 무료 기준의 판정 금액이다(이슈 #48). 비실물 줄은 빠진다.
    * 주문 상품 금액 합(`productAmount`)과 다를 수 있다.
    */
   shippableAmount: number;
@@ -325,7 +325,7 @@ export interface DeliveryQuoteInput {
  * 배송비 계산 — **순수 함수다.** 장바구니 요약, 주문서 금액, 결제 시작의 최종 확정,
  * 주문 배송비 스냅샷이 모두 이 한 곳을 쓴다.
  *
- * 순서가 규칙이다. 묶음별 조건부 무료를 먼저 보고, 그다음 스토어 전체 무료 기준으로 기본 배송비를
+ * 순서가 규칙이다. 묶음별 조건부 무료를 먼저 보고, 그다음 상점 전체 무료 기준으로 기본 배송비를
  * 한꺼번에 0으로 만들고, 마지막에 지역 추가 배송비를 묶음마다 더한다. 추가 배송비는 무료 기준에
  * 걸리지 않는다.
  */
@@ -363,7 +363,7 @@ export function quoteDelivery(input: DeliveryQuoteInput): DeliveryQuote {
       product.deliveryType === "CONDITIONAL_FREE" && product.conditionalFreeAmount !== null;
     const freeThreshold = conditionalFree ? (product.conditionalFreeAmount ?? 0) : null;
     const listFee = product.deliveryType === "FREE" ? 0 : product.deliveryFee;
-    // 면제 근거는 센 것부터 본다 — 무료배송 상품 > 스토어 전체 무료 기준 > 상품별 조건부 무료.
+    // 면제 근거는 센 것부터 본다 — 무료배송 상품 > 상점 전체 무료 기준 > 상품별 조건부 무료.
     // 환불 정산의 미달 차감은 CONDITIONAL만 대상이므로 근거를 뭉개면 안 된다.
     const waivedBy: DeliveryFeeWaiver | null =
       product.deliveryType === "FREE"

package/src/schemas/store.ts

@@ -4,7 +4,7 @@ import { refundPolicyPatchSchema, refundPolicySchema } from "./refund-policy";
 import { shippingPolicyPatchSchema, shippingPolicySchema } from "./shipping-policy";
 
 /**
- * 스토어 코드 규칙 — 스토어프론트 API가 테넌트를 가르는 값이다(`X-Store-Code` 헤더).
+ * 상점 코드 규칙 — 스토어프론트 API가 테넌트를 가르는 값이다(`X-Store-Code` 헤더).
  * **개설할 때 서버가 랜덤으로 발급하고** 이후 바꿀 수 없다. 이미 나간 링크와 승인된 결제가
  * 이 값에 묶여 있어서 바꾸면 함께 깨진다.
  *
@@ -12,7 +12,7 @@ import { shippingPolicyPatchSchema, shippingPolicySchema } from "./shipping-poli
  */
 export const STORE_CODE_PATTERN = /^[a-z0-9](?:[a-z0-9-]{1,28}[a-z0-9])$/;
 
-/** 플랫폼이 쓰거나 쓸 호스트 이름 — 스토어 코드로 내주지 않는다 */
+/** 플랫폼이 쓰거나 쓸 호스트 이름 — 상점 코드로 내주지 않는다 */
 export const RESERVED_STORE_CODES: readonly string[] = [
   "www",
   "api",
@@ -72,7 +72,7 @@ export const storeCodeSchema = z
   )
   .refine(
     (code) => !isReservedStoreCode(code),
-    "플랫폼이 쓰는 이름이라 스토어 코드로 쓸 수 없습니다",
+    "플랫폼이 쓰는 이름이라 상점 코드로 쓸 수 없습니다",
   );
 
 /** `https://shop.example.com`처럼 경로·쿼리 없는 http(s) 오리진인가 */
@@ -108,7 +108,7 @@ export const MAX_ANALYTICS_ALLOWED_ORIGINS = 20;
 export const MAX_AUTO_TRANSITION_DAYS = 30;
 
 /**
- * 약관 버전 — 스토어가 정하는 문자열이다(`1`·`2`·`2026-09-26`·`v1.2` 등). 형식은 강제하지 않고 값이 다르면 다른 버전이다.
+ * 약관 버전 — 상점이 정하는 문자열이다(`1`·`2`·`2026-09-26`·`v1.2` 등). 형식은 강제하지 않고 값이 다르면 다른 버전이다.
  * 올리면 그 약관에 동의한 구매자의 `reconsentRequired`가 켜지고, 재동의가 이력에 남는다. 되돌리면 재동의 요구도 풀린다.
  */
 export const policyVersionSchema = z
@@ -183,12 +183,12 @@ export const updateStoreRequestSchema = z
     refundPolicy: refundPolicyPatchSchema
       .optional()
       .describe(
-        "스토어 기본 환불 정책 — 준 항목만 바꾼다. 상품별 정책(`products.refundPolicy`)이 없는 상품에 적용된다",
+        "상점 기본 환불 정책 — 준 항목만 바꾼다. 상품별 정책(`products.refundPolicy`)이 없는 상품에 적용된다",
       ),
     shippingPolicy: shippingPolicyPatchSchema
       .optional()
       .describe(
-        "스토어 배송비 규칙 — 준 항목만 바꾼다. 기본 배송비, 전체 무료배송 기준액, 제주·도서산간 추가 배송비다. " +
+        "상점 배송비 규칙 — 준 항목만 바꾼다. 기본 배송비, 전체 무료배송 기준액, 제주·도서산간 추가 배송비다. " +
           "바꾼 값은 **새 주문서부터** 적용된다(이미 만든 주문서·주문의 배송비는 스냅샷이 원천이다)",
       ),
     termsVersion: policyVersionSchema
@@ -234,10 +234,10 @@ export const storeSchema = z.object({
   autoDeliverDays: z.number().int().describe(autoDeliverDaysDescription),
   autoConfirmDays: z.number().int().describe(autoConfirmDaysDescription),
   refundPolicy: refundPolicySchema.describe(
-    "스토어 기본 환불 정책. 스토어가 정하지 않은 항목은 플랫폼 기본값으로 채워 항상 전부 싣는다",
+    "상점 기본 환불 정책. 상점이 정하지 않은 항목은 플랫폼 기본값으로 채워 항상 전부 싣는다",
   ),
   shippingPolicy: shippingPolicySchema.describe(
-    "스토어 배송비 규칙. 스토어가 정하지 않은 항목은 플랫폼 기본값으로 채워 항상 전부 싣는다",
+    "상점 배송비 규칙. 상점이 정하지 않은 항목은 플랫폼 기본값으로 채워 항상 전부 싣는다",
   ),
   termsVersion: z.string().describe("현재 이용약관 버전. 가입·재동의가 이 값으로 이력에 남는다"),
   privacyVersion: z.string().describe("현재 개인정보 수집이용 동의 버전"),
@@ -270,7 +270,7 @@ export type StoreMember = z.infer<typeof storeMemberSchema>;
 
 /**
  * 초대 메일 발송 결과 — `SENDING`은 발송 요청 중(결과를 아직 적지 못함), `NOT_CONFIGURED`는 메일 발송이 설정되지 않아
- * 보내지 않은 것이다. 발송 실패는 초대를 무효로 만들지 않는다 — 재발송으로 다시 보낸다
+ * 보내지 않은 것이다. 상점의 월 메일 한도(요금제)를 다 써서 보내지 않았으면 `FAILED` + `deliveryErrorCode: MAIL_QUOTA_EXCEEDED`다. 발송 실패는 초대를 무효로 만들지 않는다 — 재발송으로 다시 보낸다
  */
 export const invitationDeliveryStatusSchema = z.enum([
   "SENDING",