kcg-ai-monitoring/docs/sfr-traceability.md

SFR 요구사항 추적 매트릭스 (Requirements Traceability Matrix)

프로젝트: AI 기반 불법조업 감시 시스템 (KCG AI Monitoring) 문서 버전: 3.0 최종 업데이트: 2026-04-17 근거 문서: 제안요청서 (RFP) 소프트웨어 기능 요구사항 (SFR)

---

기술 스택 및 아키텍처 현황 (2026-04-17 기준)

전체 스택

레이어	기술	상태
Frontend	React 19 + TypeScript 5.9 + Vite 8 + Tailwind CSS 4 + Zustand 5 + MapLibre GL 5 + deck.gl 9 + ECharts 6 + react-i18next	운영 배포 (rocky-211 nginx)
Backend	Spring Boot 3.5.7 + Java 21 + PostgreSQL 14.19 + Flyway V001~V029 + Spring Security + JWT + Caffeine + 트리 RBAC	운영 배포 (rocky-211 :18080)
Prediction	Python 3.11+ + FastAPI + APScheduler, 14 알고리즘, 7단계 분류 파이프라인	운영 배포 (redis-211 :18092, 5분 주기)
Database	PostgreSQL kcgaidb / 48 테이블 / schema kcg + snpdb(AIS 원천)	운영
Design System	/design-system.html 쇼케이스 SSOT + shared/constants/ 25개 카탈로그 + shared/components/ui/ 9개 공통 컴포넌트	SSOT 전영역 준수 (2026-04-17 PR #C 완료)
i18n	10 네임스페이스 × ko/en, common.json 에 aria/error/dialog/message 54키 추가	alert/confirm/aria-label 하드코딩 제거 완료 (2026-04-17 PR #B)

데이터 흐름

snpdb(AIS 원천) → prediction(14 algo, 5분 주기) → kcgaidb(직접 write)
                                                    ↓
Frontend ← Backend /api/analysis/* + /api/events + /api/alerts + ... (65+ API)

• Backend ↔ Prediction: HTTP 호출 없이 kcgaidb DB 공유로만 연동
• Frontend ↔ Backend: REST API + JWT 쿠키 인증

배포 토폴로지

서비스	서버	포트	배포
Frontend dist	rocky-211 (nginx 443)	HTTPS	Gitea Actions 자동배포 (main push)
Backend JAR	rocky-211	:18080	systemd kcg-ai-backend, 수동 scp + restart
Prediction FastAPI	redis-211	:18092	systemd kcg-ai-prediction, 수동 rsync + restart
PostgreSQL	211.208.115.83	:5432	kcgaidb / schema kcg / user kcg-app
Redis	redis-211	:6379	AI 채팅 컨텍스트 캐시

---

요약

구분	2026-04-06	2026-04-17
전체 SFR	20건	20건
UI 완료	20건 (100%)	20건 (100%)
백엔드 연동 완료	0건 (0%)	15건 (75%)
prediction 연동 완료	0건 (0%)	10건 (50%)
운영 배포	-	rocky-211 + redis-211

2026-04-06 이후 구현 진척

항목	상태
UI 프로토타입	✅ 완료 (31페이지)
기술 스택	✅ 모노레포 전환 (frontend + backend + prediction + database)
백엔드 (Spring Boot)	✅ JWT + 트리 RBAC + 감사 로그 + 데모 계정 5종 + 65+ API
prediction (Python)	✅ 14 algo + 7단계 파이프라인 + DAR-03 G-01~G-06 + pair tier + NAME_FUZZY 매칭
DB 마스터	✅ 48 테이블 (V001~V029), 한중어업협정 906척 레지스트리
실 API 연동	✅ Dashboard/Monitoring/Statistics/EventList/Enforcement/Detection 4종/ChinaFishing/TransferDetection/VesselDetail/LiveMapView/ParentReview/Exclusion/LabelSession/AIAlert/AccessControl/Permission/Audit 등
i18n	✅ alert/confirm/aria-label 하드코딩 제거 (2026-04-17 PR #B)
디자인 시스템 SSOT	✅ raw button/input/select/tab/checkbox → 공통 컴포넌트, 라이트/다크 쌍 (2026-04-17 PR #C)
백엔드 계층 분리	✅ controller → service → repository 일관성, RestClientConfig @Bean (2026-04-17 PR #A)
iran 백엔드 프록시	✅ 완전 제거 (2026-04-17 PR #A)

여전히 미적용 (후속 과제)

• 코드 스플리팅 (React.lazy + manualChunks)
• JSX placeholder/텍스트 한글 35건 i18n 전환
• spoofing_score 산출 재설계 (중국 MID 412 전원 0 수렴)
• external.iran_backend 매니페스트 노드 완전 삭제 (1~2 릴리즈 후)

---

SFR 목록

범례: ✅ 운영 / 🟡 구조 완성, 데이터 미연동 / 🔲 UI 프로토타입만

SFR	요구사항 명칭	구현 화면	백엔드	Prediction
SFR-01	시스템 로그인 및 권한 관리	LoginPage, AccessControl, PermissionsPanel	✅ JWT + 트리 RBAC	-
SFR-02	시스템 기본 환경설정 및 공통 기능	SystemConfig, NoticeManagement, 공통 컴포넌트	🟡 MasterData API	-
SFR-03	통합 데이터 허브 수집·연계 관리	DataHub	🔲 Mock	✅ snpdb + signal-batch
SFR-04	AI 불법조업 예측모델 관리	AIModelManagement	🔲 Mock	-
SFR-05	격자 기반 불법조업 위험도 지도	RiskMap	🔲 Mock	🟡 prediction_risk_grid
SFR-06	단속 계획·경보 연계	EnforcementPlan	✅ /api/enforcement/plans	-
SFR-07	AI 경비함정 단일 함정 순찰·경로	PatrolRoute	🔲 Mock	-
SFR-08	AI 경비함정 다함정 협력형 경로	FleetOptimization	🔲 Mock	-
SFR-09	불법 어선 패턴 탐지 (Dark Vessel)	DarkVesselDetection, TransferDetection	✅ /api/analysis/*	✅ Dark 11패턴 + Transship 5단계
SFR-10	불법 어망·어구 탐지 및 관리	GearDetection, GearIdentification	✅ /api/vessel-analysis/groups + /api/analysis/gear-detections	✅ DAR-03 G-01~G-06 + pair tier
SFR-11	단속·탐지 이력 관리	EnforcementHistory, EventList	✅ /api/events + /api/enforcement/records	✅ prediction_events
SFR-12	모니터링 및 경보 현황판	Dashboard, MonitoringDashboard, ChinaFishing	✅ /api/stats + /api/alerts + /api/analysis/*	✅ prediction_kpi_realtime + stats
SFR-13	통계·지표·성과 분석	Statistics	✅ /api/stats (daily/monthly/hourly)	✅ prediction_stats_*
SFR-14	외부 서비스 제공 결과 연계	ExternalService	🔲 Mock	-
SFR-15	단속요원 이용 모바일 대응 서비스	MobileService	🟡 /api/alerts 연동	-
SFR-16	함정용 단말 Agent 개발	ShipAgent	🔲 Mock	-
SFR-17	현장 함정 즉각 AI 알림 발송	AIAlert	✅ /api/alerts	-
SFR-18	기계학습 운영 기능 (MLOps)	MLOpsPage	🔲 Mock	-
SFR-19	LLM 운영 기능	MLOpsPage (LLMOps 탭)	🔲 Mock	-
SFR-20	자연어 처리 AI 의사결정 지원 Q&A	AIAssistant	🟡 /api/prediction/chat stub	-

---

상세 추적 내역

SFR-01: 시스템 로그인 및 권한 관리

제안요청서 정의: 사용자 유형별 안전한 인증 및 역할 기반 권한 관리 체계로 시스템 접근 보안 확보 + 사용자 활동 감사 추적.

구현 화면: features/auth/LoginPage.tsx, features/admin/AccessControl.tsx, features/admin/PermissionsPanel.tsx, features/admin/UserRoleAssignDialog.tsx

백엔드 연동 ✅ 운영:

• /api/auth/login|logout|me — JWT 쿠키 기반 인증
• /api/perm-tree + /api/roles/* + /api/admin/users/* — 트리 기반 RBAC (47 리소스 노드, Level 0 13개 + Level 1 32개 + 5 operation)
• /api/admin/audit-logs + /api/admin/access-logs + /api/admin/login-history + 통계 3종 — 감사 로그 전수 수집
• @Auditable AOP + AccessLogFilter — 자동 audit_log 기록
• 비밀번호 정책: 9자 이상 + 영문/숫자/특수, 5회 실패 계정 잠금 (Caffeine 10분 TTL)
• 데모 계정 5종 (admin/operator/analyst/field/viewer)

미구현 (기업 연동): 해양경찰 SSO / GPKI / 공무원증 인증 — 현재 자체 ID/PW + JWT

---

SFR-02: 시스템 기본 환경설정 및 공통 기능

제안요청서 정의: 공통 코드, 기준정보, 알림, GIS 지도 웹서비스, 파일 처리, 검색·페이징·엑셀 내보내기.

구현 화면: features/admin/SystemConfig.tsx, features/admin/NoticeManagement.tsx

공통 컴포넌트:

• shared/components/common/DataTable.tsx (검색·정렬·페이징·엑셀·출력)
• ExcelExport / Pagination / SearchInput / FileUpload / PrintButton / SaveButton / NotificationBanner / PageToolbar
• shared/components/ui/ 9종 (Button, Input, Select, Textarea, Checkbox, Radio, Card, Badge, TabBar+TabButton)
• shared/components/layout/ 3종 (PageContainer, PageHeader, Section)

백엔드 연동 🟡 부분:

• ✅ /api/codes + /api/codes/{id}/children — CodeMaster (875건)
• ✅ /api/gear-types — GearTypeMaster CRUD
• ✅ /api/patrol-ships — 함정 마스터
• ✅ /api/vessel-permits — 선박 허가 마스터 (2026-04-17 MasterDataService 계층 분리)
• 🔲 SystemConfig / NoticeManagement — UI 는 완성, 백엔드 API 미연동 (Mock)

지도 ✅ 운영: MapLibre GL 5 + deck.gl 9 기반 lib/map/BaseMap + createStaticLayers/createMarkerLayer/createRadiusLayer + useMapLayers RAF 기반 레이어 동기화

미구현: 알림 발송 엔진(푸시/이메일), 엑셀 서버사이드 렌더링, 공통 코드 CRUD UI

---

SFR-03: 통합 데이터 허브 수집·연계 관리

제안요청서 정의: AIS, V-PASS, 위성, 해양환경 등 이기종 데이터 통합 수집 + 실시간 모니터링 + 이상 감지.

구현 화면: features/admin/DataHub.tsx (🔲 Mock)

실제 파이프라인 ✅ 운영: prediction(redis-211:18092, 5분 주기)

• snpdb(signal.t_vessel_tracks_5min, signal.t_vessel_static, signal.snp_ais_tracks) → AIS 원천 수집
• signal-batch(192.168.1.18:18090) → 정적정보 보강 (shipKindCode/status/heading/draught)
• vessel_store cache (24h sliding window, ~55,000 선박, 2.3M points)
• 분류 파이프라인 7단계 (preprocess → behavior → resample → feature → classify → cluster → seasonal)

미구현: DataHub 화면의 실시간 수집 상태 대시보드 (현재 Mock), V-PASS·위성·해양환경 연동, 이상 감지 자동 알림

---

SFR-04: AI 불법조업 예측모델 관리

제안요청서 정의: AI 모델 등록/버전 관리/배포/모니터링.

구현 화면: features/ai-operations/AIModelManagement.tsx (🔲 Mock)

DB ✅: ai_model_versions, ai_model_metrics (V013)

미구현: MLflow/Kubeflow 연동, 모델 배포 파이프라인, A/B 테스트, 실시간 모델 성능 추적 (현재 전부 Mock)

---

SFR-05: 격자 기반 불법조업 위험도 지도

제안요청서 정의: 격자 단위 위험도 예측 + 지도 시각화.

구현 화면: features/risk-assessment/RiskMap.tsx (🔲 Mock)

DB ✅: prediction_risk_grid (V015) — prediction 이 격자별 위험도 저장

미구현: RiskMap 화면의 prediction_risk_grid 조회 연동, HexagonLayer/HeatmapLayer 실시간화

---

SFR-06: 단속 계획·경보 연계

제안요청서 정의: 고위험 구역 탐지 기반 단속 계획 수립 + 경보 연계.

구현 화면: features/risk-assessment/EnforcementPlan.tsx

백엔드 연동 ✅:

• /api/enforcement/plans (GET/POST) — EnforcementPlan CRUD
• /api/enforcement/records 연계 — 단속 이력 등록
• PatrolAssignment — 함정 배정
• 단일 함정 / 다함정 순찰 작전 탭 (2026-04-14 확장)

Prediction 연계: 위험도 기반 자동 계획은 Mock (후속 과제)

---

SFR-07: AI 경비함정 단일 함정 순찰·경로 추천

제안요청서 정의: 단일 함정 최적 순찰 경로 AI 추천.

구현 화면: features/patrol/PatrolRoute.tsx (🔲 Mock)

DB ✅: patrol_ship_master (6 함정) + patrol_assignments

미구현: A* / Dijkstra 기반 경로 최적화 알고리즘, 연료/시간 제약 고려, 실시간 위험도 반영

---

SFR-08: AI 경비함정 다함정 협력형 경로 최적화

제안요청서 정의: 다수 함정 협력 운용 최적화.

구현 화면: features/patrol/FleetOptimization.tsx (🔲 Mock)

미구현: VRP(Vehicle Routing Problem) / MIP 최적화 엔진, 함대 자원 할당 알고리즘

---

SFR-09: 불법 어선 패턴 탐지 (Dark Vessel / Spoofing / 환적)

제안요청서 정의: AIS 끊김·스푸핑·환적 등 의심 패턴 탐지.

구현 화면: features/detection/DarkVesselDetection.tsx, features/vessel/TransferDetection.tsx

Prediction 연동 ✅ 운영:

• Dark Vessel: 11패턴 P1~P11 기반 0~100점 연속 점수, 4 tier (CRITICAL≥70/HIGH≥50/WATCH≥30/NONE)
• Transshipment: 5단계 필터 파이프라인 (이종 쌍 → 감시영역 → RENDEZVOUS 90분+ → 점수 50+ → 밀집 방폭), 3,647/h → 2/cycle
• Spoofing: 1h 윈도우 teleport + extreme speed — ⚠️ 중국 MID 412 전원 0 수렴 (후속 재설계)
• 2026-04-16.7: 경량 riskScore dark_suspicion_score(0~100) × 0.3 + 기선 근접 + 반복 이력, 45점 포화 해소

백엔드 연동 ✅: /api/analysis/vessels + /api/analysis/dark + /api/analysis/transship + /api/analysis/history

• DarkDetailPanel: ScoreBreakdown + P1~P11 카탈로그
• 2026-04-17 alertLevels 헬퍼(ALERT_LEVEL_TIER_SCORE 등) 적용

---

SFR-10: 불법 어망·어구 탐지 및 관리 (DAR-03)

제안요청서 정의: 불법 어구 설치/투기/이동 탐지 + 한·중 어구 비교 판별.

구현 화면: features/detection/GearDetection.tsx, features/detection/GearIdentification.tsx

Prediction 연동 ✅ 운영 (DAR-03 G-01~G-06):

• G-01 수역-어구 불일치 (ZONE_I~IV 폴리곤)
• G-02 금어기 조업 (fishery_permit_cn.fishing_period_1/2 파싱)
• G-03 미등록/허가외 어구 (fishery_code 허용 어구 맵)
• G-04 MMSI cycling (≤30분 on/off 반복)
• G-05 고정어구 500m drift
• G-06 쌍끌이 공조 — tier 분류: STRONG / PROBABLE / SUSPECT
• 페어 탐색 find_pair_candidates (bbox + 궤적 유사도 2차)
• 한중어업협정 906척 NAME_EXACT + NAME_FUZZY 매칭 53%+

백엔드 연동 ✅:

• /api/vessel-analysis/groups + /groups/{key}/detail|correlations|candidates/{mmsi}/metrics|resolve — 모선 워크플로우 (VesselAnalysisGroupService, 2026-04-17 PARENT_RESOLVE @Auditable 추가)
• /api/analysis/gear-detections (2026-04-16.6 신설) — 자동 탐지 결과 MMSI 중복 제거
• 24h 궤적 리플레이 (gearReplayStore + useGearReplayLayers + TripsLayer)
• GearDetailPanel: 후보 클릭 → 모선 확정/제외 UI

마스터: fishery_permit_cn (V029, 29 컬럼) + fleet_vessels 확장 (permit_year/fishery_code)

---

SFR-11: 단속·탐지 이력 관리

제안요청서 정의: 이벤트/경보 수집 → 단속 등록 → 이력 조회.

구현 화면: features/enforcement/EnforcementHistory.tsx, features/enforcement/EventList.tsx

백엔드 연동 ✅ 운영:

• /api/events (GET/PATCH ack/status) + /api/events/stats — 이벤트 조회/확인/상태 변경
• /api/events/{id} — 이벤트 상세
• /api/enforcement/records (GET/POST/PATCH) — 단속 이력 CRUD
• /api/alerts — 발송된 알림 이력
• @Auditable (2026-04-17): ENFORCEMENT_CREATE / ENFORCEMENT_UPDATE / ENFORCEMENT_PLAN_CREATE
• 2026-04-17 PR #C: EventList 액션 버튼(확인/선박상세/단속등록/오탐처리) → Button variant + text--600 dark:text--400

Prediction 연동: prediction_events → event_generator 4룰 (g06_pair_trawl / g01_zone_gear / g04_mmsi_cycling / g05_gear_drift)

---

SFR-12: 모니터링 및 경보 현황판 (대시보드)

제안요청서 정의: 실시간 상황 인식 대시보드.

구현 화면: features/dashboard/Dashboard.tsx, features/monitoring/MonitoringDashboard.tsx, features/detection/ChinaFishing.tsx (중국어선 3탭)

백엔드 연동 ✅ 운영:

• /api/stats/kpi + /api/events + /api/alerts — KPI/이벤트/알림 통합
• /api/analysis/stats (2026-04-16.6 신설) — MMSI별 최신 row COUNT FILTER 집계 (total/dark/spoofing/transship/risk분포/zone분포/avgRiskScore)
• /api/analysis/vessels|dark|transship — 실시간 선박 분석 테이블
• /api/prediction/health|status — 시스템 상태

Prediction 연동 ✅: prediction_kpi_realtime + prediction_stats_hourly/daily/monthly 5분 주기 갱신

특이운항 미니맵 + 판별 패널 (2026-04-16.6): classifyAnomaly → groupAnomaliesToSegments → VesselMiniMap (24h 궤적 + severity 색 segment) + VesselAnomalyPanel

---

SFR-13: 통계·지표·성과 분석

제안요청서 정의: 월별/일별/시간별 통계 + 위반 유형 분석.

구현 화면: features/statistics/Statistics.tsx, features/statistics/ReportManagement.tsx

백엔드 연동 ✅ 운영:

• /api/stats/monthly|daily|hourly — 시계열 통계
• /api/admin/stats/audit|access|login (2026-04-17 AdminStatsService 계층 분리)

Prediction 연동 ✅: stats_aggregator → prediction_stats_monthly/daily/hourly

Report 관리: 🔲 Mock (실제 리포트 PDF/HWP 생성은 미연동)

---

SFR-14: 외부 서비스 제공 결과 연계

제안요청서 정의: 유관기관(해수부/법무부/국방부) API 연계.

구현 화면: features/statistics/ExternalService.tsx (🔲 Mock)

미구현: 유관기관 OpenAPI 연동, 결과 공유 포맷 표준화

---

SFR-15: 단속요원 이용 모바일 대응 서비스

제안요청서 정의: 현장 단속요원 모바일 UI.

구현 화면: features/field-ops/MobileService.tsx

백엔드 연동 🟡: /api/alerts 연동으로 긴급 알림 수신, 지도·KPI 는 Mock

미구현: 실제 모바일 앱 패키징 (React Native / PWA), 오프라인 동기화, 푸시 알림

---

SFR-16: 함정용 단말 Agent 개발

제안요청서 정의: 함정 탑재 단말 Agent.

구현 화면: features/field-ops/ShipAgent.tsx (🔲 Mock)

DB ✅: deviceStatuses 카탈로그 (ONLINE/OFFLINE/SYNCING/NOT_DEPLOYED)

미구현: 실제 함정 단말 SDK, GPS/AIS 수신 모듈, 백그라운드 동기화

---

SFR-17: 현장 함정 즉각 AI 알림 메시지 발송

제안요청서 정의: 고위험 이벤트 발생 시 즉각 SMS/푸시 알림.

구현 화면: features/field-ops/AIAlert.tsx

백엔드 연동 ✅: /api/alerts (2026-04-17 AlertService 계층 분리) — PredictionAlert Entity + eventId 필터 DB ✅: prediction_alerts 테이블 (V018)

미구현: 실제 SMS/푸시 발송 게이트웨이 연동, 템플릿 엔진

---

SFR-18: 기계학습 운영 기능 (MLOps)

제안요청서 정의: AI 모델 학습/배포/모니터링 자동화.

구현 화면: features/ai-operations/MLOpsPage.tsx (🔲 Mock)

미구현: MLflow/Kubeflow 파이프라인 실연동, 실험 추적, 모델 레지스트리

---

SFR-19: 대규모 언어모델(LLM) 운영 기능

제안요청서 정의: LLM 학습/추론 운영.

구현 화면: features/ai-operations/MLOpsPage.tsx LLMOps 탭 (🔲 Mock)

미구현: LLM 학습 파이프라인, 검색 서비스, 토큰 사용량 모니터링

---

SFR-20: 자연어 처리 AI 의사결정 지원 Q&A

제안요청서 정의: 운영자 자연어 질의 → AI 분석 기반 응답.

구현 화면: features/ai-operations/AIAssistant.tsx

백엔드 연동 🟡 stub: /api/prediction/chat — 현재 stub 응답. Redis 컨텍스트 캐시 인프라 준비 완료

미구현 (Phase 9): Ollama 또는 외부 LLM 연동, RAG (Retrieval-Augmented Generation), 법령 DB 임베딩

---

부록 A: 파일 경로 매핑 (2026-04-17)

SFR	주요 파일 경로
SFR-01	frontend/src/features/auth/LoginPage.tsx, features/admin/AccessControl.tsx, features/admin/PermissionsPanel.tsx, backend/.../auth/*, permission/*, audit/*
SFR-02	features/admin/SystemConfig.tsx, NoticeManagement.tsx, shared/components/common/*, shared/components/ui/*, backend/.../master/MasterDataController+Service.java
SFR-03	features/admin/DataHub.tsx, prediction/ 전체 (14 algo + 7 파이프라인), signal-batch 프록시
SFR-04	features/ai-operations/AIModelManagement.tsx, DB ai_model_versions/metrics
SFR-05	features/risk-assessment/RiskMap.tsx, DB prediction_risk_grid
SFR-06	features/risk-assessment/EnforcementPlan.tsx, backend/.../enforcement/EnforcementController+Service.java
SFR-07	features/patrol/PatrolRoute.tsx
SFR-08	features/patrol/FleetOptimization.tsx
SFR-09	features/detection/DarkVesselDetection.tsx, features/detection/components/DarkDetailPanel.tsx, features/vessel/TransferDetection.tsx, prediction/algorithms/dark_vessel.py, spoofing.py, transship.py, risk.py
SFR-10	features/detection/GearDetection.tsx, GearIdentification.tsx, features/detection/components/GearDetailPanel.tsx, GearReplayController.tsx, prediction/algorithms/pair_trawl.py, gear_violation.py, vessel_type_mapping.py, backend/.../analysis/VesselAnalysisGroupService.java
SFR-11	features/enforcement/EnforcementHistory.tsx, EventList.tsx, backend/.../event/EventController+Service.java, AlertService.java, enforcement/EnforcementService.java
SFR-12	features/dashboard/Dashboard.tsx, features/monitoring/MonitoringDashboard.tsx, features/detection/ChinaFishing.tsx, features/detection/components/VesselMiniMap.tsx, VesselAnomalyPanel.tsx, backend/.../analysis/VesselAnalysisController+Service.java
SFR-13	features/statistics/Statistics.tsx, ReportManagement.tsx, backend/.../stats/, admin/AdminStatsService.java
SFR-14	features/statistics/ExternalService.tsx
SFR-15	features/field-ops/MobileService.tsx
SFR-16	features/field-ops/ShipAgent.tsx
SFR-17	features/field-ops/AIAlert.tsx, backend/.../event/AlertController+Service.java
SFR-18	features/ai-operations/MLOpsPage.tsx
SFR-19	features/ai-operations/MLOpsPage.tsx (LLMOps 탭)
SFR-20	features/ai-operations/AIAssistant.tsx, backend/.../analysis/PredictionProxyController.java (/api/prediction/chat)

---

부록 B: 공통 컴포넌트 매핑

컴포넌트	파일	관련 SFR
DataTable	shared/components/common/DataTable.tsx	SFR-02, 10, 11, 13
PageContainer / PageHeader / Section	shared/components/layout/*	전체
Button / Input / Select / Textarea / Checkbox / Radio	shared/components/ui/*	전체 (2026-04-17 SSOT 전영역 준수)
Card / Badge	shared/components/ui/*	전체
TabBar / TabButton (underline/pill/segmented)	shared/components/ui/tabs.tsx	SFR-09, 10, 12, 18 등
SearchInput / ExcelExport / Pagination / FileUpload / PrintButton / SaveButton / NotificationBanner / PageToolbar	shared/components/common/*	SFR-02, 11, 13
BaseMap + useMapLayers	lib/map/*	SFR-02, 05, 09, 10, 12
ScoreBreakdown	shared/components/common/ScoreBreakdown.tsx	SFR-09, 10
VesselMiniMap / VesselAnomalyPanel	features/detection/components/*	SFR-12
GearReplayController	features/detection/components/*	SFR-10

---

부록 C: 카탈로그 매핑 (shared/constants/ 25개)

• 위험도 / 상태: alertLevels, violationTypes, eventStatuses, engineSeverities, performanceStatus (2026-04-17 catalogRegistry 등록), deviceStatuses, connectionStatuses, statusIntent
• 단속 / 순찰: enforcementActions, enforcementResults, patrolStatuses, trainingZoneTypes
• 탐지: darkVesselPatterns(11), vesselAnalysisStatuses, vesselTypes(7종), gearGroupTypes, gearViolationCodes(G-01~G-06), zoneCodes
• 인증 / 권한: userRoles, userAccountStatuses, loginResultStatuses, permissionStatuses
• 모선 워크플로우: parentResolutionStatuses, modelDeploymentStatuses
• API 통신: httpStatusCodes, kpiUiMap
• 알림: (i18n common.aria / error / dialog / message 2026-04-17 추가)

---

부록 D: Zustand Store 매핑

Store	파일	관련 SFR
kpiStore	stores/kpiStore.ts	SFR-12, 13
vesselStore	stores/vesselStore.ts	SFR-09, 12
eventStore	stores/eventStore.ts	SFR-11, 12, 17
enforcementStore	stores/enforcementStore.ts	SFR-06, 11
patrolStore	stores/patrolStore.ts	SFR-07, 08
gearStore	stores/gearStore.ts	SFR-10
gearReplayStore	stores/gearReplayStore.ts	SFR-10 (24h 리플레이)
transferStore	stores/transferStore.ts	SFR-09
settingsStore	stores/settingsStore.ts	SFR-01, 02 (테마/언어)

---

부록 E: 백엔드 계층 (2026-04-17 정비 완료)

모든 컨트롤러가 controller → service → repository 일관성 유지. controller 가 repository 를 직접 주입하는 사례 0건.

컨트롤러	서비스	관련 SFR
AuthController / PermTreeController / UserManagementController / RoleManagementService	-	SFR-01
MasterDataController	MasterDataService	SFR-02
AdminStatsController	AdminStatsService	SFR-13
AdminLogController	(직접 Repository)	SFR-01
VesselAnalysisController	VesselAnalysisService	SFR-09, 12
VesselAnalysisProxyController	VesselAnalysisGroupService (+@Auditable PARENT_RESOLVE)	SFR-10
PredictionProxyController	RestClient @Bean predictionRestClient	SFR-03, 20
EventController	EventService	SFR-11, 12
AlertController	AlertService	SFR-12, 17
EnforcementController	EnforcementService (+@Auditable ENFORCEMENT_*)	SFR-06, 11
ParentInferenceWorkflowController	ParentInferenceWorkflowService	SFR-10
StatsController	(Repository 조회)	SFR-13

공통 Bean 설정: config/RestClientConfig.java — predictionRestClient + signalBatchRestClient

---

부록 F: 후속 과제 우선순위 (2026-04-17 기준)

1순위 — 탐지 품질 개선

• spoofing_score 산출 재설계 — 중국 MID 412 전원 0 수렴. BD-09 필터 + teleport 25kn 임계 재검토
• RiskMap 실시간화 (SFR-05) — prediction_risk_grid 연동, HexagonLayer/HeatmapLayer
• spoofing + transship 프론트 실데이터 고도화

2순위 — 인프라

• 코드 스플리팅 — React.lazy + manualChunks (현재 단일 번들 3MB+)
• JSX placeholder/텍스트 한글 35건 i18n 전환
• external.iran_backend 매니페스트 노드 완전 삭제 (1~2 릴리즈 후)

3순위 — Mock 화면 실연동

• SFR-03 DataHub 실시간 상태 (prediction 연동)
• SFR-04 AIModelManagement (MLflow 연동)
• SFR-07, 08 경로 최적화 엔진
• SFR-14 유관기관 OpenAPI
• SFR-18, 19 MLOps/LLMOps
• SFR-20 /api/prediction/chat 실 LLM 연동

4순위 — 기업 연동

• SFR-01 SSO / GPKI / 공무원증 인증
• SFR-15 모바일 앱 패키징 (PWA 또는 React Native)
• SFR-16 함정 단말 SDK
• SFR-17 SMS/푸시 발송 게이트웨이

---

변경 이력

버전	일자	변경 내용
1.0	2026-04-06	초기 작성 (프론트엔드 프로토타입 20 SFR UI 완료)
2.0	2026-04-06	SFR 상세 추적 매트릭스 완성
3.0	2026-04-17	전면 재작성 — 백엔드/prediction 운영 배포 반영, PR #A/#B/#C 구조 정비 결과, 부록 E 백엔드 계층 신설