ShopOnboarding

개요

샵 레벨의 온보딩(MAKITT HAPPEN / MAKITT EXPLODE) 진행 상태를 관리하는 도메인. 각 샵별로 비즈니스 정보, 정책, 디자인, 물류, 배송, 결제, 상품, 가격 등의 설정 완료 여부를 추적합니다.

UserOnboarding(MAKITT BEGIN)이 사용자 레벨 온보딩이라면, ShopOnboarding은 샵 레벨 온보딩으로 Shop 파티션 하위에 저장됩니다.

마켓별 추적 지원: perMarket=true인 step은 각 마켓(국가)별로 독립적인 완료 상태를 관리합니다.

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

---

DynamoDB Entity

ShopOnboarding

Shop 파티션 하위의 온보딩 상태 엔티티.

키 구조:

필드:

Factory Methods:

• ShopOnboarding.create(shopId) — 마켓 없이 기본 생성 (모든 step PENDING)
• ShopOnboarding.create(shopId, marketCodes) — 마켓 목록과 함께 생성. perMarket=true인 step은 각 마켓별 marketStatuses 초기화.

---

Nested Objects

OnboardingStep

UserOnboarding과 동일한 OnboardingStep 엔티티를 재사용합니다.

OnboardingSubStep

---

Enums

ShopOnboardingStep

MAKITT HAPPEN (8 steps) — 샵 운영을 위한 핵심 설정:

MAKITT EXPLODE (6 steps) — 마케팅/고객 관리 확장 설정 (전부 optional):

StepStatus

---

마켓별 추적 (perMarket)

perMarket=true인 step은 각 마켓(국가)별로 독립적인 완료 상태를 가집니다.

동작 원리

• perMarket=false: 기존 status 필드만 사용 (글로벌 단위)
• perMarket=true: marketStatuses에 마켓별 상태 저장. 모든 마켓이 COMPLETED일 때 전체 status가 자동 COMPLETED.

마켓 동기화

Shop의 마켓 목록이 변경되면 syncMarkets()를 호출하여 동기화:

• 추가된 마켓: perMarket step에 PENDING 상태로 추가
• 제거된 마켓: perMarket step에서 해당 마켓 제거 → 전체 status 재계산

Progress 계산

전체 progress (가중치 기반):

총 단위 = Σ(perMarket ? marketCount : 1)  (각 step 별)
완료 단위 = Σ(perMarket ? completedMarketCount : (completed ? 1 : 0))
progress = completedUnits / totalUnits × 100

예: 8 HAPPEN steps, 3 markets, 6 perMarket + 2 global

• 총 단위 = (6 × 3) + (2 × 1) = 20
• 전부 완료 시 20/20 = 100%

마켓별 progress:

마켓별 단위 = perMarket step 수 + global step 수
마켓별 완료 = Σ(perMarket ? isCompletedForMarket(code) : isCompleted())

---

API

온보딩 상태 조회

응답:

{
  "shopId": "shop123",
  "steps": [
    {
      "stepId": "BUSINESS_INFO_SET",
      "status": "PENDING",
      "completedAt": null,
      "subSteps": null,
      "perMarket": true,
      "marketStatuses": { "KR": "COMPLETED", "US": "PENDING", "JP": "PENDING" },
      "marketCompletedAt": { "KR": "2025-01-15T09:00:00Z" }
    },
    {
      "stepId": "SHOP_DESIGN_SET",
      "status": "COMPLETED",
      "completedAt": "2025-01-16T10:00:00Z",
      "subSteps": null,
      "perMarket": false,
      "marketStatuses": null,
      "marketCompletedAt": null
    }
  ],
  "happenProgressPercent": 45,
  "explodeProgressPercent": 0,
  "marketCodes": ["KR", "US", "JP"],
  "happenMarketProgressMap": { "KR": 75, "US": 25, "JP": 25 },
  "explodeMarketProgressMap": { "KR": 0, "US": 0, "JP": 0 },
  "createdAt": "2025-01-10T00:00:00Z",
  "updatedAt": "2025-01-16T10:00:00Z"
}

단계 완료

• marketCode query param이 있으면 해당 마켓만 완료 처리
• marketCode가 없으면 글로벌 완료

---

Key Builder

클래스: com.makitt.core.common.dynamodb.key.ShopKey (Shop과 공유)

// ShopOnboarding Keys (Shop 파티션에 추가)
ShopKey.pk(shopId)                → "SHOP#{shopId}"    (Shop과 동일 PK)
ShopKey.onboardingSk()            → "ONBOARDING"

---

서버 아키텍처

ShopController (makitt-api)
    |
    v  (DTO <-> VO)
ShopApplication (makitt-application)     -- Shop과 동일 Application 클래스에서 관리
    |
    v  (VO)
ShopOnboardingService (makitt-core/service)
    |
    v  (DynamoDB 조작)
ShopOnboardingRepository (makitt-core/repository)
    |
    v
ShopOnboarding (makitt-core/entity)

패키지 구조:

makitt-core/
  com.makitt.core.domain.shop/
    entity/
      ShopOnboarding.java           # DynamoDB Entity
      ShopOnboardingStep.java       # 단계 Enum (HAPPEN + EXPLODE)
    service/
      ShopOnboardingService.java    # 상태 조회 + 완료 + 마켓 동기화
    repository/
      ShopOnboardingRepository.java # DynamoDB Repository
    vo/
      ShopOnboardingResponseVo.java # API 응답 VO

makitt-core/
  com.makitt.core.domain.user/
    entity/
      OnboardingStep.java           # 공유 Nested Object (UserOnboarding과 재사용)
      OnboardingSubStep.java        # 공유 Sub-step Object
      StepStatus.java               # 상태 Enum

makitt-application/
  com.makitt.application.shop/
    ShopApplication.java            # Shop + ShopOnboarding 통합 관리

makitt-api/
  com.makitt.api.controller.shop/
    ShopController.java             # Shop + ShopOnboarding 엔드포인트

주요 서비스 메서드:

// 조회 / 생성
ShopOnboardingService.getOrCreate(shopId)
ShopOnboardingService.getOrCreate(shopId, marketCodes)

// 글로벌 완료
ShopOnboardingService.completeStep(shopId, step)
ShopOnboardingService.completeSubStep(shopId, parentStep, subStepId)

// 마켓별 완료
ShopOnboardingService.completeStepForMarket(shopId, step, marketCode)

// 마켓 동기화
ShopOnboardingService.syncMarkets(shopId, newMarketCodes)

// 삭제
ShopOnboardingService.deleteByShopId(shopId)

---

Phase 구조 (클라이언트)

클라이언트에서 온보딩은 3단계 Phase로 구성:

MAKITT BEGIN (UserOnboarding)
    ↓ 완료 시 언락
MAKITT HAPPEN (ShopOnboarding HAPPEN steps)  ← BEGIN 완료 후 활성화
MAKITT EXPLODE (ShopOnboarding EXPLODE steps) ← BEGIN 완료 후 활성화 (HAPPEN과 독립)

• HAPPEN과 EXPLODE는 서로 독립적. BEGIN만 완료하면 둘 다 활성화.
• 클라이언트의 OnboardingDashboard에서 탭으로 전환.
• 마켓 선택 시 선택된 마켓들의 평균 progress를 표시.

---

관련 엔티티

---

참조

• Domain: Shop
• Domain: UserOnboarding
• Domain: User