# CLAUDE.md - GIS 함정용 프로젝트 가이드

## 프로젝트 개요

| 항목 | 내용 |
|------|------|
| 프로젝트명 | dark (GIS 함정용) |
| 참조 프로젝트 | mda-react-front (메인 프로젝트) |
| 목적 | 선박위치정보 전시 및 조회 기능 프론트엔드 |
| 현재 단계 | 퍼블리싱 → 구현 전환 |

---

## 메인 프로젝트(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) 기술 스택

| 항목 | 기술 | 변경 계획 |
|------|------|----------|
| 번들러 | CRA (react-scripts) | Vite 마이그레이션 검토 |
| 언어 | JavaScript | TypeScript 도입 검토 |
| 라우팅 | React Router 6.30.3 | 유지 |
| 상태관리 | React useState | Zustand 도입 |
| 스타일 | SCSS | 유지 |
| 지도 | 미연동 | OpenLayers + Deck.gl |

---

## 프로젝트 구조 설계

```
src/
├── index.js                    # 앱 엔트리 포인트
├── App.jsx                     # 라우트 정의
│
├── publish/                    # [퍼블리싱 영역] - 기존 퍼블리시 파일
│   ├── layouts/               # 퍼블리시 레이아웃
│   ├── pages/                 # 퍼블리시 페이지 (Panel1~8 등)
│   └── components/            # 퍼블리시 컴포넌트
│
├── pages/                      # [구현 영역] - 실제 페이지
│   ├── Home.jsx               # 메인 페이지
│   ├── ship/                  # 선박 관련 페이지
│   ├── satellite/             # 위성 관련 페이지
│   ├── weather/               # 기상 관련 페이지
│   └── analysis/              # 분석 관련 페이지
│
├── components/                 # [공통 컴포넌트]
│   ├── common/                # 기본 UI 컴포넌트
│   │   ├── Button/
│   │   ├── Input/
│   │   ├── Modal/
│   │   └── ...
│   ├── domain/                # 도메인별 컴포넌트
│   │   ├── ship/             # 선박 관련
│   │   ├── map/              # 지도 관련
│   │   └── ...
│   └── layout/                # 레이아웃 컴포넌트
│       ├── Header/
│       ├── Sidebar/
│       └── ...
│
├── map/                        # [지도 모듈]
│   ├── MapContext.jsx         # OpenLayers 맵 Context
│   ├── MapProvider.jsx        # 맵 Provider
│   ├── layers/                # 레이어 정의
│   │   ├── baseLayer.js      # 베이스맵
│   │   ├── shipLayer.js      # 선박 레이어
│   │   └── ...
│   ├── controls/              # 지도 컨트롤
│   └── utils/                 # 지도 유틸리티
│
├── stores/                     # [Zustand 스토어]
│   ├── mapStore.js            # 지도 상태
│   ├── shipStore.js           # 선박 상태
│   ├── filterStore.js         # 필터 상태
│   └── uiStore.js             # UI 상태
│
├── api/                        # [API 레이어]
│   ├── client.js              # API 클라이언트
│   ├── ship.js                # 선박 API
│   └── ...
│
├── hooks/                      # [커스텀 훅]
│   ├── useMap.js
│   ├── useShip.js
│   └── ...
│
├── utils/                      # [유틸리티]
│   ├── format.js
│   ├── coordinate.js
│   └── ...
│
├── types/                      # [타입 정의] (TS 도입 시)
│   └── ...
│
├── assets/                     # [정적 자원]
│   ├── images/
│   └── ...
│
└── scss/                       # [스타일]
    ├── base/
    ├── components/
    └── pages/
```

---

## 라우팅 구조

```
/                              → 메인 (지도)
├── /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: 기반 구축
- [ ] 프로젝트 구조 재편 (퍼블리시/구현 분리)
- [ ] OpenLayers 연동 (베이스맵)
- [ ] Zustand 스토어 설정
- [ ] 기본 레이아웃 구현

### Phase 2: 지도 핵심 기능
- [ ] 지도 컨트롤 (줌, 패닝)
- [ ] 레이어 관리 (토글, 순서)
- [ ] 좌표 표시
- [ ] 축척 표시

### Phase 3: 선박 표시
- [ ] Deck.gl 연동
- [ ] 선박 아이콘 렌더링
- [ ] 선박 클릭/호버 이벤트
- [ ] 선박 정보 팝업

### Phase 4: 데이터 연동
- [ ] API 클라이언트 설정
- [ ] 선박 데이터 조회
- [ ] 필터링 기능

### Phase 5: 추가 기능
- [ ] 항적 조회
- [ ] 기상 레이어
- [ ] 관심영역 설정
- [ ] 위성 영상

---

## 메인 프로젝트 참조 파일

### 지도 초기화
- `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
# 개발 서버 실행
npm start

# 프로덕션 빌드
npm run build

# 테스트
npm test
```

---

## 세션 관리

- 세션 핸드오버: `.claude/SESSION_HANDOVER.md`
- 자동 요약: 컨텍스트 95% 도달 시 자동 저장

---

## 변경 이력

| 날짜 | 내용 |
|------|------|
| 2026-01-26 | 초기 프로젝트 분석 및 워크플로우 정의 |