함정용 GIS (Dark)

선박위치정보 전시 및 조회 기능을 제공하는 해양 GIS 프론트엔드 프로젝트입니다.

기술 스택

항목	기술
지도 엔진	OpenLayers 9.2.4
실시간 렌더링	Deck.gl 9.2.6 (GPU)
UI 프레임워크	React 18.2.0
상태 관리	Zustand 4.5.2
라우팅	React Router 6.30.3
실시간 통신	STOMP WebSocket
번들러	Vite 5.2.10
스타일	SCSS

구현 완료 기능

지도

• 야간지도 렌더링 (OpenLayers + Deck.gl)
• 줌 레벨 5~15, 타일 로딩 6~11

실시간 선박 표시

• 선종별 아이콘/색상 표시
• 호버 툴팁
• 선종별 카운트
• 통합 모드 지원

선박 필터

• 선종별 ON/OFF
• 범례 표시

항적 조회

• 우클릭 메뉴 → 항적조회
• 조회 기간 설정 (최대 7일)
• 프로그레스 바
• 표시 옵션 (점/선/레이블)
• 통합선박 장비 필터: A/V/E/T/D
• 호버 하이라이트

리플레이

• WebSocket 실시간 데이터 수신
• 재생/일시정지
• 배속 조절: 1x ~ 1000x
• 선박 분류 관리
• Insert/Delete 단축키 지원

추적 모드

• 경비함정 반경 설정: 10/25/50/100/200 NM
• TopBar 정보 표시

UI/UX

• 다크/라이트 테마 전환
• 토스트 알림
• 드래그 가능 패널

개발 환경 설정

사전 요구사항

• Node.js 18 이상
• Yarn Classic 1.x (npm install -g yarn)

환경 변수 파일

파일	용도	빌드 명령어
.env.development	로컬 개발	yarn dev
.env.dev	개발서버 배포	yarn build:dev
.env.qa	QA 배포	yarn build:qa
.env.production	운영 배포	yarn build

인터넷 환경 (일반)

yarn install
yarn dev

폐쇄망 환경 (오프라인)

이 프로젝트는 Yarn Offline Mirror를 통해 폐쇄망에서도 빌드가 가능합니다. .yarn-offline-cache/ 폴더에 모든 의존성 패키지의 tgz 아카이브가 포함되어 있습니다.

Windows 폐쇄망 초기 세팅

# 방법 1: 배치 스크립트 실행
setup-windows.bat

# 방법 2: 수동 실행
yarn install --offline

yarn install --offline 실행 시 네트워크 접근 없이 .yarn-offline-cache/에서 패키지를 설치하며, 실행 환경(Windows/macOS/Linux)에 맞는 네이티브 바이너리가 자동으로 선택됩니다.

오프라인 캐시 갱신 (패키지 추가/업데이트 시)

인터넷이 가능한 환경에서 다음을 실행하면 캐시가 자동 갱신됩니다:

yarn add <패키지명>          # 캐시에 자동 추가
yarn install                 # 전체 캐시 동기화

개발 명령어

# 로컬 개발 서버 실행 (port 3000)
yarn dev

# 개발서버 배포용 빌드
yarn build:dev

# QA 배포용 빌드
yarn build:qa

# 운영 배포용 빌드
yarn build

# 빌드 결과 미리보기
yarn preview

배포 가이드

개발서버 배포 (/kcgnv/)

1. 빌드 실행:

   yarn build:dev
   

2. dist 폴더 내용을 서버의 /kcgnv/ 경로에 배포:

   # 기존 파일 백업 후 교체
   cp -r dist/* /var/www/html/kcgnv/
   

3. Apache 설정 확인 (httpd.conf):

   Alias /kcgnv /var/www/html/kcgnv
   <Directory "/var/www/html/kcgnv">
       Options Indexes FollowSymLinks
       AllowOverride All
       Require all granted
       FallbackResource /kcgnv/index.html
   </Directory>
   

환경별 BASE_URL 설정

• 로컬 개발: / (자동)
• 개발서버: /kcgnv/ (.env.dev)
• 운영서버: 환경에 맞게 설정

프로젝트 구조

src/
├── api/           # API 클라이언트
├── components/    # 공통 컴포넌트
├── hooks/         # 커스텀 훅
├── map/           # OpenLayers 지도 모듈
├── pages/         # 페이지 컴포넌트
├── publish/       # 퍼블리싱 미리보기 (개발용)
├── replay/        # 리플레이 모듈
├── stores/        # Zustand 스토어
├── tracking/      # 항적 추적 모듈
├── types/         # 타입/상수 정의
└── scss/          # 스타일시트

참조 프로젝트

• mda-react-front (메인 프로젝트)