Web 프로젝트 분석 보고서

1. 프로젝트 개요

1.1 기본 정보

프로젝트명: neordinary-template-react-ts-web
버전: 1.0.0
설명: 너디너리-템플릿-리액트-자바스크립트-웹
라이선스: Only use for softsquared project
개발사: (주)소프트스퀘어드

1.2 프로젝트 목적

React TypeScript 기반 웹 애플리케이션
하이브리드 앱의 웹뷰 컴포넌트로 활용
소프트스퀘어드의 표준 웹 템플릿 활용

2. 기술 스택 분석

2.1 주요 프레임워크

React: 18.2.0 (최신 안정 버전)
TypeScript: 4.9.5 (호환성 고려한 버전)
React Router DOM: 6.22.1 (SPA 라우팅)

2.2 상태 관리

Zustand: 4.5.1 (경량 상태 관리)
TanStack Query (React Query): 5.79.0 (서버 상태 관리)

2.3 UI/스타일링

Emotion: @emotion/react@11.11.3, @emotion/styled@11.11.0 (CSS-in-JS)
Framer Motion: 12.14.0 (애니메이션)
Normalize.css: 8.0.1 (CSS 정규화)

2.4 개발 도구

Build System: React Scripts 5.0.1 (Create React App)
Package Manager: npm (Node >=18, npm >=9)
Code Quality: ESLint, Prettier, Husky, lint-staged

2.5 외부 라이브러리

결제: @portone/browser-sdk@0.0.23 (포트원 결제 시스템)
에디터: react-quill-new@3.4.6, quill-table-better@1.1.6
UI 컴포넌트: react-datepicker, react-easy-crop, react-swipeable
유틸리티: date-fns@4.1.0, axios@1.6.7

3. 소스 구조 분석

3.1 디렉토리 구조

src/
├── apis/           # API 관련 (HTTP 클라이언트, 엔드포인트)
├── assets/         # 정적 자원 (이미지, 아이콘)
├── components/     # 재사용 가능한 UI 컴포넌트
├── config/         # 설정 파일
├── constants/      # 상수 정의
├── foundation/     # 기본 디자인 시스템 (색상, 폰트)
├── hooks/          # 커스텀 React 훅
├── layout/         # 레이아웃 컴포넌트
├── models/         # 데이터 모델 타입 정의
├── pages/          # 페이지 컴포넌트
├── routes/         # 라우팅 설정
├── services/       # 비즈니스 로직 서비스
├── store/          # Zustand 상태 관리
├── styles/         # 글로벌 스타일
├── types/          # TypeScript 타입 정의
└── utils/          # 유틸리티 함수

3.2 아키텍처 특징

관심사 분리: 명확한 폴더 구조로 기능별 분리
컴포넌트 기반: 재사용 가능한 컴포넌트 중심 설계
타입 안전성: TypeScript를 통한 정적 타입 검사
상태 관리 분산: Zustand를 이용한 모듈별 상태 관리

4. 특이사항

4.1 하이브리드 앱 연동

React Native WebView 통신: window.ReactNativeWebView를 통한 앱-웹 양방향 통신
토큰 관리: 앱과 웹 간 JWT 토큰 동기화 시스템
플랫폼 감지: iOS/Android/Web 환경별 로직 분기

4.2 환경별 설정

Multi-Environment: .env.development, .env.production, .env.development.local
빌드 분리: build-dev, build-prod 스크립트로 환경별 빌드

4.3 메시지 통신 시스템

// 앱-웹 메시지 타입
MessageType.WEB_SEND_TOKEN; // 웹→앱 토큰 전송
MessageType.APP_SEND_TOKEN; // 앱→웹 토큰 전송
MessageType.GET_NOTIFICATION_TOKEN; // 푸시 토큰 요청
MessageType.OPEN_CAMERA; // 카메라 호출

4.4 키보드 대응

visualViewport API를 이용한 모바일 키보드 감지
키보드 표시 시 safe-area padding 동적 조정

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

5.1 코드 구조의 우수성

명확한 관심사 분리: 각 폴더의 역할이 명확하게 정의됨
일관된 네이밍: TypeScript 인터페이스와 컴포넌트 명명 규칙 준수
재사용성: 컴포넌트와 훅의 높은 재사용성

5.2 기술 선택의 적절성

경량 상태 관리: Zustand 선택으로 불필요한 복잡성 제거
현대적 스택: React 18, TypeScript, TanStack Query 등 최신 기술 활용
성능 최적화: React.lazy를 통한 코드 스플리팅 구현

5.3 개발 경험

자동화된 코드 품질: ESLint, Prettier, Husky를 통한 일관된 코드 스타일
개발자 도구: React Query DevTools, History Debug 등 디버깅 도구 제공
타입 안전성: 철저한 TypeScript 타입 정의

5.4 하이브리드 앱 대응

안정적인 통신: 앱-웹 간 메시지 통신 시스템 잘 구축
플랫폼 감지: 환경별 로직 분기가 체계적으로 구현
토큰 동기화: JWT 토큰 관리가 앱과 웹에서 일관성 있게 처리

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

6.1 성능 최적화 기회

Bundle Size: 일부 큰 라이브러리들의 트리 쉐이킹 최적화 필요
Image Optimization: 이미지 최적화 및 lazy loading 강화 가능
Memoization: React.memo, useMemo, useCallback 활용도 증대 필요

6.2 코드 품질 개선

주석 부족: 복잡한 비즈니스 로직에 대한 설명 주석 부족
에러 바운더리: 컴포넌트 레벨 에러 처리 강화 필요
테스트 커버리지: 단위 테스트 및 통합 테스트 부족

6.3 의존성 관리

버전 관리: 일부 라이브러리의 최신 버전 업데이트 필요
불필요한 의존성: 사용하지 않는 패키지 정리 필요

6.4 사용자 경험

로딩 상태: 더 세밀한 로딩 상태 관리 필요
오프라인 대응: 네트워크 연결 실패 시 대응 로직 보강 필요

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

7.1 보안 취약점

테스트 토큰 노출: 로그인 페이지에 하드코딩된 테스트 토큰 (src/pages/login/index.tsx:132-157)

const testTokens =
    process.env.REACT_APP_ENV === "production"
        ? {
              accessToken: "하드코딩된 토큰...",
              refreshToken: "하드코딩된 토큰...",
          }
        : {
              accessToken: "하드코딩된 토큰...",
              refreshToken: "하드코딩된 토큰...",
          };

7.2 운영 환경 이슈

Console 로그 비활성화: 운영 환경에서 모든 console 로그 비활성화 (디버깅 어려움)
에러 처리: 전역 에러 처리 시스템 부족

7.3 코드 품질 문제

TODO 주석: 삭제 예정인 코드가 주석으로 남아있음 (src/store/user.ts:217-255)
타입 안전성: 일부 any 타입 사용으로 타입 안전성 저하

8. 개발 환경 및 배포

8.1 개발 환경 설정

# 개발 서버 실행
npm run start-dev      # development 환경
npm run start-prod     # production 환경
npm run start-local    # local 환경

# 빌드
npm run build-dev      # development 빌드 (./build-dev)
npm run build-prod     # production 빌드 (./build)

8.2 환경 변수

REACT_APP_API: API 서버 URL
REACT_APP_ENV: 환경 구분 (development/production)

8.3 CI/CD

Husky: Git hooks를 통한 커밋 전 코드 품질 검사
Lint-staged: 변경된 파일만 대상으로 린팅 실행
Build Spec: AWS CodeBuild용 설정 파일 존재

9. 의존성 분석

9.1 주요 외부 라이브러리

라이브러리	버전	용도	상태
React	18.2.0	UI 프레임워크	안정
TypeScript	4.9.5	타입 체킹	구버전
Zustand	4.5.1	상태 관리	안정
TanStack Query	5.79.0	서버 상태	최신
Axios	1.6.7	HTTP 클라이언트	안정

9.2 보안 취약점

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

9.3 라이선스

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

10. 향후 개발 권장사항

10.1 즉시 수정 필요

보안: 하드코딩된 테스트 토큰 제거
코드 정리: TODO 주석 및 사용하지 않는 코드 삭제
에러 처리: 전역 에러 바운더리 구현

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

테스트: Jest, React Testing Library를 이용한 테스트 코드 작성
성능: 번들 분석 및 최적화
타입 안전성: any 타입 제거 및 엄격한 타입 정의

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

기술 스택 업그레이드: TypeScript 5.x, React 19 고려
아키텍처: 마이크로 프론트엔드 고려
성능 모니터링: Sentry, 웹 바이탈 측정 도구 도입

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

빌드 시스템: Vite로 빌드 시스템 마이그레이션 고려
디자인 시스템: Storybook을 이용한 컴포넌트 문서화
PWA: 프로그레시브 웹 앱 기능 추가

10.5 팀 개발 규칙 제안

커밋 컨벤션: Conventional Commits 도입
브랜치 전략: Git Flow 또는 GitHub Flow 정립
코드 리뷰: PR 템플릿 및 리뷰 가이드라인 수립
문서화: README 업데이트 및 개발 가이드 작성

11. 결론

Web 프로젝트는 React TypeScript 기반의 현대적인 웹 애플리케이션으로, 하이브리드 앱의 웹뷰 컴포넌트로서 잘 설계되어 있습니다. 특히 앱-웹 간 통신 시스템과 상태 관리 구조가 우수하며, 코드 품질 도구들이 잘 갖춰져 있습니다.

다만, 보안 측면에서 하드코딩된 토큰 제거와 에러 처리 시스템 보강이 즉시 필요하며, 테스트 코드 작성과 성능 최적화를 통해 더욱 안정적이고 효율적인 애플리케이션으로 발전시킬 수 있을 것으로 판단됩니다.

1. 프로젝트 개요​

1.1 기본 정보​

1.2 프로젝트 목적​

2. 기술 스택 분석​

2.1 주요 프레임워크​

2.2 상태 관리​

2.3 UI/스타일링​

2.4 개발 도구​

2.5 외부 라이브러리​

3. 소스 구조 분석​

3.1 디렉토리 구조​

3.2 아키텍처 특징​

4. 특이사항​

4.1 하이브리드 앱 연동​

4.2 환경별 설정​

4.3 메시지 통신 시스템​

4.4 키보드 대응​

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

5.1 코드 구조의 우수성​

5.2 기술 선택의 적절성​

5.3 개발 경험​

5.4 하이브리드 앱 대응​

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

6.1 성능 최적화 기회​

6.2 코드 품질 개선​

6.3 의존성 관리​

6.4 사용자 경험​

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

7.1 보안 취약점​

7.2 운영 환경 이슈​

7.3 코드 품질 문제​

8. 개발 환경 및 배포​

8.1 개발 환경 설정​

8.2 환경 변수​

8.3 CI/CD​

9. 의존성 분석​

9.1 주요 외부 라이브러리​

9.2 보안 취약점​

9.3 라이선스​

10. 향후 개발 권장사항​

10.1 즉시 수정 필요​

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

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

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

10.5 팀 개발 규칙 제안​

11. 결론​