핵심 요약
- 카탈로그는 commerce의 모든 흐름이 시작되는 상품 원장이에요.
- SKU, 옵션, 가격, 판매 상태를 카탈로그에 고정해야 checkout과 orders가 안정적으로 연결돼요.
- CRUD는 상품 생성에서 끝나지 않고 목록 조회와 상태 전환까지 포함해야 운영이 가능해요.
- 상품 상태를 명확히 나누면 품절, 숨김, 판매중을 코드와 운영 화면에서 같은 의미로 쓸 수 있어요.
이 기능이 왜 필요한지·무엇을 먼저 정할지는 블로그에서 다뤄요.
- 결제만 붙이면 되나요, 주문까지 해야 하나요? — 상품 데이터를 사내 DB에 둘지 commerce에 맡길지 판단 기준
이런 상황이라면
상품 정보를 사내 DB만으로 관리하기보다 commerce에 같이 싣고 싶다면 카탈로그부터 정리해야 해요. 여러 옵션, 묶음 가격, SKU 구분이 있는 상품이라면 주문 전에 카탈로그 모델을 먼저 고정해야 해요. 품절과 판매중지, 임시 숨김을 운영자가 자주 바꿔야 한다면 상태 관리 문맥까지 같이 봐야 해요.
카탈로그는 단순 등록 화면이 아니라 checkout과 orders를 지탱하는 데이터 기준점이에요.
1카탈로그 모델
카탈로그는 상품 하나를 보여주는 화면용 데이터가 아니라, 결제와 주문에 재사용될 기준 데이터를 관리하는 모델이에요.
핵심 필드는 다음 축으로 이해하면 돼요.
| 축 | 설명 | 예시 |
|---|---|---|
| SKU | 상품 식별자 | 색상별, 사이즈별 재고 구분 |
| 옵션 | 고객 선택 단위 | 색상, 용량, 구독 타입 |
| 가격 | 청구 기준 금액 | 정상가, 옵션가, 할인 전 기준가 |
| 상태 | 판매 가능 여부 | 판매중, 품절, 숨김 |
SKU는 내부 재고와 매칭하기 위한 식별자에 가깝고, 옵션은 고객이 선택하는 판매 단위에 가까워요. 가격은 화면 표시용이면서 동시에 주문 검증 기준이 되므로, 운영자가 수정할 때 이력과 반영 시점을 같이 보는 편이 안전해요.
카탈로그 설계에서 먼저 정해야 할 질문은 다음과 같아요.
- 옵션 조합마다 SKU를 따로 둘 것인가
- 가격이 옵션별로 달라지는가
- 품절을 옵션 단위로 제어할 것인가 상품 단위로 제어할 것인가
- 숨김 상태의 상품을 기존 주문 상세에서 어떻게 보여줄 것인가
관련 문서:
2CRUD 흐름
카탈로그 CRUD는 생성, 수정, 조회, 삭제를 각각 분리해서 보기보다 운영 순환으로 이해하는 편이 나아요.
생성
신규 상품을 만들 때는 이름, 가격, SKU, 옵션 구조를 먼저 등록해요. 이 단계에서 상품 타입이 일반 상품인지 구독 상품인지까지 분리해 두면 이후 checkout과 subscription 연결이 쉬워져요.
수정
수정은 상품명 교정만이 아니라 가격 변경, 옵션 구조 보정, 노출 정책 변경까지 포함해요. 이미 판매된 주문이 있는 상품이라면 수정 전후 의미가 달라지지 않도록 주의해야 해요.
조회
목록 조회는 관리자 화면과 운영 배치 모두에 쓰여요. 판매중 상품만 볼 것인지, 숨김 상품까지 함께 볼 것인지 조회 조건을 분리해 두는 편이 좋아요.
삭제
삭제는 물리 삭제보다 운영 중단에 가까운 경우가 많아요. 이미 주문과 연결된 상품은 완전 삭제보다 상태 전환이 더 안전해요.
문서 연결:
3상태 관리
상품 상태는 운영자 언어와 API 언어가 어긋나기 쉬운 부분이에요. 최소한 다음 세 가지는 분리해서 써야 해요.
| 상태 | 의미 | 언제 쓰는가 |
|---|---|---|
| 판매중 | 고객이 지금 구매할 수 있어요 | 정상 판매 |
| 품절 | 판매 의도는 있지만 재고나 수량 조건이 부족하다 | 재입고 예정 |
| 숨김 | 고객에게 노출하지 않는다 | 프로모션 종료, 테스트, 일시 중단 |
품절과 숨김을 같은 상태로 다루면 운영상 문제가 생겨요.
- 품절은 재고 이슈예요.
- 숨김은 노출 정책 이슈예요.
- 판매중지는 법적 이슈나 운영 중단 같은 별도 정책일 수 있어요.
카탈로그 상태가 정확해야 checkout에서 선택 불가 상품을 걸러낼 수 있고, orders에서도 과거 주문과 현재 진열 상태를 함께 해석할 수 있어요.
관련 문서:
4다음 단계
카탈로그를 이해한 뒤에는 아래 순서가 자연스러워요.
- 상품 생성으로 최소 필드를 등록해요.
- 체크아웃 이해하기에서 카트와 주문 연결 방식을 봐요.
- 주문 이해하기에서 상품 데이터가 주문에 어떻게 고정되는지 확인해요.
- 구독 상품이라면 계약 조회와 구독 모델 구조까지 이어서 읽어요.
카탈로그를 먼저 잡아 두면 이후 문서 대부분이 같은 용어로 읽히기 시작해요.