mirror of
https://github.com/ktds-dg0501/kt-event-marketing-fe.git
synced 2025-12-06 10:16:25 +00:00
7개 마이크로서비스 반영하여 프론트엔드 설계서 수정 (ia.md, api-mapping.md)
🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
cherry2250
parent
3f6e005026
commit
ca4dff559c
77
claude/frontend-design.md
Normal file
77
claude/frontend-design.md
Normal file
@ -0,0 +1,77 @@
|
|||||||
|
# 프론트엔드설계가이드
|
||||||
|
|
||||||
|
[요청사항]
|
||||||
|
- <설계원칙>을 준용하여 설계
|
||||||
|
- <설계순서>에 따라 설계
|
||||||
|
- [결과파일] 안내에 따라 파일 작성
|
||||||
|
|
||||||
|
[가이드]
|
||||||
|
<설계원칙>
|
||||||
|
- 기술스택: TypeScript 5.5 + React 18.3 + Vite 5.4
|
||||||
|
- 프로토타입과 동일하게 설계
|
||||||
|
- 각 백엔드서비스 API명세서와 반드시 일치
|
||||||
|
- 모바일, 태블릿, 웹 화면 크기에 맞게 반응형으로 디자인
|
||||||
|
|
||||||
|
<설계순서>
|
||||||
|
- 준비:
|
||||||
|
- 프로토타입 분석: '../{시스템}/design/uiux/prototype'디렉토리의 모든 파일을 'design/prototype' 디렉토리로 복사하고 분석 및 이해
|
||||||
|
- API 분석: "[백엔드시스템]"섹션의 정보를 이용하여 API명세서를 'design/api'에 다운로드하여 분석 및 이해
|
||||||
|
- 화면요구사항 분석: "[요구사항]" 섹션을 읽어 화면 요구사항 이해
|
||||||
|
|
||||||
|
- 설계:
|
||||||
|
- 1. **UI/UX 설계**
|
||||||
|
- 1.1 UI프레임워크 선택: MUI, Ant Design, Chakra UI, Mantine, React Bootstrap 등
|
||||||
|
- 1.2 화면목록 정의
|
||||||
|
- 1.3 화면 간 사용자 플로우 정의
|
||||||
|
- 1.4 화면별 상세 설계:
|
||||||
|
- 1.4.1 상세기능
|
||||||
|
- 1.4.2 UI 구성요소
|
||||||
|
- 1.4.3 인터랙션
|
||||||
|
- 1.5 화면간 전환 및 네비게이션
|
||||||
|
- 1.6 반응형 설계 전략
|
||||||
|
- 1.7 접근성 보장 방안
|
||||||
|
- 1.8 성능 최적화 방안
|
||||||
|
|
||||||
|
- 2. **스타일가이드 작성**:
|
||||||
|
API명세서 분석 결과와 선택한 UI프레임워크 특성을 반영
|
||||||
|
- 2.1 브랜드 아이덴티티: 디자인 컨셉 등
|
||||||
|
- 2.2 디자인 원칙
|
||||||
|
- 2.3 컬러 시스템
|
||||||
|
- 2.4 타이포그래피
|
||||||
|
- 2.5 간격 시스템
|
||||||
|
- 2.6 컴포넌트 스타일
|
||||||
|
- 2.7 반응형 브레이크포인트
|
||||||
|
- 2.8 대상 서비스 특화 컴포넌트
|
||||||
|
- 2.9 인터랙션 패턴
|
||||||
|
|
||||||
|
- 3. **정보 아키텍처 설계**
|
||||||
|
- 3.1 사이트맵: 페이지 구조 및 네비게이션 흐름
|
||||||
|
- 3.2 프로젝트 구조 설계: 패키지와 파일까지 설계
|
||||||
|
|
||||||
|
- 4. **API매핑설계서**
|
||||||
|
- 4.1 API경로 매핑
|
||||||
|
public/runtime-env.js파일을 읽어 API그룹과 '"[백엔드시스템]"섹션에 정의된 각 서비스별 HOST를 지정
|
||||||
|
예시)
|
||||||
|
```
|
||||||
|
window.__runtime_config__ = {
|
||||||
|
API_GROUP: "/api/${version:v1}",
|
||||||
|
USER_HOST: "http://localhost:8081",
|
||||||
|
ORDER_HOST: "http://localhost:8082"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
- 4.2 **API와 화면 상세기능 매칭**: '1.4.1 상세기능'과 API 매핑
|
||||||
|
- 화면, 기능, 백엔드 서비스, API경로, 요청데이터 구조, 응답데이터 구조 명시
|
||||||
|
- API 요청데이타와 API 응답데이터 예시
|
||||||
|
|
||||||
|
[참고자료]
|
||||||
|
- 프로토타입: design/prototype/*
|
||||||
|
- API명세서: design/api/*.json
|
||||||
|
|
||||||
|
[결과파일]
|
||||||
|
- UI/UX설계서: design/frontend/uiux-design.md
|
||||||
|
- 스타일가이드: design/frontend/style-guide.md
|
||||||
|
- 정보아키텍처: design/frontend/ia.md
|
||||||
|
- API매핑설계서: design/frontend/api-mapping.md
|
||||||
|
|
||||||
|
|
||||||
1158
design/frontend/api-mapping.md
Normal file
1158
design/frontend/api-mapping.md
Normal file
File diff suppressed because it is too large
Load Diff
614
design/frontend/ia.md
Normal file
614
design/frontend/ia.md
Normal file
@ -0,0 +1,614 @@
|
|||||||
|
# 정보 아키텍처 설계서
|
||||||
|
|
||||||
|
## 목차
|
||||||
|
1. [사이트맵](#1-사이트맵)
|
||||||
|
2. [프로젝트 구조 설계](#2-프로젝트-구조-설계)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. 사이트맵
|
||||||
|
|
||||||
|
### 1.1 전체 사이트 구조
|
||||||
|
|
||||||
|
```
|
||||||
|
KT 이벤트 마케팅 플랫폼
|
||||||
|
│
|
||||||
|
├── 🔐 인증 영역 (Public)
|
||||||
|
│ ├── /login - 로그인
|
||||||
|
│ ├── /register - 회원가입
|
||||||
|
│ └── /profile - 프로필 관리
|
||||||
|
│
|
||||||
|
├── 🏠 대시보드 영역 (Private)
|
||||||
|
│ ├── / - 메인 대시보드
|
||||||
|
│ │ ├── 진행중 이벤트 현황
|
||||||
|
│ │ ├── 최근 성과 요약
|
||||||
|
│ │ └── 빠른 작업 버튼
|
||||||
|
│ │
|
||||||
|
│ └── /events - 이벤트 목록
|
||||||
|
│ ├── 전체 이벤트 조회
|
||||||
|
│ ├── 상태별 필터링 (진행중/예정/종료)
|
||||||
|
│ └── 검색 기능
|
||||||
|
│
|
||||||
|
├── ✨ 이벤트 생성 플로우 (Private)
|
||||||
|
│ └── /events/create - 이벤트 생성 Funnel
|
||||||
|
│ ├── Step 1: /events/create?step=objective - 목적 선택
|
||||||
|
│ ├── Step 2: /events/create?step=recommendation - AI 추천 확인
|
||||||
|
│ ├── Step 3: /events/create?step=content - 콘텐츠 미리보기
|
||||||
|
│ ├── Step 4: /events/create?step=edit - 콘텐츠 편집
|
||||||
|
│ ├── Step 5: /events/create?step=channels - 배포 채널 선택
|
||||||
|
│ └── Step 6: /events/create?step=publish - 최종 승인
|
||||||
|
│
|
||||||
|
└── 📊 이벤트 관리 영역 (Private)
|
||||||
|
└── /events/[eventId]
|
||||||
|
├── /events/[eventId] - 이벤트 상세
|
||||||
|
├── /events/[eventId]/participants - 참여자 목록
|
||||||
|
├── /events/[eventId]/participate - 고객 참여 화면 (Public)
|
||||||
|
├── /events/[eventId]/draw - 당첨자 추첨
|
||||||
|
└── /events/[eventId]/analytics - 성과 분석
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.2 네비게이션 흐름
|
||||||
|
|
||||||
|
#### Bottom Navigation (인증 후 모든 화면)
|
||||||
|
```
|
||||||
|
┌─────────────────────────────────────────────────┐
|
||||||
|
│ 홈 이벤트 분석 프로필 │
|
||||||
|
│ / /events /analytics /profile │
|
||||||
|
└─────────────────────────────────────────────────┘
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 주요 사용자 여정
|
||||||
|
|
||||||
|
**여정 1: 신규 이벤트 생성**
|
||||||
|
```
|
||||||
|
/ (대시보드)
|
||||||
|
→ [+ 새 이벤트 생성] 버튼 클릭
|
||||||
|
→ /events/create?step=objective (목적 선택)
|
||||||
|
→ /events/create?step=recommendation (AI 추천)
|
||||||
|
→ /events/create?step=content (미리보기)
|
||||||
|
→ /events/create?step=edit (편집)
|
||||||
|
→ /events/create?step=channels (채널 선택)
|
||||||
|
→ /events/create?step=publish (승인)
|
||||||
|
→ /events/[eventId] (생성 완료, 상세 페이지)
|
||||||
|
```
|
||||||
|
|
||||||
|
**여정 2: 이벤트 관리 및 분석**
|
||||||
|
```
|
||||||
|
/events (이벤트 목록)
|
||||||
|
→ [이벤트 카드] 클릭
|
||||||
|
→ /events/[eventId] (상세)
|
||||||
|
├── [참여자 관리] → /events/[eventId]/participants
|
||||||
|
├── [당첨자 추첨] → /events/[eventId]/draw
|
||||||
|
└── [성과 분석] → /events/[eventId]/analytics
|
||||||
|
```
|
||||||
|
|
||||||
|
**여정 3: 고객 참여**
|
||||||
|
```
|
||||||
|
QR 코드 스캔 또는 링크 접속
|
||||||
|
→ /events/[eventId]/participate (참여 화면)
|
||||||
|
→ 참여 정보 입력
|
||||||
|
→ 참여 완료
|
||||||
|
```
|
||||||
|
|
||||||
|
### 1.3 접근 권한 설정
|
||||||
|
|
||||||
|
| 페이지 경로 | 접근 권한 | 인증 필요 | 설명 |
|
||||||
|
|------------|----------|---------|------|
|
||||||
|
| `/login` | Public | ❌ | 로그인 페이지 |
|
||||||
|
| `/register` | Public | ❌ | 회원가입 페이지 |
|
||||||
|
| `/` | Private | ✅ | 메인 대시보드 |
|
||||||
|
| `/events` | Private | ✅ | 이벤트 목록 |
|
||||||
|
| `/events/create` | Private | ✅ | 이벤트 생성 플로우 |
|
||||||
|
| `/events/[eventId]` | Private | ✅ | 이벤트 상세 |
|
||||||
|
| `/events/[eventId]/participants` | Private | ✅ | 참여자 관리 |
|
||||||
|
| `/events/[eventId]/draw` | Private | ✅ | 당첨자 추첨 |
|
||||||
|
| `/events/[eventId]/analytics` | Private | ✅ | 성과 분석 |
|
||||||
|
| `/events/[eventId]/participate` | **Public** | ❌ | 고객 참여 화면 |
|
||||||
|
| `/profile` | Private | ✅ | 프로필 관리 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. 프로젝트 구조 설계
|
||||||
|
|
||||||
|
### 2.1 Next.js 14 App Router 기반 디렉토리 구조
|
||||||
|
|
||||||
|
```
|
||||||
|
fe-kt-event-marketing/
|
||||||
|
│
|
||||||
|
├── 📁 app/ # Next.js 14 App Router
|
||||||
|
│ ├── (auth)/ # 인증 레이아웃 그룹
|
||||||
|
│ │ ├── login/
|
||||||
|
│ │ │ └── page.tsx # 로그인 페이지
|
||||||
|
│ │ ├── register/
|
||||||
|
│ │ │ └── page.tsx # 회원가입 페이지
|
||||||
|
│ │ └── layout.tsx # 인증 전용 레이아웃
|
||||||
|
│ │
|
||||||
|
│ ├── (main)/ # 메인 레이아웃 그룹 (인증 필요)
|
||||||
|
│ │ ├── page.tsx # 대시보드 (/)
|
||||||
|
│ │ ├── events/
|
||||||
|
│ │ │ ├── page.tsx # 이벤트 목록
|
||||||
|
│ │ │ ├── create/
|
||||||
|
│ │ │ │ └── page.tsx # 이벤트 생성 Funnel
|
||||||
|
│ │ │ └── [eventId]/
|
||||||
|
│ │ │ ├── page.tsx # 이벤트 상세
|
||||||
|
│ │ │ ├── participants/
|
||||||
|
│ │ │ │ └── page.tsx # 참여자 목록
|
||||||
|
│ │ │ ├── draw/
|
||||||
|
│ │ │ │ └── page.tsx # 당첨자 추첨
|
||||||
|
│ │ │ └── analytics/
|
||||||
|
│ │ │ └── page.tsx # 성과 분석
|
||||||
|
│ │ ├── profile/
|
||||||
|
│ │ │ └── page.tsx # 프로필 관리
|
||||||
|
│ │ └── layout.tsx # 메인 레이아웃 (Bottom Nav 포함)
|
||||||
|
│ │
|
||||||
|
│ ├── events/ # Public 이벤트 경로
|
||||||
|
│ │ └── [eventId]/
|
||||||
|
│ │ └── participate/
|
||||||
|
│ │ └── page.tsx # 고객 참여 화면 (인증 불필요)
|
||||||
|
│ │
|
||||||
|
│ ├── api/ # API Routes (서버 컴포넌트)
|
||||||
|
│ │ └── auth/
|
||||||
|
│ │ └── [...nextauth]/
|
||||||
|
│ │ └── route.ts # NextAuth API 라우트
|
||||||
|
│ │
|
||||||
|
│ ├── layout.tsx # 루트 레이아웃
|
||||||
|
│ ├── error.tsx # 전역 에러 핸들링
|
||||||
|
│ ├── loading.tsx # 전역 로딩 상태
|
||||||
|
│ └── not-found.tsx # 404 페이지
|
||||||
|
│
|
||||||
|
├── 📁 src/
|
||||||
|
│ ├── components/ # React 컴포넌트
|
||||||
|
│ │ ├── common/ # 공통 컴포넌트
|
||||||
|
│ │ │ ├── Button/
|
||||||
|
│ │ │ │ ├── Button.tsx
|
||||||
|
│ │ │ │ └── Button.test.tsx
|
||||||
|
│ │ │ ├── Card/
|
||||||
|
│ │ │ │ └── Card.tsx
|
||||||
|
│ │ │ ├── Input/
|
||||||
|
│ │ │ │ └── Input.tsx
|
||||||
|
│ │ │ ├── Layout/
|
||||||
|
│ │ │ │ ├── BottomNavigation.tsx
|
||||||
|
│ │ │ │ ├── Header.tsx
|
||||||
|
│ │ │ │ └── Container.tsx
|
||||||
|
│ │ │ └── Loading/
|
||||||
|
│ │ │ └── Loading.tsx
|
||||||
|
│ │ │
|
||||||
|
│ │ ├── auth/ # 인증 관련 컴포넌트
|
||||||
|
│ │ │ ├── LoginForm.tsx
|
||||||
|
│ │ │ ├── RegisterForm.tsx
|
||||||
|
│ │ │ └── ProfileForm.tsx
|
||||||
|
│ │ │
|
||||||
|
│ │ ├── dashboard/ # 대시보드 컴포넌트
|
||||||
|
│ │ │ ├── EventSummaryCard.tsx
|
||||||
|
│ │ │ ├── PerformanceChart.tsx
|
||||||
|
│ │ │ └── QuickActions.tsx
|
||||||
|
│ │ │
|
||||||
|
│ │ ├── event/ # 이벤트 관련 컴포넌트
|
||||||
|
│ │ │ ├── EventCard.tsx
|
||||||
|
│ │ │ ├── EventList.tsx
|
||||||
|
│ │ │ ├── EventDetail.tsx
|
||||||
|
│ │ │ ├── ParticipantTable.tsx
|
||||||
|
│ │ │ └── WinnerDrawModal.tsx
|
||||||
|
│ │ │
|
||||||
|
│ │ └── funnel/ # Funnel 관련 컴포넌트
|
||||||
|
│ │ ├── ObjectiveStep.tsx
|
||||||
|
│ │ ├── RecommendationStep.tsx
|
||||||
|
│ │ ├── ContentStep.tsx
|
||||||
|
│ │ ├── EditStep.tsx
|
||||||
|
│ │ ├── ChannelsStep.tsx
|
||||||
|
│ │ ├── PublishStep.tsx
|
||||||
|
│ │ └── FunnelLayout.tsx
|
||||||
|
│ │
|
||||||
|
│ ├── hooks/ # Custom React Hooks
|
||||||
|
│ │ ├── useAuth.ts # 인증 상태 관리
|
||||||
|
│ │ ├── useEvent.ts # 이벤트 CRUD
|
||||||
|
│ │ ├── useEventList.ts # 이벤트 목록
|
||||||
|
│ │ ├── useParticipants.ts # 참여자 관리
|
||||||
|
│ │ ├── useJobPolling.ts # Job 상태 폴링
|
||||||
|
│ │ └── useToast.ts # Toast 알림
|
||||||
|
│ │
|
||||||
|
│ ├── lib/ # 라이브러리 및 유틸리티
|
||||||
|
│ │ ├── api/ # API 클라이언트
|
||||||
|
│ │ │ ├── client.ts # Axios 인스턴스
|
||||||
|
│ │ │ ├── auth.ts # 인증 API
|
||||||
|
│ │ │ ├── events.ts # 이벤트 API
|
||||||
|
│ │ │ └── participants.ts # 참여 API
|
||||||
|
│ │ │
|
||||||
|
│ │ ├── utils/ # 유틸리티 함수
|
||||||
|
│ │ │ ├── format.ts # 날짜/숫자 포맷팅
|
||||||
|
│ │ │ ├── validation.ts # 폼 검증 헬퍼
|
||||||
|
│ │ │ └── storage.ts # localStorage 헬퍼
|
||||||
|
│ │ │
|
||||||
|
│ │ └── constants/ # 상수 정의
|
||||||
|
│ │ ├── api.ts # API 엔드포인트
|
||||||
|
│ │ ├── routes.ts # 라우트 경로
|
||||||
|
│ │ └── event.ts # 이벤트 상수
|
||||||
|
│ │
|
||||||
|
│ ├── store/ # 상태 관리 (Zustand)
|
||||||
|
│ │ ├── authStore.ts # 인증 상태
|
||||||
|
│ │ ├── funnelStore.ts # Funnel 임시 저장
|
||||||
|
│ │ └── uiStore.ts # UI 상태 (Toast, Modal 등)
|
||||||
|
│ │
|
||||||
|
│ ├── styles/ # 스타일
|
||||||
|
│ │ ├── globals.css # 전역 스타일
|
||||||
|
│ │ └── theme.ts # MUI 테마 설정
|
||||||
|
│ │
|
||||||
|
│ └── types/ # TypeScript 타입 정의
|
||||||
|
│ ├── auth.ts # 인증 관련 타입
|
||||||
|
│ ├── event.ts # 이벤트 타입
|
||||||
|
│ ├── participant.ts # 참여자 타입
|
||||||
|
│ └── api.ts # API 응답 타입
|
||||||
|
│
|
||||||
|
├── 📁 public/ # 정적 파일
|
||||||
|
│ ├── images/ # 이미지 파일
|
||||||
|
│ ├── icons/ # 아이콘 파일
|
||||||
|
│ └── runtime-env.js # 런타임 환경 변수
|
||||||
|
│
|
||||||
|
├── 📁 tests/ # 테스트 파일
|
||||||
|
│ ├── unit/ # 단위 테스트
|
||||||
|
│ ├── integration/ # 통합 테스트
|
||||||
|
│ └── e2e/ # E2E 테스트 (Playwright)
|
||||||
|
│
|
||||||
|
├── .env.local # 로컬 환경 변수
|
||||||
|
├── .env.development # 개발 환경 변수
|
||||||
|
├── .env.production # 프로덕션 환경 변수
|
||||||
|
├── next.config.js # Next.js 설정
|
||||||
|
├── tsconfig.json # TypeScript 설정
|
||||||
|
├── package.json # 의존성 관리
|
||||||
|
└── README.md # 프로젝트 문서
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.2 주요 파일 설명
|
||||||
|
|
||||||
|
#### 2.2.1 레이아웃 구조
|
||||||
|
|
||||||
|
**app/layout.tsx** (루트 레이아웃)
|
||||||
|
```typescript
|
||||||
|
// React Query Provider, MUI ThemeProvider, Toast Provider 설정
|
||||||
|
export default function RootLayout({ children }) {
|
||||||
|
return (
|
||||||
|
<html lang="ko">
|
||||||
|
<body>
|
||||||
|
<QueryClientProvider>
|
||||||
|
<ThemeProvider theme={theme}>
|
||||||
|
<CssBaseline />
|
||||||
|
{children}
|
||||||
|
</ThemeProvider>
|
||||||
|
</QueryClientProvider>
|
||||||
|
</body>
|
||||||
|
</html>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**app/(main)/layout.tsx** (메인 레이아웃)
|
||||||
|
```typescript
|
||||||
|
// Bottom Navigation 포함 레이아웃
|
||||||
|
// 인증 체크 미들웨어
|
||||||
|
export default function MainLayout({ children }) {
|
||||||
|
return (
|
||||||
|
<>
|
||||||
|
<Header />
|
||||||
|
<Container>{children}</Container>
|
||||||
|
<BottomNavigation />
|
||||||
|
</>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**app/(auth)/layout.tsx** (인증 레이아웃)
|
||||||
|
```typescript
|
||||||
|
// 로고 중심의 심플한 레이아웃
|
||||||
|
export default function AuthLayout({ children }) {
|
||||||
|
return (
|
||||||
|
<Container maxWidth="sm">
|
||||||
|
<Logo />
|
||||||
|
{children}
|
||||||
|
</Container>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2.2.2 Funnel 구현
|
||||||
|
|
||||||
|
**app/(main)/events/create/page.tsx**
|
||||||
|
```typescript
|
||||||
|
'use client';
|
||||||
|
|
||||||
|
import { useFunnel } from '@use-funnel/next';
|
||||||
|
import { ObjectiveStep, RecommendationStep, ... } from '@/components/funnel';
|
||||||
|
|
||||||
|
export default function EventCreatePage() {
|
||||||
|
const [Funnel, state, setStep] = useFunnel({
|
||||||
|
id: 'event-creation',
|
||||||
|
initial: 'objective',
|
||||||
|
});
|
||||||
|
|
||||||
|
return (
|
||||||
|
<Funnel>
|
||||||
|
<Funnel.Step name="objective">
|
||||||
|
<ObjectiveStep onNext={() => setStep('recommendation')} />
|
||||||
|
</Funnel.Step>
|
||||||
|
<Funnel.Step name="recommendation">
|
||||||
|
<RecommendationStep
|
||||||
|
onNext={() => setStep('content')}
|
||||||
|
onBack={() => setStep('objective')}
|
||||||
|
/>
|
||||||
|
</Funnel.Step>
|
||||||
|
{/* ... 나머지 Step들 */}
|
||||||
|
</Funnel>
|
||||||
|
);
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 2.2.3 API 클라이언트
|
||||||
|
|
||||||
|
**src/lib/api/client.ts**
|
||||||
|
```typescript
|
||||||
|
import axios from 'axios';
|
||||||
|
|
||||||
|
// runtime-env.js에서 환경 변수 로드
|
||||||
|
declare global {
|
||||||
|
interface Window {
|
||||||
|
__runtime_config__: {
|
||||||
|
API_GROUP: string;
|
||||||
|
USER_HOST: string;
|
||||||
|
EVENT_HOST: string;
|
||||||
|
CONTENT_HOST: string;
|
||||||
|
AI_HOST: string;
|
||||||
|
PARTICIPATION_HOST: string;
|
||||||
|
DISTRIBUTION_HOST: string;
|
||||||
|
ANALYTICS_HOST: string;
|
||||||
|
};
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const config = window.__runtime_config__;
|
||||||
|
|
||||||
|
// 1. User Service API Client (인증, 프로필)
|
||||||
|
export const userClient = axios.create({
|
||||||
|
baseURL: `${config.USER_HOST}${config.API_GROUP}`,
|
||||||
|
timeout: 10000,
|
||||||
|
});
|
||||||
|
|
||||||
|
// 2. Event Service API Client (이벤트 생명주기 관리)
|
||||||
|
export const eventClient = axios.create({
|
||||||
|
baseURL: `${config.EVENT_HOST}${config.API_GROUP}`,
|
||||||
|
timeout: 30000, // AI/이미지 생성 Job 폴링 고려
|
||||||
|
});
|
||||||
|
|
||||||
|
// 3. Content Service API Client (이미지 생성 및 편집)
|
||||||
|
export const contentClient = axios.create({
|
||||||
|
baseURL: `${config.CONTENT_HOST}${config.API_GROUP}`,
|
||||||
|
timeout: 30000, // 이미지 생성 Job 폴링
|
||||||
|
});
|
||||||
|
|
||||||
|
// 4. AI Service API Client (AI 추천 생성)
|
||||||
|
export const aiClient = axios.create({
|
||||||
|
baseURL: `${config.AI_HOST}${config.API_GROUP}`,
|
||||||
|
timeout: 30000, // AI 생성 Job 폴링
|
||||||
|
});
|
||||||
|
|
||||||
|
// 5. Participation Service API Client (참여자/당첨자 관리)
|
||||||
|
export const participationClient = axios.create({
|
||||||
|
baseURL: `${config.PARTICIPATION_HOST}${config.API_GROUP}`,
|
||||||
|
timeout: 10000,
|
||||||
|
});
|
||||||
|
|
||||||
|
// 6. Distribution Service API Client (다중 채널 배포)
|
||||||
|
export const distributionClient = axios.create({
|
||||||
|
baseURL: `${config.DISTRIBUTION_HOST}${config.API_GROUP}`,
|
||||||
|
timeout: 20000, // 다중 채널 배포 시간 고려
|
||||||
|
});
|
||||||
|
|
||||||
|
// 7. Analytics Service API Client (성과 분석 및 대시보드)
|
||||||
|
export const analyticsClient = axios.create({
|
||||||
|
baseURL: `${config.ANALYTICS_HOST}${config.API_GROUP}`,
|
||||||
|
timeout: 10000,
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.3 컴포넌트 재사용 전략
|
||||||
|
|
||||||
|
#### Atomic Design 기반 컴포넌트 계층
|
||||||
|
|
||||||
|
```
|
||||||
|
Atoms (원자)
|
||||||
|
└── Button, Input, Icon, Typography
|
||||||
|
↓
|
||||||
|
Molecules (분자)
|
||||||
|
└── SearchBar, EventCard, ParticipantRow
|
||||||
|
↓
|
||||||
|
Organisms (유기체)
|
||||||
|
└── EventList, ParticipantTable, Dashboard
|
||||||
|
↓
|
||||||
|
Templates (템플릿)
|
||||||
|
└── MainLayout, AuthLayout, FunnelLayout
|
||||||
|
↓
|
||||||
|
Pages (페이지)
|
||||||
|
└── HomePage, EventListPage, EventCreatePage
|
||||||
|
```
|
||||||
|
|
||||||
|
#### MUI 컴포넌트 커스터마이징
|
||||||
|
|
||||||
|
```typescript
|
||||||
|
// src/components/common/Button/Button.tsx
|
||||||
|
import { Button as MuiButton, ButtonProps } from '@mui/material';
|
||||||
|
|
||||||
|
export const Button: React.FC<ButtonProps> = (props) => {
|
||||||
|
return (
|
||||||
|
<MuiButton
|
||||||
|
variant="contained"
|
||||||
|
color="primary"
|
||||||
|
sx={{
|
||||||
|
borderRadius: '8px',
|
||||||
|
textTransform: 'none',
|
||||||
|
fontWeight: 600,
|
||||||
|
...props.sx,
|
||||||
|
}}
|
||||||
|
{...props}
|
||||||
|
/>
|
||||||
|
);
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.4 상태 관리 전략
|
||||||
|
|
||||||
|
| 상태 유형 | 관리 도구 | 사용 사례 |
|
||||||
|
|---------|---------|---------|
|
||||||
|
| 서버 상태 | React Query v5 | API 데이터 캐싱, 자동 재검증 |
|
||||||
|
| 전역 클라이언트 상태 | Zustand | 인증 상태, UI 상태 (Toast, Modal) |
|
||||||
|
| 로컬 상태 | useState | 컴포넌트 내부 상태 |
|
||||||
|
| 폼 상태 | React Hook Form | 폼 입력, 검증 |
|
||||||
|
| Funnel 상태 | @use-funnel/next | Step 전환, 데이터 임시 저장 |
|
||||||
|
|
||||||
|
### 2.5 라우팅 및 미들웨어
|
||||||
|
|
||||||
|
**middleware.ts** (Next.js Middleware)
|
||||||
|
```typescript
|
||||||
|
import { NextResponse } from 'next/server';
|
||||||
|
import type { NextRequest } from 'next/server';
|
||||||
|
|
||||||
|
export function middleware(request: NextRequest) {
|
||||||
|
const token = request.cookies.get('accessToken');
|
||||||
|
const { pathname } = request.nextUrl;
|
||||||
|
|
||||||
|
// 인증이 필요한 경로
|
||||||
|
const protectedRoutes = ['/', '/events', '/profile'];
|
||||||
|
const isProtectedRoute = protectedRoutes.some(route =>
|
||||||
|
pathname.startsWith(route)
|
||||||
|
);
|
||||||
|
|
||||||
|
// 인증되지 않은 사용자가 보호된 경로 접근 시 로그인으로 리다이렉트
|
||||||
|
if (isProtectedRoute && !token) {
|
||||||
|
return NextResponse.redirect(new URL('/login', request.url));
|
||||||
|
}
|
||||||
|
|
||||||
|
// 인증된 사용자가 로그인/회원가입 접근 시 대시보드로 리다이렉트
|
||||||
|
if ((pathname === '/login' || pathname === '/register') && token) {
|
||||||
|
return NextResponse.redirect(new URL('/', request.url));
|
||||||
|
}
|
||||||
|
|
||||||
|
return NextResponse.next();
|
||||||
|
}
|
||||||
|
|
||||||
|
export const config = {
|
||||||
|
matcher: ['/((?!api|_next/static|_next/image|favicon.ico).*)'],
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2.6 환경 변수 관리
|
||||||
|
|
||||||
|
**.env.local**
|
||||||
|
```
|
||||||
|
# 로컬 개발 환경
|
||||||
|
NEXT_PUBLIC_USER_HOST=http://localhost:8081
|
||||||
|
NEXT_PUBLIC_EVENT_HOST=http://localhost:8080
|
||||||
|
NEXT_PUBLIC_CONTENT_HOST=http://localhost:8082
|
||||||
|
NEXT_PUBLIC_AI_HOST=http://localhost:8083
|
||||||
|
NEXT_PUBLIC_PARTICIPATION_HOST=http://localhost:8084
|
||||||
|
NEXT_PUBLIC_DISTRIBUTION_HOST=http://localhost:8085
|
||||||
|
NEXT_PUBLIC_ANALYTICS_HOST=http://localhost:8086
|
||||||
|
NEXT_PUBLIC_API_VERSION=v1
|
||||||
|
```
|
||||||
|
|
||||||
|
**.env.production**
|
||||||
|
```
|
||||||
|
# 프로덕션 환경
|
||||||
|
NEXT_PUBLIC_USER_HOST=https://api.kt-event-marketing.com/user/v1
|
||||||
|
NEXT_PUBLIC_EVENT_HOST=https://api.kt-event-marketing.com/event/v1
|
||||||
|
NEXT_PUBLIC_CONTENT_HOST=https://api.kt-event-marketing.com/content/v1
|
||||||
|
NEXT_PUBLIC_AI_HOST=https://api.kt-event-marketing.com/ai/v1
|
||||||
|
NEXT_PUBLIC_PARTICIPATION_HOST=https://api.kt-event-marketing.com/participation/v1
|
||||||
|
NEXT_PUBLIC_DISTRIBUTION_HOST=https://api.kt-event-marketing.com/distribution/v1
|
||||||
|
NEXT_PUBLIC_ANALYTICS_HOST=https://api.kt-event-marketing.com/analytics/v1
|
||||||
|
NEXT_PUBLIC_API_VERSION=v1
|
||||||
|
```
|
||||||
|
|
||||||
|
**public/runtime-env.js**
|
||||||
|
```javascript
|
||||||
|
window.__runtime_config__ = {
|
||||||
|
API_GROUP: "/api/v1",
|
||||||
|
|
||||||
|
// 7개 마이크로서비스 호스트
|
||||||
|
USER_HOST: process.env.NEXT_PUBLIC_USER_HOST || "http://localhost:8081",
|
||||||
|
EVENT_HOST: process.env.NEXT_PUBLIC_EVENT_HOST || "http://localhost:8080",
|
||||||
|
CONTENT_HOST: process.env.NEXT_PUBLIC_CONTENT_HOST || "http://localhost:8082",
|
||||||
|
AI_HOST: process.env.NEXT_PUBLIC_AI_HOST || "http://localhost:8083",
|
||||||
|
PARTICIPATION_HOST: process.env.NEXT_PUBLIC_PARTICIPATION_HOST || "http://localhost:8084",
|
||||||
|
DISTRIBUTION_HOST: process.env.NEXT_PUBLIC_DISTRIBUTION_HOST || "http://localhost:8085",
|
||||||
|
ANALYTICS_HOST: process.env.NEXT_PUBLIC_ANALYTICS_HOST || "http://localhost:8086",
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. 기술 스택 정리
|
||||||
|
|
||||||
|
| 카테고리 | 기술 | 버전 | 용도 |
|
||||||
|
|---------|-----|------|-----|
|
||||||
|
| **Framework** | Next.js | 14.x | App Router, SSR, SSG |
|
||||||
|
| **Library** | React | 18.x | UI 라이브러리 |
|
||||||
|
| **Language** | TypeScript | 5.x | 정적 타입 검사 |
|
||||||
|
| **UI Framework** | Material-UI (MUI) | 6.x | UI 컴포넌트 |
|
||||||
|
| **State (Server)** | React Query | 5.x | 서버 상태 관리 |
|
||||||
|
| **State (Client)** | Zustand | 4.x | 전역 상태 관리 |
|
||||||
|
| **Form** | React Hook Form | 7.x | 폼 관리 |
|
||||||
|
| **Validation** | Zod | 3.x | 스키마 검증 |
|
||||||
|
| **Funnel** | @use-funnel/next | 1.x | Funnel 상태 관리 |
|
||||||
|
| **HTTP Client** | Axios | 1.x | API 통신 |
|
||||||
|
| **Charts** | Chart.js | 4.x | 데이터 시각화 |
|
||||||
|
| **Testing** | Jest, Playwright | - | 단위/E2E 테스트 |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. 배포 및 환경 설정
|
||||||
|
|
||||||
|
### 4.1 개발 환경
|
||||||
|
```bash
|
||||||
|
npm run dev # 개발 서버 실행 (localhost:3000)
|
||||||
|
npm run build # 프로덕션 빌드
|
||||||
|
npm run start # 프로덕션 서버 실행
|
||||||
|
npm run lint # ESLint 검사
|
||||||
|
npm run test # Jest 단위 테스트
|
||||||
|
npm run test:e2e # Playwright E2E 테스트
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4.2 빌드 최적화
|
||||||
|
- **Code Splitting**: 동적 import로 번들 크기 최적화
|
||||||
|
- **Image Optimization**: Next.js Image 컴포넌트 사용
|
||||||
|
- **Font Optimization**: next/font로 웹폰트 최적화
|
||||||
|
- **Tree Shaking**: 사용하지 않는 코드 제거
|
||||||
|
|
||||||
|
### 4.3 성능 모니터링
|
||||||
|
- **Lighthouse**: 성능, 접근성, SEO 점수
|
||||||
|
- **Web Vitals**: LCP, FID, CLS 측정
|
||||||
|
- **Bundle Analyzer**: 번들 크기 분석
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. 접근성 및 반응형 설계
|
||||||
|
|
||||||
|
### 5.1 반응형 브레이크포인트
|
||||||
|
```typescript
|
||||||
|
// src/styles/theme.ts
|
||||||
|
const breakpoints = {
|
||||||
|
xs: 0, // Mobile: 320px ~ 599px
|
||||||
|
sm: 600, // Tablet: 600px ~ 1023px
|
||||||
|
md: 1024, // Desktop: 1024px ~ 1439px
|
||||||
|
lg: 1440, // Large Desktop: 1440px+
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5.2 접근성 준수 (WCAG 2.1 AA)
|
||||||
|
- **키보드 네비게이션**: Tab, Enter, Space 지원
|
||||||
|
- **스크린 리더**: aria-label, role 속성
|
||||||
|
- **색상 대비**: 최소 4.5:1 비율
|
||||||
|
- **포커스 표시**: 명확한 focus 상태
|
||||||
|
- **대체 텍스트**: 모든 이미지에 alt 속성
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**문서 버전**: 1.0
|
||||||
|
**작성일**: 2025-01-24
|
||||||
|
**작성자**: Frontend Design Team
|
||||||
1554
design/frontend/style-guide.md
Normal file
1554
design/frontend/style-guide.md
Normal file
File diff suppressed because it is too large
Load Diff
502
design/frontend/uiux-design.md
Normal file
502
design/frontend/uiux-design.md
Normal file
@ -0,0 +1,502 @@
|
|||||||
|
# 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 선택
|
||||||
|
- 반응형 디자인 전략 수립
|
||||||
|
- 접근성 및 성능 최적화 방안 수립
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**문서 끝**
|
||||||
Loading…
x
Reference in New Issue
Block a user