kt-event-marketing-fe/design/frontend/uiux-design.md

KT AI 기반 소상공인 이벤트 자동 생성 서비스 - 프론트엔드 UI/UX 설계서

문서 정보

• 작성일: 2025-10-24
• 버전: 1.0
• 기술 스택: Next.js 14 + React 18 + TypeScript 5
• 기반 문서: design/uiux/uiux-design.md, 프로토타입 분석
• 프로토타입: design/uiux/prototype/*.html

---

1. UI/UX 설계

1.1 UI 프레임워크 선택

선택한 프레임워크: Material-UI (MUI) v6

선택 이유:

• React 18과 Next.js 14와의 완벽한 호환성
• TypeScript 기본 지원
• 모바일 우선 반응형 디자인 (Mobile First)
• 접근성 (WCAG 2.1 AA) 기본 준수
• 풍부한 컴포넌트 라이브러리
• KT 브랜드 컬러 커스터마이징 용이

대안 고려:

• Ant Design: 한국어 지원 우수하나 파일 크기가 큼
• Chakra UI: 경량이나 기업 디자인 시스템에 부적합
• Tailwind CSS + HeadlessUI: 커스터마이징은 우수하나 개발 속도 느림

최종 결정: MUI의 컴포넌트 완성도와 기업용 UI 패턴 지원으로 선택

---

1.2 화면 목록 정의

인증 영역 (4개)

화면 ID	화면명	URL	설명
AUTH-01	로그인	/login	전화번호/비밀번호 로그인
AUTH-02	회원가입	/register	소상공인 회원가입 (매장 정보 포함)
AUTH-03	프로필	/profile	사용자 및 매장 정보 관리
AUTH-04	로그아웃 확인	Modal	로그아웃 확인 다이얼로그

대시보드 영역 (2개)

화면 ID	화면명	URL	설명
DASH-01	대시보드	/	KPI 요약, 빠른 시작, 진행 중 이벤트
DASH-02	이벤트 목록	/events	전체 이벤트 목록 (필터, 검색, 페이징)

이벤트 생성 플로우 (6개)

화면 ID	화면명	URL	설명	Funnel Step
EVENT-01	이벤트 목적 선택	/events/create/objective	4가지 목적 선택	Step 1
EVENT-02	AI 이벤트 추천	/events/create/recommendation	AI 트렌드 분석 및 추천	Step 2
EVENT-03	콘텐츠 미리보기	/events/create/content	SNS 이미지 스타일 선택	Step 3
EVENT-04	콘텐츠 편집	/events/create/edit	텍스트 및 이미지 편집	Step 4
EVENT-05	배포 채널 선택	/events/create/channels	배포 채널 선택	Step 5
EVENT-06	최종 승인	/events/create/publish	최종 검토 및 배포	Step 6

이벤트 관리 및 모니터링 (5개)

화면 ID	화면명	URL	설명
MANAGE-01	이벤트 상세	/events/[id]	이벤트 상세 정보 및 실시간 KPI
MANAGE-02	참여자 목록	/events/[id]/participants	참여자 관리 및 필터링
MANAGE-03	이벤트 참여 (고객용)	/participate/[id]	고객 이벤트 참여 화면
MANAGE-04	당첨자 추첨	/events/[id]/draw	당첨자 추첨 및 관리
MANAGE-05	성과 분석	/analytics	실시간 대시보드 및 성과 분석

총 17개 화면 (모달 포함)

---

1.3 화면 간 사용자 플로우

[로그인] → [대시보드] ←→ [Bottom Navigation]
                ↓
         ┌──────┴──────┐
         ↓             ↓
    [이벤트 목록]   [성과 분석]
         ↓             ↓
    [이벤트 상세] → [참여자 목록] → [당첨자 추첨]

[대시보드] → [FAB: 새 이벤트] → [이벤트 생성 Funnel]
                                      ↓
                              (Objective → AI추천 → 콘텐츠 → 편집 → 채널 → 승인)
                                      ↓
                                [이벤트 상세]

[Bottom Navigation]
- 홈: 대시보드
- 이벤트: 이벤트 목록
- 분석: 성과 분석
- 프로필: 프로필

---

1.4 화면별 상세 설계

1.4.1 AUTH-01: 로그인

상세 기능:

• 전화번호 (010XXXXXXXX) 입력
• 비밀번호 입력
• "로그인 유지" 체크박스
• 로그인 버튼 (API: POST /users/login)
• 회원가입 링크
• 비밀번호 찾기 링크 (향후 구현)

UI 구성요소:

• Logo (KT 로고)
• TextField: phoneNumber (pattern 검증)
• TextField: password (type="password")
• Checkbox: "로그인 유지"
• Button: "로그인" (variant="contained", color="primary")
• Link: "회원가입", "비밀번호 찾기"

인터랙션:

• 전화번호 입력 시 자동 하이픈 제거
• 비밀번호 8자 이상 검증
• Enter 키로 로그인
• 로그인 성공 시 "/" 리다이렉트
• 로그인 실패 시 에러 Toast 표시

---

1.4.2 EVENT-01 ~ EVENT-06: 이벤트 생성 Funnel

Funnel 구현: @use-funnel/next 사용

Funnel 설계:

const steps = [
  'objective',      // 목적 선택
  'recommendation', // AI 추천
  'content',        // 콘텐츠 미리보기
  'edit',           // 콘텐츠 편집
  'channels',       // 배포 채널
  'publish'         // 최종 승인
] as const;

// useFunnel 사용
const [Funnel, state, setStep] = useFunnel({
  id: 'event-creation',
  initial: 'objective'
});

Step 1: Objective (목적 선택)

상세 기능:

• 4개 목적 중 1개 선택 (Radio)
  1. 신규 고객 유치
  2. 재방문 유도
  3. 매출 증대
  4. 인지도 향상
• 선택 후 다음 버튼 활성화
• API: POST /events/objectives

UI 구성요소:

• Stepper: 1/6 진행 표시
• OptionCard: 4개 (아이콘 + 제목 + 설명)
• Button: "다음" (하단 고정)

인터랙션:

• 카드 클릭 시 Radio 선택
• 선택 시 카드 강조 (border: KT Red)
• 다음 버튼 클릭 → API 호출 → eventId 저장 → Step 2 이동

---

Step 2: AI Recommendation (AI 추천)

상세 기능:

• AI 트렌드 분석 결과 표시 (업종, 지역, 시즌)
• 예산별 추천 이벤트 (저/중/고)
  • 각 예산당 온라인/오프라인 2가지 방식 제공
  • 총 6개 옵션 중 1개 선택
• 이벤트명, 경품 인라인 편집 가능
• 예산 네비게이션 (Sticky)
• API: POST /events/{eventId}/ai-recommendations
  • Job 발행 → 폴링 (GET /jobs/{jobId})

UI 구성요소:

• TrendAnalysis Card: 3개 (업종/지역/시즌)
• BudgetNavigation: 3개 버튼 (Sticky)
• RecommendationCard: 6개 (온라인/오프라인 배지, 편집 가능 제목/경품)
• LoadingIndicator: AI 처리 중 (5초 예상)
• Button: "다음"

인터랙션:

• 예산 네비게이션 클릭 → smooth scroll
• 이벤트명/경품 hover → 점선 테두리 (편집 가능 표시)
• 클릭 → 인라인 편집 (TextField 전환)
• Enter/Blur → 저장
• AI Job 폴링 (5초 간격)
• 완료 시 추천 결과 표시
• 1개 선택 → PUT /events/{eventId}/recommendations → Step 3 이동

---

Step 3: Content (콘텐츠 미리보기)

상세 기능:

• 5가지 SNS 이미지 스타일 선택
  1. 심플
  2. 모던
  3. 귀여움
  4. 고급스러움
  5. 트렌디
• 각 스타일 미리보기 이미지
• "크게보기" 버튼 → 전체화면 모달
• API: POST /events/{eventId}/images
  • Job 발행 → 폴링 (GET /jobs/{jobId})

UI 구성요소:

• StyleCard: 5개 (이미지 + 제목 + 설명 + "크게보기")
• SelectBadge: 우측 상단 (선택 시만 표시)
• FullscreenModal: 이미지 확대
• LoadingIndicator: 이미지 생성 중 (5초 예상)
• Button: "다음"

인터랙션:

• 카드 클릭 → Radio 선택 (숨김)
• 선택 시 테두리 강조 + 체크 배지
• "크게보기" → 전체화면 모달 (이벤트 버블링 방지)
• Job 폴링 (3초 간격)
• 완료 시 이미지 URL 표시
• 1개 선택 → PUT /events/{eventId}/images/{imageId}/select → Step 4 이동

---

Step 4: Edit (콘텐츠 편집)

상세 기능:

• 텍스트 편집 (제목, 경품, 참여 안내)
• 실시간 미리보기
• API: PUT /events/{eventId}/images/{imageId}/edit

UI 구성요소:

• TextField: 제목
• TextField: 경품
• TextField: 참여 안내 (multiline)
• PreviewCard: 실시간 미리보기 (우측/하단)
• Button: "다음", "저장"

인터랙션:

• 입력 시 debounce (300ms) 후 미리보기 업데이트
• 저장 버튼 → 임시 저장
• 다음 버튼 → API 호출 → Step 5 이동

---

Step 5: Channels (배포 채널 선택)

상세 기능:

• 복수 채널 선택 (Checkbox)
  • 우리동네TV
  • 링고비즈
  • SNS (Instagram, Naver, Kakao)
  • QR코드
• 채널별 옵션 (조건부 표시)
• API: PUT /events/{eventId}/channels

UI 구성요소:

• Checkbox: 각 채널
• ConditionalOptions: 각 채널 (펼침/접힘)
• Button: "다음"

인터랙션:

• 체크박스 선택 → 해당 옵션 펼침
• 최소 1개 선택 필수
• 다음 버튼 → API 호출 → Step 6 이동

---

Step 6: Publish (최종 승인)

상세 기능:

• 이벤트 요약 표시
• 이미지 미리보기
• 배포 채널 목록
• 일정 설정 (시작일, 종료일)
• 최종 승인 및 배포
• API: POST /events/{eventId}/publish

UI 구성요소:

• SummaryCard: 이벤트 정보
• ImagePreview: 최종 이미지
• ChannelBadges: 선택된 채널
• DatePicker: 시작일, 종료일
• Button: "수정" (이전 단계), "승인 및 배포"

인터랙션:

• 수정 버튼 → Funnel 이전 단계 이동
• 승인 버튼 → Confirm 다이얼로그 → API 호출 → 배포 완료 Toast → /events/[id] 이동

---

1.4.3 MANAGE-01: 이벤트 상세

상세 기능:

• 이벤트 헤더 (이미지, 제목, 상태, 기간)
• 실시간 KPI (4개)
  • 참여자 수
  • 조회수
  • ROI
  • 전환율
• 빠른 액션 (4개 버튼)
  • 참여자 목록
  • 당첨자 관리
  • 성과 분석
  • 이벤트 수정
• 참여 추이 차트 (Line Chart)
• API: GET /events/{eventId}

UI 구성요소:

• EventHeader: 이미지 + 정보
• KPICard: 4개 (Grid)
• ActionButton: 4개 (Grid)
• LineChart: 참여 추이 (Chart.js)

인터랙션:

• 실시간 업데이트 (5분마다 자동 갱신)
• Pull to Refresh (모바일)
• 액션 버튼 클릭 → 해당 페이지 이동

---

1.4.4 MANAGE-03: 이벤트 참여 (고객용)

상세 기능:

• 이벤트 이미지
• 이벤트 정보 (제목, 경품, 참여 방법)
• 참여 폼 (이름, 전화번호)
• 개인정보 동의 (필수)
• 마케팅 수신 동의 (선택)
• API: POST /events/{eventId}/participate

UI 구성요소:

• EventBanner: 이미지
• InfoCard: 이벤트 정보
• TextField: 이름, 전화번호
• Checkbox: 개인정보 동의, 마케팅 동의
• Button: "참여하기"

인터랙션:

• 전화번호 검증 (010-XXXX-XXXX)
• 중복 참여 방지
• 개인정보 동의 필수
• 참여 성공 시 응모 번호 모달 표시

---

1.5 화면 간 전환 및 네비게이션

Bottom Navigation (4개 탭):

• 홈 (/): DASH-01 대시보드
• 이벤트 (/events): DASH-02 이벤트 목록
• 분석 (/analytics): MANAGE-05 성과 분석
• 프로필 (/profile): AUTH-03 프로필

Header Navigation:

• 로고 (클릭 시 홈 이동)
• 뒤로가기 버튼 (조건부 표시)
• 프로필 아이콘 (로그인 시만 표시)

FAB (Floating Action Button):

• 위치: 우측 하단 고정
• 기능: 새 이벤트 생성 (/events/create/objective)
• 표시 조건: 대시보드, 이벤트 목록 화면에서만

---

1.6 반응형 설계 전략

Breakpoints:

• Mobile: 320px ~ 767px (기본)
• Tablet: 768px ~ 1023px
• Desktop: 1024px 이상

레이아웃 변화:

화면	Mobile	Tablet	Desktop
대시보드	KPI 세로 스택	KPI 2x2 Grid	KPI 4열 + 사이드바
이벤트 목록	1열	2열	3열
이벤트 생성	세로 스택	세로 스택	편집 | 미리보기 (Split)
성과 분석	차트 세로 스택	차트 2x1 Grid	차트 2x2 Grid

반응형 컴포넌트:

• Box with sx prop (MUI)
• Grid with xs/md/lg props
• useMediaQuery hook
• Container with maxWidth prop

---

1.7 접근성 보장 방안

WCAG 2.1 AA 준수:

• 색상 대비: 4.5:1 (텍스트), 3:1 (UI 요소)
• 터치 영역: 최소 44x44px
• 키보드 네비게이션: Tab, Enter, Escape 지원
• Focus Indicator: 명확한 포커스 표시

스크린 리더 지원:

• ARIA Labels: 모든 버튼, 링크, 폼 필드
• ARIA Roles: 적절한 역할 지정
• Live Regions: 동적 콘텐츠 업데이트 알림

대안 제공:

• 색상 외 표현: 아이콘 + 텍스트 조합
• 이미지 alt 텍스트
• 폼 검증 에러 메시지

---

1.8 성능 최적화 방안

Next.js 최적화:

• App Router 사용 (Next.js 14)
• Server Components (기본)
• Client Components (인터랙션 필요 시만)
• Image 컴포넌트 (자동 최적화)
• Font 최적화 (next/font)

Code Splitting:

• 페이지별 자동 코드 분할
• Dynamic Import (Chart.js, 큰 라이브러리)
• Lazy Loading (이미지, 컴포넌트)

캐싱 전략:

• React Query (서버 상태 관리)
  • staleTime: 5분 (대시보드)
  • cacheTime: 30분
  • refetchOnWindowFocus: true
• SWR (대안)
• Redux (클라이언트 상태 관리, 필요 시)

이미지 최적화:

• WebP 포맷 (fallback: JPG)
• 압축: Quality 80-85%
• Lazy Loading
• Responsive Images (srcset)

폰트 최적화:

• next/font 사용
• Font Display: swap
• Preload: 주요 폰트
• Subset: 한글 + 영문 + 숫자

애니메이션 최적화:

• GPU 가속: transform, opacity
• Framer Motion (선택적 사용)
• CSS Transitions (기본)

---

2. 참조 문서

• 프로토타입: design/uiux/prototype/*.html
• UI/UX 설계서: design/uiux/uiux-design.md
• 스타일 가이드: design/uiux/style-guide.md (→ design/frontend/style-guide.md)
• 정보 아키텍처: design/frontend/ia.md
• API 매핑 설계서: design/frontend/api-mapping.md

---

3. 기술 스택 요약

항목	기술
프레임워크	Next.js 14 (App Router)
라이브러리	React 18
언어	TypeScript 5
UI 프레임워크	Material-UI (MUI) v6
Funnel 관리	@use-funnel/next
상태 관리	React Query v5 (서버 상태), Zustand (클라이언트 상태)
폼 관리	React Hook Form v7 + Zod (검증)
차트	Chart.js v4 + react-chartjs-2
날짜	dayjs
HTTP 클라이언트	Axios
스타일링	MUI sx prop, Emotion (CSS-in-JS)

---

4. 변경 이력

Version 1.0 (2025-10-24)

• 초안 작성
• Next.js 14 기반 설계
• @use-funnel/next 검토 및 적용
• MUI v6 선택
• 반응형 디자인 전략 수립
• 접근성 및 성능 최적화 방안 수립

---

문서 끝