# CLAUDE.md - GIS 함정용 프로젝트 가이드 ## 응답 규칙 - **모든 응답은 반드시 한글로 작성한다.** ## 프로젝트 개요 | 항목 | 내용 | |------|------| | 프로젝트명 | dark (GIS 함정용) | | 참조 프로젝트 | mda-react-front (메인 프로젝트) | | 목적 | 선박위치정보 전시 및 조회 기능 프론트엔드 | | 현재 단계 | Phase 6 진행 중 - 리플레이 기능 구현 완료 | --- ## 메인 프로젝트(mda-react-front) 기술 스택 | 항목 | 기술 | |------|------| | 지도 엔진 | OpenLayers 9.2.4 | | 실시간 렌더링 | Deck.gl 9.0.38 (GPU) | | UI 프레임워크 | React 18.2.0 | | 상태 관리 | Zustand 4.5.2 | | 라우팅 | React Router 6.15.0 | | 데이터 페칭 | React Query 4.32.6 | | 실시간 통신 | STOMP WebSocket | | 번들러 | Vite 5.2.10 | | 타입 | TypeScript 5.0.2 | --- ## 현재 프로젝트(dark) 기술 스택 | 항목 | 기술 | |------|------| | 번들러 | Vite 5.2.10 | | 언어 | JavaScript (TypeScript 도입 검토) | | UI | React 18.2.0 | | 라우팅 | React Router 6.30.3 | | 상태관리 | Zustand 4.5.2 (subscribeWithSelector) | | 지도 엔진 | OpenLayers 9.2.4 | | 선박 렌더링 | Deck.gl 9.2.6 (core, layers, extensions) | | 실시간 통신 | @stomp/stompjs (STOMP WebSocket) | | HTTP | Axios 1.4.0 | | 스타일 | SCSS | --- ## 프로젝트 구조 ``` src/ ├── index.js # 앱 엔트리 포인트 ├── App.jsx # 라우트 정의 │ ├── publish/ # [퍼블리싱 원본] - 직접 수정 금지, 참조용 │ ├── pages/ # [구현 페이지] │ └── HomePage.jsx # 메인 페이지 (지도 + 레이아웃) │ ├── components/ │ ├── layout/ # Header, Sidebar, ToolBar, MainLayout, SideNav │ ├── ship/ # ShipLegend, ShipDetailModal, ShipContextMenu, TrackQueryModal │ └── map/ # TopBar (좌표/시간표시, 검색), PatrolShipSelector (함정선택) │ ├── map/ # [지도 모듈] │ ├── MapContainer.jsx # OpenLayers + Deck.gl 통합 (window.__mainMap__) │ ├── ShipBatchRenderer.js # 배치 렌더러 (적응형 렌더링, 필터 캐시) │ └── layers/ │ ├── baseLayer.js # 베이스맵 (worldMap, eastAsiaMap, korMap) │ ├── shipLayer.js # Deck.gl 선박 레이어 (아이콘, 라벨, 벡터, 신호상태) │ └── trackLayer.js # 항적 레이어 │ ├── stores/ # [Zustand 스토어] │ ├── shipStore.js # 선박 데이터 (핵심 - mutable Map/Set + 버전 카운터) │ ├── mapStore.js # 지도 상태 │ ├── trackStore.js # 항적 상태 │ └── trackingModeStore.js # 추적 모드 (지도/선박 모드, 반경 설정) │ ├── tracking/ # [항적조회 패키지] - 메인 프로젝트 TS→JS 변환 │ ├── stores/ # trackQueryStore, trackQueryAnimationStore │ ├── services/ # trackQueryApi (API + 통합선박 처리) │ ├── components/ # TrackQueryViewer, TrackQueryTimeline, GlobalTrackQueryViewer │ ├── hooks/ # useEquipmentFilter, useTrackHighlight │ ├── utils/ # trackQueryLayerUtils, TrackQueryBatchRenderer, shipIconUtil │ └── types/ # trackQuery.types.js │ ├── replay/ # [리플레이 패키지] - 메인 프로젝트 TS→JS 변환 │ ├── stores/ # replayStore, animationStore, mergedTrackStore, playbackTrailStore │ ├── services/ # ReplayWebSocketService (WebSocket 청크 수신) │ ├── components/ # ReplayTimeline, ReplayControlV2, VesselListManager │ ├── hooks/ # useReplayLayer (Deck.gl 레이어 관리) │ ├── utils/ # replayLayerRegistry │ └── types/ # replay.types.js │ ├── hooks/ # useShipData, useShipLayer, useShipSearch, useTrackingMode, useRadiusFilter ├── api/ # signalApi ├── common/ # stompClient (STOMP WebSocket) ├── types/ # constants.js (신호원/선종/플래그 상수) ├── assets/ # 이미지, 아이콘 아틀라스 └── scss/ # 스타일 ``` --- ## 라우팅 구조 ``` / → 메인 (지도) ├── /ship → 선박 조회 ├── /satellite → 위성 ├── /weather → 기상 ├── /analysis → 분석 ├── /settings → 설정 └── /mypage → 마이페이지 /publish → 퍼블리싱 미리보기 ├── /publish/panel1 → 선박 패널 ├── /publish/panel2 → 위성 패널 ├── /publish/panel3 → 기상 패널 ├── /publish/panel4 → 분석 패널 ├── /publish/panel5 → 타임라인 ├── /publish/panel6 → AI모드 ├── /publish/panel7 → 리플레이 ├── /publish/panel8 → 항적조회 └── /publish/... → 기타 퍼블리시 페이지 ``` --- ## 기능 구현 로드맵 ### Phase 1: 기반 구축 (01-26 완료) - [x] CRA → Vite 마이그레이션 - [x] 프로젝트 구조 재편 (퍼블리시/구현 분리) - [x] Zustand 스토어 설정 (mapStore, shipStore) - [x] 기본 레이아웃 구현 (MainLayout, Header, Sidebar, ToolBar) ### Phase 2: 지도 및 선박 표시 (01-26 완료) - [x] OpenLayers 맵 컨테이너 + 베이스맵 레이어 - [x] STOMP WebSocket 클라이언트 - [x] Deck.gl 선박 아이콘 레이어 (IconLayer + 아틀라스) - [x] 선박 범례 컴포넌트 (ShipLegend) ### Phase 3: 선박 레이어 고도화 (01-27 완료) - [x] 신호상태(AVETDR) 아이콘, 속도벡터 좌표 투영 - [x] 배치 렌더러 최적화 (ShipBatchRenderer) - [x] 선명표시 클러스터링, 선박통합 ON/OFF ### Phase 4: shipStore 성능 최적화 + 카운트 동기화 (01-28~30 완료) - [x] Map/Set mutable update + 버전 카운터 패턴 - [x] 카운트 5초 쓰로틀 + targetId 중복 제거 - [x] 레이더 카운트 제외 (통합 여부 무관) - [x] Ctrl+Drag 박스 선택 + 우클릭 컨텍스트 메뉴 - [x] 통합모드 전환 시 selectedShipIds 동기화 ### Phase 5: 항적조회 + 버그 수정 (02-02~03 완료) - [x] tracking 패키지 TS→JS 변환 (13개 파일) - [x] 모달 항적조회 + 우클릭 항적조회 - [x] 라이브 연결선 (PathStyleExtension dash + 1초 인터벌) - [x] 레이더 타겟 통합 표시 버그 수정 (integrate 플래그 기반) ### Phase 6: 리플레이 기능 (02-03 완료) - [x] replay 패키지 TS→JS 변환 (stores, components, hooks, services, utils, types) - [x] WebSocket 기반 청크 데이터 수신 (ReplayWebSocketService) - [x] 시간 기반 애니메이션 (재생/일시정지/정지, 배속 1x~1000x) - [x] 프로그레스 바 슬라이더 (CSS 변수 방식, thumb/progress/배경 동기화) - [x] 항적 표시 토글 (playbackTrailStore - 프레임 기반 페이딩) - [x] 선박 상태 관리 (기본/선택/삭제) + 필터링 (선종, 신호원) - [x] 드래그 가능한 타임라인 컨트롤러 - [x] 닫기 시 초기화 (라이브 선박 복원) ### Phase 6.5: TopBar 및 추적 모드 (02-04 완료) - [x] TopBar 컴포넌트 (좌표 표시, 시간 표시, 선박 검색) - [x] 좌표/시간 포맷 설정 드롭다운 (도분초/도, KST/UTC) - [x] 선박 검색 기능 (like 검색, 디바운싱, 통합모드 지원) - [x] 추적 모드 구현 (trackingModeStore) - 지도 모드 / 선박 모드 전환 (라디오 버튼) - 경비함정 선택 드롭다운 (PatrolShipSelector) - 반경 설정 (10/25/50/100/200 NM) - [x] 반경 필터링 (useRadiusFilter, ShipBatchRenderer) - Bounding Box 사전 필터 + Haversine 거리 계산 - 렌더링, 카운트, 검색 결과 모두 반경 내 선박만 표시 - [x] 추적 함정 지도 따라가기 (useTrackingMode) - 반경 원 표시 (OpenLayers VectorLayer) - 지도 중심 자동 이동 - [x] 추적 함정 아이콘 강조 (ScatterplotLayer - 시안색 마커) - [x] 컨텍스트 메뉴 반경설정 (경비함정 우클릭 → 반경설정 서브메뉴) ### Phase 7: 미구현 (예정) - [ ] 동적 우선순위 (Dynamic Priority) - 계획 수립 완료 (`.claude/plans/`) - [ ] 퍼블리시 → 구현 전환 (Panel1~8, 기능 페이지) - [ ] 기상 레이어 - [ ] 관심영역 설정 - [ ] 위성 영상 --- ## 메인 프로젝트 참조 파일 ### 지도 초기화 - `mda-react-front/src/map/MainMapContext.tsx` - OpenLayers 맵 초기화 ### 레이어 설정 - `mda-react-front/src/common/mapLayer.ts` - 베이스맵 타일 - `mda-react-front/src/common/targetLayer.ts` - 선박 레이어 - `mda-react-front/src/common/deck.ts` - Deck.gl 설정 ### 상태 관리 - `mda-react-front/src/shared/model/` - Zustand 스토어 ### 스타일 - `mda-react-front/src/map/control.css` - 지도 컨트롤 스타일 --- ## 개발 명령어 ```bash # 개발 서버 실행 (Vite, http://localhost:3000) npm run dev # 프로덕션 빌드 npm run build # 환경별 빌드 npm run build:dev npm run build:prod # 빌드 미리보기 npm run preview # 린트 npm run lint ``` --- ## 세션 관리 - 세션 핸드오버: `.claude/SESSION_HANDOVER.md` - 자동 요약: 컨텍스트 95% 도달 시 자동 저장 --- ## 변경 이력 | 날짜 | 내용 | |------|------| | 2026-02-04 | Phase 6.5 완료 (TopBar, 추적 모드, 반경 필터링) | | 2026-02-03 | Phase 6 완료 (리플레이 기능 구현) | | 2026-02-03 | Phase 5 완료 (항적조회, 레이더 통합 버그 수정), CLAUDE.md 현황 동기화 | | 2026-01-30 | Phase 4 완료 (shipStore 성능 최적화, 카운트 동기화) | | 2026-01-27 | Phase 2~3 완료 (지도, 선박 레이어 고도화) | | 2026-01-26 | 초기 프로젝트 분석 및 워크플로우 정의, Phase 1 완료 |