htlee b37e18d952 docs: prediction-analysis 신규 + 루트/SFR 문서 drift 해소

- docs/prediction-analysis.md 신설 — opus 4.7 독립 리뷰 기반 prediction 구조/방향 심층 분석
  (9개 섹션: 아키텍처·5분 사이클·17 알고리즘·4대 도메인 커버리지·6축 구조 평가·개선 제안 P1~P4·임계값 전수표)
- AGENTS.md / README.md — V001~V016→V030, Python 3.9→3.11+, 14→17 알고리즘 모듈
- docs/architecture.md — /gear-collision 라우트 추가 (26→27 보호 경로)
- docs/sfr-traceability.md — V029→V030, 48→51 테이블, SFR-10 에 GEAR_IDENTITY_COLLISION 추가
- docs/sfr-user-guide.md — 어구 정체성 충돌 페이지 섹션 신설
- docs/system-flow-guide.md — 노드 수 102→115, V030 manifest 미반영 경고
- backend/README.md — "Phase 2 예정" 상태 → 실제 운영 구성 + PR #79 hotfix 요구사항 전면 재작성

2026-04-17 11:20:53 +09:00

38 KiB

Raw 고유링크 Blame 히스토리

SFR 요구사항별 화면 사용 가이드

문서 작성일: 2026-04-06 최종 업데이트: 2026-04-17 (2026-04-17 릴리즈 기준) 시스템 버전: 운영 배포 (rocky-211 + redis-211) 다국어: 한국어/영어 전환 지원 (헤더 우측 EN/한국어 버튼) 테마: 다크/라이트 전환 지원 (헤더 우측 해/달 아이콘 버튼)

문서 안내

이 문서는 KCG AI 모니터링 시스템의 각 SFR(소프트웨어 기능 요구사항)이 화면에서 어떻게 구현되어 있는지를 비개발자(일반 사용자, 사업 PM, 산출물 작성자)가 이해할 수 있도록 정리한 가이드입니다.

시스템 현황 (2026-04-17 기준)

프런트엔드·백엔드·분석엔진(prediction) 운영 배포 완료 — 자체 JWT 인증 + 트리 기반 RBAC + 감사 로그 + 65+ API
AI 분석 엔진(prediction): 5분 주기로 AIS 원천 데이터(snpdb)를 분석하여 결과를 kcgaidb 에 자동 저장 (14 알고리즘 + DAR-03 G-01~G-06)
실시간 연동 화면: Dashboard / MonitoringDashboard / ChinaFishing / DarkVesselDetection / GearDetection / EnforcementHistory / EventList / AIAlert / Statistics / AccessControl / PermissionsPanel / Audit 등 15+ 화면이 실 API + prediction 결과를 실시간으로 표시
Mock 화면: DataHub / AIModelManagement / RiskMap / PatrolRoute / FleetOptimization / ExternalService / ShipAgent / MLOpsPage / AIAssistant 는 UI 완성, 백엔드/AI 엔진 연동은 단계적 추가 중
자세한 추적 매트릭스: docs/sfr-traceability.md v3.0 참조

SFR-01: 사용자 인증 및 접근 제어
SFR-02: 시스템 공통기능 및 환경설정
SFR-03: 데이터 수집 허브
SFR-04: AI 모델 관리
SFR-05: 위험도 분석 지도
SFR-06: 단속 계획 및 경보
SFR-07: 단일함정 순찰경로 최적화
SFR-08: 다함정 경로 최적화
SFR-09: Dark Vessel 탐지
SFR-10: 어망/어구 탐지
SFR-11: 단속/탐지 이력 관리
SFR-12: 종합 상황판 및 경보 현황판
SFR-13: 통계 및 성과 분석
SFR-14: 외부 서비스 연계
SFR-15: 모바일 서비스
SFR-16: 함정 Agent
SFR-17: AI 알림 발송
SFR-18/19: MLOps 플랫폼
SFR-20: AI 의사결정 지원

SFR-01: 사용자 인증 및 접근 제어

✅ 로그인 화면 UI + 자체 ID/PW 인증 + JWT 쿠키 세션 + 역할별 데모 계정 5종 실 로그인
✅ 비밀번호 정책(9자 이상 영문+숫자+특수) + 5회 실패 30분 잠금 + BCrypt 해시
✅ 트리 기반 RBAC (47 리소스 노드, Level 0 13개 + Level 1 32개, 5 operation) + Caffeine 10분 TTL
✅ 모든 로그인 시도 감사 로그 저장 및 조회 (로그인 이력 화면)
✅ 역할 기반 세션 유지 및 메뉴 접근 제어 (사이드바/라우트 가드)

향후 구현 예정 (기업 환경 연동):

🔲 SSO(해양경찰 통합인증) 연동
🔲 GPKI(정부 공인인증서) 인증 연동
🔲 공무원증 기반 인증 연동
🔲 인사 시스템 연동 역할 자동 부여

권한 관리

메뉴 위치: 시스템 관리 > 권한 관리 URL: /access-control 접근 권한: ADMIN

화면 설명: 시스템 사용자의 역할(Role)과 권한을 관리하는 화면입니다. RBAC(역할 기반 접근 제어) 방식으로 5가지 역할을 정의하고 각 역할별 메뉴 접근 권한을 설정할 수 있습니다.

주요 기능:

5가지 역할(ADMIN, OPERATOR, ANALYST, FIELD, VIEWER) 조회
역할별 접근 가능 메뉴 및 기능 권한 설정
사용자 목록 조회 및 역할 할당

구현 완료 (2026-04-17 기준):

✅ 트리 기반 RBAC 실 운영 — 47 리소스 노드 × 5 operation (READ/CREATE/UPDATE/DELETE/EXPORT) × 다중 역할 OR 합집합
✅ 역할별 권한 매트릭스 시각화 (셀 클릭 Y → N → 상속 사이클)
✅ 부모 READ 거부 시 자식 강제 거부, 상속 표시
✅ 역할 CRUD (admin:role-management) + 권한 매트릭스 갱신 (admin:permission-management)
✅ 사용자-역할 할당 다이얼로그 (admin:user-management)
✅ 모든 권한 변경은 auth_audit_log 에 자동 기록 (ROLE_CREATE/UPDATE/DELETE/PERM_UPDATE/USER_ROLE_ASSIGN)

향후 구현 예정:

🔲 권한 변경 이력 UI (auth_audit_log 조회는 현재 별도 화면)
🔲 역할 템플릿 복제 기능

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

환경설정

메뉴 위치: 시스템 관리 > 환경설정 URL: /system-config 접근 권한: ADMIN, OPERATOR

화면 설명: 시스템 운영에 필요한 기준정보를 조회하고 관리하는 화면입니다. 875건의 기준정보 항목이 표시되며, 검색 및 필터링이 가능합니다.

주요 기능:

기준정보 875건 목록 조회 및 검색
카테고리별 필터링
설정값 수정 UI

구현 완료:

✅ 875건 기준정보 목록 표시 및 검색/필터 UI
✅ 공통 컴포넌트 적용 (DataTable, 엑셀 내보내기, 인쇄 기능)

향후 구현 예정:

🔲 기준정보 DB 연동 (조회/수정/저장)
🔲 설정 변경 이력 관리

보완 필요:

⚠️ 현재 표시 데이터는 샘플이며, DB 연동 후 실제 운영 데이터로 교체 필요

공지사항

메뉴 위치: 시스템 관리 > 공지사항 URL: /notices 접근 권한: ADMIN (작성/수정/삭제), 전체 역할 (조회)

화면 설명: 시스템 운영 관련 공지사항을 등록하고 조회하는 게시판입니다.

주요 기능:

공지사항 목록 조회
공지사항 작성, 수정, 삭제 (CRUD)
공지사항 상세 조회

구현 완료:

✅ 공지사항 CRUD UI 완성
✅ 목록/상세/작성/수정 화면 전환

향후 구현 예정:

🔲 공지사항 DB 연동
🔲 첨부파일 업로드/다운로드

보완 필요:

⚠️ 현재 작성한 공지사항은 새로고침 시 초기화됨

이벤트 목록

메뉴 위치: 단속/이력 > 이벤트 목록 URL: /event-list 접근 권한: ADMIN, OPERATOR, ANALYST

화면 설명: 시스템에서 발생한 각종 이벤트(탐지, 경보, 알림 등)를 통합 목록으로 조회하는 화면입니다.

주요 기능:

이벤트 유형별 필터링 및 검색
이벤트 상세 정보 조회
이벤트 목록 엑셀 내보내기

구현 완료:

✅ 이벤트 통합 목록 UI 및 필터/검색
✅ DataTable 공통 컴포넌트 적용 (정렬, 페이징, 엑셀, 인쇄)

향후 구현 예정:

🔲 실시간 이벤트 수신 및 목록 자동 갱신
🔲 이벤트 DB 연동

보완 필요:

⚠️ 현재 목록은 샘플 데이터이며, 실시간 연동 후 자동 업데이트 필요

SFR-03: 데이터 수집 허브

메뉴 위치: 시스템 관리 > 데이터 허브 URL: /data-hub 접근 권한: ADMIN, OPERATOR

화면 설명: 외부 데이터 소스(AIS, LRIT, SAR, CCTV, VMS 등 5개 신호원)로부터 데이터를 수집하는 현황을 모니터링하는 화면입니다. 22개 수집 채널의 상태를 실시간으로 확인할 수 있습니다.

주요 기능:

5개 신호원별 수집 상태 대시보드
22개 수집 채널별 연결 상태, 수신량, 오류율 조회
채널별 상세 수집 이력 확인

구현 완료:

✅ 5개 신호원 + 22개 수집 채널 현황 대시보드 UI
✅ 채널별 상태(정상/경고/오류) 시각화

향후 구현 예정:

🔲 실제 데이터 수집 엔진 연동
🔲 수집 채널 실시간 상태 모니터링
🔲 수집 데이터 품질 검증 기능

보완 필요:

⚠️ 현재 모든 수집 현황은 샘플 데이터이며, 실제 신호원 연결 후 실데이터로 교체 필요

SFR-04: AI 모델 관리

메뉴 위치: 시스템 관리 > AI 모델관리 URL: /ai-model 접근 권한: ADMIN, OPERATOR

화면 설명: AI 탐지 모델의 버전, 탐지 규칙, 입력 피처(Feature), 학습 파이프라인을 관리하는 화면입니다. 모델의 성능을 확인하고 운영 중인 모델을 교체하거나 새 버전을 등록할 수 있습니다.

주요 기능:

AI 모델 5개 버전 목록 및 상세 정보 조회
6개 탐지 규칙 관리 (임계값, 조건 설정)
20개 입력 피처 목록 및 중요도 확인
학습 파이프라인 실행 현황 조회

구현 완료:

✅ 모델 버전 관리 UI (5버전 목록, 성능지표 비교)
✅ 탐지 규칙 6건 설정 화면
✅ 피처 20건 목록 및 중요도 시각화
✅ 파이프라인 현황 표시

향후 구현 예정:

🔲 실제 AI 모델 서버 연동 (모델 등록/배포/롤백)
🔲 모델 학습 파이프라인 실행 연동
🔲 모델 성능 모니터링 실시간 연동

보완 필요:

⚠️ 현재 모델 성능 지표는 샘플 데이터이며, 실제 모델 연동 후 정확한 지표로 교체 필요

SFR-05: 위험도 분석 지도

메뉴 위치: 탐지/분석 > 위험도 지도 URL: /risk-map 접근 권한: ADMIN, OPERATOR, ANALYST

화면 설명: 해역별 불법조업 위험도를 히트맵(열지도) 형태로 시각화한 화면입니다. 10x18 격자로 분할된 관할 해역의 위험도를 색상으로 표현하며, MTIS 해양사고 통계를 6개 탭으로 분류하여 제공합니다.

주요 기능:

10x18 격자 기반 위험도 히트맵 지도 표시
격자별 상세 위험도 정보 팝업
MTIS 해양사고 통계 6탭 (사고유형별, 해역별, 월별 등)
기간별 위험도 변화 추이 확인

구현 완료:

✅ 위험도 히트맵 10x18 격자 시각화
✅ MTIS 해양사고 통계 6탭 UI

향후 구현 예정:

🔲 AI 위험도 예측 모델 연동
🔲 실시간 AIS/VMS 데이터 기반 동적 위험도 갱신
🔲 과거 데이터 기반 위험도 예측 기능

보완 필요:

⚠️ 현재 히트맵 데이터는 샘플이며, 예측 모델 연동 후 정확한 위험도로 교체 필요

SFR-06: 단속 계획 및 경보

메뉴 위치: 탐지/분석 > 단속 계획/경보 URL: /enforcement-plan 접근 권한: ADMIN, OPERATOR, ANALYST

화면 설명: 불법조업 단속 계획을 수립하고, 경보 발생 조건(임계값)을 설정하는 화면입니다. 현재 등록된 5건의 단속 계획과 경보 조건을 확인하고 관리할 수 있습니다.

주요 기능:

단속 계획 5건 목록 조회 및 상세 확인
신규 단속 계획 작성 및 수정
경보 임계값(위험도 기준, 선박 수 기준 등) 설정
단속 계획별 투입 함정/인력 배치 확인

구현 완료:

✅ 단속 계획 5건 목록/상세 UI
✅ 경보 임계값 설정 화면

향후 구현 예정:

🔲 AI 기반 단속 계획 자동 추천
🔲 경보 임계값 도달 시 자동 경보 발생
🔲 단속 계획 DB 연동

보완 필요:

⚠️ 현재 단속 계획 데이터는 샘플이며, 자동 추천 및 경보 기능은 AI 모델 연동 후 구현 필요

SFR-07: 단일함정 순찰경로 최적화

메뉴 위치: 현장 대응 > 단일함정 순찰경로 URL: /patrol-route 접근 권한: ADMIN, OPERATOR, FIELD

화면 설명: 개별 함정(경비함)의 순찰 경로를 지도 위에 표시하고, AI가 최적화한 경로를 제안하는 화면입니다. 4척의 함정별 경로와 3가지 시나리오(최단거리, 위험지역 우선, 연료절감)를 비교할 수 있습니다.

주요 기능:

4척 함정별 순찰 경로 지도 표시
3가지 시나리오별 경로 비교
경유지 추가/제거를 통한 수동 경로 조정
예상 소요시간, 연료소모량, 해역 커버리지 정보 표시

구현 완료:

✅ 함정 4척 경로 지도 시각화
✅ 3가지 시나리오 비교 UI

향후 구현 예정:

🔲 AI 경로 최적화 엔진 연동
🔲 실시간 함정 위치 반영
🔲 기상/해황 정보 반영 경로 재계산

보완 필요:

⚠️ 현재 경로는 샘플 데이터이며, AI 최적화 엔진 연동 후 실제 최적 경로 제공 필요

SFR-08: 다함정 경로 최적화

메뉴 위치: 현장 대응 > 다함정 경로최적화 URL: /fleet-optimization 접근 권한: ADMIN, OPERATOR

화면 설명: 여러 함정을 동시에 운용할 때 전체 해역 커버리지를 최대화하는 최적 경로를 계산하는 화면입니다. 5척의 함정이 6개 구역을 효율적으로 분담 순찰하도록 배치합니다.

주요 기능:

5척 함정의 담당 구역 배정 및 지도 시각화
6개 구역별 커버리지율 표시
전체 해역 커버리지 최적화 결과 확인
함정별 순찰 스케줄 표시

구현 완료:

✅ 5척 함정 배치 및 6구역 커버리지 시각화
✅ 구역별 커버리지율 표시 UI

향후 구현 예정:

🔲 AI 다함정 경로 최적화 알고리즘 연동
🔲 실시간 함정 위치 기반 동적 재배치
🔲 기상/해황 조건 반영 최적화

보완 필요:

⚠️ 현재 배치 결과는 샘플 데이터이며, AI 최적화 알고리즘 연동 후 실제 최적 배치로 교체 필요

SFR-09: Dark Vessel 탐지

메뉴 위치: 탐지/분석 > Dark Vessel 탐지 URL: /dark-vessel 접근 권한: ADMIN, OPERATOR, ANALYST

화면 설명: AIS(선박자동식별장치) 신호를 의도적으로 끈 의심 선박(Dark Vessel)을 탐지하는 화면입니다. 7척의 의심 선박과 5가지 행동 패턴 분석 결과를 확인할 수 있습니다.

주요 기능:

Dark Vessel 의심 선박 7척 목록 및 지도 표시
5가지 의심 패턴(AIS 소실, 속도 급변, 해역 이탈 등) 분석 결과
의심 선박 상세 프로필 및 이동 궤적 조회
위험도 등급별 분류 표시

구현 완료 (2026-04-17 기준):

✅ AI 분석 엔진(prediction) 5분 주기 실시간 탐지 결과 표시 — snpdb AIS 원천 데이터 기반
✅ Dark Vessel 11패턴 기반 0~100점 연속 점수 + 4단계 tier(CRITICAL≥70 / HIGH≥50 / WATCH≥30 / NONE)
✅ DarkDetailPanel — 선박 선택 시 ScoreBreakdown으로 P1~P11 각 패턴별 기여도 표시
✅ 지도 기반 실시간 위치 + tier별 색상 구분 (라이트/다크 모드 대응)
✅ 최근 1시간 / 중국 선박(MMSI 412*) 필터, MMSI/선박명/패턴 검색
✅ 특이운항 미니맵 (24h 궤적 + DARK/SPOOFING/TRANSSHIP/GEAR_VIOLATION/HIGH_RISK 구간 병합 하이라이트)

향후 구현 예정:

🔲 spoofing_score 산출 재설계 (중국 MID 412 선박 전원 0 수렴 이슈, BD-09 필터 + teleport 25kn 임계 재검토)
🔲 SAR(위성영상) 기반 탐지 연동
🔲 과거 이력 차트 (현재는 최근 24h 중심)

중국어선 분석

메뉴 위치: 탐지/분석 > 중국어선 분석 URL: /china-fishing 접근 권한: ADMIN, OPERATOR, ANALYST

화면 설명: 중국 어선의 불법조업 활동을 집중 분석하는 화면입니다. Dark Vessel 탐지(SFR-09) 및 어구 탐지(SFR-10) 결과를 중국 어선에 특화하여 종합 분석합니다.

주요 기능:

중국 어선 활동 현황 지도 표시
불법조업 의심 어선 목록 조회
해역별 중국 어선 밀집도 분석
시계열 활동 패턴 분석

구현 완료 (2026-04-17 기준):

✅ 3개 탭(AI 감시 대시보드 / 환적접촉탐지 / 어구·어망 판별) 전부 실데이터 연동 — /api/analysis/* 경유, MMSI prefix 412 고정
✅ 중국 선박 전체 분석 결과 실시간 그리드 (최근 1h, 위험도순 상위 200건)
✅ 특이운항 판별 — riskScore ≥ 40 상위 목록 + 선박 클릭 시 24h 궤적 미니맵 + 판별 구간 패널
✅ 해역별 통항량 + 안전도 분석 (종합 위험/안전 지수) + 위험도 도넛
✅ 자동탐지 결과(어구 판별 탭) row 클릭 시 상단 입력 폼 자동 프리필

향후 구현 예정:

🔲 관심영역 / VIIRS 위성영상 / 기상 예보 / VTS연계 (현재 "데모 데이터" 배지)
🔲 비허가 / 제재 / 관심 선박 탭 데이터 소스 연동 (현재 "준비중" 배지)
🔲 월별 집계 API 연동 (현재 통계 탭 "준비중")

SFR-10: 어망/어구 탐지

메뉴 위치: 탐지/분석 > 어망/어구 탐지 URL: /gear-detection 접근 권한: ADMIN, OPERATOR, ANALYST

화면 설명: 불법 어망 및 어구를 탐지하고 분류하는 화면입니다. 6건의 탐지 결과와 어구 종류를 식별하는 결정트리(Decision Tree) 분석 결과를 제공합니다.

주요 기능:

어구 탐지 6건 목록 및 지도 표시
어구 종류별 식별 결정트리 시각화
탐지 결과 상세 정보 (위치, 크기, 어구 유형, 위험도)
탐지 이미지 확인

구현 완료 (2026-04-17 기준):

✅ DAR-03 G-01~G-06 실시간 탐지 결과 — prediction 5분 주기 + 한중어업협정 906척 레지스트리(V029) 매칭 53%+
✅ G코드별 탐지: G-01(수역-어구 불일치) / G-02(금어기) / G-03(미등록 어구) / G-04(MMSI cycling) / G-05(고정어구 drift) / G-06(쌍끌이 — STRONG/PROBABLE/SUSPECT tier)
✅ 어구 그룹 지도 (ZONE_I~IV 폴리곤 + GeoJsonLayer + IconLayer) + 세부 필터 패널(해역/판정/위험도/모선 상태/허가/멤버 수) + localStorage 영속화
✅ GearDetailPanel — 후보 클릭 → 점수 근거(관측 7종 + 보정 3종) + 모선 확정/제외 버튼
✅ 24h 궤적 리플레이 (GearReplayController + TripsLayer, SPEED_FACTOR=2880, 24h→30s)
✅ 어구/어망 판별 화면 — 허가코드/어구물리특성/발견위치 입력 → 국적 판별(한/중/미확인) + 판별 근거·경고·AI 탐지 Rule·교차 검증 파이프라인

향후 구현 예정:

🔲 영상(CCTV/SAR) 기반 어구 자동 분류
🔲 한·중 어구 5종 구조 비교 이미지 라이브러리 확장

어구 정체성 충돌 (V030, 2026-04-17 추가)

메뉴 위치: 탐지/분석 > 어구 정체성 충돌 URL: /gear-collision 접근 권한: ADMIN, OPERATOR, ANALYST, FIELD, VIEWER (READ) / ADMIN, OPERATOR (UPDATE)

화면 설명: 동일한 어구 이름이 서로 다른 MMSI 로 같은 5분 사이클에 동시 송출되는 공존 케이스를 탐지해 어구 복제/스푸핑 증거로 기록·분류하는 화면입니다. 이전에는 "MMSI 교체"로 오해해 덮어쓰는 바람에 gear_correlation_scores_pkey 제약 충돌로 prediction 사이클 전체가 실패하던 이슈(PR #73)를 "공존 패턴"으로 재정의하면서 신설되었습니다.

주요 기능:

충돌 쌍(name, MMSI 저/고) 목록 + 공존 누적 횟수 + 양 위치 최대 거리 + severity tier
운영자 분류 워크플로우: OPEN → REVIEWED / CONFIRMED_ILLEGAL / FALSE_POSITIVE (REOPEN 가능)
severity 자동 산정: CRITICAL(거리≥50km OR 공존≥3회) / HIGH(거리≥10km OR 공존≥2회) / MEDIUM / LOW
상세 패널 — 양 MMSI 최근 궤적, 어구 이름 파싱(선박명+어구코드), 매칭된 모선(fleet_vessels)

구현 완료 (V030 / PR #73, 2026-04-17):

✅ gear_identity_collisions 테이블 + UNIQUE(name, mmsi_lo, mmsi_hi) 제약 + 5 인덱스
✅ prediction algorithms/gear_identity.py 순수함수 + fleet_tracker.track_gear_identity() 공존/교체 분기
✅ 백엔드 4 엔드포인트 /api/analysis/gear-collisions + GEAR_COLLISION_RESOLVE @Auditable
✅ 프론트 페이지 GearCollisionDetection.tsx (DataTable + KPI 5장 + SidePanel + 상태/심각도 필터)
✅ 이벤트 허브 연동 — HIGH/CRITICAL 은 prediction_events 에 자동 등록 (dedup 367분)

향후 구현 예정:

🔲 FALSE_POSITIVE 반복 쌍 자동 화이트리스트 (v2 학습 피드백 루프)
🔲 KPI 테이블 (prediction_stats_*) 에 severity 별 집계 반영

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

메뉴 위치: 단속/이력 > 단속/탐지 이력 URL: /enforcement-history 접근 권한: ADMIN, OPERATOR, ANALYST

화면 설명: 과거 단속 및 탐지 활동의 이력을 조회하고 관리하는 화면입니다. 6건의 단속 이력과 AI 매칭 검증 결과를 확인할 수 있습니다.

주요 기능:

단속 이력 6건 목록 조회 (날짜, 위치, 대상 선박, 결과)
AI 매칭 검증 — 탐지 결과와 실제 단속 결과 비교 분석
이력 상세 정보 조회 및 검색/필터
이력 데이터 엑셀 내보내기

구현 완료 (2026-04-17 기준):

✅ 실시간 이벤트 조회 — /api/events 페이징/필터/확인(ACK)/상태 변경
✅ 단속 이력 CRUD — /api/enforcement/records (GET/POST/PATCH) + ENF-yyyyMMdd-NNNN UID 자동 발급
✅ 이벤트 발생 → 확인 → 단속 등록 → 오탐 처리 워크플로우 (액션 버튼 4종)
✅ 모든 쓰기 액션 auth_audit_log 자동 기록 (ENFORCEMENT_CREATE / ENFORCEMENT_UPDATE / ACK_EVENT / UPDATE_EVENT_STATUS)
✅ KPI 카운트 (CRITICAL/HIGH/MEDIUM/LOW) + 엑셀 내보내기 + 출력
✅ 단속 완료 시 prediction_events.status 자동 RESOLVED 갱신

향후 구현 예정:

🔲 증거 파일(사진/영상) 업로드 서버 연동
🔲 AI 매칭 검증 정량 지표 (탐지↔단속 confusion matrix)

SFR-12: 종합 상황판 및 경보 현황판

종합 상황판

메뉴 위치: 모니터링 > 종합 상황판 URL: /dashboard 접근 권한: ADMIN, OPERATOR, ANALYST, FIELD, VIEWER

화면 설명: 시스템의 전체 운영 현황을 한눈에 파악할 수 있는 종합 대시보드입니다. KPI(핵심 성과 지표), 해역 위험도 히트맵, 이벤트 타임라인, 함정 배치 현황 등이 통합 표시됩니다.

주요 기능:

KPI 카드 (탐지 건수, 정확도, 대응 시간 등) 표시
해역 위험도 히트맵 축소판
최근 이벤트 타임라인
함정 배치 현황 요약
실시간 경보 알림 표시

구현 완료 (2026-04-17 기준):

✅ 실시간 KPI 카드 — /api/stats/kpi 연동, prediction 5분 주기 결과 기반
✅ 실시간 상황 타임라인 — 최근 prediction_events 스트림 (긴급/경고 카운트 실시간)
✅ 함정 배치 현황 + 경보 알림 + 순찰 현황 통합
✅ 라이트/다크 모드 반응형 (2026-04-17 PR #C 하드코딩 색상 제거)

향후 구현 예정:

🔲 WebSocket 기반 실시간 push (현재는 주기 polling)
🔲 맞춤형 대시보드 레이아웃 (드래그/리사이즈)

경보 현황판

메뉴 위치: 모니터링 > 경보 현황판 URL: /monitoring 접근 권한: ADMIN, OPERATOR, ANALYST

화면 설명: 현재 발생 중인 경보를 중심으로 긴급 상황을 모니터링하는 화면입니다. 경보 등급별 분류, 미처리 경보 목록, 경보 상세 정보를 확인할 수 있습니다.

주요 기능:

경보 등급별(긴급/경고/주의/정보) 현황 표시
미처리 경보 목록 및 상세 조회
경보 처리(확인/대응/종결) 워크플로우
경보 발생 이력 조회

구현 완료 (2026-04-17 기준):

✅ 실시간 경보 수신 — /api/events + /api/alerts 실 API 연동, prediction event_generator 4룰 기반
✅ 경보 등급별(CRITICAL/HIGH/MEDIUM/LOW) 현황 + KPI 카운트
✅ 경보 처리 워크플로우 — 확인(ACK) → 단속 등록 → 오탐 처리 (DB 저장 + auth_audit_log 기록)
✅ 시스템 상태 패널 (백엔드/AI 분석 엔진/DB 상태 실시간 표시, 30초 자동 갱신)

향후 구현 예정:

🔲 경보 자동 에스컬레이션 정책
🔲 경보 룰 커스터마이즈 UI

실시간 감시

메뉴 위치: 모니터링 > 실시간 감시 URL: /events 접근 권한: ADMIN, OPERATOR, ANALYST, FIELD

화면 설명: 실시간 지도(LiveMap)를 통해 해역 상황을 감시하는 화면입니다. 선박 위치, 이벤트 발생 지점, 함정 위치 등을 실시간으로 확인할 수 있습니다.

주요 기능:

실시간 지도 기반 선박/함정 위치 표시
이벤트 발생 시 지도 상 알림 표시
선박/이벤트 클릭 시 상세 정보 팝업
지도 확대/축소 및 해역 필터링

구현 완료 (2026-04-17 기준):

✅ 실시간 선박 위치 + 이벤트 마커 — prediction 5분 주기 분석 결과(vessel_analysis_results.lat/lon) + prediction_events 기반
✅ MapLibre GL 5 + deck.gl 9 GPU 렌더링 (40만척+ 지원)
✅ 위험도별 마커 opacity/radius 차등 (2026-04-17 ALERT_LEVEL_MARKER_OPACITY/RADIUS 헬퍼 적용)
✅ 이벤트 상세 패널 + 고위험 사건 실시간 알림 (LIVE 표시)

향후 구현 예정:

🔲 WebSocket 기반 실시간 push (현재는 주기 갱신)
🔲 SAR 위성영상 오버레이

해역 통제

메뉴 위치: 모니터링 > 해역 통제 URL: /map-control 접근 권한: ADMIN, OPERATOR

화면 설명: 특정 해역에 대한 통제 구역을 설정하고 관리하는 지도 기반 화면입니다. 통제 구역 진입 선박을 감시할 수 있습니다.

주요 기능:

통제 구역 지도 상 설정 및 표시
통제 구역 진입/이탈 선박 모니터링
통제 구역 관리 (생성/수정/삭제)

구현 완료:

✅ 지도 기반 해역 통제 구역 표시 UI
✅ 통제 구역 관리 인터페이스

향후 구현 예정:

🔲 실시간 선박 위치 기반 진입 감시
🔲 통제 구역 위반 자동 경보

보완 필요:

⚠️ 현재 통제 구역 데이터는 샘플이며, 실시간 연동 필요

SFR-13: 통계 및 성과 분석

메뉴 위치: 통계/보고 > 통계/성과 분석 URL: /statistics 접근 권한: ADMIN, OPERATOR, ANALYST

화면 설명: 시스템의 운영 성과를 통계적으로 분석하는 화면입니다. 월별 추이 그래프와 5개 KPI(탐지 정확도 93.2%, 오탐율 7.8% 등)를 제공합니다.

주요 기능:

월별 탐지/단속 추이 그래프
KPI 5개 지표 대시보드 (탐지 정확도, 오탐율, 대응 시간, 커버리지, 가동률)
기간별/해역별/유형별 필터링
통계 데이터 엑셀 내보내기 및 인쇄

구현 완료 (2026-04-17 기준):

✅ 실시간 통계 데이터 — /api/stats/monthly|daily|hourly 연동, prediction stats_aggregator 집계 결과 기반
✅ 월별/일별/시간별 추이 그래프 (ECharts, KST 기준)
✅ 해역별/유형별 필터링 + 엑셀 내보내기/인쇄
✅ 감사·보안 통계 — /api/admin/stats/audit|access|login (2026-04-17 AdminStatsService 계층 분리)

향후 구현 예정:

🔲 보고서 자동 생성 (PDF/HWP) — 현재는 UI만
🔲 맞춤형 지표 대시보드 설정

보고서 관리

메뉴 위치: 통계/보고 > 보고서 관리 URL: /reports 접근 권한: ADMIN, OPERATOR, ANALYST

화면 설명: 시스템 운영 보고서를 생성하고 관리하는 화면입니다. 정기/비정기 보고서를 작성하고 조회할 수 있습니다.

주요 기능:

보고서 목록 조회 및 검색
보고서 작성/수정/삭제
보고서 템플릿 관리

구현 완료:

✅ 보고서 관리 UI 및 목록/상세 화면

향후 구현 예정:

🔲 보고서 DB 연동
🔲 통계 데이터 자동 삽입
🔲 PDF 보고서 생성 및 다운로드

보완 필요:

⚠️ 현재 보고서 데이터는 샘플이며, DB 연동 필요

SFR-14: 외부 서비스 연계

메뉴 위치: 시스템 관리 > 외부 서비스 연계 URL: /external-service 접근 권한: ADMIN

화면 설명: 외부 시스템과의 API 연계 현황을 관리하는 화면입니다. 5개 외부 서비스(해양경찰청 통합시스템, GICOMS, 해양교통관제 등)의 API 연결 상태를 확인할 수 있습니다.

주요 기능:

외부 서비스 5건 연계 현황 대시보드
서비스별 API 연결 상태(정상/오류) 확인
API 호출 이력 및 오류 로그 조회
연계 설정 관리

구현 완료:

✅ 외부 서비스 5건 연계 현황 UI
✅ API 상태 표시 대시보드

향후 구현 예정:

🔲 실제 외부 API 연동 구현
🔲 API 헬스체크 자동화
🔲 장애 시 자동 알림 및 재연결

보완 필요:

⚠️ 현재 API 상태는 샘플 데이터이며, 실제 API 연동 후 실시간 상태 표시 필요

SFR-15: 모바일 서비스

메뉴 위치: 현장 대응 > 모바일 서비스 URL: /mobile-service 접근 권한: ADMIN, OPERATOR, FIELD

화면 설명: 현장 요원이 사용할 모바일 앱의 화면을 웹에서 미리보기(프리뷰)하는 시뮬레이션 화면입니다. 실제 모바일 앱이 아닌 웹 기반 시뮬레이션으로, 모바일 앱의 기능과 화면 구성을 확인할 수 있습니다.

주요 기능:

모바일 앱 화면 프리뷰 (웹 시뮬레이션)
주요 기능 화면 미리보기 (경보 수신, 위치 공유, 보고서 작성 등)
모바일 레이아웃 시뮬레이션

구현 완료:

✅ 모바일 앱 프리뷰 화면 (웹 시뮬레이션)
✅ 주요 기능별 화면 미리보기

향후 구현 예정:

🔲 실제 모바일 앱(iOS/Android) 개발
🔲 Push 알림 연동
🔲 오프라인 모드 지원

보완 필요:

⚠️ 현재는 웹 시뮬레이션으로, 실제 모바일 앱과 UI/UX가 다를 수 있음

SFR-16: 함정 Agent

메뉴 위치: 현장 대응 > 함정 Agent URL: /ship-agent 접근 권한: ADMIN, OPERATOR

화면 설명: 각 경비함에 설치되는 Agent 소프트웨어의 상태를 모니터링하는 화면입니다. 6건의 함정 Agent 상태(온라인/오프라인, 버전, 마지막 통신 시간 등)를 확인할 수 있습니다.

주요 기능:

함정 Agent 6건 상태 목록 조회
Agent별 온라인/오프라인 상태 확인
Agent 소프트웨어 버전 및 업데이트 현황
마지막 통신 시간 및 통신 이력 확인

구현 완료:

✅ 함정 Agent 6건 상태 모니터링 UI
✅ 상태별 시각적 표시 (온라인/오프라인)

향후 구현 예정:

🔲 실제 Agent 소프트웨어 개발 및 배포
🔲 Agent 실시간 통신 연동
🔲 Agent 원격 업데이트 기능

보완 필요:

⚠️ 현재 Agent 상태는 샘플 데이터이며, 실제 Agent SW 개발 후 연동 필요

SFR-17: AI 알림 발송

메뉴 위치: 현장 대응 > AI 알림 발송 URL: /ai-alert 접근 권한: ADMIN, OPERATOR

화면 설명: AI가 분석한 결과를 기반으로 관련 담당자에게 알림을 발송하는 화면입니다. 5건의 알림 전송 현황을 확인하고 새로운 알림을 발송할 수 있습니다.

주요 기능:

AI 알림 5건 전송 현황 조회
알림 유형별(긴급/일반/정보) 분류
알림 수신자 설정 및 발송
알림 전송 결과(성공/실패) 확인

구현 완료 (2026-04-17 기준):

✅ AI 알림 이력 실 API 조회 — /api/alerts 연동 (2026-04-17 AlertService 계층 분리)
✅ prediction alert_dispatcher 모듈이 event_generator 결과 기반으로 prediction_alerts 테이블에 자동 기록
✅ 알림 유형별 분류 + DataTable 검색/정렬/페이징/엑셀 내보내기

향후 구현 예정:

🔲 실제 SMS/푸시 발송 게이트웨이 연동 (현재는 DB 기록만)
🔲 알림 템플릿 엔진
🔲 수신자 그룹 관리

SFR-18/19: MLOps 플랫폼

메뉴 위치: 시스템 관리 > MLOps URL: /mlops 접근 권한: ADMIN

화면 설명: AI 모델의 전체 생명주기(실험, 학습, 배포, 모니터링)를 관리하는 MLOps 플랫폼 화면입니다. 7개 탭으로 구성되어 실험 관리, 모델 레지스트리, 배포 관리, API 서빙, LLMOps 등의 기능을 제공합니다.

주요 기능:

실험 관리 — AI 모델 학습 실험 기록 및 비교
모델 레지스트리 — 학습된 모델 버전 관리
배포 관리 — 모델 서빙 환경 배포 및 모니터링
API 서빙 — 모델 추론 API 관리
LLMOps — 대규모 언어 모델(LLM) 운영 관리
모니터링 — 모델 성능 드리프트 감시
파이프라인 — 자동화된 학습/배포 파이프라인 관리

구현 완료:

✅ MLOps 7탭 UI (실험/모델/배포/API/LLMOps/모니터링/파이프라인)
✅ 각 탭별 상세 관리 화면

향후 구현 예정:

🔲 실제 MLOps 인프라 연동 (MLflow, Kubeflow 등)
🔲 모델 학습/배포 파이프라인 자동화
🔲 모델 성능 모니터링 실시간 연동
🔲 LLM 운영 관리 기능 연동

보완 필요:

⚠️ 현재 모든 데이터는 샘플이며, MLOps 인프라 구축 후 실제 데이터로 교체 필요

SFR-20: AI 의사결정 지원

메뉴 위치: 시스템 관리 > AI 의사결정 지원 URL: /ai-assistant 접근 권한: ADMIN, OPERATOR, ANALYST

화면 설명: AI에게 질문하고 답변을 받을 수 있는 대화형(채팅) 인터페이스입니다. RAG(검색 증강 생성) 기술을 활용하여 관련 법령, 규정, 매뉴얼을 참조한 답변을 제공합니다.

주요 기능:

AI Q&A 채팅 UI (질문 입력 및 답변 표시)
RAG 기반 법령/규정 참조 답변 (참조 출처 표시)
대화 이력 관리
답변 품질 피드백 (유용함/유용하지 않음)

구현 완료:

✅ AI Q&A 채팅 UI
✅ RAG 법령 참조 답변 표시 화면

향후 구현 예정:

🔲 LLM(대규모 언어 모델) 백엔드 서버 연동
🔲 RAG 시스템 구축 (법령/규정/매뉴얼 벡터 DB)
🔲 답변 품질 개선을 위한 Fine-tuning

보완 필요:

⚠️ 현재 답변은 사전 작성된 샘플이며, LLM 백엔드 연동 후 실제 AI 답변으로 교체 필요

부록: 시스템 관리 메뉴

시스템 관리

메뉴 위치: 시스템 관리 > 시스템 관리 URL: /admin 접근 권한: ADMIN

화면 설명: 시스템 전반의 관리 기능을 제공하는 화면입니다. 서버 상태, 로그 조회, 사용자 관리 등 시스템 운영에 필요한 관리 기능을 포함합니다.

주요 기능:

시스템 상태 모니터링
사용자 계정 관리
시스템 로그 조회

구현 완료:

✅ 시스템 관리 기본 UI

향후 구현 예정:

🔲 실제 서버 상태 모니터링 연동
🔲 사용자 관리 DB 연동
🔲 시스템 로그 수집/조회 연동

부록: 역할(Role)별 접근 권한 요약

역할	설명	접근 가능 주요 메뉴
ADMIN	시스템 관리자	모든 메뉴 접근 가능
OPERATOR	운영 담당자	모니터링, 탐지/분석, 단속/이력, 통계/보고, 현장 대응, 일부 시스템 관리
ANALYST	분석 담당자	모니터링, 탐지/분석, 단속/이력, 통계/보고, AI 의사결정 지원
FIELD	현장 요원	종합 상황판, 실시간 감시, 순찰경로, 모바일 서비스
VIEWER	조회 전용	종합 상황판 (조회만 가능)

부록: 현재 시스템 상태 요약 (2026-04-17 기준)

항목	상태
UI 구현	모든 SFR 완료
백엔드 연동	15+ 화면 실 API 연동 완료 (Auth/RBAC/Audit/Events/Alerts/Enforcement/Stats/Analysis/Master 등 65+ API)
AI 분석 엔진 (prediction)	운영 중 — 5분 주기로 snpdb 분석 → kcgaidb 저장, 14 알고리즘 + DAR-03 G-01~G-06
데이터	실 AIS 원천(snpdb) + prediction 분석 결과 + 자체 DB 저장 데이터 (일부 화면은 여전히 Mock)
인증 체계	자체 ID/PW + JWT + 트리 기반 RBAC + 5회 실패 잠금 (SSO/GPKI 미연동)
실시간 기능	prediction 5분 주기 + 프론트 30초 폴링 (WebSocket push 미도입)
AI 모델	Dark Vessel 11패턴 / DAR-03 G-01~G-06 / 환적 5단계 / 경량 risk 등 14종 운영 중 (일부 모델은 Mock 계획 단계)
외부 시스템	snpdb / gc-signal-batch 연동 완료. 유관기관 OpenAPI(GICOMS/MTIS 등)는 미연동
디자인 시스템	`design-system.html` 쇼케이스 SSOT 전영역 준수, 라이트/다크 모드 완전 대응
다국어	한/영 alert/confirm/aria-label 전수 치환 완료 (JSX placeholder 35건은 후속 과제)
모바일 앱	웹 시뮬레이션만 제공 (PWA/네이티브 앱 미개발)

변경 이력

일자	내용
2026-04-06	초기 작성 (프론트엔드 프로토타입 v0.1.0 기준)
2026-04-17	헤더 + SFR-01/02/09/10/11/12/13/17 주요 섹션 업데이트. 실 API 연동 / prediction 운영 상태 / 2026-04-17 PR #A/#B/#C 반영

38 KiB Raw 고유링크 Blame 히스토리 Unescape Escape

SFR 요구사항별 화면 사용 가이드

문서 안내

시스템 현황 (2026-04-17 기준)

목차

SFR-01: 사용자 인증 및 접근 제어

로그인

권한 관리

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

환경설정

공지사항

이벤트 목록

SFR-03: 데이터 수집 허브

SFR-04: AI 모델 관리

SFR-05: 위험도 분석 지도

SFR-06: 단속 계획 및 경보

SFR-07: 단일함정 순찰경로 최적화

SFR-08: 다함정 경로 최적화

SFR-09: Dark Vessel 탐지

중국어선 분석

SFR-10: 어망/어구 탐지

어구 정체성 충돌 (V030, 2026-04-17 추가)

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

SFR-12: 종합 상황판 및 경보 현황판

종합 상황판

경보 현황판

실시간 감시

해역 통제

SFR-13: 통계 및 성과 분석

보고서 관리

SFR-14: 외부 서비스 연계

SFR-15: 모바일 서비스

SFR-16: 함정 Agent

SFR-17: AI 알림 발송

SFR-18/19: MLOps 플랫폼

SFR-20: AI 의사결정 지원

부록: 시스템 관리 메뉴

시스템 관리

부록: 역할(Role)별 접근 권한 요약

부록: 현재 시스템 상태 요약 (2026-04-17 기준)

변경 이력

38 KiB

Raw 고유링크 Blame 히스토리