ship-gis/CLAUDE.md

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

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

## 기술 스택
- **언어**: TypeScript (strict 모드)
- **프레임워크**: React 19 + Vite 7
- **지도 엔진**: OpenLayers 9 + Deck.gl 9 (MapLibre 전환 예정)
- **상태관리**: Zustand 5
- **HTTP**: Axios
- **스타일**: SASS
- **라우팅**: React Router DOM 6 (v7 future flag 적용)
- **Lint**: ESLint 9 flat config + typescript-eslint 8

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

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

## 환경변수
```env
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 / Lint 설정
- `tsconfig.json`: composite 프로젝트 (tsconfig.app.json + tsconfig.node.json)
- `eslint.config.js`: ESLint 9 flat config (typescript-eslint 8, react-hooks 7)
- pre-commit hook: `npx eslint src/ --quiet`
- 타입 체크: `npx tsc -b --noEmit`

## Git 저장소
- **Remote**: https://gitea.gc-si.dev/gc/ship-gis.git
- **브랜치**: main (보호), develop (작업 브랜치), chore/react19-vite7 (Step 1)

## 팀 워크플로우
- 버전: 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 19.2.4, Vite 7.3.1, ESLint 9.39.2, Zustand 5.0.11
- sockjs-client, flatgeobuf 제거 (@stomp/stompjs는 리플레이 모듈 사용으로 유지)

### 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 신규