글로벌 샵 온보딩 여정 및 Progress UX

개요

MAKITT 플랫폼의 글로벌 샵 온보딩 사용자 경험(UX) 명세서입니다. 지구본(Globe) 화면을 통한 초기 온보딩과 /home 화면의 온보딩 진행 현황 대시보드를 정의합니다.

배경

현재 구현 현황:

• 3D 지구본 온보딩 씬(Scene 0-6): 국가 선택 → 샵 정보 → 상품 정보 → 디자인 스타일
• /home 대시보드: Quick Link 그리드 + 하단 채팅박스

변경 방향:

1. /home 화면 상단에 "10분만에 전세계 론칭하기" CTA 배치
2. 하단 채팅박스 제거
3. 국가별 온보딩 진행도 대시보드 추가

목표

1. 초기 온보딩(지구본 화면)에서 메인 마켓 기준점 확립
2. /home 화면에서 국가별 온보딩 진행 현황 시각화
3. 5가지 설정 카테고리별 완성도 트래킹
4. 사용자가 "다음 해야 할 일"을 직관적으로 파악

---

스코프

1. 지구본 화면 (초기 온보딩)

경로: /onboarding 디렉토리: makitt-client/apps/web/src/app/[locale]/onboarding/page.tsx

3D 지구본을 활용한 몰입형 온보딩 경험을 제공합니다.

2. /home 화면 (온보딩 진행 현황)

경로: /home 디렉토리: makitt-client/apps/web/src/app/[locale]/home/page.tsx

샵 운영 대시보드에서 국가별 온보딩 진행도를 확인합니다.

---

지구본 화면 (초기 온보딩)

Scene 구조

Scene 0 → Scene 1 → Scene 2 → Scene 3 → Scene 4 → Scene 5 → Scene 6
(안개)    (인사)    (국가선택)  (샵정보)   (상품정보)  (디자인)   (완료)

전체 온보딩 플로우 다이어그램

flowchart TB
    subgraph Onboarding["초기 온보딩 (지구본 화면)"]
        direction TB
        S0[Scene 0<br/>안개 효과]
        S1[Scene 1<br/>인사말]
        S2[Scene 2<br/>국가 선택]
        S3[Scene 3<br/>샵 정보 입력]
        S4[Scene 4<br/>샘플 상품 추가]
        S5[Scene 5<br/>디자인 스타일]
        S6[Scene 6<br/>AI 생성 + 가입]

        S0 --> S1
        S1 --> S2
        S2 --> S3
        S3 --> S4
        S4 --> S5
        S5 --> S6
    end

    subgraph CountrySelection["국가/마켓 선택"]
        direction LR
        Globe[3D 지구본]
        Primary["첫 번째 선택<br/>= 메인 마켓"]
        Additional["추가 마켓<br/>(복수 선택 가능)"]

        Globe --> Primary
        Primary --> Additional
    end

    subgraph HomeOnboarding["/home 화면 온보딩"]
        direction TB
        CTA["10분만에 전세계 론칭하기<br/>CTA 배너"]
        Progress["전체 진행률<br/>Progress Bar"]
        Dashboard["국가별 온보딩 대시보드"]
        Categories["5가지 설정 카테고리"]

        CTA --> Progress
        Progress --> Dashboard
        Dashboard --> Categories
    end

    S6 --> HomeOnboarding
    S2 -.-> CountrySelection

Scene 상세

3D Globe 컴포넌트

디렉토리: makitt-client/apps/web/src/features/onboarding/lib/

국가(마켓) 선택 플로우

┌─────────────────────────────────────────────────────────────────┐
│                     지구본 (3D Globe)                            │
│                                                                  │
│                        🌍                                        │
│                   ╭──────────╮                                   │
│                  │   🇰🇷     │ ← 클릭하면 글로브가 해당 국가로 회전 │
│                   ╰──────────╯                                   │
│                                                                  │
│   선택된 국가: 🇰🇷 한국 (메인 마켓)                                │
│                                                                  │
│   [+ 마켓 추가]  [다음 →]                                         │
└─────────────────────────────────────────────────────────────────┘

메인 마켓 기준점:

• 첫 번째로 선택한 국가가 **메인 마켓(Primary Market)**으로 설정
• 메인 마켓의 언어/통화가 샵의 기본 설정이 됨
• 이후 추가 마켓은 번역 대상이 됨

Country Store 상태 관리

파일: makitt-client/apps/web/src/features/onboarding/model/country.store.ts

interface CountryState {
  selectedCountries: SimpleCountryData[];      // 선택된 국가 목록
  targetCountry: SimpleCountryData | null;     // 글로브 회전 대상
  hoveredCountry: string | null;               // hover 상태
}

---

/home 화면 UI 변경

현재 구조

┌─────────────────────────────────────────────────────────────────┐
│  Welcome Section                                                 │
│  {shopName} - Let's MAKITT Happen                               │
├─────────────────────────────────────────────────────────────────┤
│  Quick Actions Grid (2x2)                                        │
│  ┌─────────────┐ ┌─────────────┐                                │
│  │ Customize   │ │ Manage      │                                │
│  │ Your Shop   │ │ Products    │                                │
│  └─────────────┘ └─────────────┘                                │
│  ┌─────────────┐ ┌─────────────┐                                │
│  │ Get Paid    │ │ Ship It     │                                │
│  │ Anywhere    │ │ to World    │                                │
│  └─────────────┘ └─────────────┘                                │
├─────────────────────────────────────────────────────────────────┤
│  Chat Section                                                    │
│  "Or Just Talk It" - ChatInterface                              │
└─────────────────────────────────────────────────────────────────┘

변경 후 구조

flowchart TB
    subgraph HomeLayout["/home 화면 레이아웃"]
        direction TB

        subgraph TopCTA["상단 CTA 배너 (NEW)"]
            CTATitle["10분만에 전세계 론칭하기"]
            CTAProgress["전체 진행률: 60%"]
            CTANextAction["다음 할 일: 결제 연동"]
        end

        subgraph WelcomeSection["Welcome Section"]
            ShopName["샵 이름"]
            Tagline["Let's MAKITT Happen"]
        end

        subgraph QuickActions["Quick Actions Grid 2x2"]
            Card1["Customize Your Shop"]
            Card2["Manage Products"]
            Card3["Get Paid Anywhere"]
            Card4["Ship It to World"]
        end

        subgraph MarketDashboard["국가별 온보딩 대시보드 (NEW)"]
            Market1["🇰🇷 한국 Primary 100%"]
            Market2["🇺🇸 미국 60%"]
            Market3["🇯🇵 일본 0%"]
        end

        TopCTA --> WelcomeSection
        WelcomeSection --> QuickActions
        QuickActions --> MarketDashboard
    end

    Removed["❌ 제거: Chat Section"]

와이어프레임

┌─────────────────────────────────────────────────────────────────┐
│  🚀 10분만에 전세계 론칭하기                               [시작→] │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━░░░░░░░░░░░░░░░░░░░░░░░ 40%     │
├─────────────────────────────────────────────────────────────────┤
│  Welcome Section                                                 │
│  {shopName} - Let's MAKITT Happen                               │
├─────────────────────────────────────────────────────────────────┤
│  Quick Actions Grid (2x2)                                        │
│  ┌─────────────┐ ┌─────────────┐                                │
│  │ Customize   │ │ Manage      │                                │
│  │ Your Shop   │ │ Products    │                                │
│  └─────────────┘ └─────────────┘                                │
│  ┌─────────────┐ ┌─────────────┐                                │
│  │ Get Paid    │ │ Ship It     │                                │
│  │ Anywhere    │ │ to World    │                                │
│  └─────────────┘ └─────────────┘                                │
├─────────────────────────────────────────────────────────────────┤
│  국가별 온보딩 진행도                                             │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ 🇰🇷 한국 (Primary)                        [설정 완료] ━━━━ 100%│
│  │ 🇺🇸 미국                                  [진행중]    ━━░░ 60%│
│  │ 🇯🇵 일본                                  [설정 필요] ░░░░  0%│
│  │ [+ 마켓 추가]                                                 │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘

변경 사항

---

온보딩 진행도 대시보드

5가지 설정 카테고리

flowchart LR
    subgraph Categories["5가지 설정 카테고리"]
        P[정책 및 약관<br/>필수]
        PR[상품등록<br/>필수]
        T[가격 및 세금<br/>마켓별]
        PAY[결제<br/>마켓별]
        L[물류<br/>선택]
    end

    Start((시작)) --> P --> PR --> T --> PAY --> L --> Complete((런칭))

카테고리별 상세 (서브카테고리)

1. 정책 및 약관

디렉토리: app/[locale]/home/shop/policies/page.tsx

2. 상품등록

디렉토리: app/[locale]/home/products/

3. 가격 및 세금

디렉토리: app/[locale]/home/shop/preference/page.tsx

4. 결제

디렉토리: app/[locale]/home/payment/settings/page.tsx

5. 물류

디렉토리: app/[locale]/home/logistics/settings/page.tsx

---

진행도 위젯 UI 설계

전체 Progress Bar

┌─────────────────────────────────────────────────────────────────┐
│  🚀 10분만에 전세계 론칭하기                 예상 소요: 약 5분   │
│                                                                  │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━░░░░░░░░░░░░░░░░░░░░░░░  60%       │
│                                                                  │
│  📍 다음 할 일: 결제 연동 완료하기                               │
│     US 마켓 Stripe 연동이 필요합니다.                [계속하기 →] │
└─────────────────────────────────────────────────────────────────┘

국가별 진행도 카드

┌─────────────────────────────────────────────────────────────────┐
│  🇰🇷 한국 (Primary)                                   ✓ 완료    │
│  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  100%      │
│                                                                  │
│  ✓ 정책 및 약관    ✓ 상품등록    ✓ 가격/세금                    │
│  ✓ 결제 연동       ⊘ 물류 (건너뜀)                              │
├─────────────────────────────────────────────────────────────────┤
│  🇺🇸 미국                                           ◐ 진행중    │
│  ━━━━━━━━━━━━━━━━━━━━━░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   40%      │
│                                                                  │
│  ✓ 정책 및 약관    ✓ 상품등록    ○ 가격/세금 ← 필수             │
│  ○ 결제 연동       ○ 물류                                       │
│                                                        [설정 →]  │
├─────────────────────────────────────────────────────────────────┤
│  🇯🇵 일본                                            🔒 잠김     │
│  ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░   0%      │
│                                                                  │
│  선행 조건: 기본 샵 설정 완료 필요                               │
│                                                        [준비 중] │
└─────────────────────────────────────────────────────────────────┘

상태 아이콘

상태 컬러

---

서버 모델링: 진행상태 트래킹

데이터 모델 다이어그램

erDiagram
    SHOP ||--o{ ONBOARDING_PROGRESS : has
    ONBOARDING_PROGRESS ||--|{ CATEGORY_PROGRESS : contains
    CATEGORY_PROGRESS ||--|{ SUBCATEGORY_PROGRESS : contains

    SHOP {
        string shopId PK
        string shopName
        string shopUrl
        string primaryMarket
        string status
    }

    ONBOARDING_PROGRESS {
        string progressId PK
        string shopId FK
        string marketCode
        number overallProgress
        string status
        datetime createdAt
        datetime updatedAt
    }

    CATEGORY_PROGRESS {
        string categoryId PK
        string progressId FK
        string categoryName
        string status
        number progress
        boolean requiredForLaunch
        datetime completedAt
    }

    SUBCATEGORY_PROGRESS {
        string subCategoryId PK
        string categoryId FK
        string name
        string status
        boolean required
        datetime completedAt
    }

OnboardingProgress 엔티티

interface OnboardingProgress {
  progressId: string;           // PK
  shopId: string;               // 샵 ID
  marketCode: string;           // 마켓 코드 (KR, US, JP, SG)

  // 대카테고리 진행상태
  categories: {
    policies: CategoryProgress;
    products: CategoryProgress;
    pricing: CategoryProgress;
    payment: CategoryProgress;
    logistics: CategoryProgress;
  };

  // 전체 진행률
  overallProgress: number;      // 0-100
  status: 'NOT_STARTED' | 'IN_PROGRESS' | 'COMPLETED';

  // 메타 정보
  createdAt: string;
  updatedAt: string;
}

interface CategoryProgress {
  status: 'NOT_STARTED' | 'IN_PROGRESS' | 'COMPLETED' | 'SKIPPED';
  progress: number;             // 0-100
  subCategories: SubCategoryProgress[];
  requiredForLaunch: boolean;
  completedAt?: string;
}

interface SubCategoryProgress {
  id: string;
  name: string;
  status: 'PENDING' | 'COMPLETED' | 'SKIPPED';
  required: boolean;
  completedAt?: string;
}

API 엔드포인트

GET    /api/v1/shops/:shopId/onboarding/progress
       → 전체 온보딩 진행상태 조회

GET    /api/v1/shops/:shopId/onboarding/progress/:marketCode
       → 특정 마켓 진행상태 조회

PATCH  /api/v1/shops/:shopId/onboarding/progress/:marketCode/:category
       → 카테고리 진행상태 업데이트

POST   /api/v1/shops/:shopId/onboarding/progress/:marketCode/:category/skip
       → 선택 카테고리 건너뛰기

진행률 계산 로직

function calculateOverallProgress(categories: Categories): number {
  const weights = {
    policies: 20,    // 필수
    products: 25,    // 필수
    pricing: 20,     // 마켓별
    payment: 25,     // 마켓별
    logistics: 10    // 선택
  };

  let totalWeight = 0;
  let completedWeight = 0;

  for (const [category, progress] of Object.entries(categories)) {
    const weight = weights[category];
    totalWeight += weight;

    if (progress.status === 'COMPLETED') {
      completedWeight += weight;
    } else if (progress.status === 'SKIPPED') {
      // 선택 항목 건너뛰면 해당 가중치 제외
      if (!progress.requiredForLaunch) {
        totalWeight -= weight;
      }
    } else if (progress.status === 'IN_PROGRESS') {
      completedWeight += (weight * progress.progress / 100);
    }
  }

  return Math.round((completedWeight / totalWeight) * 100);
}

---

단계별 의존성

1. 조직 설정 ─────────────┐
                         ↓
2. 샵 기본 설정 ─────────┬──────────────────┐
                        ↓                   ↓
3. 상품 준비 ←─────→ 4. 마켓별 설정 ←──── 6. 물류 연동
       │                   ↓
       │              5. 결제 연동
       │                   │
       └───────────────────┴──────→ 7. 콘텐츠 & 런칭

---

구현 고려사항

상태 저장

• 서버: DynamoDB onboarding_progress 테이블
• 클라이언트: Zustand store에 캐싱
• 실시간 동기화: 설정 변경 시 자동 progress 업데이트

성능

• Progress 위젯은 대시보드 초기 로딩에 포함
• 상세 체크리스트는 lazy loading
• 국가별 상태는 캐싱하여 불필요한 API 호출 방지

접근성

• 키보드 네비게이션 지원 (Tab, Enter)
• 스크린 리더 호환 (ARIA labels)
• 고대비 모드 지원

---

관련 문서

• 글로벌 자사몰 온보딩 기능 명세 - 7단계 온보딩 상세