테크 스택 및 앱 구조

테크 스택

• React v18.x (Vite 기반)

• TypeScript

• TailwindCSS

• React Query

• jotai (상태관리)

• React Router

• i18next (다국어 지원)

• shadcn/ui, radix-ui

디렉토리 구조

src/
├── api/                        # API 통신 관련 함수
├── assets/                     # 이미지, 폰트 등 정적 리소스
├── atoms/                      # Zotai 상태 관리
├── components/                 # 공통 컴포넌트
├── constants/                  # 상수 정의
├── contexts/                   # React Context
├── hooks/                      # 커스텀 훅
├── lib/                        # 유틸리티 함수 및 설정
├── locales/                    # i18n 다국어 리소스
├── pages/                      # 페이지 컴포넌트
├── queries/                    # React Query 관련 로직
├── types/                      # TypeScript 타입 정의
└── utils/                      # 유틸리티 함수

💡 주요 특징

• Vite를 사용한 빠른 개발 환경 구성

• React Query를 통한 서버 상태 관리

• React Context API와 Recoil을 이용한 클라이언트 상태 관리

• i18next를 통한 다국어 지원

• TailwindCSS + shadcn/ui 조합으로 일관된 UI/UX 제공

파일 컨벤션

• *.tsx: React 컴포넌트

• *.types.ts: 타입 정의 파일

• *.utils.ts: 유틸리티 함수

• *.query.ts: React Query 관련 로직

• *.atom.ts: Recoil 상태 정의

• *.constant.ts: 상수 정의

• *.hook.ts: 커스텀 훅

앱 구조

환경 설정

.env                           # 환경 변수
.eslintrc.js                   # ESLint 설정
.prettierrc                    # Prettier 설정
tsconfig.json                  # TypeScript 설정
vite.config.ts                 # Vite 설정
tailwind.config.js             # TailwindCSS 설정

서비스 프로세스

단계별 프로세스

분석 프로세스는 단계별로 구성되어 있으며, 각 단계는 handle: { step: n } 속성으로 관리됩니다:

AI 모드 프로세스

1. 파일 업로드 (/ai-mode/upload)

2. 정보 입력 (/ai-mode/information/:jobId)

3. 비디오 편집 (/ai-mode/trim-video/:jobId) 후 (/ai-mode)에서 AI 분석 완료 대기 (이메일 알림)

4. 프레임 선택 (/ai-mode/pick-frame/:jobId)

5. 거리 입력 (/ai-mode/distance/:jobId) 후 (/ai-mode)에서 시각화 완료 대기 (이메일 알림)

6. 결과 확인 (/ai-mode/result/:jobId)

거리 측정 모드 프로세스

1. 이미지와 비디오 중 분석 유형 선택 (/distance-mode)

2. 파일 업로드 (/distance-mode/video-upload 또는 /distance-mode/image-upload)

3. 정보 입력 (/distance-mode/video-information/:jobId 또는 /distance-mode/image-information/:jobId

4. 거리 측정 (/distance-mode/video-distance/:jobId 또는 /distance-mode/image-distance/:jobId)

5. 결과 확인 (/distance-mode/video-result/:jobId 또는 /distance-mode/image-result/:jobId)

개발 가이드라인

1. 컴포넌트 개발

• Presentational/Container 패턴 사용

• 재사용 가능한 컴포넌트는 components 디렉토리에 위치

• 페이지별 컴포넌트는 pages 디렉토리 하위에 위치

1. 상태 관리

• 서버 상태: React Query 사용

• 클라이언트 상태: 전역 상태 Recoil 사용

• 컴포넌트 로컬 상태: React useState 또는 Context API 사용

1. API 통신

• axios 인스턴스 사용

• React Query를 통한 데이터 캐싱

• 에러 핸들링은 utils/error.ts에서 통합 관리 또는 개별 모달 표출

1. 스타일링

• TailwindCSS 클래스 사용

• shadcn/ui, radix-ui 컴포넌트 활용

• 부분 반응형 디자인 적용

1. 다국어 처리

• locales 디렉토리에 언어별 리소스 파일 관리

• 번역 키는 도메인별로 구조화

• 동적 번역은 interpolation 사용

공통 컴포넌트

UI 기본 컴포넌트 (src/components/ui/)

• shadcn/ui 기반의 기본 UI 컴포넌트 모음

• 버튼, 입력폼, 모달 등 기본적인 UI 요소들을 포함

• 프로젝트의 디자인 시스템을 반영한 커스텀 스타일링 적용

레이아웃 컴포넌트 (HomeLayout.tsx)

• 애플리케이션의 기본 레이아웃을 정의

• 네비게이션, 사이드바, 메인 콘텐츠 영역 구조화

• 반응형 레이아웃 지원

공통 기능 컴포넌트

1. Dialog.tsx

• 모달 다이얼로그 컴포넌트

• 알림, 확인, 입력 등 다양한 용도로 사용

1. VideoPlayer.tsx & FramePlayer.tsx

• 비디오 및 프레임 재생을 위한 커스텀 플레이어

• 컨트롤 기능 및 프레임 단위 제어 지원

1. Breadcrumb.tsx

• 계층적 구조 표현으로 현재 페이지 위치를 나타내는 네비게이션

1. ProtectedRoute.tsx

• 인증이 필요한 라우트 보호

• 권한 체크 및 리다이렉션 처리

페이지별 주요 컴포넌트

인증 관련 페이지

- LoginPage.tsx: 로그인 페이지
  - 사용자 로그인 폼
  - 소셜 로그인 옵션
  - 비밀번호 찾기 링크

- FindPasswordPage.tsx: 비밀번호 찾기
  - 이메일 인증
  - 비밀번호 재설정 프로세스

- ChangePassword.tsx: 비밀번호 변경
  - 현재 비밀번호 확인
  - 새 비밀번호 설정

메인 페이지

- HomePage.tsx: 메인 랜딩 페이지
  - 서비스 소개
  - 주요 기능 안내
  - 시작하기 가이드

- AiHomePage.tsx: AI 모드 홈
  - 파일 업로드 또는 AI 분석 목록 확인
  - AI 분석 작업 목록 - JobTable.tsx (components/login/JobTable.tsx)
  

모드 선택 페이지

- ModeSelectionPage.tsx: 기본 모드 선택
  - AI/비AI 모드 선택

- DistanceModeSelectionPage.tsx: 거리 측정 모드 선택
  - 이미지/비디오 모드 선택

분석 프로세스 페이지

- UploadPage.tsx: 파일 업로드
  - 드래그 앤 드롭 업로드
  - 파일 유효성 검사
  - 업로드 진행률 표시
  - 파일 업로드 Dropzone - Dronzone.tsx (components/droneInfo/Dropzone.tsx)

- InformationPage.tsx: 정보 입력
	- 질문과 답변 옵션은 어드민에서 관리
  - 분석 관련 메타데이터 입력
  - 지도 선택 모달 - MapModal.tsx (components/map/MapModal.tsx)

- TrimVideoPage.tsx: 비디오 구간 설정
	- 비디오 트리머에서 YPR 필터를 통해 BEV(Bird Eyed View) 변환이 잘되는 구간 표시
  - 우측 구간 설정 패널 - TrimForm.tsx (components/videoTrim/TrimForm.tsx) 
	- 재생, 배속 등 영상 컨트롤 메뉴 - VideoPlayer.tsx (components/VideoPlayer.tsx)
	- 영상 하단 비디오 트리머 - VideoTrimmer.tsx (components/videoTrim/VideoTrimmer.tsx)
	
- PickFramePage.tsx: 프레임 선택
  - 프레임 이동 등 영상 컨트롤 메뉴 - FramePlayer.tsx (components/FramePlayer.tsx)
	- 우측 프레임 선택 패널 - PickForm.tsx (components/PickForm.tsx)
	- 영상 하단 프레임 선택 UI - VideoSeeker.tsx (components/videoTrim/VideoSeeker.tsx)

- DistancePage.tsx: 거리 측정
  - 거리 측정 도구
  - 캘리브레이션 설정
  - 우측 패널의 거리 입력 패널 - DistanceForm.tsx (components/dinstance/DistanceForm.tsx)
  - 거리 표시 캔버스 DistanceCanvas (components/dinstance/canvas.tsx)
  - DistanceForm의 선박 정보 표시 부분 - ShipInfo.tsx (components/dinstance/ShipInfo.tsx)

결과 페이지

- ResultPage.tsx: AI 분석 결과
  - 분석 결과 시각화 영상
  - 결과 공유 옵션
  - 우측 결과 표시 패널 - AiResultForm.tsx (components/result/AiResultForm.tsx)
  
- NonAiResultPage.tsx: 비AI 분석 결과
  - 이미지 또는 특정 프레임에 대한 시각화 이미지
  - 결과 공유 옵션
  - 우측 결과 표시 패널 - NonAiResultForm.tsx (components/result/NonAiResultForm.tsx)
	- 분석 결과 표시 캔버스 - ResultCanvas.tsx (components/result/ResultCanvas.tsx)

사용자 관련 페이지

- MyPage.tsx: 사용자 프로필
  - 개인정보 관리
  - 분석 히스토리
  - 설정 관리