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 설계**:
```typescript
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 선택
- 반응형 디자인 전략 수립
- 접근성 및 성능 최적화 방안 수립

---

**문서 끝**