Skip to main content

Admin 프로젝트 분석 보고서

1. 프로젝트 개요​

1.1 기본 정보​

  • 프로젝트명: dasee-react-ts-admin
  • 버전: 1.3.5
  • 설명: 다시-리액트-타입스크립트-어드민
  • 라이선스: Only use for softsquared project
  • 개발사: (주)소프트스퀘어드

1.2 프로젝트 목적​

  • React TypeScript 기반 관리자 시스템
  • 다시(Dasee) 서비스의 백오피스 관리 도구
  • 사용자, 주문, 콘텐츠, 리뷰 등 종합 관리

2. 기술 스택 분석​

2.1 주요 프레임워크​

  • React: 18.2.0 (최신 안정 버전)
  • TypeScript: 5.1.3 (최신 버전)
  • React Router DOM: 6.14.2 (SPA 라우팅)

2.2 빌드 시스템​

  • Vite: 6.3.5 (최신 고속 빌드 도구)
  • @vitejs/plugin-react: 4.4.1 (React 플러그인)
  • vite-plugin-svgr: 4.3.0 (SVG 컴포넌트 변환)

2.3 상태 관리​

  • Recoil: 0.7.7 (Meta에서 개발한 상태 관리 라이브러리)
  • TanStack Query: 5.79.0 (서버 상태 관리)

2.4 UI/스타일링​

  • TailwindCSS: 4.1.7 (유틸리티 우선 CSS 프레임워크)
  • @tailwindcss/vite: 4.1.7 (Vite 플러그인)
  • Autoprefixer: 10.4.21 (CSS 벤더 프리픽스 자동 추가)

2.5 개발 도구​

  • ESLint: 8.42.0 (코드 품질 검사)
  • Prettier: 2.8.8 (코드 포맷팅)
  • Husky: 8.0.3 (Git hooks)
  • lint-staged: 13.2.2 (스테이징된 파일만 린팅)

2.6 외부 라이브러리​

  • 에디터: react-quill-new@3.4.6, quill-table-better@1.1.6
  • 파일 처리: file-saver@2.0.5, xlsx@0.18.5
  • HTTP 클라이언트: axios@1.4.0
  • 날짜 처리: dayjs@1.11.13
  • 알림: react-toastify@9.1.3

3. 소스 구조 분석​

3.1 디렉토리 구조​

src/
├── apis/           # API 관련 (핸들러, 코어)
├── assets/         # 정적 자원 (이미지, 아이콘)
├── components/     # 재사용 가능한 UI 컴포넌트
├── config/         # 설정 파일 (라우트 등)
├── layout/         # 레이아웃 컴포넌트
├── pages/          # 페이지 컴포넌트
├── state/          # Recoil 상태 관리
└── utils/          # 유틸리티 함수

3.2 주요 페이지 구성​

  • account/UserManage: 사용자 관리
  • content/: 콘텐츠 관리 (Guide, Service, Notice)
  • order/: 주문 관리 (Details, Refund)
  • ba/: BA 수리 관리
  • brandrepair/: 브랜드 수리 관리
  • review/: 리뷰 관리
  • restriction/: 제한 설정
  • setting/Admin: 관리자 설정

3.3 아키텍처 특징​

  • 컴포넌트 기반: 재사용 가능한 컴포넌트 중심 설계
  • 상태 관리 분리: Recoil을 통한 원자적 상태 관리
  • API 계층 분리: 핸들러별로 API 로직 모듈화
  • 타입 안전성: TypeScript 모듈 타입 정의

4. 특이사항​

4.1 상태 관리 패턴​

  • Recoil Atoms: 사용자 정보, 토큰 등 전역 상태 관리
  • LocalStorage Effect: 브라우저 새로고침 시 상태 유지
// tokenState.ts
export default atom<Token>({
    key: JWT_KEY,
    default: initToken,
    effects: [localStorageEffect(JWT_KEY)],
});

4.2 빌드 시스템​

  • Vite 기반: CRA 대비 빠른 개발 서버 및 빌드
  • Path Alias: @ 별칭을 통한 절대 경로 import
  • TailwindCSS Vite 플러그인: 최신 버전 활용

4.3 인증 시스템​

  • 자동 토큰 갱신: DefaultLayout에서 토큰 자동 갱신 처리
  • 토큰 만료 처리: 만료 시 자동 로그인 페이지 리다이렉트

4.4 에디터 기능​

  • Rich Text Editor: Quill 기반의 강력한 에디터
  • 테이블 지원: quill-table-better를 통한 고급 테이블 기능
  • 이미지 업로드: 커스텀 이미지 핸들러 구현

5. 장점 (잘 구축된 부분)​

5.1 현대적 기술 스택​

  • 최신 빌드 도구: Vite를 통한 빠른 개발 환경
  • 최신 TypeScript: 5.1.3 버전으로 최신 기능 활용
  • TailwindCSS 4.x: 최신 버전의 유틸리티 CSS 프레임워크

5.2 효율적인 상태 관리​

  • Recoil 활용: Meta에서 개발한 현대적 상태 관리
  • 원자적 상태: 세밀한 상태 관리로 불필요한 리렌더링 방지
  • Local Storage 연동: 새로고침 시에도 상태 유지

5.3 개발 경험​

  • 빠른 HMR: Vite의 Hot Module Replacement로 개발 속도 향상
  • 타입 안전성: 엄격한 TypeScript 설정
  • 자동화된 코드 품질: ESLint, Prettier, Husky를 통한 일관된 품질

5.4 컴포넌트 설계​

  • 재사용성: Table, Input, Textarea 등 범용 컴포넌트
  • 일관성: TailwindCSS를 통한 디자인 시스템 일관성
  • 접근성: 체계적인 컴포넌트 인터페이스 설계

5.5 API 관리​

  • 구조화된 API: 핸들러별로 모듈화된 API 관리
  • 에러 처리: TanStack Query의 글로벌 에러 처리
  • 자동 재시도 비활성화: 관리자 시스템 특성에 맞는 설정

6. 단점 (개선 가능한 부분)​

6.1 코드 품질 개선​

  • 주석 부족: 복잡한 비즈니스 로직에 대한 설명 부족
  • 에러 처리: 더 세밀한 에러 처리 및 사용자 피드백 필요
  • 테스트 부족: 단위 테스트 및 통합 테스트 코드 부재

6.2 사용자 경험​

  • 로딩 상태: 더 세밀한 로딩 상태 관리 필요
  • 에러 피드백: 사용자 친화적인 에러 메시지 개선
  • 접근성: ARIA 속성 및 키보드 네비게이션 개선

6.3 성능 최적화​

  • 번들 크기: 일부 라이브러리의 트리 쉐이킹 최적화 필요
  • 메모이제이션: React.memo, useMemo 등 성능 최적화 기법 부족
  • 가상화: 대용량 데이터 테이블의 가상화 미적용

6.4 보안 강화​

  • 권한 관리: 페이지/기능별 세밀한 권한 제어 필요
  • 입력 검증: 클라이언트 사이드 validation 강화 필요

7. 단점 (반드시 개선해야 하는 부분)​

7.1 보안 취약점​

  • 토큰 처리: localStorage에 토큰 저장 시 XSS 취약점
  • API 에러 노출: 상세 에러 정보가 사용자에게 노출될 수 있음

7.2 인증 시스템 문제​

  • 토큰 갱신 로직: DefaultLayout에서 매번 토큰 갱신 시도 (불필요한 API 호출)
  • 라우트 보호: 인증이 필요한 라우트와 불필요한 라우트 구분 부족

7.3 코드 품질 문제​

  • 하드코딩: 일부 설정값들이 하드코딩되어 있음
  • 타입 안전성: 일부 any 타입 사용으로 타입 안전성 저하

8. 개발 환경 및 배포​

8.1 개발 환경 설정​

# 개발 서버 실행
npm run dev      # development 환경 (포트 3001)
npm run local    # local 환경
npm run prod     # production 미리보기

# 빌드
npm run build-dev    # development 빌드
npm run build-prod   # production 빌드

# 코드 품질
npm run lint         # ESLint 실행

8.2 환경 변수​

  • VITE_API: API 서버 URL
  • Vite의 import.meta.env를 통한 환경 변수 관리

8.3 CI/CD​

  • Husky: Git hooks를 통한 커밋 전 품질 검사
  • lint-staged: 변경된 파일만 대상으로 린팅

9. 의존성 분석​

9.1 주요 외부 라이브러리​

라이브러리버전용도상태
React18.2.0UI 프레임워크안정
TypeScript5.1.3타입 체킹최신
Vite6.3.5빌드 도구최신
Recoil0.7.7상태 관리안정
TailwindCSS4.1.7CSS 프레임워크최신
TanStack Query5.79.0서버 상태최신

9.2 보안 취약점​

  • 정기적인 npm audit 실행 필요
  • 의존성 업데이트 시 호환성 테스트 필요

9.3 라이선스​

  • 대부분 MIT 라이선스로 상업적 사용 가능
  • 특별한 라이선스 제약 없음

10. 향후 개발 권장사항​

10.1 즉시 수정 필요​

  1. 보안: localStorage 토큰 저장 방식 개선 (httpOnly 쿠키 고려)
  2. 인증: 불필요한 토큰 갱신 API 호출 최적화
  3. 라우트 보호: 인증 필요 라우트와 공개 라우트 명확히 구분

10.2 단기 개선 사항 (1-2개월)​

  1. 테스트: Jest, React Testing Library를 이용한 테스트 코드 작성
  2. 에러 처리: 글로벌 에러 바운더리 및 세밀한 에러 핸들링
  3. 접근성: ARIA 속성 추가 및 키보드 네비게이션 개선

10.3 중기 개선 사항 (3-6개월)​

  1. 권한 관리: RBAC(Role-Based Access Control) 시스템 구축
  2. 성능 최적화: 가상화, 메모이제이션, 번들 최적화
  3. 모니터링: Sentry 등 에러 모니터링 도구 도입

10.4 장기 개선 사항 (6개월 이상)​

  1. 디자인 시스템: Storybook을 이용한 컴포넌트 문서화
  2. MSW: Mock Service Worker를 이용한 API 모킹
  3. E2E 테스트: Playwright 또는 Cypress를 이용한 자동화 테스트

10.5 팀 개발 규칙 제안​

  1. 커밋 컨벤션: Conventional Commits 도입
  2. 브랜치 전략: Git Flow 또는 GitHub Flow 정립
  3. 코드 리뷰: PR 템플릿 및 리뷰 체크리스트 수립
  4. 문서화: 관리자 기능별 사용자 가이드 작성

11. 결론​

Admin 프로젝트는 최신 기술 스택(Vite, TypeScript 5.x, TailwindCSS 4.x)을 활용한 현대적인 관리자 시스템입니다. Recoil을 통한 효율적인 상태 관리와 TanStack Query를 통한 서버 상태 관리가 잘 구축되어 있어 개발 생산성이 높습니다.

특히 Vite 기반의 빠른 개발 환경과 TailwindCSS를 통한 일관된 디자인 시스템이 장점입니다. React Quill을 활용한 리치 에디터와 체계적인 API 관리 구조도 잘 설계되어 있습니다.

다만, 보안 측면에서 토큰 저장 방식의 개선과 불필요한 API 호출 최적화가 즉시 필요하며, 테스트 코드 작성과 권한 관리 시스템 구축을 통해 더욱 안정적이고 확장 가능한 관리자 시스템으로 발전시킬 수 있을 것으로 판단됩니다.