htlee fb922fa793 docs: CLAUDE.md TypeScript 전환 및 Phase 3 계획 반영

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

2026-02-15 11:05:47 +09:00

3.6 KiB

Raw Blame 히스토리

Ship GIS - 해양 선박위치정보 GIS 프론트엔드

프로젝트 개요

해양 선박위치정보를 지도 위에 실시간으로 시각화하는 GIS 프론트엔드 애플리케이션. 민간용 데모 버전으로, OSM + OpenSeaMap 기반 지도와 AIS API 폴링 방식의 선박 데이터를 사용.

기술 스택

언어: TypeScript (strict 모드, JS→TS 전환 완료)
프레임워크: React 18 + Vite 5
지도 엔진: OpenLayers 9 + Deck.gl 9 (MapLibre 전환 예정)
상태관리: Zustand 4
HTTP: Axios
스타일: SASS
라우팅: React Router DOM 6
Lint: ESLint 8 + @typescript-eslint

빌드 / 실행

yarn install         # 의존성 설치
yarn dev             # 로컬 개발 서버 (port 3000)
yarn build           # 프로덕션 빌드

데이터 소스

선박 위치: SNP-Batch API (/api/ais-target/search) HTTP 폴링
- 초기: 최근 60분 전체 로드
- 이후: 1분마다 최근 2분 증분 조회
인증: 임시 비활성화 (VITE_DEV_SKIP_AUTH=true)

환경변수

VITE_BASE_URL=/                                    # 배포 경로
VITE_API_URL=http://211.208.115.83:8041/snp-api   # API 서버
VITE_DEV_SKIP_AUTH=true                            # 인증 우회

핵심 디렉토리 구조

src/
├── api/              # API 클라이언트 (aisTargetApi, signalApi, trackApi)
├── areaSearch/       # 항적분석 모듈
├── assets/           # 이미지, 아이콘 에셋
├── common/           # STOMP 클라이언트 (비활성화)
├── components/       # 공통 컴포넌트 (layout, ship, map, auth, common)
├── hooks/            # 커스텀 훅 (useShipData, useShipLayer 등)
├── map/              # 지도 컨테이너, 레이어, 측정 도구
├── pages/            # 페이지 (Home, Replay)
├── replay/           # 리플레이 모듈
├── scss/             # 글로벌 SCSS
├── stores/           # Zustand 스토어 (ship, map, auth, tracking 등)
├── tracking/         # 항적조회 모듈
├── types/            # 타입 정의 (ship.ts, constants.ts, global.d.ts 등)
├── utils/            # 유틸리티
└── workers/          # Web Worker (signalWorker)

TypeScript 설정

tsconfig.json: composite 프로젝트 (tsconfig.app.json + tsconfig.node.json)
.eslintrc.cjs: @typescript-eslint/recommended, react-hooks, react-refresh
pre-commit hook: npx eslint src/ --ext .ts,.tsx --quiet
타입 체크: npx tsc -b --noEmit

Git 저장소

Remote: https://gitea.gc-si.dev/gc/ship-gis.git
브랜치: main (보호), develop (작업 브랜치), chore/typescript-migration (TS 전환)

팀 워크플로우

버전: v1.2.0
커밋 형식: Conventional Commits (한/영 혼용)
브랜치 전략: main ← develop ← feature/*

Phase 3 계획 (React 19 + Vite 7 + MapLibre 전환)

상세 계획: /Users/lht/.claude/plans/glittery-zooming-feigenbaum.md

Step 1: React 19 + Vite 7 + ESLint 9 업그레이드

브랜치: chore/react19-vite7 (develop 기반)
React 18→19, Vite 5→7, ESLint 8→9 flat config
미사용 패키지 제거 (@stomp/stompjs, sockjs-client, flatgeobuf)
react-router-dom v6.x 유지

Step 2: OpenLayers → MapLibre GL JS 전환

브랜치: refactor/maplibre-migration (Step 1 병합 후)
@deck.gl/mapbox MapboxOverlay로 Deck.gl 자동 통합
OL EPSG:3857 변환 제거 → MapLibre LngLat(4326) 직접 사용
@turf/turf로 측정/좌표 계산 대체
22개 기존 파일 수정 + projection.ts 신규

3.6 KiB Raw Blame 히스토리