HcsAsset

개요

HcsAsset(Headless Component System Asset)은 Builder에서 사전 정의된 컴포넌트 구조를 재사용 가능한 에셋으로 관리하는 도메인. 사용자는 직접 만든 컴포넌트 트리를 HcsAsset으로 저장하고, 다른 페이지나 프로젝트에서 쉽게 재사용할 수 있다.

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

핵심 기능:

• Builder에서 만든 커스텀 컴포넌트 구조 저장 및 재사용
• 비즈니스 의미를 담는 shopComponentType 라벨 시스템
• OpenSearch 기반 전문 검색 (name, description, tags)
• 필터링 (componentType, shopComponentType, createdBy, tags)
• 사용 횟수 추적 (usageCount)
• 생성자(createdBy) 기반 접근 제어

---

DynamoDB Entity

HcsAsset

Single Table Design 기반의 HcsAsset 엔티티. 사용자(User)별로 관리되며, OpenSearch와 이벤트 기반 동기화된다.

키 구조:

필드:

Factory Methods:

• HcsAsset.create(name, description, treeNodeJson, thumbnailUrl, componentType, shopComponentType, createdBy, tags) — 새로운 HcsAsset 생성 (UUID 및 타임스탬프 자동 생성)

Business Methods:

• incrementUsageCount() — 사용 횟수 증가 + updatedAt 갱신
• update(name, description, treeNodeJson, thumbnailUrl, componentType, shopComponentType, tags) — 에셋 메타데이터 업데이트 (nullable 필드)

---

GSI 키 구조

GSI1 설명:

• 사용자가 만든 모든 HcsAsset을 생성 시간순으로 조회
• KEYS_ONLY Projection → 2단계 조회 (GSI 쿼리 → 메인 테이블 Fetch)
• Reverse Scan으로 최신순 정렬

Key Builder (com.makitt.core.common.dynamodb.key.HcsAssetKey):

HcsAssetKey.pk(hcsAssetId)                                      → "HCSASSET#{hcsAssetId}"
HcsAssetKey.sk()                                                → "METADATA"
HcsAssetKey.gsi1Pk(userId)                                      → "USER#{userId}"
HcsAssetKey.gsi1Sk(createdAtEpochMs, hcsAssetId)               → "HCSASSET#{createdAtEpochMs}#{hcsAssetId}"
HcsAssetKey.gsi1SkPrefix()                                      → "HCSASSET#"
HcsAssetKey.extractHcsAssetId(pk)                               → "550e8400..." (from "HCSASSET#550e8400...")

---

OpenSearch Document

HcsAssetDocument

HcsAsset의 검색 및 필터링을 위한 OpenSearch 인덱스.

Index 이름: hcs-assets

필드 매핑:

Factory Method:

• HcsAssetDocument.fromEntity(hcsAsset) — DynamoDB Entity → OpenSearch Document 변환 (Instant → epoch ms)

검색 전략:

• name, description: 전문 검색 (name에 2x 가중치)
• tags: Keyword로 필터 (AND 조건 / OR 조건 양쪽 사용)
• componentType, shopComponentType, createdBy: Keyword 필터
• 기본 정렬: created_at DESC (최신순)
• 태그 검색: usage_count DESC (인기순)
• 페이지네이션: from = page * size

---

Value Objects

CreateHcsAssetRequestVo

UpdateHcsAssetRequestVo

SearchHcsAssetRequestVo

HcsAssetResponseVo

Conversion: HcsAssetResponseVo.fromEntity(HcsAsset) — 정적 팩토리 메서드

---

Repository

HcsAssetRepository (DynamoDB)

public interface HcsAssetRepository {
    void save(HcsAsset hcsAsset);
    Optional<HcsAsset> findById(String hcsAssetId);
    List<HcsAsset> findByUserId(String userId, int limit);
    List<HcsAsset> scanAll();
    void delete(HcsAsset hcsAsset);
}

구현 상세:

• save(): PutItem (생성/수정 동일)
• findById(): GetItem (PK=HCSASSET#{hcsAssetId}, SK=METADATA)
• findByUserId(): GSI1 Query (KEYS_ONLY) → Main Table BatchGetItem. Reverse scan (최신순)
• scanAll(): Scan + entityType 필터 (개발/관리용, 운영 주의)
• delete(): DeleteItem

HcsAssetSearchRepository (OpenSearch)

public interface HcsAssetSearchRepository {
    String index(HcsAssetDocument document);
    Optional<HcsAssetDocument> findById(String hcsAssetId);
    void update(HcsAssetDocument document);
    void delete(String hcsAssetId);
    List<HcsAssetDocument> search(String userId, String keyword, String componentType,
                                   String shopComponentType, List<String> tags, int page, int size);
    List<HcsAssetDocument> findByUserId(String userId, int size);
    List<HcsAssetDocument> findByTagsAny(List<String> tags, int size);
    void bulkIndex(List<HcsAssetDocument> documents);
    long deleteAllDocuments();
}

Search 로직:

• search(): BoolQuery — filter(createdBy, componentType, shopComponentType, tags AND 조건) + must(keyword → name^2, description)
• findByTagsAny(): BoolQuery — should(tags OR 조건), minimum_should_match=1, 정렬: usage_count DESC

---

Service

HcsAssetService

public interface HcsAssetService {
    void createHcsAsset(HcsAsset hcsAsset);
    void updateHcsAsset(HcsAsset hcsAsset);
    Optional<HcsAsset> findHcsAsset(String hcsAssetId);
    HcsAsset getHcsAsset(String hcsAssetId);  // throws HCS_ASSET_NOT_FOUND
    List<HcsAsset> findByUserId(String userId, int limit);
    List<HcsAsset> getAllHcsAssets();
    void deleteHcsAsset(HcsAsset hcsAsset);
    void incrementUsageCount(String hcsAssetId);
}

이벤트 발행: 생성/수정/삭제 시 EntityChangedEvent 발행 → OpenSearch 자동 동기화

HcsAssetSearchService (OpenSearch)

public interface HcsAssetSearchService {
    String indexHcsAsset(HcsAsset hcsAsset);
    String indexHcsAssetDocument(HcsAssetDocument document);
    Optional<HcsAssetDocument> getHcsAssetById(String hcsAssetId);
    void updateHcsAsset(HcsAsset hcsAsset);
    void updateHcsAssetDocument(HcsAssetDocument document);
    void deleteHcsAsset(String hcsAssetId);
    List<HcsAssetDocument> searchHcsAssets(String userId, String keyword, String componentType,
                                            String shopComponentType, List<String> tags, int page, int size);
    List<HcsAssetDocument> findByUserId(String userId, int size);
    List<HcsAssetDocument> findByTagsAny(List<String> tags, int size);
    void bulkIndexHcsAssets(List<HcsAsset> hcsAssets);
    void bulkIndexHcsAssetDocuments(List<HcsAssetDocument> documents);
}

---

Application

HcsAssetApplication

@Service
public class HcsAssetApplication {
    HcsAssetResponseVo createHcsAsset(CreateHcsAssetRequestVo requestVo);
    HcsAssetResponseVo getHcsAsset(String hcsAssetId, String userId);
    List<HcsAssetResponseVo> listHcsAssets(String userId, int limit);
    List<HcsAssetResponseVo> searchHcsAssets(SearchHcsAssetRequestVo requestVo);
    HcsAssetResponseVo updateHcsAsset(String hcsAssetId, UpdateHcsAssetRequestVo requestVo, String userId);
    void deleteHcsAsset(String hcsAssetId, String userId);
    void incrementUsageCount(String hcsAssetId, String userId);
}

접근 제어: 모든 수정/삭제/조회 메서드에서 createdBy == userId 확인. 불일치 시 MakittBizException(HCS_ASSET_ACCESS_DENIED) 발생.

---

API

HcsAssetController

Base Path: /api/v1/hcs-assets

인증: 모든 엔드포인트에 SecurityContext 필요 (SecurityContextUtil.getCurrentUserId())

Request/Response DTOs

CreateHcsAssetRequest:

Conversion: CreateHcsAssetRequest.toVo(request, createdBy) — userId를 createdBy로 설정

UpdateHcsAssetRequest:

SearchHcsAssetRequest:

Conversion: SearchHcsAssetRequest.toVo(request, createdBy) — userId를 createdBy 필터로 설정

HcsAssetResponse:

에러 응답:

• 401 Unauthorized: 인증 실패
• 403 Forbidden: 접근 권한 없음 (createdBy != userId)
• 404 Not Found: HcsAsset 없음

---

OpenSearch 동기화

HcsAssetSearchSyncListener

AbstractSearchSyncListener<HcsAsset, HcsAssetDocument> 상속. EntityChangedEvent 리스닝으로 DynamoDB → OpenSearch 자동 동기화.

조건부 활성화: @ConditionalOnProperty(name = "search.sync.enabled", havingValue = "true", matchIfMissing = true)

메서드:

• toDocument(HcsAsset) → HcsAssetDocument
• indexDocument(HcsAssetDocument) → 인덱싱
• updateDocument(HcsAssetDocument) → 업데이트
• deleteDocument(String id) → 삭제

동기화 흐름:

HcsAssetService.createHcsAsset(entity)
  → repository.save(entity)
  → eventPublisher.publishEvent(EntityChangedEvent.created(entity))
    → HcsAssetSearchSyncListener
      → HcsAssetSearchService.indexHcsAsset(entity)
        → HcsAssetSearchRepository.index(document)

---

Error Codes

---

서버 아키텍처

HcsAssetController (makitt-api)
    |
    v  (Request DTO → VO)
HcsAssetApplication (makitt-application)
    |
    v  (VO → Entity)
HcsAssetService (makitt-core/service)
    |
    +---> HcsAssetRepository (DynamoDB)
    |
    +---> EntityChangedEvent → HcsAssetSearchSyncListener
    |                              |
    |                              v
    +---> HcsAssetSearchService → HcsAssetSearchRepository (OpenSearch)
    |
    v
HcsAsset (makitt-core/entity)

패키지 구조:

makitt-core/
  com.makitt.core.domain.hcsasset/
    entity/
      HcsAsset.java                    # DynamoDB Entity
    vo/
      CreateHcsAssetRequestVo.java
      UpdateHcsAssetRequestVo.java
      SearchHcsAssetRequestVo.java
      HcsAssetResponseVo.java
    service/
      HcsAssetService.java             # 인터페이스
      HcsAssetServiceImpl.java         # 비즈니스 로직
    repository/
      HcsAssetRepository.java          # DynamoDB Repository
      HcsAssetRepositoryImpl.java

  com.makitt.core.common.dynamodb.key/
    HcsAssetKey.java                   # Key Builder
    KeyPrefix.java                     # HCS_ASSET = "HCSASSET#"

  com.makitt.core.opensearch/
    document/
      HcsAssetDocument.java            # OpenSearch Document
    repository/
      HcsAssetSearchRepository.java
      HcsAssetSearchRepositoryImpl.java
    service/
      HcsAssetSearchService.java
      HcsAssetSearchServiceImpl.java
    listener/
      HcsAssetSearchSyncListener.java  # 이벤트 기반 동기화

makitt-application/
  com.makitt.application.hcsasset/
    HcsAssetApplication.java

makitt-api/
  com.makitt.api.controller.hcsasset/
    HcsAssetController.java
    dto/
      CreateHcsAssetRequest.java
      UpdateHcsAssetRequest.java
      SearchHcsAssetRequest.java
      HcsAssetResponse.java

---

접근 제어

검증 패턴:

if (!entity.getCreatedBy().equals(currentUserId)) {
    throw new MakittBizException(ErrorCode.HCS_ASSET_ACCESS_DENIED, ...);
}

---

관련 설정

HcsConfig

@Configuration
@ConfigurationProperties(prefix = "hcs")
public class HcsConfig {
    private SystemDefaults systemDefaults;

    public static class SystemDefaults {
        private String tokensKey;        // S3 object key for default tokens
        private String presetsKey;       // S3 object key for default presets
        private String nodeDefaultsKey;  // S3 object key for default node-defaults
    }
}

---

참조

• Epic: HcsAsset 시스템
• Domain: Shop
• Domain: User