Skip to Content
TemplatesProject견적관리 임직원 GPT

견적관리 임직원 GPT

서브원AI의 AI 기반 고객 상담 및 견적 관리 시스템을 위한 현대적인 웹 애플리케이션입니다.


MeritzFire

📋 목차

✨ 주요 기능

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-web

Docker 구성

  • 베이스 이미지: Node.js (빌드), Nginx (런타임)
  • 포트: 80
  • 웹 서버: Nginx
  • 설정: nginx.conf 참조

Dockerfile 주요 단계

  1. 빌드 스테이지: Node.js 환경에서 애플리케이션 빌드
  2. 프로덕션 스테이지: Nginx로 정적 파일 서빙
  3. 최적화: 멀티 스테이지 빌드로 이미지 크기 최소화

🌍 환경 변수

프로젝트 루트에 .env 파일을 생성하세요:

# API 설정 VITE_API_URL=http://localhost:3001 VITE_GUEST_TOKEN=your_guest_token_here # 개발 환경 설정 VITE_NODE_ENV=development

환경 변수 설명

변수명설명기본값예시
VITE_API_URL백엔드 API 서버 URLhttp://localhost:3001https://api.serveone.ai
VITE_GUEST_TOKEN게스트 사용자 JWT 토큰(없음)eyJhbGc...
VITE_NODE_ENV실행 환경developmentproduction, test

프로덕션 환경

프로덕션 배포 시 .env.production 파일을 생성하거나 서버 환경 변수로 설정하세요.

⚠️ 보안 주의사항:

  • 민감한 정보를 .env 파일에 저장하지 마세요
  • .env 파일을 Git에 커밋하지 마세요
  • 프로덕션에서는 서버 환경 변수 사용을 권장합니다

자세한 내용은 docs/environment-setup.md 참조

🎨 코드 품질 관리

린팅 및 포맷팅

이 프로젝트는 일관된 코드 품질을 유지하기 위해 여러 도구를 사용합니다:

ESLint

  • TypeScript 및 React 규칙 적용
  • 최대 경고: 20개
  • 사용하지 않는 disable 지시문 리포트
# 린팅 실행 npm run lint # 자동 수정 npm run lint:fix

Prettier

  • 일관된 코드 스타일 유지
  • 지원 파일: .js, .jsx, .ts, .tsx, .json, .css, .md
# 포맷팅 실행 npm run format # 포맷팅 검사 npm run format:check

Git 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:


Copyright© AXD Design System. All rights reserved. 2026