id: 'product-list-grid'
status: in-progress
Product List Grid
Reference
- URL: https://biodance.com/ (메인 페이지 상품 목록 영역)
- 위치: 메인 페이지 중간부 — 상품 카드 그리드
- 구조: 4컬럼 그리드 → 태블릿 3컬럼 → 모바일 2컬럼. 카드 = 이미지(1:1) + 카테고리 + 상품명 + 짧은 설명 + 할인율/판매가/정가
React Component
- Path:
apps/makitt-standard-commerce/src/components/assets/product-list-grid/
- Status: implemented
- 반응형: Desktop 4컬럼 / Tablet 3컬럼 / Mobile 2컬럼 (useIsMobile, useIsTablet)
- i18n: ko, en, ja (assets.productListGrid.* namespace)
- API:
shopApi.searchProductCards() — 경량 product card 전용 API, mock mode 지원
- Currency:
auth.me → i18n.currency.symbol 로 통화 기호 결정
- 필터 파라미터: categories, tags, attributes (key:value), sortBy
HCS JSON Asset
- Path:
apps/builder/data/hcs-asset/product-list-grid.json
- Status: implemented
- Resource 바인딩:
product.cards — 상품 카드 검색 (categories, tags, sortBy, page 파라미터)product.categories — 카테고리 필터 (rootOnly: true)
- 카테고리 필터: 버튼 chip으로 categories.items repeat, 클릭 시 pagination action
- 상품 카드: productCards.items repeat, 이미지/카테고리/상품명/설명/가격
- 페이지네이션: prev/next + page numbers (pageRange transform)
Resource Registry
- Package:
@makitt/api
- Key:
product.cards
- Schema:
ProductCardSearchResponseSchema / ProductCardSchema
- Fetcher:
productApi.cards()
- AcceptedParams: q, categories, tags, attributes, sortBy
Prerequisites
makitt-server (shop-api)
고객 대면 API. shop storefront에서 호출.
| API | Method | Endpoint | Status |
|---|
| 상품 카드 검색 | GET | /shop/{shopId}/products/cards | available |
| 상품 검색 (full) | GET | /shop/{shopId}/products/search | available |
| 상품 상세 | GET | /shop/{shopId}/products/{id} | available |
| 상품 slug 조회 | GET | /shop/{shopId}/products/by-slug/{slug} | available |
| 카테고리 목록 | GET | /shop/{shopId}/categories/list | available |
| 태그 목록 | GET | /shop/{shopId}/tags/list | available |
makitt-server (admin-api)
셀러 어드민에서 상품을 관리하기 위한 API.
| API | Method | Endpoint | Status |
|---|
| 상품 CRUD | - | /shops/{shopId}/products/... | available |
| 태그 관리 | - | /shops/{shopId}/tags/... | available |
| 카테고리 관리 | - | /shops/{shopId}/categories/... | available |
makitt-server (도메인/모델링)
| 항목 | 내용 | Status |
|---|
| Product Entity | DynamoDB + OpenSearch 연동 | available |
| Tag Entity | DynamoDB | available |
| Category Entity | DynamoDB | available |
makitt-web (셀러 어드민 UI)
| 기능 | 설명 | Status |
|---|
| 상품 관리 | 상품 CRUD, 이미지 업로드, 가격/옵션 설정 | available |
| 태그 관리 | 상품 태그 생성/편집/삭제 | available |
| 카테고리 관리 | 카테고리 트리 관리 | available |
@makitt/api (리소스 레지스트리)
| 항목 | 설명 | Status |
|---|
product.cards resource | ProductCardSearchResponseSchema + fetcher | available |
product.categories resource | CategorySchema + fetcher | available |
product.tags resource | TagSchema + fetcher | available |
makitt-shop (HCS 렌더링)
| 항목 | 설명 | Status |
|---|
data-list renderer | data-list 컴포넌트 렌더링 | available |
product.cards resource fetch | fetchByResourceRef 지원 | available |
pagination action | URL 쿼리 파라미터 업데이트 | available |
navigate action | 상품 상세 페이지 이동 | available |
HCS Conversion Notes
- 구조: section → container(max-width) → category filter(repeat) + data-list(grid + empty + pagination)
- 데이터 바인딩:
product.cards resource로 상품 카드 fetch → productCards.items repeat
- 카테고리 필터:
product.categories resource → categories.items repeat → chip buttons
- 가격:
featuredPrice, featuredCompareAtPrice, discountPercent — 서버 계산 할인율
- 이미지:
thumbnailImage || mainImage fallback
- 가격 포맷:
|currency transform (i18n currency 기반)