kcg-monitoring/docs/RELEASE-NOTES.md

# Release Notes

이 문서는 [Keep a Changelog](https://keepachangelog.com/ko/1.0.0/) 형식을 따릅니다.

## [Unreleased]

### 수정
- 1h 활성 판정을 parent_name 전체 합산 기준으로 변경 (서브클러스터 분리 후 개별 소수 문제 해결)
- vessel_store의 _last_bucket 타임존 오류 수정 (tz-naive KST → UTC 잘못 변환 → incremental fetch 0건)

## [2026-04-01.2]

### 추가
- 한국 현황 위성지도/ENC 토글 (gcnautical 벡터 타일 연동)
- ENC 스타일 설정 패널 (12개 심볼 토글 + 8개 색상 수정 + 초기화)

### 수정
- 라이브 어구 현황에서 fallback 그룹 제외 (1h-fb resolution 분리)
- FLEET 타입 resolution='1h' 누락 수정
- DB resolution 컬럼 VARCHAR(4)→VARCHAR(8) 확장

## [2026-04-01]

### 추가
- 어구 그룹 1h/6h 듀얼 폴리곤 (Python 듀얼 스냅샷 + DB resolution 컬럼 + Backend/Frontend 독립 렌더)
- 리플레이 컨트롤러 A-B 구간 반복 기능
- 리플레이 프로그레스바 통합 (1h/6h 스냅샷 막대 + 호버 툴팁 + 클릭 고정)
- 리치 툴팁: 선박/어구 구분 + 모델 소속 컬러 표시 + 멤버 호버 강조
- 항공기 아이콘 줌레벨 기반 스케일 적용
- 심볼 크기 조정 패널 (선박/항공기 개별 0.5~2.0x)
- 실시간 선박 13K MapLibre → deck.gl IconLayer 전환 (useShipDeckLayers + shipDeckStore)
- 선단/어구 폴리곤 MapLibre → deck.gl GeoJsonLayer 전환 (useFleetClusterDeckLayers)
- 선박 클릭 팝업 React 오버레이 전환 (ShipPopupOverlay + 드래그 지원)
- 선박 호버 툴팁 (이름, MMSI, 위치, 속도, 수신시각)
- 리플레이 집중 모드 — 주변 라이브 정보 숨김 토글
- 라벨 클러스터링 (줌 레벨별 그리드, z10+ 전체 표시)
- 어구 서브클러스터 독립 추적 (DB sub_cluster_id + Python group_key 고정)
- 서브클러스터별 독립 center trail (PathLayer 색상 구분)

### 변경
- 일치율 후보 탐색: 6h 멤버 → 1h 활성 멤버 기반 center/radius
- 일치율 반경 밖 이탈 선박 OUT_OF_RANGE 감쇠 적용
- 폴리곤 노출: DISPLAY_STALE_SEC=1h time_bucket 기반 필터링
- 선단 폴리곤 색상: API 기본색 → 밝은 파스텔 팔레트 (바다 배경 대비)
- 멤버/연관 라벨: SDF outline → 검정 배경 블록 + fontScale.analysis 연동
- 모델 패널: 헤더→푸터 구조, 개별 확장/축소, 우클릭 툴팁 고정

### 수정
- 어구 group_key 변동 → 이력 불연속 문제 해결 (sub_cluster_id 구조 전환)
- 한국 국적 선박(440/441) 어구 오탐 제외
- Backend correlation API 서브클러스터 중복 제거 (DISTINCT ON CTE)
- 리플레이 종료/탭 off 시 deck.gl 레이어 + gearReplayStore 완전 초기화

### 기타
- DB 마이그레이션: sub_cluster_id + resolution 컬럼, 인덱스 교체

## [2026-03-31]

### 추가
- 어구 연관성 프론트엔드 표시 — Backend API + 모델별 팝업/토글 UI
- 어구 그룹 멀티모델 폴리곤 오버레이 + 토글 패널
- 어구 리플레이 deck.gl + Zustand 전환 (TripsLayer GPU 트레일 + rAF 10fps)
- 리플레이 IconLayer (SVG ship-triangle/gear-diamond, COG 회전)
- 재생 컨트롤 확장: 항적/이름 토글, 일치율 드롭다운(50~90%), 개별 on/off
- 트랙 API 전체 모델 확장 — 모델별 점수 + 24h 트랙 반환
- 모델별 폴리곤 중심 경로 + 현재 중심점 렌더링 (모델명 라벨)

### 변경
- FleetClusterLayer 2357줄 → 10파일 리팩토링 (오케스트레이터 + 서브컴포넌트)
- 리플레이 렌더링: MapLibre GeoJSON → deck.gl (React re-render 20회/초 → 0회)
- 연관 선박 위치: 트랙 보간 우선, live 선박 fallback
- 토글 패널 위치 고정 + 모델 카드 가로 스크롤
- enabledVessels 토글 시 폴리곤 + 중심경로 동시 재계산

### 수정
- 이름 기반 레이어 항상 ON 고정 + 최상위 z-index (다른 모델에 가려지지 않음)
- Prediction API DB 접속 context manager 누락
- Prediction proxy rewrite 경로 불일치 (/api/prediction → /api)
- nginx prediction API 라우팅 추가

### 기타
- CI/CD: Prediction 자동 배포 제거 → 수동 배포 전환
- zustand 5.0.12, @deck.gl/geo-layers 9.2.11 의존성 추가

## [2026-03-26]

### 추가
- AI 해양분석 채팅: Ollama Qwen3 14B 로컬 LLM 기반 해양 상황 분석 챗봇
- Ollama Docker 컨테이너 (redis-211, CPU 64코어, 64GB RAM 할당)
- Python SSE 채팅 엔드포인트 + Redis 컨텍스트 캐싱 + 계정별 대화 히스토리
- 도메인 지식 시스템 + 사전 쿼리 패턴 매칭 + LLM Tool Calling (5개 도구)
- 채팅 UI: SSE 스트리밍 + 응답 타이머 + thinking 접기 + 확장/축소

### 변경
- AiChatPanel: 클라이언트 프롬프트 → Python 서버사이드 압축 프롬프트
- nginx SSE 프록시 + kcgdb 분석 요약 쿼리 추가

## [2026-03-25]

### 추가
- 현장분석 항적 미니맵: 선박 클릭 시 72시간 항적 + 현재 위치 표시
- 현장분석 위험도 점수 기준 섹션
- Python 경량 분석: 파이프라인 미통과 412* 선박 간이 위험도

### 변경
- 위험도 용어 통일: HIGH→WATCH, MEDIUM→MONITOR, LOW→NORMAL (전체)
- 현장분석/보고서: 클라이언트 fallback 제거 → Python 분석 결과 전용
- 보고서: Python riskCounts 실데이터 기반 위험 평가
- 현장분석: AI 파이프라인 ON/OFF 실상태 + BD-09 실측 탐지 수
- 보고서 버튼: 현장분석 내부로 이동, 수역별 허가업종 동적 참조

## [2026-03-25]

### 추가
- 폴리곤 히스토리 애니메이션: 12시간 타임라인 기반 재생 (중심 궤적 + 어구별 궤적 + 가상 아이콘)
- 재생 컨트롤러: 재생/일시정지 + 프로그레스 바 (드래그/클릭) + 신호없음 구간 표시
- nginx /api/gtts 프록시 (Google TTS CORS 우회)

### 변경
- 분석 파이프라인: MIN_TRAJ_POINTS 100→20 (16척→684척 분석 대상 확대)
- risk.py: SOG 급변 count 위험도 점수 반영
- spoofing.py: BD09 오프셋 중국 MMSI(412*) 예외 처리
- VesselAnalysisService: Caffeine 캐시 → 인메모리 캐시 + 증분 갱신
- polygon_builder: STALE_SEC 3600→21600 (6시간, 어구 갭 P75 커버)

### 수정
- fishing_pattern.py: 마지막 조업 세그먼트 누락 버그 수정
- 히스토리 모드 시 현재 강조 레이어 (deck.gl + MapLibre) 정상 숨김

## [2026-03-24]

### 추가
- 선단/어구그룹 폴리곤 서버사이드 생성: Shapely convex hull + buffer → PostGIS 저장 (DB migration 009, 5분 APPEND, 7일 보존)
- Backend API: groups 목록/상세/히스토리 + vessel-analysis stats 필드 (집계 통계 서버 제공)
- 가상 선박 마커: ship-triangle 아이콘 (COG 회전 + zoom interpolate) + 어구 겹침 다중 선택 팝업
- AI 분석 통계 서버사이드 전환: dark/spoofing/risk/cluster/gear 집계를 Backend에서 계산
- 경비함정 작전가이드 모달: 3탭 + 임검침로 해상 루트 시각화 + 중국어 TTS
- 중국어선 감시현황 보고서 자동 생성 모달
- 웹폰트 내장: @fontsource-variable Inter/Noto Sans KR/Fira Code + 폰트 상수
- LayerPanel 공통 트리 구조: 재귀 렌더러 + 부모 캐스케이드 ON/OFF
- 위험시설/해외시설 SVG IconLayer 전환 (12 SVG 함수)
- 이란 리플레이 실데이터 전환: Events CRUD + 시점 조회 API + 피격 선박 27척
- 지도 글꼴 크기 커스텀: 4그룹 슬라이더 (0.5~2.0x)
- useGroupPolygons 훅 (5분 폴링) + useIranData dataSource 분기

### 변경
- FleetClusterLayer: 클라이언트 convexHull 제거 → API GeoJSON 렌더링 + 패널 아코디언 전환
- AI 분석 패널: 클라이언트 stats 계산 제거 → 서버 제공 (14K+ 순회 useMemo 삭제)
- 프론트 어구그룹 탐지 Python 이관 + 어구 클릭 시 좌측 패널 섹션 자동 전환
- 전체 font-family 통일 (CSS 55곳 + deck.gl 30곳) + 이란 시설물 사막 대비 고채도 팔레트
- feature/korea-layers-enhancement 브랜치 기능 → develop 아키텍처에 이식

### 수정
- 불법어선 탭 복원 + 어구 줌인 최대 제한 (maxZoom: 12)

## [2026-03-23]

### 추가
- 해외시설 레이어: 위험시설(원전/화학/연료저장) + 중국·일본 발전소/군사시설
- 현장분석 Python 연동 + FieldAnalysisModal (어구/선단 분석 대시보드)
- 이란 시설 deck.gl SVG 전환: 26개 고유 SVG 아이콘 (IconLayer + TextLayer)
- 중동 에너지/위험시설 데이터 84개 (meEnergyHazardFacilities)
- 환적탐지 Python 이관: 서버사이드 그리드 공간인덱스 O(n log n)
- 중국어선감시 탭: CN 어선 + 어구 패턴 필터링, 조업수역 폴리곤
- AI 해양분석 챗 UI (AiChatPanel, placeholder)
- localStorage 기반 레이어/필터 상태 영속화 (13개 항목)

### 변경
- App.tsx 분해: IranDashboard + KoreaDashboard 추출 (771줄→163줄)
- useStaticDeckLayers 분할: 레이어별 서브훅 4개
- DOM Marker → deck.gl 전환 + 줌 스케일 연동
- 한국 군사/정부/NK 아이콘: emoji → SVG IconLayer (19종)
- 선박 카테고리/국적 토글: MapLibre GPU-side filter 표현식
- LIVE 모드 currentTime 의존성 분리 → 매초 재계산 제거
- 시설 라벨 SDF 테두리 적용 (fontSettings.sdf + outlineWidth)

### 수정
- LIVE 모드 렌더링 최적화: useMonitor 1초 setInterval 제거
- 특정어업수역 실제 폴리곤 좌표 적용 (EPSG:3857→WGS84 변환)
- DB migration 008 적용 (AI 분석 API 500 에러 해결)
- 불법어선 탭 복원 + ShipLayer feature-state 필터 에러 수정
- prediction 증분 수집 버그 수정

## [2026-03-20]

### 변경
- deck.gl 전면 전환: DOM Marker → GPU 렌더링 (WebGL)
- 정적 마커 11종 deck.gl 전환 + 줌 레벨별 스케일

### 추가
- NK 미사일 궤적선 + 정적 마커 Popup + 어구 강조
- Python 분석 결과 오버레이: 위험도 마커 + 다크베셀/GPS 스푸핑 경고
- AI 분석 통계 패널 (우상단, 접이식): 분석 대상/위험/다크/선단 집계
- 불법어선/다크베셀/중국어선감시 Python 분석 연동
- Backend vessel-analysis REST API + DB 테이블 복원
- 특정어업수역 Ⅰ~Ⅳ 실제 폴리곤 기반 수역 분류

### 수정
- 해저케이블 날짜변경선 좌표 보정 + 렌더링 성능 개선

## [2026-03-19]

### 추가
- OpenSky OAuth2 Client Credentials 인증 (토큰 자동 갱신)

### 변경
- OpenSky 수집 주기 60초 → 300초 (일일 크레딧 소비 11,520 → 2,304)
- 인라인 CSS 정리 — 공통 클래스 추출 + Tailwind 전환

### 수정
- OSINT 기사 중복 수집 방지: title 기반 24h 중복 체크 추가 (GDELT/Google News)
- MapLibre symbol layer race condition 해소: hover를 feature-state로 분리, ships-korean-label visibility 제어로 변경

## [2026-03-18]

### 추가
- OSINT 수집기: GDELT + Google News RSS 백엔드 수집 (@Scheduled 2분)
- Satellite 수집기: CelesTrak TLE 백엔드 수집 (@Scheduled 10분)
- `GET /api/osint?region=iran|korea`, `GET /api/satellites?region=iran|korea` REST API
- Caffeine 캐시 TTL 2일 (Aircraft 포함 전체 통일)
- DB 마이그레이션: `ship_positions`, `osint_feeds`, `satellite_tle` 테이블 + 샘플 데이터
- 프론트엔드 OSINT/위성 데이터 백엔드 API 우선 호출 + 직접 호출 fallback
- 지진파 수집기: USGS FDSN API, 이란 bbox(M2+), 5분 주기
- 기압 수집기: Open-Meteo API, 이란 5개 관측점, 10분 주기
- DB: seismic_events, pressure_readings 테이블 (마이그레이션 004)
- REST: GET /api/sensor/seismic, GET /api/sensor/pressure
- 센서 API 서비스(sensorApi.ts): 백엔드 지진/기압 실데이터 연동
- 선박 모달 S&P Global 다중 사진 슬라이드 (좌우 화살표 + 인디케이터)
- 선박 모달 드래그 이동 (헤더 영역 grab)
- LiveControls KST/UTC 라디오 버튼 그룹
- 한국 선박 현황 헤더 ON/OFF 토글 → 지도 강조 링+라벨 표시 (기본 ON)
- 우측 패널 한국 선박 목록: hover 시 지도 강조 링, 클릭 시 선박 모달 호출
- 지진 포인트 클릭 → 지도 flyTo + SeismicMarker 진도별 펄스 원형 영향범위 표시
- SatelliteMap flyTo 지원

### 변경
- 프론트엔드 패키지 구조 리팩토링: components/ → common/layers/iran/korea/ 분리
- App.tsx 분해: 1,179줄 → 588줄 (useIranData, useKoreaData, useKoreaFilters 훅 추출)
- SensorChart: 더미 → 실데이터(지진/기압), x축 동적 시간 표시
- SensorChart 그래프 순서: 지진파 → 기압 → 소음(DEMO) → 방사선(DEMO)
- 히스토리 프리셋: 1H/2H/3H/6H (최소 1시간, 8칸 구조)
- 센서 API 파라미터: hours → min (기본 2880=48h)
- 센서 데이터 polling: 초기 48h 전체 → 10분마다 incremental merge
- 선박 데이터 polling: 초기 60분 → 5분마다 6분 윈도우 merge + 60분 stale 제거
- 선박 모달 고정 크기(300px) + 사진 영역 고정(160px, object-contain)
- 선박 모달 데이터 레이아웃: 2컬럼 그리드 + 연관 정보 쌍 배치 + 긴 값 단독행
- 선박 모달 CSS 통일 (태그 패딩/배경, 컬럼 간격 12px)
- 선박 모달 사진 탭: S&P Global 명칭, 고화질(_2) 기본 표시
- Overpass API 외부 호출 제거 → 정적 인프라 데이터
- 지진파 그래프: LineChart → ScatterChart (진도별 색상/크기, 이벤트 점 표시)
- 기압 그래프: 해수면 기압 보정(SLP), 관측소별 개별 라인, 원본 포인트 기반 렌더링
- 그래프 데이터 범위: 표시 범위보다 1칸 확장 (y축 시작점 연결)
- Tooltip: KST 시간 포맷, 상단 고정, 전체 스타일 통일
- OilFacilityLayer: planned ring SVG 내부 이동 (아이콘 중심 정렬)
- 밝은 테마: 지도 라벨 text-shadow CSS 변수 분리

### 수정
- 002 마이그레이션 search_path에 public 추가 (PostGIS 타입 참조)
- LiveControls KST 시간 이중 오프셋(+9h×2) 수정 + KST/UTC 토글
- nginx /shipimg/ 프록시: ^~ 추가 (정적파일 regex 우선매칭 방지)
- 센서 API(/api/sensor/*) 인증 예외 처리 (공개 데이터)
- 선박 모달 열 때마다 S&P Global 우선 탭 리셋 (MarineTraffic 포커스 유지 버그)
- S&P Global 사진 URL: IMO 기반 이미지 목록 API 연동 (잘못된 번호 패턴 제거)
- deploy.yml: SSH SCP+실행 각 3회 재시도 (kex_exchange 거부 대응)

### 기타
- 로그인 화면 KCG 로고에 DEMO 문구 오버레이

## [2026-03-17]

### 추가
- 프론트엔드 모노레포 이관 (`frontend/` 폴더 구조)
- signal-batch API 연동 (한국 선박 실시간 위치 데이터)
- Tailwind CSS 4 + CSS 변수 테마 시스템 (dark/light)
- i18next 다국어 지원 (ko/en) — 28개 컴포넌트 적용
- 레이어 패널 트리 구조 재설계 (카테고리별 온/오프, 접이식 범례)
- Google OAuth 로그인 + DEV LOGIN 인증 우회 (개발 모드)
- 선박 이미지 탭 전환 UI (signal-batch / MarineTraffic)
- 백엔드 Spring Boot 3.2 스켈레톤 (JDK 21)
- Google OAuth + JWT 인증 API (`@gcsc.co.kr` 도메인 제한)
- 백엔드 항공기 수집기 (Airplanes.live + OpenSky, @Scheduled 60초 주기)
- 인메모리 캐시 + PostGIS DB 적재 (향후 리플레이 지원)
- `GET /api/aircraft?region=iran|korea` REST API
- DB 마이그레이션: `aircraft_positions` 테이블 (geometry + GiST 인덱스)
- 헤더 우측 사용자 프로필/이름 + 로그아웃 버튼
- 로그인 화면 KCG 로고 적용 (kcg.svg)
- 브라우저 탭 favicon/제목 변경 (kcg-dashboard-demo)
- PostgreSQL 스키마 (events, news, osint, users, login_history)
- Python FastAPI 분석서버 placeholder
- Gitea Actions CI/CD 파이프라인 (main merge 시 자동 배포)
- nginx 설정 (SPA + API 프록시 + 외부 API CORS 프록시)
- systemd 서비스 (kcg-backend, JDK 21, 2~4GB 힙)

### 수정
- 항공기 API 폴링 주기 15초/25초 → 60초 (Rate Limit 대응)
- CORS: CorsFilter 최우선 순위 등록 (프로덕션 도메인 허용)
- 프로덕션 빌드 시 console/debugger 자동 제거
- CI/CD 워크플로우 전면 재구성: act 컨테이너(node:24) 환경 대응
- CI 빌드 실패 해결: `@rollup/rollup-darwin-arm64` 직접 의존성 제거
- 모노레포 pre-commit hook `frontend/` 디렉토리 기준 실행

### 변경
- JDK 17 → 21 업그레이드 (pom.xml, sdkmanrc, CI/CD, systemd)
- 프론트엔드 REPLAY 모드: 외부 API 호출 제거, 샘플 데이터 전용
- 프론트엔드 airplaneslive.ts / opensky.ts 삭제 (백엔드로 대체)
- Vite 프록시에서 airplaneslive / opensky 항목 제거
- deploy.yml: Gitea secrets → .env 파일로 백엔드 환경변수 배포
- systemd/nginx: 배포 경로 /devdata/services/kcg/ 반영
- 외부 API 호출 CORS 프록시 전환 (Airplanes.live, OpenSky, CelesTrak)
- App.css 하드코딩 색상 → CSS 변수 토큰 전환 (테마 반응)
- 선박 분류 체계 AIS shipTy 파싱 개선
- 한국 선박 데이터 폴링 주기 15초 → 4분