견적관리 임직원 GPT
서브원AI의 AI 기반 고객 상담 및 견적 관리 시스템을 위한 현대적인 웹 애플리케이션입니다.
📋 목차
✨ 주요 기능
1. AI 채팅 인터페이스 (/chat)
- 실시간 AI 상담 챗봇
- 마크다운 렌더링 지원
- 이미지 확대 기능
- 대화 히스토리 관리
2. 에이전트 모니터링 (/agent-monitoring)
- AI 에이전트 활동 실시간 모니터링
- 성능 메트릭 대시보드
3. 견적 요청 관리 (/quote-requests)
- 견적 요청 목록 조회
- 상세 정보 관리
- 이메일 발송 기능
- 리치 텍스트 에디터 (TinyMCE)
4. 인증 시스템
- JWT 기반 인증
- 게스트 토큰 지원
- 보호된 라우트
- 자동 리다이렉션
🛠 기술 스택
핵심 프레임워크 및 라이브러리
- React 18.2 - 사용자 인터페이스 구축
- TypeScript 5.2 - 정적 타입 지원
- Vite 5.0 - 초고속 빌드 도구 및 개발 서버
상태 관리 및 데이터 페칭
- TanStack Query (React Query) 5.81 - 서버 상태 관리 및 데이터 캐싱
- Zustand 5.0 - 클라이언트 상태 관리
- Axios 1.10 - HTTP 클라이언트
라우팅 및 네비게이션
- React Router DOM 7.6 - SPA 라우팅
UI 및 스타일링
- Tailwind CSS 3.4 - 유틸리티 우선 CSS 프레임워크
- shadcn/ui - 재사용 가능한 컴포넌트 시스템
- Radix UI - 접근성이 우수한 헤드리스 UI 컴포넌트
- Lucide React - 아이콘 라이브러리
- next-themes - 다크모드 지원
- Sonner - 토스트 알림
에디터 및 마크다운
- TinyMCE 7.9 - WYSIWYG 리치 텍스트 에디터
- Jodit React - 대체 리치 텍스트 에디터
- React Markdown - 마크다운 렌더링
- remark-gfm - GitHub Flavored Markdown 지원
- remark-breaks - 줄바꿈 처리
- lowlight - 코드 하이라이팅
유틸리티
- class-variance-authority (CVA) - CSS 클래스 변형 관리
- clsx - 조건부 클래스명 생성
- tailwind-merge - Tailwind 클래스 병합
- js-cookie - 쿠키 관리
- vaul - 드로어 컴포넌트
- react-medium-image-zoom - 이미지 확대 기능
개발 도구
- Vitest 3.2 - 단위 테스트 프레임워크
- Testing Library - React 컴포넌트 테스트
- ESLint 8 - 코드 린팅
- Prettier 3.5 - 코드 포맷팅
- Husky 9.1 - Git hooks 관리
- Lint-staged 16.1 - 스테이지된 파일 린팅
📁 프로젝트 구조
serveone-front-web/
├── src/
│ ├── components/ # 재사용 가능한 컴포넌트
│ │ ├── auth/ # 인증 관련 컴포넌트
│ │ │ └── ProtectedRoute.tsx
│ │ ├── ui/ # shadcn/ui 컴포넌트
│ │ │ ├── sidebar.tsx
│ │ │ ├── button.tsx
│ │ │ ├── dialog.tsx
│ │ │ ├── toast.tsx
│ │ │ └── ... # 33개의 UI 컴포넌트
│ │ └── not-found-error.tsx
│ │
│ ├── templates/ # 페이지 템플릿
│ │ ├── ChatPage.tsx
│ │ ├── AgentMonitoringPage.tsx
│ │ ├── QuoteRequestListPage.tsx
│ │ └── LoginPage.tsx
│ │
│ ├── services/ # API 서비스 계층
│ │ ├── conversations/ # 대화 관리 API
│ │ ├── email/ # 이메일 발송 API
│ │ ├── product-list/ # 제품 목록 API
│ │ ├── address/ # 주소 검색 API
│ │ ├── openai.ts # OpenAI 통합
│ │ ├── queryKeys.ts # React Query 키 관리
│ │ └── service.ts # 공통 서비스 로직
│ │
│ ├── stores/ # Zustand 스토어
│ │ └── authStore.ts # 인증 상태 관리
│ │
│ ├── contexts/ # React Context
│ │ └── ChatContext.tsx # 채팅 컨텍스트
│ │
│ ├── hooks/ # 커스텀 훅
│ │ ├── use-mobile.ts # 모바일 감지
│ │ └── use-window-size.ts
│ │
│ ├── types/ # TypeScript 타입 정의
│ │ ├── api.types.ts
│ │ ├── chat.types.ts
│ │ ├── business.types.ts
│ │ ├── product-list.types.ts
│ │ ├── quote-request.types.ts
│ │ └── ...
│ │
│ ├── lib/ # 유틸리티 함수
│ │ ├── utils.ts # 공통 유틸리티
│ │ ├── constants.ts # 상수 정의
│ │ └── logger.ts # 로깅 유틸리티
│ │
│ ├── styles/ # 전역 스타일
│ │ ├── _variables.scss
│ │ └── _keyframe-animations.scss
│ │
│ ├── assets/ # 정적 자산
│ │ ├── logo_serveone.svg
│ │ ├── serveone.mp4
│ │ └── fonts/
│ │
│ ├── test/ # 테스트 설정
│ │ └── setup.ts
│ │
│ ├── App.tsx # 메인 애플리케이션
│ ├── main.tsx # 엔트리 포인트
│ └── index.css # 전역 스타일
│
├── public/ # 정적 파일
│ ├── tinymce/ # TinyMCE 에디터 리소스
│ └── favicon_192.png
│
├── docs/ # 문서
│ └── environment-setup.md
│
├── vite.config.ts # Vite 설정
├── vitest.config.ts # Vitest 설정
├── tailwind.config.js # Tailwind CSS 설정
├── tsconfig.json # TypeScript 설정
├── Dockerfile # Docker 설정
├── nginx.conf # Nginx 설정
└── package.json # 프로젝트 의존성🚀 시작하기
필수 조건
- Node.js 18.0.0 이상
- npm 또는 yarn
설치 및 실행
# 1. 저장소 클론
git clone <repository-url>
cd serveone-front-web
# 2. 의존성 설치
npm install
# 또는
yarn install
# 3. 환경 변수 설정 (아래 "환경 변수" 섹션 참조)
cp .env.example .env
# .env 파일을 편집하여 필요한 값 설정
# 4. 개발 서버 실행 (포트 80)
npm run dev
# 또는
yarn dev
# 브라우저에서 http://localhost 접속📝 개발 가이드
사용 가능한 스크립트
# 개발 서버 실행
npm run dev
# TypeScript 타입 체크 후 프로덕션 빌드
npm run build
# 프로덕션 모드로 빌드
npm run build:prod
# 빌드된 앱 미리보기
npm run preview
# 코드 린팅
npm run lint
# 자동 수정과 함께 린팅
npm run lint:fix
# 코드 포맷팅
npm run format
# 포맷팅 검사 (CI용)
npm run format:check
# Docker 이미지 빌드
npm run docker:build
# Docker 컨테이너 실행
npm run docker:run개발 서버 설정
개발 서버는 다음과 같이 구성되어 있습니다:
- 호스트:
0.0.0.0(외부 접근 가능) - 포트:
80 - HMR: Hot Module Replacement 지원
- 프록시: API 프록시 설정 가능 (주석 참조)
빌드 최적화
프로덕션 빌드 시 다음과 같은 최적화가 적용됩니다:
- 코드 분할: vendor, ui 청크 분리
- 트리 쉐이킹: 미사용 코드 제거
- 콘솔 제거: console, debugger 자동 제거
- 미니파이: esbuild를 사용한 최적화
🧪 테스트
테스트 프레임워크
- Vitest - 빠른 단위 테스트
- Testing Library - React 컴포넌트 테스트
- jsdom - DOM 환경 시뮬레이션
테스트 실행
# 테스트 실행 (watch 모드)
npm run test
# 테스트 UI 실행
npm run test:ui
# 단일 실행 (CI용)
npm run test:run
# 커버리지 리포트 생성
npm run test:coverage테스트 파일 위치
- 단위 테스트:
src/**/__tests__/**/*.test.ts(x) - 설정 파일:
src/test/setup.ts - 설정:
vitest.config.ts
📦 빌드 및 배포
로컬 빌드
# 개발 빌드 (소스맵 포함)
npm run build
# 프로덕션 빌드 (최적화)
npm run build:prod
# 빌드 결과 미리보기
npm run preview빌드 결과물은 dist/ 디렉토리에 생성됩니다.
빌드 결과물
dist/
├── index.html
├── assets/
│ ├── index-[hash].js # 메인 애플리케이션
│ ├── vendor-[hash].js # React, React-DOM, Router
│ ├── ui-[hash].js # UI 라이브러리
│ ├── index-[hash].css # 스타일시트
│ └── fonts/ # 웹 폰트
└── tinymce/ # 에디터 리소스🐳 Docker
Docker 이미지 빌드
npm run docker:build
# 또는
docker build -t front-web .Docker 컨테이너 실행
npm run docker:run
# 또는
docker run -p 80:80 front-webDocker 구성
- 베이스 이미지: Node.js (빌드), Nginx (런타임)
- 포트: 80
- 웹 서버: Nginx
- 설정:
nginx.conf참조
Dockerfile 주요 단계
- 빌드 스테이지: Node.js 환경에서 애플리케이션 빌드
- 프로덕션 스테이지: Nginx로 정적 파일 서빙
- 최적화: 멀티 스테이지 빌드로 이미지 크기 최소화
🌍 환경 변수
프로젝트 루트에 .env 파일을 생성하세요:
# API 설정
VITE_API_URL=http://localhost:3001
VITE_GUEST_TOKEN=your_guest_token_here
# 개발 환경 설정
VITE_NODE_ENV=development환경 변수 설명
| 변수명 | 설명 | 기본값 | 예시 |
|---|---|---|---|
VITE_API_URL | 백엔드 API 서버 URL | http://localhost:3001 | https://api.serveone.ai |
VITE_GUEST_TOKEN | 게스트 사용자 JWT 토큰 | (없음) | eyJhbGc... |
VITE_NODE_ENV | 실행 환경 | development | production, test |
프로덕션 환경
프로덕션 배포 시 .env.production 파일을 생성하거나 서버 환경 변수로 설정하세요.
⚠️ 보안 주의사항:
- 민감한 정보를
.env파일에 저장하지 마세요 .env파일을 Git에 커밋하지 마세요- 프로덕션에서는 서버 환경 변수 사용을 권장합니다
자세한 내용은 docs/environment-setup.md 참조
🎨 코드 품질 관리
린팅 및 포맷팅
이 프로젝트는 일관된 코드 품질을 유지하기 위해 여러 도구를 사용합니다:
ESLint
- TypeScript 및 React 규칙 적용
- 최대 경고: 20개
- 사용하지 않는 disable 지시문 리포트
# 린팅 실행
npm run lint
# 자동 수정
npm run lint:fixPrettier
- 일관된 코드 스타일 유지
- 지원 파일:
.js,.jsx,.ts,.tsx,.json,.css,.md
# 포맷팅 실행
npm run format
# 포맷팅 검사
npm run format:checkGit Hooks (Husky)
커밋 전 자동으로 코드 품질 검사:
- pre-commit: Lint-staged 실행
- 스테이지된 TypeScript/React 파일 린팅
- 스테이지된 파일 포맷팅
- commit-msg: 커밋 메시지 검증 (선택사항)
Lint-staged 구성
커밋 시 스테이지된 파일에만 린팅/포맷팅 적용:
{
"*.{ts,tsx}": ["eslint --fix", "prettier --write"],
"*.{js,jsx,json,css,md}": ["prettier --write"]
}Happy Coding! 🚀
개발: ServeOne AI Team
Last updated on: