Product Domain

개요

상품 등록, 옵션 관리, 가격 설정, 재고 연동을 담당하는 핵심 커머스 도메인. 셀러가 상품을 구성하고, 구매자가 옵션을 선택하여 주문하기까지의 전체 상품 데이터 구조를 정의합니다.

서버 패키지: com.makitt.core.domain.product

---

엔티티 관계도

┌─────────────────────────────────────────────────────────┐
│  Shop                                                   │
│  ├── Category (상품 분류)                                │
│  ├── Tag (상품 태그)                                     │
│  ├── ShopAttribute (상품 속성 정의)                       │
│  ├── VariantGroup (옵션 템플릿)                           │
│  │                                                      │
│  └── Product ◄──────────────────────────────────────┐   │
│       ├── ProductVariantGroup (상품별 옵션 그룹)      │   │
│       │    ├── Option (옵션 키 + 값 목록)             │   │
│       │    └── Combination (옵션 조합 → SU 매핑)      │   │
│       │                                              │   │
│       └── StoreItem (판매 단위) ─────────────────────┘   │
│            └── SellableUnit (출고 단위)                   │
│                 └── BomItem (구성품)                      │
│                      └── SKU (최소 재고 단위, Argo 연동)  │
└─────────────────────────────────────────────────────────┘

계층 요약:

---

1. Product

DynamoDB Entity

소스: makitt-core/.../product/core/entity/Product.java 키빌더: makitt-core/.../common/dynamodb/key/ProductKey.java

키 구조:

필드:

ProductStatus enum:

Embedded: ProductAttribute

{ "key": "skin_type", "value": "sensitive,all" }

Embedded: ProductSeo

{ "slug": "vitamin-c-serum", "title": "비타민C 세럼", "description": "..." }

Embedded: ImageGroup

{ "groupKey": "color_red", "groupName": "빨강 컬러샷", "sortOrder": 0, "images": ["https://..."] }

OpenSearch Document

인덱스: products 매핑 파일: opensearch/mappings/products-index.json 문서 클래스: ProductDocument.java Sync: ProductSearchSyncListener — Product 엔티티 변경 시 자동 인덱싱

DynamoDB → OpenSearch 변환 규칙:

인덱싱되지 않는 필드: pk, sk, gsi*, entityType, imageGroups

JSON 예시

DynamoDB (P03 Vitamin C Serum — OFFER 타입 옵션):

{
  "PK": "PRODUCT#c5278d25-409c-4db6-893c-54df8d16d509",
  "SK": "METADATA",
  "entity_type": "PRODUCT",
  "product_id": "c5278d25-409c-4db6-893c-54df8d16d509",
  "shop_id": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "status": "ACTIVE",
  "name": "Vitamin C Brightening Serum",
  "description": "순수 비타민C 15% 함유 브라이트닝 세럼.",
  "short_description": "비타민C 15% 브라이트닝 세럼 30ml",
  "category_name": "Serums & Ampoules",
  "tags": ["Best Seller", "Vegan"],
  "brand_name": "MAKITT Beauty",
  "featured_price": 35000,
  "attributes": [
    { "key": "product_type", "value": "serum" },
    { "key": "skin_type", "value": "all" },
    { "key": "volume_ml", "value": "30" }
  ],
  "main_images": ["https://cdn.dev.makitt.shop/products/main/2026/02/79514563.png"],
  "detail_images": [
    "https://cdn.dev.makitt.shop/products/detail/2026/02/c225197f.png",
    "https://cdn.dev.makitt.shop/products/detail/2026/02/73a50050.png"
  ],
  "thumbnail_image": "https://cdn.dev.makitt.shop/products/main/2026/02/79514563.png",
  "product_variant_groups": [
    {
      "product_variant_group_id": "pvg_serum_of",
      "product_variant_group_name": "Offer",
      "sort_order": 0,
      "group_type": "OFFER",
      "required": true,
      "ui_mode": "AUTO",
      "options": [
        {
          "option_key": "offer",
          "option_name": "구매 옵션",
          "option_type": "text",
          "sort_order": 0,
          "values": [
            { "value_key": "single", "value_name": "단품", "sort_order": 0 },
            { "value_key": "1plus1", "value_name": "1+1", "sort_order": 1 },
            { "value_key": "fullcare", "value_name": "풀케어 세트", "sort_order": 2 }
          ]
        }
      ],
      "combinations": [
        {
          "combination_key": "offer:single",
          "combination_name": "단품",
          "selections": { "offer": "single" },
          "sellable_unit_id": "su_7557e47428c5",
          "is_enabled": true
        },
        {
          "combination_key": "offer:1plus1",
          "combination_name": "1+1",
          "selections": { "offer": "1plus1" },
          "sellable_unit_id": "su_de08acd51cc2",
          "is_enabled": true
        },
        {
          "combination_key": "offer:fullcare",
          "combination_name": "풀케어 세트",
          "selections": { "offer": "fullcare" },
          "sellable_unit_id": "su_e62fa6101127",
          "is_enabled": true
        }
      ]
    }
  ],
  "gsi1_pk": "SHOP#8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "gsi1_sk": "PRODUCT#2026-02-18T05:21:05Z#c5278d25-409c-4db6-893c-54df8d16d509",
  "created_at": "2026-02-18T05:21:05.711721Z",
  "updated_at": "2026-02-18T08:08:06.123456Z"
}

OpenSearch (동일 상품):

{
  "product_id": "c5278d25-409c-4db6-893c-54df8d16d509",
  "shop_id": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "name": "Vitamin C Brightening Serum",
  "description": "순수 비타민C 15% 함유 브라이트닝 세럼.",
  "short_description": "비타민C 15% 브라이트닝 세럼 30ml",
  "category_name": "Serums & Ampoules",
  "tags": ["Best Seller", "Vegan"],
  "brand_name": "MAKITT Beauty",
  "attribute_values": ["product_type:serum", "skin_type:all", "volume_ml:30"],
  "thumbnail_image": "https://cdn.dev.makitt.shop/products/main/2026/02/79514563.png",
  "main_images": ["https://cdn.dev.makitt.shop/products/main/2026/02/79514563.png"],
  "detail_images": ["https://cdn.dev.makitt.shop/products/detail/2026/02/c225197f.png"],
  "featured_price": 35000,
  "product_variant_groups": [
    {
      "product_variant_group_id": "pvg_serum_of",
      "product_variant_group_name": "Offer",
      "sort_order": 0,
      "group_type": "OFFER",
      "required": true,
      "ui_mode": "AUTO",
      "options": [
        {
          "option_key": "offer",
          "option_name": "구매 옵션",
          "option_type": "text",
          "sort_order": 0,
          "values": [
            { "value_key": "single", "value_name": "단품", "sort_order": 0 },
            { "value_key": "1plus1", "value_name": "1+1", "sort_order": 1 },
            { "value_key": "fullcare", "value_name": "풀케어 세트", "sort_order": 2 }
          ]
        }
      ],
      "combinations": [
        {
          "combination_key": "offer:single",
          "combination_name": "단품",
          "selections": { "offer": "single" },
          "sellable_unit_id": "su_7557e47428c5",
          "is_enabled": true
        },
        {
          "combination_key": "offer:1plus1",
          "combination_name": "1+1",
          "selections": { "offer": "1plus1" },
          "sellable_unit_id": "su_de08acd51cc2",
          "is_enabled": true
        },
        {
          "combination_key": "offer:fullcare",
          "combination_name": "풀케어 세트",
          "selections": { "offer": "fullcare" },
          "sellable_unit_id": "su_e62fa6101127",
          "is_enabled": true
        }
      ]
    }
  ],
  "variant_group_count": 1,
  "group_types": ["OFFER"],
  "has_offer_variants": true,
  "option_names": ["구매 옵션"],
  "option_values": ["단품", "1+1", "풀케어 세트"],
  "status": "ACTIVE",
  "search_text": "Vitamin C Brightening Serum 순수 비타민C 15% 함유 ... MAKITT Beauty Best Seller Vegan serum all 30",
  "created_at": 1771392065711,
  "updated_at": 1771396886123
}

---

2. ProductVariantGroup & Combination

ProductVariantGroup

Product에 내장(embedded) 되는 옵션 그룹. 독립 DynamoDB 엔티티가 아닙니다.

소스: product/core/entity/ProductVariantGroup.java

필드:

groupType: ATTRIBUTE vs OFFER

Option & OptionValue

Option:

OptionValue:

Combination

옵션 선택 조합과 SellableUnit 간의 매핑.

소스: product/core/entity/Combination.java

combinationKey 생성 규칙 (CombinationKeyUtil):

optionKey:valueKey|optionKey:valueKey|...

• 구분자: : (key-value 사이), | (쌍 사이)
• optionKey 기준 사전순(lexical) 정렬

예시:

JSON 예시 (P06 Lip Tint — ATTRIBUTE 타입)

{
  "product_variant_group_id": "pvg_lip5",
  "product_variant_group_name": "Color",
  "sort_order": 0,
  "group_type": "ATTRIBUTE",
  "required": true,
  "ui_mode": "AUTO",
  "options": [
    {
      "option_key": "lip_color",
      "option_name": "컬러",
      "option_type": "color",
      "sort_order": 0,
      "values": [
        { "value_key": "rose", "value_name": "Rose Pink", "color_hex": "#E8909C", "sort_order": 0 },
        { "value_key": "coral", "value_name": "Coral", "color_hex": "#FF7F50", "sort_order": 1 },
        { "value_key": "berry", "value_name": "Berry", "color_hex": "#8B0A50", "sort_order": 2 },
        { "value_key": "nude", "value_name": "Nude", "color_hex": "#C4A882", "sort_order": 3 },
        { "value_key": "red", "value_name": "Classic Red", "color_hex": "#CC0000", "sort_order": 4 }
      ]
    }
  ],
  "combinations": [
    { "combination_key": "lip_color:rose", "combination_name": "Rose Pink", "selections": { "lip_color": "rose" }, "sellable_unit_id": "su_49812e5be5c9", "is_enabled": true },
    { "combination_key": "lip_color:coral", "combination_name": "Coral", "selections": { "lip_color": "coral" }, "sellable_unit_id": "su_643255da484f", "is_enabled": true },
    { "combination_key": "lip_color:berry", "combination_name": "Berry", "selections": { "lip_color": "berry" }, "sellable_unit_id": "su_01e6702972ee", "is_enabled": true },
    { "combination_key": "lip_color:nude", "combination_name": "Nude", "selections": { "lip_color": "nude" }, "sellable_unit_id": "su_f23246ded0d0", "is_enabled": true },
    { "combination_key": "lip_color:red", "combination_name": "Classic Red", "selections": { "lip_color": "red" }, "sellable_unit_id": "su_96f010ee07f9", "is_enabled": true }
  ]
}

JSON 예시 (P11 Primer — ATTRIBUTE + OFFER 혼합)

하나의 Product에 ATTRIBUTE PVG와 OFFER PVG가 공존하는 경우:

{
  "product_variant_groups": [
    {
      "product_variant_group_id": "pvg_primer_shade",
      "product_variant_group_name": "Shade",
      "sort_order": 0,
      "group_type": "ATTRIBUTE",
      "combinations": [
        { "combination_key": "shade:pink", "combination_name": "Pink", "selections": { "shade": "pink" }, "sellable_unit_id": "su_eec1a3df243a", "is_enabled": true },
        { "combination_key": "shade:lavender", "combination_name": "Lavender", "selections": { "shade": "lavender" }, "sellable_unit_id": "su_ebacba78d2ad", "is_enabled": true },
        { "combination_key": "shade:peach", "combination_name": "Peach", "selections": { "shade": "peach" }, "sellable_unit_id": "su_349bb1a0dac5", "is_enabled": true }
      ]
    },
    {
      "product_variant_group_id": "pvg_primer_offer",
      "product_variant_group_name": "Offer",
      "sort_order": 1,
      "group_type": "OFFER",
      "combinations": [
        { "combination_key": "offer:single", "combination_name": "단품", "selections": { "offer": "single" }, "is_enabled": true },
        { "combination_key": "offer:fullset", "combination_name": "풀케어 세트", "selections": { "offer": "fullset" }, "is_enabled": true }
      ]
    }
  ]
}

이 경우 StoreItem은 3 shades × 2 offers = 6개 생성됩니다.

---

3. StoreItem

옵션 조합별 판매 단위. Product와 별도의 독립 DynamoDB 엔티티로 저장됩니다.

DynamoDB Entity

소스: product/storeitem/entity/StoreItem.java 키빌더: common/dynamodb/key/StoreItemKey.java

키 구조:

GSI3은 canonical key로 StoreItem을 직접 조회할 때 사용됩니다. 구매자가 옵션을 선택하면 프론트엔드에서 storeItemKey를 구성하여 매칭합니다.

필드:

PriceConfig (내장):

OpenSearch Document

인덱스: store-items 매핑 파일: opensearch/mappings/store-items-index.json Sync: StoreItemSearchSyncListener — Product에서 brandName 비정규화

DynamoDB → OpenSearch 변환:

JSON 예시

DynamoDB (P03의 StoreItem — "단품" 옵션):

{
  "PK": "STOREITEM#57400bf2-541e-41e7-8f18-2dcfb989a627",
  "SK": "METADATA",
  "entity_type": "STORE_ITEM",
  "store_item_id": "57400bf2-541e-41e7-8f18-2dcfb989a627",
  "product_id": "c5278d25-409c-4db6-893c-54df8d16d509",
  "shop_id": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "store_item_key": "pvg_serum_of-offer:single",
  "product_name": "Vitamin C Brightening Serum",
  "store_item_name": "Vitamin C Serum 단품",
  "price_config": {
    "price": 35000,
    "compare_at_price": null,
    "cost": null,
    "currency": "KRW"
  },
  "sellable_unit_ids": ["su_7557e47428c5"],
  "is_enabled": true,
  "sort_order": 0,
  "gsi1_pk": "PRODUCT#c5278d25-409c-4db6-893c-54df8d16d509",
  "gsi1_sk": "STOREITEM#00000000#57400bf2-541e-41e7-8f18-2dcfb989a627",
  "gsi2_pk": "SHOP#8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "gsi2_sk": "STOREITEM#2026-02-18T05:21:05Z#57400bf2-541e-41e7-8f18-2dcfb989a627",
  "gsi3_pk": "PRODUCT#c5278d25-409c-4db6-893c-54df8d16d509#STOREITEMKEY",
  "gsi3_sk": "pvg_serum_of-offer:single",
  "created_at": 1771392065786,
  "updated_at": 1771392065786
}

OpenSearch:

{
  "store_item_id": "57400bf2-541e-41e7-8f18-2dcfb989a627",
  "product_id": "c5278d25-409c-4db6-893c-54df8d16d509",
  "shop_id": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "store_item_key": "pvg_serum_of-offer:single",
  "store_item_name": "Vitamin C Serum 단품",
  "price": 35000,
  "compare_at_price": null,
  "cost": null,
  "currency": "KRW",
  "is_enabled": true,
  "sort_order": 0,
  "product_name": "Vitamin C Brightening Serum",
  "brand_name": "MAKITT Beauty",
  "sellable_unit_ids": ["su_7557e47428c5"],
  "search_text": "Vitamin C Serum 단품 Vitamin C Brightening Serum",
  "created_at": 1771392065786,
  "updated_at": 1771392065786
}

---

4. SellableUnit & BOM

출고 단위. SKU의 구성(BOM)을 정의하여, 하나의 SellableUnit이 여러 SKU를 묶을 수 있습니다.

DynamoDB Entity

소스: product/sellableunit/entity/SellableUnit.java 키빌더: common/dynamodb/key/SellableUnitKey.java

키 구조:

필드:

SellableUnitType enum:

BomItem (내장)

canonicalBomKey 규칙

BOM 구성을 고유하게 식별하는 정규화 키:

{skuId}:{qty}|{skuId}:{qty}|...

• skuId 기준 사전순 정렬
• 동일 BOM 구성은 항상 동일한 canonicalBomKey 생성

예시:

OpenSearch Document

인덱스: sellable-units Sync: 자동 Sync 리스너 없음 — 수동/벌크 인덱싱 필요

파생 필드:

JSON 예시

DynamoDB (P03 단품용 SU — SINGLE 타입):

{
  "PK": "SELLABLEUNIT#su_7557e47428c5",
  "SK": "METADATA",
  "entity_type": "SELLABLE_UNIT",
  "sellable_unit_id": "su_7557e47428c5",
  "shop_id": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "organization_id": "a68a160d-4678-42e0-876d-0bbea3dd1001",
  "canonical_bom_key": "SKU-SERUM-VC:1",
  "name": "Vitamin C Serum 단품",
  "type": "SINGLE",
  "enabled": true,
  "bom": [
    { "sku_id": "SKU-SERUM-VC", "qty": 1, "role": "REQUIRED" }
  ],
  "gsi1_pk": "SHOP#8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "gsi1_sk": "SELLABLEUNIT#2026-02-18T05:15:00Z#su_7557e47428c5",
  "created_at": "2026-02-18T05:15:00.123Z",
  "updated_at": "2026-02-18T05:15:00.123Z"
}

DynamoDB (P03 풀케어 세트용 SU — BUNDLE 타입):

{
  "sellable_unit_id": "su_e62fa6101127",
  "canonical_bom_key": "SKU-CREAM-CICA:1|SKU-SERUM-VC:1|SKU-TONER-HA:1",
  "name": "Vitamin C 풀케어 세트",
  "type": "BUNDLE",
  "bom": [
    { "sku_id": "SKU-SERUM-VC", "qty": 1, "role": "REQUIRED" },
    { "sku_id": "SKU-TONER-HA", "qty": 1, "role": "REQUIRED" },
    { "sku_id": "SKU-CREAM-CICA", "qty": 1, "role": "REQUIRED" }
  ]
}

OpenSearch:

{
  "sellable_unit_id": "su_e62fa6101127",
  "shop_id": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "organization_id": "a68a160d-4678-42e0-876d-0bbea3dd1001",
  "canonical_bom_key": "SKU-CREAM-CICA:1|SKU-SERUM-VC:1|SKU-TONER-HA:1",
  "name": "Vitamin C 풀케어 세트",
  "type": "BUNDLE",
  "enabled": true,
  "bom": [
    { "sku_id": "SKU-SERUM-VC", "qty": 1, "role": "REQUIRED" },
    { "sku_id": "SKU-TONER-HA", "qty": 1, "role": "REQUIRED" },
    { "sku_id": "SKU-CREAM-CICA", "qty": 1, "role": "REQUIRED" }
  ],
  "bom_sku_ids": ["SKU-SERUM-VC", "SKU-TONER-HA", "SKU-CREAM-CICA"],
  "sku_count": 3,
  "total_qty": 3,
  "search_text": "Vitamin C 풀케어 세트 SKU-CREAM-CICA:1|SKU-SERUM-VC:1|SKU-TONER-HA:1 SKU-SERUM-VC SKU-TONER-HA SKU-CREAM-CICA",
  "created_at": 1771391700123,
  "updated_at": 1771391700123
}

---

5. SKU

최소 재고 관리 단위. Argo CMS에서 생성되어 Kafka를 통해 MAKITT으로 동기화됩니다.

DynamoDB Entity

소스: product/sku/entity/SKU.java 키빌더: common/dynamodb/key/SKUKey.java

키 구조:

skuId는 Argo의 referenceSkuId (UUID). argoSkuId는 Argo 내부 시퀀스 ID (Long).

주요 필드:

동기화: Kafka 토픽 cms-sku-info-change → MAKITT DynamoDB 저장

OpenSearch Document

인덱스: skus Sync: 자동 Sync 리스너 없음 — Kafka 소비 시 인덱싱 또는 벌크 처리

JSON 예시

DynamoDB:

{
  "PK": "SKU#a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "SK": "METADATA",
  "entity_type": "SKU",
  "sku_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "argo_sku_id": 12345,
  "organization_id": "a68a160d-4678-42e0-876d-0bbea3dd1001",
  "sku_code": "SKU-SERUM-VC-30ML",
  "sku_name": "비타민C 브라이트닝 세럼 30ml",
  "barcode": "8809123456789",
  "brand": "MAKITT Beauty",
  "price": 18000,
  "weight": 0.15,
  "dimensions": {
    "length": 4.5,
    "width": 4.5,
    "height": 12.0
  },
  "storage_temperature": "ROOM",
  "stock_status": "IN_STOCK",
  "active": true,
  "enabled": true,
  "gsi1_pk": "ORGANIZATION#a68a160d-4678-42e0-876d-0bbea3dd1001",
  "gsi1_sk": "SKU#2026-01-15T10:00:00Z#a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "gsi3_pk": "ARGO_SKU#12345",
  "gsi3_sk": "METADATA",
  "created_at": "2026-01-15T10:00:00Z",
  "updated_at": "2026-02-10T14:30:00Z"
}

OpenSearch:

{
  "sku_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "organization_id": "a68a160d-4678-42e0-876d-0bbea3dd1001",
  "reference_sku_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "sku_code": "SKU-SERUM-VC-30ML",
  "sku_name": "비타민C 브라이트닝 세럼 30ml",
  "barcode": "8809123456789",
  "brand": "MAKITT Beauty",
  "price": 18000,
  "weight": 0.15,
  "length": 4.5,
  "width": 4.5,
  "height": 12.0,
  "storage_temperature": "ROOM",
  "stock_status": "IN_STOCK",
  "active": true,
  "enabled": true,
  "search_text": "비타민C 브라이트닝 세럼 30ml 8809123456789 MAKITT Beauty SKU-SERUM-VC-30ML",
  "created_at": 1736935200000,
  "updated_at": 1739194200000
}

---

6. Category

상품 분류 체계. Shop 단위로 생성하며, 계층 구조(parent-child)를 지원합니다.

DynamoDB Entity

소스: product/category/entity/Category.java 키빌더: common/dynamodb/key/CategoryKey.java

키 구조:

GSI1 SK에 level과 position을 패딩하여 정렬 가능하게 합니다.

필드:

JSON 예시

{
  "PK": "CATEGORY#f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "SK": "METADATA",
  "entity_type": "CATEGORY",
  "category_id": "f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "shop_id": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "category_name": "Serums & Ampoules",
  "description": "세럼, 앰플, 에센스 등 집중 케어 제품",
  "parent_category_id": "parent-uuid-skincare",
  "path": "/Skincare/Serums & Ampoules",
  "level": 1,
  "position": 2,
  "slug": "serums-ampoules",
  "is_active": true,
  "gsi1_pk": "SHOP#8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "gsi1_sk": "CATEGORY#001#00002#f1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "created_at": "2026-02-18T04:44:54Z",
  "updated_at": "2026-02-18T04:44:54Z"
}

---

7. Tag

상품에 부착하는 태그. Shop 단위로 관리됩니다.

DynamoDB Entity

소스: product/tag/entity/Tag.java 키빌더: common/dynamodb/key/TagKey.java

키 구조:

필드:

JSON 예시

{
  "PK": "TAG#a1b2c3d4-tag-uuid",
  "SK": "METADATA",
  "entity_type": "TAG",
  "tag_id": "a1b2c3d4-tag-uuid",
  "shop_id": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "tag_name": "Best Seller",
  "slug": "best-seller",
  "color": "#FF6B35",
  "position": 0,
  "is_active": true,
  "gsi1_pk": "SHOP#8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "gsi1_sk": "TAG#00000#a1b2c3d4-tag-uuid",
  "created_at": "2026-02-18T04:50:00Z",
  "updated_at": "2026-02-18T04:50:00Z"
}

---

8. ShopAttribute

Shop이 정의하는 동적 상품 속성. Product의 attributes 필드에서 key-value로 참조됩니다.

DynamoDB Entity

소스: product/shopattribute/entity/ShopAttribute.java 키빌더: common/dynamodb/key/ShopAttributeKey.java

키 구조:

필드:

AttributeType enum:

AttributeValueDef (내장 — SELECT 타입의 선택지):

JSON 예시

{
  "PK": "SHOPATTRIBUTE#attr-uuid-skin-type",
  "SK": "METADATA",
  "entity_type": "SHOP_ATTRIBUTE",
  "attribute_id": "attr-uuid-skin-type",
  "shop_id": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "key": "skin_type",
  "name": "Skin Type",
  "description": "대상 피부 타입",
  "type": "MULTI_SELECT",
  "values": [
    { "value_id": "val-uuid-1", "value": "oily", "label": "Oily", "sort_order": 0, "is_active": true },
    { "value_id": "val-uuid-2", "value": "dry", "label": "Dry", "sort_order": 1, "is_active": true },
    { "value_id": "val-uuid-3", "value": "sensitive", "label": "Sensitive", "sort_order": 2, "is_active": true }
  ],
  "show_in_filter": true,
  "show_in_product": true,
  "sort_order": 1,
  "is_required": false,
  "gsi1_pk": "SHOP#8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "gsi1_sk": "SHOPATTRIBUTE#00001#attr-uuid-skin-type",
  "created_at": "2026-02-18T04:55:00Z",
  "updated_at": "2026-02-18T04:55:00Z"
}

---

9. VariantGroup (템플릿)

Shop 수준의 옵션 그룹 템플릿. Product에 적용하면 ProductVariantGroup으로 복사됩니다.

DynamoDB Entity

소스: product/variant/entity/VariantGroup.java 키빌더: common/dynamodb/key/VariantGroupKey.java

키 구조:

필드:

attributeJson/offerJson은 DynamoDB에 JSON 문자열로 저장됩니다. 비즈니스 getter(getAttributeConfig(), getOfferConfig())가 역직렬화합니다.

OpenSearch Document

인덱스: variant-groups Sync: VariantGroupSearchSyncListener

JSON 예시 (ATTRIBUTE 타입)

{
  "PK": "VARIANTGROUP#vg_a1b2c3d4e5f6",
  "SK": "METADATA",
  "entity_type": "VARIANT_GROUP",
  "variant_group_id": "vg_a1b2c3d4e5f6",
  "shop_id": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "name": "컬러 옵션",
  "type": "ATTRIBUTE",
  "required": true,
  "ui_mode": "AUTO",
  "attribute": "{\"options\":[{\"optionId\":\"opt1\",\"optionKey\":\"color\",\"optionName\":\"색상\",\"optionType\":\"COLOR\",\"values\":[{\"valueId\":\"v1\",\"value\":\"Red\",\"displayLabel\":\"빨강\",\"colorHex\":\"#FF0000\",\"sortOrder\":0}],\"sortOrder\":0}]}",
  "gsi1_pk": "SHOP#8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "gsi1_sk": "VARIANTGROUP#vg_a1b2c3d4e5f6",
  "created_at": "2026-02-01T10:00:00Z",
  "updated_at": "2026-02-01T10:00:00Z"
}

OpenSearch:

{
  "variant_group_id": "vg_a1b2c3d4e5f6",
  "shop_id": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "name": "컬러 옵션",
  "type": "ATTRIBUTE",
  "required": true,
  "ui_mode": "AUTO",
  "options": [
    {
      "option_id": "opt1",
      "option_key": "color",
      "option_name": "색상",
      "option_type": "COLOR",
      "values": ["Red"],
      "value_count": 1,
      "sort_order": 0
    }
  ],
  "option_names": ["색상"],
  "option_values": ["Red"],
  "option_count": 1,
  "offer_variants": [],
  "offer_variant_names": [],
  "sellable_unit_ids": [],
  "offer_variant_count": 0,
  "search_text": "컬러 옵션 Red",
  "created_at": 1738400400000,
  "updated_at": 1738400400000
}

---

10. StoreItem Canonical Key 규칙

StoreItem의 storeItemKey는 구매자가 선택한 옵션 조합을 고유하게 식별하는 정규화 키입니다. PDP에서 옵션 선택 → StoreItem 매칭의 핵심입니다.

소스:

• StoreItemCanonicalKeyUtil.java — storeItemKey 생성/파싱/정규화
• CombinationKeyUtil.java — combinationKey 생성/파싱/정규화
• StoreItemValidator.java — storeItemKey 유효성 검증
• StoreItemCandidateApplication.java — 후보 StoreItem 생성

10.1 CombinationKey (내부 키)

하나의 PVG 내에서 선택된 옵션 조합을 표현합니다.

형식:

optionKey:valueKey|optionKey:valueKey|...

규칙:

• 구분자: : (key-value), | (쌍 사이)
• optionKey 기준 사전순(lexical) 정렬
• normalize(): 파싱 후 재정렬하여 정규화

예시:

10.2 StoreItemKey (외부 키)

여러 PVG에 걸친 전체 선택을 하나의 키로 합칩니다.

형식:

{pvgId}-{combinationKey}::{pvgId}-{combinationKey}::...

규칙:

• 세그먼트 구분자: :: (combinationKey 내부에 :가 있으므로 :: 사용)
• 세그먼트 내부: {pvgId}-{combinationKey} (-로 연결)
• 파싱: 각 세그먼트의 첫 번째 -를 기준으로 pvgId와 combinationKey 분리

세그먼트 정렬 규칙:

pvgId 사전순(lexical) 정렬 — 단일 규칙.

모든 컨텍스트(생성, 조회, 정규화)에서 StoreItemCanonicalKeyUtil.generate()를 통해 동일한 lexical order로 키를 생성합니다. PVG 타입(ATTRIBUTE/OFFER)이나 sortOrder는 키 정렬에 영향을 주지 않습니다.

OFFER required=false 시 none 슬롯:

선택적 OFFER PVG에서 사용자가 선택하지 않은 경우, combinationKey 자리에 "none" 사용:

pvg_gift-none           → 사은품 미선택
pvg_gift-gift:sample    → 샘플 키트 선택

10.3 유형별 예시

Case 1: 단일 상품 (옵션 없음)

pvg_94e75949-default:default

단일 StoreItem도 PVG가 필요합니다. "Default" PVG를 생성하여 default:default 조합 사용.

Case 2: OFFER 단일 PVG (P03 Serum)

3개 옵션 → 3개 StoreItem:

pvg_serum_of-offer:single      → 단품 ₩35,000
pvg_serum_of-offer:1plus1      → 1+1 ₩56,000
pvg_serum_of-offer:fullcare    → 풀케어 세트 ₩72,000

Case 3: ATTRIBUTE 단일 PVG (P06 Lip Tint)

5개 컬러 → 5개 StoreItem:

pvg_lip5-lip_color:rose    → Rose Pink ₩22,000
pvg_lip5-lip_color:coral   → Coral ₩22,000
pvg_lip5-lip_color:berry   → Berry ₩22,000
pvg_lip5-lip_color:nude    → Nude ₩22,000
pvg_lip5-lip_color:red     → Classic Red ₩22,000

Case 4: ATTRIBUTE + OFFER 혼합 (P11 Primer)

3 shades × 2 offers = 6개 StoreItem. 각 StoreItem의 키는 두 PVG의 조합:

pvg_primer_offer-offer:fullset::pvg_primer_shade-shade:lavender
pvg_primer_offer-offer:fullset::pvg_primer_shade-shade:peach
pvg_primer_offer-offer:fullset::pvg_primer_shade-shade:pink
pvg_primer_offer-offer:single::pvg_primer_shade-shade:lavender
pvg_primer_offer-offer:single::pvg_primer_shade-shade:peach
pvg_primer_offer-offer:single::pvg_primer_shade-shade:pink

pvgId 사전순: pvg_primer_offer < pvg_primer_shade → OFFER 세그먼트가 먼저 옵니다. PVG 타입과 무관하게 항상 pvgId lexical order로 정렬됩니다.

Case 5: OFFER required=false (선택적 OFFER)

required=false인 OFFER PVG는 선택하지 않을 수 있습니다. 이 경우 none 슬롯이 추가:

pvg_attr_color-color:red::pvg_gift-none            → 빨강, 사은품 없음
pvg_attr_color-color:red::pvg_gift-gift:sample_kit  → 빨강, 샘플 키트 추가

10.4 Validation 규칙 (StoreItemValidator)

1. 최소 1개: StoreItem 목록은 비어있을 수 없음
2. 키 유일성: 동일 Product 내 중복 storeItemKey 불가
3. 형식 검증: StoreItemCanonicalKeyUtil.parse(key)가 1개 이상의 GroupSelection 반환
4. PVG 참조: storeItemKey의 모든 pvgId가 Product의 PVG 목록에 존재해야 함
5. 이름: 비어있지 않음, 최대 200자
6. 가격: priceConfig.price 필수, >= 0

10.5 PDP 판매 가능 판단 흐름

사용자가 옵션 선택 완료
       │
       ▼
각 PVG의 선택된 combinationKey로 storeItemKey 구성
 (pvgId-combKey 세그먼트를 :: 로 연결, pvgId 사전순 정렬)
       │
       ▼
storeItems.find(item =>
    item.storeItemKey === expectedKey
    && item.isEnabled === true
)
       │
    찾았나?
   /       \
 YES        NO
  │          │
 구매가능    "판매하지 않는 옵션입니다"
  │          버튼 비활성화
 장바구니/
 바로구매

---

11. Shop API (상점 공개 API)

Shop API는 Builder/PDP에서 소비하는 API입니다. 상품 조회는 OpenSearch에서, resolve는 DynamoDB에서 처리됩니다.

Base URL: http://localhost:10000/shop/{shopId}

소스:

• Controller: makitt-shop-api/.../shop/controller/ProductController.java
• DTO: makitt-shop-api/.../shop/dto/product/ProductDto.java
• Response: makitt-shop-api/.../shop/dto/product/ProductSearchResponse.java

11.1 상품 목록 API

GET /shop/{shopId}/products/list

기본 페이지네이션 목록. 필터 없이 전체 상품 조회.

Query Parameters:

GET /shop/{shopId}/products/search

고급 검색/필터링 + Facet 지원.

Query Parameters:

정렬 → OpenSearch 필드 매핑:

목록 응답: ProductSearchResponse

{
  "items": [ ProductDto, ... ],
  "page": 1,
  "size": 20,
  "totalItems": 150,
  "totalPages": 8,
  "hasNext": true,
  "hasPrevious": false,
  "facets": { ... },
  "priceStats": { ... }
}

Facet 필드 (includeFacets=true 일 때만):

11.2 상품 상세 API

GET /shop/{shopId}/products/{productId}

Product ID로 단건 조회. OpenSearch products 인덱스에서 조회.

GET /shop/{shopId}/products/by-slug/{slug}

SEO slug로 단건 조회. shop_id == shopId AND seo_slug == slug 매칭.

상세 응답: ProductDto

{
  "id": "c5278d25-409c-4db6-893c-54df8d16d509",
  "shopId": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "name": "Vitamin C Brightening Serum",
  "description": "순수 비타민C 15% 함유 브라이트닝 세럼.",
  "shortDescription": "비타민C 15% 브라이트닝 세럼 30ml",
  "categoryName": "Serums & Ampoules",
  "tags": ["Best Seller", "Vegan"],
  "brandName": "MAKITT Beauty",
  "supplierName": null,
  "attributeValues": ["product_type:serum", "skin_type:all", "volume_ml:30"],
  "thumbnailImage": "https://cdn.dev.makitt.shop/products/main/2026/02/79514563.png",
  "mainImages": ["https://cdn.dev.makitt.shop/products/main/2026/02/79514563.png"],
  "detailImages": [
    "https://cdn.dev.makitt.shop/products/detail/2026/02/c225197f.png",
    "https://cdn.dev.makitt.shop/products/detail/2026/02/73a50050.png"
  ],
  "featuredPrice": 35000,
  "featuredCompareAtPrice": null,
  "seoSlug": null,
  "seoTitle": null,
  "seoDescription": null,
  "productVariantGroups": [
    {
      "productVariantGroupName": "Offer",
      "sortOrder": 0,
      "groupType": "OFFER",
      "required": true,
      "uiMode": "AUTO",
      "options": [
        {
          "optionName": "구매 옵션",
          "optionType": "text",
          "sortOrder": 0,
          "values": [
            {
              "valueName": "단품",
              "colorHex": null,
              "sortOrder": 0,
              "valueSelection": "pvg_serum_of-offer:single"
            },
            {
              "valueName": "1+1",
              "colorHex": null,
              "sortOrder": 1,
              "valueSelection": "pvg_serum_of-offer:1plus1"
            },
            {
              "valueName": "풀케어 세트",
              "colorHex": null,
              "sortOrder": 2,
              "valueSelection": "pvg_serum_of-offer:fullcare"
            }
          ]
        }
      ]
    }
  ],
  "status": { "name": "ACTIVE", "description": "ACTIVE" },
  "createdAt": 1771392065711,
  "updatedAt": 1771396886123
}

Shop API 응답에서 제외된 필드

아래 필드들은 OpenSearch 인덱스에는 존재하지만, Shop API ProductDto 응답에는 포함되지 않습니다. valueSelection 토큰과 Resolve API 도입으로 클라이언트가 내부 키 구조를 알 필요가 없어졌기 때문입니다.

참고: optionNames, optionValues, groupTypes, hasOfferVariants 등은 OpenSearch 인덱스에는 유지됩니다 (검색/필터링/facet에 사용).

valueSelection 필드

각 옵션 값에 서버가 생성한 selection 토큰을 포함합니다. 클라이언트는 이 토큰을 opaque string으로 취급하여 resolve/cart API에 그대로 전달합니다.

생성 규칙: {pvgId}-{optionKey}:{valueKey} — StoreItemCanonicalKeyUtil의 세그먼트 형식과 동일

구현 위치: Shop API의 ProductDto.fromDocument() 변환 시 생성. 도메인 모델이나 OpenSearch 인덱스에는 저장하지 않습니다. StoreItemCanonicalKeyUtil의 기존 상수(GROUP_KEY_DELIMITER, SEGMENT_DELIMITER)와 CombinationKeyUtil을 활용하여 생성합니다.

valueSelection = pvgId + "-" + CombinationKeyUtil.generate(optionKey, valueKey)
               = pvgId + "-" + optionKey + ":" + valueKey

예시:

ProductDto 필드 목록

ProductVariantGroupDto

OptionDto

OptionValueDto

11.3 StoreItem Resolve API

사용자의 옵션 선택을 서버에 보내면, 서버가 매칭되는 StoreItem을 반환합니다. 클라이언트는 valueSelection 토큰을 수집하여 배열로 전송하기만 하면 됩니다. 키 조합/정렬 로직이 클라이언트에 필요 없습니다.

GET /shop/{shopId}/products/{productId}/resolve?selections={token}&selections={token}

selections query parameter로 valueSelection 토큰을 전달합니다. 순서는 상관없습니다.

GET /shop/{shopId}/products/{productId}/resolve
  ?selections=pvg_primer_shade-shade:pink
  &selections=pvg_primer_offer-offer:single

Response:

{
  "storeItemId": "57400bf2-541e-41e7-8f18-2dcfb989a627",
  "storeItemName": "Tone-Up Glow Primer Pink / 단품",
  "price": 28000,
  "compareAtPrice": null,
  "currency": "KRW",
  "isEnabled": true,
  "sellableUnitIds": ["su_eec1a3df243a"]
}

Response 필드:

내부 처리 흐름:

Builder: 사용자가 옵션 선택 → 각 선택의 valueSelection 수집
    │
    ▼
POST /resolve { selections: ["pvg_x-opt:val", "pvg_y-opt:val"] }
    │
    ▼
서버: 각 selection 문자열을 StoreItemCanonicalKeyUtil.parse()로 GroupSelection 리스트 변환
    │
    ▼
서버: StoreItemCanonicalKeyUtil.generate(groupSelections)로 정렬된 storeItemKey 생성
    │
    ▼
서버: DynamoDB GSI3 (PRODUCT#{productId}#STOREITEMKEY, {storeItemKey})로 조회
    │
    ▼
Response: { storeItemId, price, ... }

핵심: 클라이언트가 보낸 selections의 순서는 무관합니다. generate()가 pvgId lexical order로 정렬하므로 항상 동일한 canonical key가 생성됩니다.

에러 응답:

Builder PDP 통합 흐름

1. 페이지 로드
   GET /products/{id} → ProductDto
   └─ featuredPrice/featuredCompareAtPrice로 기본 가격 표시
   └─ productVariantGroups 렌더링 (옵션 UI)
   └─ 각 value의 valueSelection은 내부에 보관

2. 옵션 선택 완료 (모든 required PVG 선택 시)
   POST /products/{id}/resolve
     { "selections": [선택된 value들의 valueSelection 배열] }
   └─ 응답의 price로 실제 가격 갱신
   └─ isEnabled=false면 "품절" 표시

3. 장바구니 추가
   POST /cart/items { storeItemId, quantity }
   └─ resolve 응답의 storeItemId 그대로 전송

required=false PVG 처리:

선택적 PVG (required=false)의 경우, 상품 상세 응답에 "선택안함" 옵션 값이 자동으로 포함됩니다. 이 값의 valueSelection은 {pvgId}-none 형식이며, sortOrder=-1로 맨 앞에 위치합니다.

// 상품 상세 응답 예시 — required=false PVG
{
  "productVariantGroupName": "사은품",
  "required": false,
  "options": [{
    "optionName": "사은품 선택",
    "values": [
      { "valueName": "선택안함", "sortOrder": -1, "valueSelection": "pvg_gift-none" },
      { "valueName": "샘플키트", "sortOrder": 0, "valueSelection": "pvg_gift-gift:sample_kit" }
    ]
  }]
}

클라이언트는 "선택안함"을 일반 옵션 값과 동일하게 처리하면 됩니다. 추가로, 서버는 Resolve/Cart API에서 누락된 required=false PVG에 대해 {pvgId}-none을 자동 보충합니다 (safety net).

// 사은품 미선택 시 — "선택안함"의 valueSelection 전송
{ "selections": ["pvg_attr_color-color:red", "pvg_gift-none"] }

// 사은품 선택 시
{ "selections": ["pvg_attr_color-color:red", "pvg_gift-gift:sample_kit"] }

// 선택적 PVG를 아예 생략해도 서버가 자동 보충
{ "selections": ["pvg_attr_color-color:red"] }
// → 서버 내부: ["pvg_attr_color-color:red", "pvg_gift-none"]

11.4 Full Product Detail API

별도의 Resolve 호출 없이, 한 번의 API 호출로 상품 정보와 모든 StoreItem(가격/재고/ID)을 함께 반환합니다. Builder PDP에서 옵션 선택 시 클라이언트 사이드에서 즉시 가격을 표시할 수 있습니다.

GET /shop/{shopId}/products/{productId}/full

기존 ProductDto의 모든 필드에 storeItems 맵을 추가한 응답을 반환합니다.

응답 예시

P11 "Ampoule Mask Combo Set" 기준 (PVG 3개 — 앰플 ATTRIBUTE, 마스크 OFFER, 사은품 OFFER required=false):

{
  "id": "e91d3996-6623-4e56-b5c0-ccf631cb7154",
  "shopId": "8e450dc8-2434-4ab4-aa75-252bbb8ace42",
  "name": "Ampoule Mask Combo Set",
  "description": "고농축 앰플과 마스크 팩을 함께 구성한 스페셜 세트.",
  "shortDescription": "앰플 + 마스크 콤보 세트",
  "categoryName": "Sets & Kits",
  "tags": ["Best Seller"],
  "brandName": "MAKITT Beauty",
  "featuredPrice": 18000,
  "featuredCompareAtPrice": 25000,
  "thumbnailImage": "https://cdn.dev.makitt.shop/products/main/2026/02/abcdef01.png",
  "productVariantGroups": [
    {
      "productVariantGroupName": "앰플 선택",
      "sortOrder": 0,
      "groupType": "ATTRIBUTE",
      "required": true,
      "uiMode": "SHOW",
      "options": [
        {
          "optionName": "성분",
          "optionType": "text",
          "sortOrder": 0,
          "values": [
            { "valueName": "나이아신아마이드", "sortOrder": 0, "valueSelection": "pvg_ample-ingredient:ing_niacinamide" },
            { "valueName": "히알루론산", "sortOrder": 1, "valueSelection": "pvg_ample-ingredient:ing_hyaluronic" }
          ]
        },
        {
          "optionName": "용량",
          "optionType": "text",
          "sortOrder": 1,
          "values": [
            { "valueName": "10ml", "sortOrder": 0, "valueSelection": "pvg_ample-ml:ml_10" },
            { "valueName": "30ml", "sortOrder": 1, "valueSelection": "pvg_ample-ml:ml_30" }
          ]
        }
      ]
    },
    {
      "productVariantGroupName": "마스크 수량",
      "sortOrder": 1,
      "groupType": "OFFER",
      "required": true,
      "uiMode": "AUTO",
      "options": [
        {
          "optionName": "마스크 수량",
          "optionType": "text",
          "sortOrder": 0,
          "values": [
            { "valueName": "1매", "sortOrder": 0, "valueSelection": "pvg_mask_offer-mask_qty:mask_1ea" },
            { "valueName": "2매 세트", "sortOrder": 1, "valueSelection": "pvg_mask_offer-mask_qty:mask_2ea" },
            { "valueName": "4매 세트", "sortOrder": 2, "valueSelection": "pvg_mask_offer-mask_qty:mask_4ea" }
          ]
        }
      ]
    },
    {
      "productVariantGroupName": "사은품",
      "sortOrder": 2,
      "groupType": "OFFER",
      "required": false,
      "uiMode": "AUTO",
      "options": [
        {
          "optionName": "사은품 선택",
          "optionType": "text",
          "sortOrder": 0,
          "values": [
            { "valueName": "선택안함", "sortOrder": -1, "valueSelection": "pvg_gift-none" },
            { "valueName": "미니 트래블 세트 증정", "sortOrder": 0, "valueSelection": "pvg_gift-gift_option:gift_mini_set" }
          ]
        }
      ]
    }
  ],
  "status": { "name": "ACTIVE", "description": "ACTIVE" },

  "storeItems": {
    "pvg_ample-ingredient:ing_niacinamide|ml:ml_10::pvg_gift-none::pvg_mask_offer-mask_qty:mask_1ea": {
      "storeItemId": "720f4dbe-8e57-49d6-be96-a17ed477cf8f",
      "storeItemName": "나이아신아마이드 10ml / 마스크 1매",
      "price": 18000,
      "compareAtPrice": 25000,
      "currency": "KRW",
      "isEnabled": true,
      "selections": [
        "pvg_ample-ingredient:ing_niacinamide",
        "pvg_ample-ml:ml_10",
        "pvg_gift-none",
        "pvg_mask_offer-mask_qty:mask_1ea"
      ]
    },
    "pvg_ample-ingredient:ing_niacinamide|ml:ml_10::pvg_gift-none::pvg_mask_offer-mask_qty:mask_2ea": {
      "storeItemId": "11c56e8e-5528-4eec-925a-690f6e93fde7",
      "storeItemName": "나이아신아마이드 10ml / 마스크 2매 세트",
      "price": 34000,
      "compareAtPrice": 50000,
      "currency": "KRW",
      "isEnabled": true,
      "selections": [
        "pvg_ample-ingredient:ing_niacinamide",
        "pvg_ample-ml:ml_10",
        "pvg_gift-none",
        "pvg_mask_offer-mask_qty:mask_2ea"
      ]
    },
    "pvg_ample-ingredient:ing_niacinamide|ml:ml_10::pvg_gift-gift_option:gift_mini_set::pvg_mask_offer-mask_qty:mask_1ea": {
      "storeItemId": "55bc822a-31f1-407d-910d-67f355ed39f5",
      "storeItemName": "나이아신아마이드 10ml / 마스크 1매 / 미니 트래블 세트 증정",
      "price": 21000,
      "compareAtPrice": 28000,
      "currency": "KRW",
      "isEnabled": true,
      "selections": [
        "pvg_ample-ingredient:ing_niacinamide",
        "pvg_ample-ml:ml_10",
        "pvg_gift-gift_option:gift_mini_set",
        "pvg_mask_offer-mask_qty:mask_1ea"
      ]
    },
    "pvg_ample-ingredient:ing_niacinamide|ml:ml_30::pvg_gift-gift_option:gift_mini_set::pvg_mask_offer-mask_qty:mask_2ea": {
      "storeItemId": "494e9b55-629c-4ee2-a32e-87e3fb08e243",
      "storeItemName": "나이아신아마이드 30ml / 마스크 2매 세트 / 미니 트래블 세트 증정",
      "price": 42000,
      "compareAtPrice": 58000,
      "currency": "KRW",
      "isEnabled": true,
      "selections": [
        "pvg_ample-ingredient:ing_niacinamide",
        "pvg_ample-ml:ml_30",
        "pvg_gift-gift_option:gift_mini_set",
        "pvg_mask_offer-mask_qty:mask_2ea"
      ]
    }
  }
}

참고: 위 예시는 30개 StoreItem 중 4개만 발췌한 것입니다. 실제 응답에는 모든 유효 조합이 포함됩니다.

storeItems 맵 구조

StoreItemInfo 필드

selections 필드 생성 규칙

서버가 storeItemKey를 개별 valueSelection 토큰으로 확장합니다:

storeItemKey (canonical key):
  pvg_ample-ingredient:ing_niacinamide|ml:ml_10::pvg_gift-none::pvg_mask_offer-mask_qty:mask_1ea

1. "::" 로 세그먼트 분리:
   - pvg_ample-ingredient:ing_niacinamide|ml:ml_10
   - pvg_gift-none
   - pvg_mask_offer-mask_qty:mask_1ea

2. 각 세그먼트에서 pvgId 추출 (첫 번째 "-" 앞):
   - pvg_ample → ingredient:ing_niacinamide|ml:ml_10

3. combinationKey를 "|" 로 분리하여 개별 토큰 생성:
   - pvg_ample-ingredient:ing_niacinamide
   - pvg_ample-ml:ml_10

4. "none" 세그먼트는 그대로 유지:
   - pvg_gift-none

결과 selections:
  ["pvg_ample-ingredient:ing_niacinamide", "pvg_ample-ml:ml_10", "pvg_gift-none", "pvg_mask_offer-mask_qty:mask_1ea"]

Builder PDP 통합 흐름

1. 페이지 로드
   GET /products/{id}/full → ProductDto + storeItems
   └─ featuredPrice/featuredCompareAtPrice로 기본 가격 표시
   └─ productVariantGroups 렌더링 (옵션 UI)
   └─ storeItems 맵을 메모리에 보관

2. 옵션 선택 시 (실시간, API 호출 없음)
   사용자가 옵션 선택 → 각 선택의 valueSelection 토큰 수집
   └─ storeItems를 순회하며 selections가 사용자 선택과 일치하는 항목 찾기
      (Set equality: 사용자 선택 토큰 Set == storeItem.selections Set)
   └─ 매칭 항목의 price로 가격 갱신
   └─ isEnabled=false면 "품절" 표시

3. 장바구니 추가
   POST /cart/items { storeItemId, quantity }
   └─ 매칭된 storeItem의 storeItemId 사용

기존 방식 대비 차이: 기존 GET /products/{id} + POST /resolve 2-call 흐름 대신, 1-call로 모든 정보를 받아 클라이언트 사이드에서 즉시 매칭합니다. Resolve API는 개별 조합 확인이 필요한 경우 여전히 사용 가능합니다.

기존 API와의 관계

서버 내부 처리

1. ProductSearchService.getProductById(productId) → ProductDocument
2. StoreItemService.findByProductId(productId) → List<StoreItem> (GSI1 조회)
3. ProductDto.fromDocument(document) → 기존 상품 정보
4. 각 StoreItem에 대해:
   ├─ storeItemKey → selections 토큰 확장
   └─ StoreItemInfo 생성 (price, isEnabled, ...)
5. storeItems 맵 구성 (키: storeItemKey)
6. 응답 반환

11.5 에러 응답

모든 비즈니스 에러는 HTTP 400으로 반환됩니다.

{
  "code": "error.product.not_found",
  "defaultMessage": "Product not found",
  "message": "상품을 찾을 수 없습니다",
  "timestamp": "2026-02-18T08:00:00Z",
  "path": "/shop/8e450dc8-.../products/invalid-id"
}

---

GSI 인덱스 사용 현황

OpenSearch Sync 현황