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 완료)
Phase 2: 지도 및 선박 표시 (01-26 완료)
Phase 3: 선박 레이어 고도화 (01-27 완료)
Phase 4: shipStore 성능 최적화 + 카운트 동기화 (01-28~30 완료)
Phase 5: 항적조회 + 버그 수정 (02-02~03 완료)
Phase 6: 리플레이 기능 (02-03 완료)
Phase 6.5: TopBar 및 추적 모드 (02-04 완료)
Phase 7: 미구현 (예정)
메인 프로젝트 참조 파일
지도 초기화
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 - 지도 컨트롤 스타일
개발 명령어
# 개발 서버 실행 (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 완료 |
HeungTak Lee
8292251758