KBE5_AntMen Frontend

앤트맨(AntMen) - 개미들의 공간을 위한 프론트엔드 애플리케이션입니다.

🎯 프로젝트 소개

안트맨은 수요자(고객)와 공급자(매니저)를 연결하는 서비스 플랫폼의 프론트엔드입니다. 사용자 친화적인 인터페이스를 통해 고객이 쉽게 서비스를 예약하고, 매니저가 효율적으로 작업을 관리할 수 있도록 지원합니다.

📺 시연 영상

🏗️ 프로젝트 구조

KBE5_AntMen_FE/
├── apps/                    # Next.js 앱 (고객/매니저용)
│   ├── src/
│   │   ├── app/            # App Router 페이지
│   │   │   ├── (user)/     # 고객 페이지
│   │   │   ├── manager/    # 매니저 페이지
│   │   │   └── ...
│   │   ├── components/     # 공통 컴포넌트
│   │   ├── entities/       # 도메인 엔티티
│   │   ├── features/       # 기능별 모듈
│   │   └── shared/         # 공통 유틸리티
├── admin/                   # React 앱 (관리자용)
│   ├── src/
│   │   ├── pages/          # 관리자 페이지
│   │   ├── components/     # 관리자 컴포넌트
│   │   └── api/            # API 호출 함수
└── packages/                # 공통 패키지
    └── ui/                 # 공통 UI 컴포넌트

📱 Apps (Next.js - 고객/매니저용)

🎨 주요 기능

🏠 홈 화면

• 오늘의 혜택: 특별 이벤트 및 할인 정보
• 추천 서비스: 개인화된 서비스 추천
• 빠른 예약: 자주 이용하는 서비스 빠른 예약
• 실시간 알림: 새로운 매칭, 예약 상태 변경 알림

📋 서비스 예약

• 카테고리별 검색: 청소, 이사, 수리 등 서비스 분류
• 지역별 필터링: 내 주변 서비스 제공자 검색
• 가격 비교: 여러 매니저의 가격 비교
• 리뷰 확인: 매니저별 평점 및 후기 확인

💳 결제 시스템

• 다양한 결제 수단: 카드, 계좌이체, 간편결제
• 안전한 결제: SSL 암호화 및 보안 인증
• 결제 내역: 상세한 결제 내역 및 영수증
• 환불 처리: 간편한 환불 신청 및 처리

📱 모바일 최적화

• 반응형 디자인: 모든 디바이스에서 최적화된 화면
• 터치 친화적: 모바일에서 편리한 터치 인터페이스
• 오프라인 지원: 네트워크 없이도 기본 기능 사용
• 푸시 알림: 중요한 알림을 실시간으로 받기

🔐 보안 및 인증

• 소셜 로그인: Google, Kakao 등 간편 로그인
• JWT 인증: 안전한 토큰 기반 인증
• 권한 관리: 사용자 역할별 접근 제어
• 개인정보 보호: 암호화된 개인정보 처리

📱 주요 페이지

고객용 페이지

• 홈: 메인 화면, 오늘의 혜택
• 서비스 예약: 카테고리별 서비스 검색 및 예약
• 내 예약: 예약 내역 및 상태 확인
• 리뷰: 서비스 후기 작성 및 확인
• 이벤트: 특별 이벤트 및 혜택
• 내 정보: 프로필 관리, 설정

매니저용 페이지

• 홈: 작업 현황, 수익 요약
• 내 업무: 수락한 작업 관리
• 매칭 요청: 새로운 작업 매칭 신청
• 게시판: 매니저 커뮤니티
• 내 정보: 프로필, 급여 정산

🖥️ Admin (React - 관리자용)

🎯 주요 기능

📊 대시보드

• 전체 현황 요약: 매출, 예약, 사용자 통계
• 실시간 모니터링: 시스템 상태 및 알림
• 차트 및 그래프: 데이터 시각화

👥 사용자 관리

• 고객 관리: 고객 계정 정보 및 상태 관리
• 매니저 관리: 매니저 승인, 상태 관리
• 블랙리스트 관리: 부정 사용자 관리

📅 예약 관리

• 전체 예약 현황: 모든 예약 조회 및 관리
• 예약 상태 관리: 예약 승인, 취소, 변경
• 예약 통계: 예약 패턴 및 트렌드 분석

🔗 매칭 관리

• 수동 매칭: 관리자가 직접 매니저 배정
• 추천 매칭: AI 기반 매니저 추천 시스템
• 매칭 통계: 매칭 성공률 및 만족도 분석

📈 통계 및 분석

• 매출 통계: 일별, 월별, 연도별 매출 분석
• 만족도 분석: 리뷰 및 평점 통계
• 환불률 분석: 환불 사유 및 패턴 분석

💰 재무 관리

• 매출 관리: 매출 내역 및 정산 관리
• 정산 관리: 매니저별 정산 내역
• 환불 관리: 환불 요청 처리 및 승인

🖥️ 주요 페이지

관리자용 페이지

• 대시보드: 전체 현황 요약
• 회원관리: 고객/매니저 계정 관리
• 예약관리: 전체 예약 현황
• 매칭관리: 수동/자동 매칭 시스템
• 통계: 매출, 만족도, 환불률 분석
• 재무관리: 매출, 정산, 환불 관리

🛠️ 기술 스택

Frontend Framework

• Next.js 14 (apps) - React 기반 풀스택 프레임워크
• React 18 (admin) - 사용자 인터페이스 라이브러리

UI/UX

• Tailwind CSS - 유틸리티 기반 CSS 프레임워크
• Headless UI - 접근성 중심 컴포넌트
• Lucide React - 모던 아이콘 라이브러리
• Framer Motion - 부드러운 애니메이션

State Management

• Zustand - 경량 상태 관리
• React Query - 서버 상태 관리

Development Tools

• TypeScript - 타입 안전성
• ESLint - 코드 품질 관리
• Prettier - 코드 포맷팅

📋 사전 요구사항

• Node.js 18.0 이상
• Yarn 1.22.0 이상
• Git

🚀 설치 및 실행

1. 전체 프로젝트 설치

# 루트 디렉토리에서
yarn install

2. 개발 서버 실행

전체 앱 동시 실행

# 고객/매니저 앱 + 관리자 앱 동시 실행
yarn dev

개별 앱 실행

# 고객/매니저용 앱 (http://localhost:4000)
yarn dev:apps

# 관리자용 앱 (http://localhost:5001)
yarn dev:admin

3. HTTPS 개발환경 (선택사항)

# 처음 한 번만 실행
yarn setup-https

# HTTPS로 개발 서버 실행
yarn dev:apps:https
yarn dev:admin:https

🌐 접속 URL

앱	URL	설명
Apps (고객/매니저용)	http://localhost:3000	메인 애플리케이션
Admin (관리자용)	http://localhost:3001	관리자 대시보드

🎨 UI/UX 특징

디자인 시스템

• 일관된 디자인: 통일된 색상, 폰트, 간격
• 접근성: WCAG 2.1 AA 준수
• 다크 모드: 사용자 선호도에 따른 테마 변경
• 국제화: 다국어 지원 준비

사용자 경험

• 직관적 네비게이션: 쉬운 메뉴 구조
• 빠른 로딩: 최적화된 이미지 및 코드
• 오류 처리: 친화적인 오류 메시지
• 피드백: 사용자 액션에 대한 즉각적인 피드백

🔧 환경 변수 설정

Apps (Next.js) (.env.local)

NEXT_PUBLIC_API_URL=http://localhost:9091
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your_google_client_id
NEXT_PUBLIC_KAKAO_CLIENT_ID=your_kakao_client_id

Admin (React) (.env)

REACT_APP_API_URL=http://localhost:9093
REACT_APP_GOOGLE_CLIENT_ID=your_google_client_id

📦 빌드 및 배포

개발용 빌드

# 전체 앱 빌드
yarn build

# 개별 앱 빌드
yarn build:apps
yarn build:admin

프로덕션 배포

# Docker 배포
docker-compose build
docker-compose up -d

# 정적 배포
yarn workspace apps export
yarn workspace admin build

🧪 테스트

# 전체 테스트 실행
yarn test

# 개별 앱 테스트
yarn workspace apps test
yarn workspace admin test

🔍 개발 도구

코드 품질

# 린트 검사
yarn lint

# 코드 포맷팅
yarn format

캐시 관리

# 캐시 정리
yarn clean

🐛 문제 해결

일반적인 문제들

1. 포트 충돌

   # 사용 중인 포트 확인
   lsof -i :3000
   lsof -i :3001

2. 의존성 문제

   # node_modules 삭제 후 재설치
   rm -rf node_modules
   yarn install

3. 캐시 문제

   # 모든 캐시 정리
   yarn clean
   yarn cache clean

📞 지원

문제가 발생하면 다음을 확인해주세요:

1. Node.js 버전 확인
2. 의존성 설치 상태 확인
3. 환경 변수 설정 확인
4. 브라우저 콘솔 에러 확인