보험사 임직원 GPT

이 프로젝트는 보험사GPT 서비스의 프론트엔드 애플리케이션입니다. React, TypeScript, Vite를 기반으로 구축되었으며, 모던 웹 개발 환경을 제공합니다.

목차 (Table of Contents)

1. 기술 스택
2. 시작하기
3. 환경 변수 설정
4. 빌드 및 배포
5. Docker 운영 가이드
6. 프로젝트 구조
7. 개발 워크플로우
8. 트러블슈팅
9. 모니터링 및 로깅
10. 보안 설정
11. 성능 최적화
12. CI/CD 파이프라인

기술 스택 (Tech Stack)

Core

• Framework: React 18
• Language: TypeScript
• Build Tool: Vite 5.0.8
• Routing: React Router v7.6.2

Styling & UI

• CSS Framework: Tailwind CSS 3.4.1
• UI Components: shadcn/ui (Radix UI 기반)
• Icons: Lucide React, Tabler Icons
• Animation: tailwindcss-animate

State Management & Data Fetching

• Global State: Zustand 5.0.7
• Server State: TanStack Query (React Query) v5.81.2
• Query DevTools: TanStack Query DevTools (개발 환경)

Forms & Validation

• Form Handling: React Hook Form 7.59.0
• Validation: Zod 3.25.67
• Resolver: @hookform/resolvers

Utilities

• HTTP Client: Axios 1.10.0
• Date Handling: date-fns 4.1.0
• Cookie Management: cookies-next 6.1.0
• JWT Decoding: jwt-decode 4.0.0
• Markdown Rendering: react-markdown 10.1.0

시작하기 (Getting Started)

필수 조건 (Prerequisites)

• Node.js: 18.0.0 이상
• Package Manager: Yarn 또는 NPM
• Git: 버전 관리
• Docker (선택): 컨테이너화 배포 시

설치 (Installation)

# 저장소 클론
git clone <repository-url>
cd meritzfire-gpt
 
# 의존성 설치
yarn install
# 또는
npm install

환경 변수 파일 생성

프로젝트 루트에 환경 변수 파일을 생성해야 합니다:

# 개발 환경 설정 파일 생성
cp .env.example .env.development
 
# 상용 환경 설정 파일 생성 (운영팀에서 제공)
cp .env.example .env.production

환경 변수 설정에 대한 자세한 내용은 환경 변수 설정 섹션을 참조하세요.

개발 서버 실행 (Development)

# 개발 서버 실행 (개발 환경)
yarn dev
# 또는
npm run dev

브라우저에서 http://localhost:5173으로 접속하여 확인할 수 있습니다.

개발 서버 특징:

• Hot Module Replacement (HMR) 지원
• 소스맵 활성화
• React Query DevTools 자동 활성화
• 상세한 에러 메시지 및 스택 트레이스

빌드 (Build)

# 개발 환경용 빌드
yarn build:dev
# 또는
npm run build:dev
 
# 상용 환경용 빌드
yarn build:prod
# 또는
npm run build:prod
 
# 빌드된 앱 미리보기 (개발 환경)
yarn preview
# 또는
npm run preview
 
# 빌드된 앱 미리보기 (상용 환경)
yarn preview:prod
# 또는
npm run preview:prod

빌드 결과물:

• dist/ 디렉토리에 정적 파일 생성
• 상용 빌드 시 소스맵 제거 및 코드 최소화
• 자동 청크 분할 (vendor, ui, main)

환경 변수 설정

필수 환경 변수

프로젝트는 다음 환경 변수들을 필수로 요구합니다:

선택적 환경 변수

환경별 설정 예시

.env.development (개발 환경)

# 환경 설정
NODE_ENV=development
VITE_ENVIRONMENT=development

# API 설정 (개발 서버)
VITE_API_URL=http://localhost:3000/api
VITE_API_BASE_URL=http://localhost:3000

# 인증 설정 (개발용)
VITE_GUEST_TOKEN=dev_guest_token_12345
VITE_SAML_URL=http://localhost:3000/auth/saml

# 애플리케이션 설정
VITE_APP_NAME=Meritz Fire GPT (Development)
VITE_APP_VERSION=1.0.0-dev

# 개발 도구 설정
VITE_LOG_LEVEL=debug
VITE_ENABLE_DEVTOOLS=true
VITE_ENABLE_ANALYTICS=false
VITE_DEBUG_MODE=true
VITE_SHOW_DEBUG_INFO=true

.env.production (상용 환경)

# 환경 설정
NODE_ENV=production
VITE_ENVIRONMENT=production

# API 설정 (상용 서버)
VITE_API_URL=https://api.meritzfire.com/api
VITE_API_BASE_URL=https://api.meritzfire.com

# 인증 설정 (상용)
VITE_GUEST_TOKEN=prod_guest_token_secure
VITE_SAML_URL=https://auth.meritzfire.com/saml

# 애플리케이션 설정
VITE_APP_NAME=Meritz Fire GPT
VITE_APP_VERSION=1.0.0

# 상용 환경 최적화 설정
VITE_LOG_LEVEL=error
VITE_ENABLE_DEVTOOLS=false
VITE_ENABLE_ANALYTICS=true
VITE_DEBUG_MODE=false
VITE_SHOW_DEBUG_INFO=false

환경 변수 사용법

TypeScript 코드에서 환경 변수를 사용하는 방법:

import { environment, envUtils } from "@/config/environment";
 
// 환경 확인
if (environment.isDevelopment) {
  console.log("개발 환경입니다");
}
 
// 환경별 조건부 실행
envUtils.onlyInDevelopment(() => {
  console.log("개발 환경에서만 실행됩니다");
});
 
envUtils.onlyInProduction(() => {
  // 상용 환경에서만 실행될 코드
});
 
// 환경별 값 설정
const logLevel = envUtils.getByEnvironment({
  development: "debug",
  production: "error",
  default: "info",
});

주의사항

1. 보안: 상용 환경의 환경 변수 파일은 절대 Git에 커밋하지 마세요.
2. 접두사: VITE_ 접두사가 있는 변수만 클라이언트에서 접근 가능합니다.
3. 빌드 시점: 환경 변수는 빌드 시점에 주입되므로, 변경 후 재빌드가 필요합니다.
4. 타입 안정성: 환경 변수는 src/config/environment.ts에서 타입 검증됩니다.

빌드 및 배포

빌드 모드

프로젝트는 두 가지 빌드 모드를 지원합니다:

개발 빌드 (build:dev)

yarn build:dev

특징:

• 소스맵 생성
• 코드 최소화 비활성화
• 디버그 정보 포함
• 개발 도구 활성화

상용 빌드 (build:prod)

yarn build:prod

특징:

• 소스맵 제거
• 코드 최소화 (esbuild)
• 디버그 정보 제거
• 성능 최적화
• Console 로그 제거 (설정 시)

빌드 최적화

빌드 시 자동으로 다음 최적화가 수행됩니다:

1. 코드 스플리팅: vendor, ui, main 청크로 분리
2. 트리 쉐이킹: 사용하지 않는 코드 제거
3. 압축: JavaScript 및 CSS 압축
4. 정적 자산 최적화: 이미지 및 폰트 최적화

배포 전 체크리스트

• 환경 변수 파일이 올바르게 설정되었는지 확인
• 상용 빌드로 빌드되었는지 확인 (yarn build:prod)
• 빌드 결과물이 정상적으로 생성되었는지 확인 (dist/ 디렉토리)
• 정적 파일이 올바르게 서빙되는지 확인
• API 엔드포인트가 올바르게 설정되었는지 확인
• 인증 토큰이 유효한지 확인
• 헬스 체크 엔드포인트가 동작하는지 확인 (/health)

배포 방법

정적 파일 서버 배포

1. 빌드 실행: yarn build:prod
2. dist/ 디렉토리 내용을 웹 서버에 업로드
3. Nginx 또는 Apache 설정 (SPA 라우팅 지원 필요)

Docker 배포

Docker를 사용한 배포는 Docker 운영 가이드 섹션을 참조하세요.

Docker 운영 가이드

Docker 이미지 빌드

개발 환경용 빌드

yarn docker:build:dev

특징:

• 개발용 Nginx 설정 사용
• 상세한 로깅 활성화
• 캐싱 비활성화
• 개발 도구 포함

상용 환경용 빌드

yarn docker:build:prod

특징:

• 상용용 Nginx 설정 사용
• 보안 헤더 포함
• Gzip 압축 활성화
• 정적 자산 캐싱 최적화

환경 변수 전달

Docker 빌드 시 환경 변수를 전달하려면:

# 빌드 인자로 전달
docker build \
  --build-arg APP_ENV=production \
  -t merizfire-gpt-frontend:prod \
  -f Dockerfile .
 
# 또는 .env 파일 사용
docker build \
  --build-arg-file .env.production \
  -t merizfire-gpt-frontend:prod \
  -f Dockerfile .

Docker 컨테이너 실행

기본 실행

yarn docker:run

포트 매핑 변경

docker run -p 8080:80 merizfire-gpt-frontend:prod

환경 변수 전달

docker run \
  -p 80:80 \
  -e VITE_API_URL=https://api.example.com/api \
  -e VITE_API_BASE_URL=https://api.example.com \
  merizfire-gpt-frontend:prod

Docker Compose (선택사항)

docker-compose.yml 파일을 생성하여 더 편리하게 관리할 수 있습니다:

version: "3.8"
 
services:
  frontend:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        APP_ENV: production
    ports:
      - "80:80"
    environment:
      - VITE_API_URL=${VITE_API_URL}
      - VITE_API_BASE_URL=${VITE_API_BASE_URL}
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:80/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s

헬스 체크

Docker 컨테이너는 자동으로 헬스 체크를 수행합니다:

# 헬스 체크 확인
curl http://localhost:80/health
 
# 예상 응답
healthy

로그 확인

# 컨테이너 로그 확인
docker logs <container-id>
 
# 실시간 로그 확인
docker logs -f <container-id>

트러블슈팅

컨테이너가 시작되지 않는 경우

1. 포트 충돌 확인: netstat -an | grep 80
2. 이미지 빌드 확인: docker images | grep merizfire-gpt
3. 로그 확인: docker logs <container-id>

빌드 실패 시

1. Dockerfile 경로 확인
2. 환경 변수 설정 확인
3. 네트워크 프록시 설정 확인 (내부 레지스트리 사용 시)

프로젝트 구조 (Project Structure)

src/
├── components/          # 재사용 가능한 UI 컴포넌트
│   ├── ui/             # shadcn/ui 컴포넌트
│   ├── layout/        # 레이아웃 컴포넌트
│   └── ...            # 기타 컴포넌트
├── config/             # 앱 설정 파일
│   ├── environment.ts # 환경 변수 설정
│   └── fonts.ts       # 폰트 설정
├── contexts/           # React Context API
│   ├── ChatContext.tsx
│   ├── search-context.tsx
│   └── theme-context.tsx
├── hooks/              # 커스텀 React Hooks
│   ├── use-mobile.tsx
│   └── useWindowSize.ts
├── lib/                # 유틸리티 및 라이브러리 설정
│   └── utils.ts        # 공통 유틸리티 함수
├── services/           # API 통신 로직
│   ├── account/        # 계정 관련 API
│   ├── chat/           # 채팅 관련 API
│   ├── file-approval/  # 파일 승인 관련 API
│   ├── maintenance/    # 유지보수 관련 API
│   ├── team-members/   # 팀 멤버 관련 API
│   ├── upload/         # 파일 업로드 관련 API
│   ├── service.ts       # HTTP 클라이언트 설정
│   └── queryKeys.ts    # React Query 키 관리
├── store/              # Zustand 스토어
│   └── session.ts      # 세션 관리
├── templates/          # 페이지 컴포넌트 및 레이아웃
│   ├── dashboard/      # 대시보드 페이지
│   ├── document/       # 문서 페이지
│   ├── operator/       # 운영자 페이지
│   ├── settings/       # 설정 페이지
│   └── ...            # 기타 페이지
├── types/              # TypeScript 타입 정의
│   ├── api.types.ts
│   ├── chat.types.ts
│   └── ...            # 기타 타입 정의
└── utils/              # 공통 유틸리티 함수
    ├── file-validation.ts
    └── logger.ts       # 로깅 유틸리티

주요 디렉토리 설명

components/

• 재사용 가능한 UI 컴포넌트
• shadcn/ui 기반 컴포넌트 라이브러리
• 레이아웃 및 공통 컴포넌트

services/

• API 통신 로직
• React Query hooks 및 mutations
• 각 도메인별 API 모듈화

templates/

• 페이지 레벨 컴포넌트
• 라우트별 페이지 구성
• 도메인별 페이지 그룹화

types/

• TypeScript 타입 정의
• API 응답 타입
• 도메인 모델 타입

개발 워크플로우

브랜치 전략

프로젝트는 Git Flow를 따릅니다:

• main: 상용 배포 브랜치
• develop: 개발 통합 브랜치
• feature/*: 기능 개발 브랜치
• hotfix/*: 긴급 수정 브랜치
• release/*: 릴리스 준비 브랜치

커밋 메시지 규칙

커밋 메시지는 다음 형식을 따릅니다:

<type>(<scope>): <subject>

<body>

<footer>

타입:

• feat: 새로운 기능
• fix: 버그 수정
• docs: 문서 수정
• style: 코드 포맷팅
• refactor: 리팩토링
• test: 테스트 추가/수정
• chore: 빌드 설정 변경

예시:

feat(chat): 채팅 메시지 전송 기능 추가

- 메시지 입력 컴포넌트 구현
- API 연동 완료
- 에러 처리 추가

Closes #123

코드 리뷰 프로세스

1. 기능 개발 완료 후 Pull Request 생성
2. 자동화된 테스트 및 린트 검사 통과 확인
3. 코드 리뷰 요청
4. 승인 후 develop 브랜치에 머지

개발 환경 설정

IDE 설정 (VSCode 권장)

.vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "typescript.tsdk": "node_modules/typescript/lib",
  "typescript.enablePromptUseWorkspaceTsdk": true
}

필수 확장 프로그램

• ESLint
• Prettier
• TypeScript and JavaScript Language Features
• Tailwind CSS IntelliSense

트러블슈팅

일반적인 문제

1. 환경 변수가 로드되지 않는 경우

증상:

• 환경 변수 VITE_API_URL가 설정되지 않았습니다 에러

해결 방법:

1. .env.development 또는 .env.production 파일이 프로젝트 루트에 있는지 확인
2. 파일명이 정확한지 확인 (대소문자 구분)
3. VITE_ 접두사가 있는지 확인
4. Vite 서버 재시작

2. 빌드 오류가 발생하는 경우

증상:

• TypeScript 타입 오류
• 모듈을 찾을 수 없음

해결 방법:

1. 필수 환경 변수가 설정되었는지 확인
2. TypeScript 타입 오류 확인: yarn lint
3. 의존성 재설치: rm -rf node_modules && yarn install
4. 캐시 삭제: rm -rf dist && yarn build

3. 개발 서버가 시작되지 않는 경우

증상:

• 포트 5173이 이미 사용 중
• 연결 오류

해결 방법:

1. 포트 충돌 확인: netstat -an | grep 5173
2. 다른 포트 사용: vite --port 3000
3. 실행 중인 프로세스 종료

4. Docker 컨테이너가 시작되지 않는 경우

증상:

• 컨테이너가 즉시 종료됨
• 헬스 체크 실패

해결 방법:

1. 로그 확인: docker logs <container-id>
2. 포트 충돌 확인
3. 이미지 재빌드: yarn docker:build:prod
4. 환경 변수 확인

5. API 요청이 실패하는 경우

증상:

• CORS 오류
• 401/403 인증 오류

해결 방법:

1. API URL이 올바른지 확인
2. 인증 토큰이 유효한지 확인
3. CORS 설정 확인 (백엔드)
4. 네트워크 탭에서 요청/응답 확인

성능 문제

느린 빌드 시간

해결 방법:

1. 의존성 최적화
2. Vite 캐시 활용
3. 병렬 빌드 사용

느린 개발 서버 시작

해결 방법:

1. 불필요한 플러그인 제거
2. 파일 시스템 모니터링 최적화
3. SSD 사용 권장

모니터링 및 로깅

로깅 시스템

프로젝트는 환경별 로깅 시스템을 제공합니다:

import { logger } from "@/utils/logger";
 
// 로그 레벨별 사용
logger.debug("디버그 정보");
logger.info("일반 정보");
logger.warn("경고");
logger.error("에러");

로그 레벨

• debug: 개발 환경에서만 표시
• info: 일반 정보
• warn: 경고 메시지
• error: 에러 메시지 (모든 환경에서 표시)

상용 환경 로깅

상용 환경에서는 다음이 자동으로 제거됩니다:

• console.log, console.debug, console.info
• 소스맵
• 디버그 정보

모니터링 도구 통합

React Query DevTools

개발 환경에서 자동으로 활성화됩니다:

// src/main.tsx
import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
 
// 개발 환경에서만 표시
{environment.isDevelopment && <ReactQueryDevtools />}

에러 추적

에러 발생 시 다음 정보를 수집합니다:

• 에러 메시지
• 스택 트레이스
• 사용자 정보 (선택)
• 환경 정보

보안 설정

보안 헤더

상용 환경 Nginx 설정에 다음 보안 헤더가 포함됩니다:

• X-Frame-Options: SAMEORIGIN
• X-XSS-Protection: 1; mode=block
• X-Content-Type-Options: nosniff

환경 변수 보안

1. 절대 Git에 커밋하지 않기: .env.production 파일은 .gitignore에 포함
2. 민감한 정보 암호화: 토큰 및 키는 환경 변수로 관리
3. 접근 제한: 상용 환경 변수는 운영팀만 접근 가능

인증 및 인가

• JWT 토큰 기반 인증
• SAML SSO 지원
• 게스트 토큰 지원

API 보안

• HTTPS 통신 강제 (상용 환경)
• CORS 설정
• 요청 검증

성능 최적화

빌드 최적화

1. 코드 스플리팅: 자동 청크 분할
2. 트리 쉐이킹: 사용하지 않는 코드 제거
3. 압축: JavaScript 및 CSS 압축
4. 정적 자산 최적화: 이미지 및 폰트 최적화

런타임 최적화

1. React Query 캐싱: API 응답 캐싱
2. 메모이제이션: React.memo, useMemo, useCallback 활용
3. 지연 로딩: 라우트별 코드 스플리팅
4. 이미지 최적화: WebP 형식 사용

네트워크 최적화

1. Gzip 압축: Nginx에서 활성화
2. 정적 자산 캐싱: 1년 캐싱 설정
3. CDN 사용: 정적 자산 CDN 배포

성능 측정

다음 도구를 사용하여 성능을 측정할 수 있습니다:

• Lighthouse
• React DevTools Profiler
• Chrome DevTools Performance

CI/CD 파이프라인

GitHub Actions (예시)

.github/workflows/ci.yml:

name: CI
 
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: "18"
      - run: yarn install
      - run: yarn lint
      - run: yarn test:run
      - run: yarn build:prod
 
  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
    steps:
      - uses: actions/checkout@v3
      - name: Build Docker image
        run: docker build -t merizfire-gpt-frontend:prod .
      - name: Deploy
        run: |
          # 배포 스크립트

배포 프로세스

1. 코드 푸시: main 브랜치에 푸시
2. 자동 테스트: CI 파이프라인 실행
3. 빌드: Docker 이미지 빌드
4. 배포: 컨테이너 배포
5. 헬스 체크: 배포 후 헬스 체크 확인

개발 도구 (Development Tools)

코드 품질 유지를 위해 다음 도구들이 설정되어 있습니다.

ESLint

코드 린팅을 수행합니다.

# 린트 실행
yarn lint
 
# 자동 수정
yarn lint:fix

Prettier

코드 포맷팅을 수행합니다.

# 포맷팅 실행
yarn format
 
# 포맷팅 확인
yarn format:check

Husky

Git Hooks를 통해 커밋 전 자동 검사를 수행합니다.

• pre-commit: 린트 및 포맷팅 확인
• commit-msg: 커밋 메시지 형식 확인

Lint-staged

변경된 파일에 대해서만 린트를 수행합니다.

추가 리소스

문서

• 환경 설정 가이드
• 프론트엔드 디자인 가이드라인

외부 링크

• React 공식 문서 
• Vite 공식 문서 
• TanStack Query 문서 
• shadcn/ui 문서 

지원

문제가 발생하거나 질문이 있으시면 다음 채널로 문의하세요:

• 이슈 트래커: GitHub Issues
• 이메일: [운영팀 이메일]

라이센스 (License)

이 프로젝트는 MIT 라이센스 하에 배포됩니다.

변경 이력 (Changelog)

v1.0.0 (2024-01-01)

• 초기 릴리스
• 기본 기능 구현
• Docker 지원 추가

마지막 업데이트: 2024-01-01