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~V030 + Spring Security + JWT + Caffeine + 트리 RBAC | 운영 배포 (rocky-211 :18080) |
| Prediction | Python 3.11+ + FastAPI + APScheduler, 17 알고리즘 모듈 + 7단계 분류 파이프라인 + 5 출력/룰 모듈 | 운영 배포 (redis-211 :18092, 5분 주기) |
| Database | PostgreSQL `kcgaidb` / 51 테이블 / 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, GearCollisionDetection(V030) | ✅ /api/vessel-analysis/groups + /api/analysis/gear-detections + /api/analysis/gear-collisions | ✅ DAR-03 G-01~G-06 + pair tier + GEAR_IDENTITY_COLLISION(PR #73) |
| 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%+
- **GEAR_IDENTITY_COLLISION (V030/PR #73)** — 동일 어구 이름이 서로 다른 MMSI 로 동일 사이클 내 공존 감지 → `gear_identity_collisions` UPSERT(name, mmsi_lo, mmsi_hi), CRITICAL/HIGH/MEDIUM/LOW severity 분류. 이전 "교체(sequential)" 로 오해하던 케이스를 "어구 복제/스푸핑 증거" 로 재정의. SAVEPOINT + try/except 로 `gear_correlation_scores_pkey` 충돌 격리

**백엔드 연동 ✅**:
- `/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 중복 제거
- `/api/analysis/gear-collisions` (V030, 4 엔드포인트) — GET list/stats/{id} + POST {id}/resolve (REVIEWED/CONFIRMED_ILLEGAL/FALSE_POSITIVE/REOPEN), `@Auditable GEAR_COLLISION_RESOLVE`
- 24h 궤적 리플레이 (gearReplayStore + useGearReplayLayers + TripsLayer)
- GearDetailPanel: 후보 클릭 → 모선 확정/제외 UI

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

---

### 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`, `GearCollisionDetection.tsx`(V030), `features/detection/components/GearDetailPanel.tsx`, `GearReplayController.tsx`, `prediction/algorithms/pair_trawl.py`, `gear_violation.py`, `gear_identity.py`(V030), `gear_correlation.py`, `gear_parent_inference.py`, `vessel_type_mapping.py`, `backend/.../analysis/VesselAnalysisGroupService.java`, `GearCollisionController+Service.java`(V030) |
| 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 |
| GearCollisionController (V030) | GearCollisionService (+`@Auditable GEAR_COLLISION_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 백엔드 계층 신설 |