kcg-ai-monitoring/docs/page-workflow.md
htlee c0ce01eaf6 chore: 팀 워크플로우 기반 초기 프로젝트 구성
KCG AI 기반 불법조업 탐지·차단 플랫폼 프론트엔드.
React 19 + TypeScript 5.9 + Vite 8 + MapLibre + deck.gl + Zustand + Tailwind CSS.
SFR 20개 전체 UI 구현 완료, 백엔드 연동 대기.

- npm + Nexus 프록시 레지스트리 설정
- 팀 워크플로우 v1.6.1 부트스트랩 파일 배치
- .githooks (commit-msg, post-checkout)
- package.json name: kcg-ai-monitoring v0.1.0

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-04-06 14:11:29 +09:00

25 KiB

페이지 역할표 및 업무 파이프라인

최초 작성일: 2026-04-06
마지막 업데이트: 2026-04-06
대상: kcg-ai-monitoring 프론트엔드 31개 페이지


0. 공통 아키텍처

디렉토리 구조

모든 페이지는 src/features/ 아래 도메인별 디렉토리에 배치되어 있다.

src/features/
  admin/          AccessControl, AdminPanel, DataHub, NoticeManagement, SystemConfig
  ai-operations/  AIAssistant, AIModelManagement, MLOpsPage
  auth/           LoginPage
  dashboard/      Dashboard
  detection/      ChinaFishing, DarkVesselDetection, GearDetection, GearIdentification
  enforcement/    EnforcementHistory, EventList
  field-ops/      AIAlert, MobileService, ShipAgent
  monitoring/     MonitoringDashboard
  patrol/         FleetOptimization, PatrolRoute
  risk-assessment/ EnforcementPlan, RiskMap
  statistics/     ExternalService, ReportManagement, Statistics
  surveillance/   LiveMapView, MapControl
  vessel/         TransferDetection, VesselDetail

데이터 흐름

모든 공유 데이터는 mock -> store -> page 패턴으로 흐른다.

src/data/mock/*.ts  -->  src/stores/*Store.ts  -->  src/features/*/*.tsx
  (7개 공유 모듈)        (7개 Zustand 스토어)       (16개 페이지가 스토어 소비)
  • 스토어는 load() 호출 시 import()로 mock 데이터를 lazy loading
  • 도메인 특화 데이터는 페이지 내 인라인으로 유지 (MLOps, MapControl, DataHub 등)
  • 상세 매핑은 docs/data-sharing-analysis.md 참조

지도 렌더링

지도가 필요한 11개 페이지는 공통 src/lib/map/ 인프라를 사용한다.

  • deck.gl 기반 렌더링 (BaseMap.tsx)
  • useMapLayers 훅: 페이지별 동적 레이어 구성
  • STATIC_LAYERS: EEZ/KDLZ 등 정적 레이어를 상수로 분리하여 zero rerender 보장
  • 사용 페이지: Dashboard, LiveMapView, MapControl, EnforcementPlan, PatrolRoute, FleetOptimization, GearDetection, DarkVesselDetection, RiskMap, VesselDetail, MobileService

다국어 (i18n)

  • react-i18next 기반, 24개 페이지 + MainLayout + LoginPage에 i18n 적용
  • 지원 언어: 한국어 (ko), 영어 (en)
  • 페이지 타이틀, 주요 UI 라벨이 번역 키로 관리됨

테마

  • settingsStore에서 dark/light 테마 전환 지원
  • 기본값: dark (해양 감시 시스템 특성상)
  • localStorage에 선택 유지, CSS 클래스 토글 방식

1. 31개 페이지 역할표

1.1 인증/관리 (4개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
SFR-01 LoginPage /login 전체 SSO/GPKI/비밀번호 인증, 5회 실패 잠금 ID/PW, 인증 방식 선택 세션 발급, 역할 부여 - 모든 페이지 (인증 게이트)
SFR-01 AccessControl /access-control 관리자 RBAC 권한 관리, 감사 로그 역할/사용자/권한 설정 권한 변경, 감사 기록 LoginPage 전체 시스템 접근 제어
SFR-02 SystemConfig /system-config 관리자 공통코드 기준정보 관리 (해역52/어종578/어업59/선박186) 코드 검색/필터 코드 조회, 설정 변경 AccessControl 탐지/분석 엔진 기준데이터
SFR-02 NoticeManagement /notices 관리자 시스템 공지(배너/팝업/토스트), 역할별 대상 설정 공지 작성, 기간/대상 설정 배너/팝업 노출 AccessControl 모든 페이지 (NotificationBanner)

1.2 데이터 수집/연계 (1개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
SFR-03 DataHub /data-hub 관리자 통합데이터 허브 — 선박신호 수신 현황 히트맵, 연계 채널 모니터링 수신 소스 선택 수신률 조회, 연계 상태 확인 외부 센서 (VTS, AIS, V-PASS 등) 탐지 파이프라인 전체

1.3 AI 모델/운영 (3개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
SFR-04 AIModelManagement /ai-model 분석관 모델 레지스트리, 탐지 규칙, 피처 엔지니어링, 학습 파이프라인, 7대 탐지엔진 모델 버전/규칙/피처 설정 모델 배포, 성능 리포트 DataHub (학습 데이터) DarkVessel, GearDetection, TransferDetection 등 탐지 엔진
SFR-18/19 MLOpsPage /mlops 분석관/관리자 MLOps/LLMOps 운영 대시보드 (실험, 배포, API Playground, LLM 테스트) 실험 템플릿, HPS 설정 실험 결과, 모델 배포 AIModelManagement AIAssistant, 탐지 엔진
SFR-20 AIAssistant /ai-assistant 상황실/분석관 자연어 Q&A 의사결정 지원 (법령 조회, 대응 절차 안내) 자연어 질의 답변 + 법령 참조 MLOpsPage (LLM 모델) 작전 의사결정

1.4 탐지 (4개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
SFR-09 DarkVesselDetection /dark-vessel 분석관 AIS 조작/위장/Dark Vessel 패턴 탐지 (6가지 패턴), 지도+테이블 AIS 데이터 스트림 의심 선박 목록, 위험도, 라벨 분류 DataHub (AIS/레이더) RiskMap, LiveMapView, EventList
SFR-10 GearDetection /gear-detection 분석관 불법 어망/어구 탐지 및 관리, 허가 상태 판정 어구 센서/영상 어구 목록, 불법 판정 결과 DataHub (센서) RiskMap, EnforcementPlan
- GearIdentification features/detection/ 분석관 어구 국적 판별 (중국/한국/불확실), GB/T 5147 기준 어구 물리적 특성 입력 판별 결과 (국적, 신뢰도, 경보등급) GearDetection EnforcementHistory
- ChinaFishing /china-fishing 분석관/상황실 중국어선 통합 감시 (센서 카운터, 특이운항, 월별 통계, 환적 탐지, VTS 연계) 센서 데이터 융합 감시 현황, 환적 의심 목록 DataHub, DarkVessel RiskMap, EnforcementPlan

1.5 환적 탐지 (1개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
- TransferDetection features/vessel/ 분석관 선박 간 근접 접촉 및 환적 의심 행위 분석 (거리/시간/속도 기준) AIS 궤적 분석 환적 이벤트 목록, 의심도 점수 DataHub, DarkVessel EventList, EnforcementPlan

1.6 위험도 평가/계획 (2개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
SFR-05 RiskMap /risk-map 분석관/상황실 격자 기반 불법조업 위험도 지도 + MTIS 해양사고 통계 연계 탐지 결과, 사고 통계 히트맵, 해역별 위험도, 사고 통계 차트 DarkVessel, GearDetection, ChinaFishing EnforcementPlan, PatrolRoute
SFR-06 EnforcementPlan /enforcement-plan 상황실 단속 계획 수립, 경보 연계, 우선지역 예보 위험도 데이터, 가용 함정 단속 계획 테이블, 지도 표시 RiskMap PatrolRoute, FleetOptimization

1.7 순찰/함대 (2개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
SFR-07 PatrolRoute /patrol-route 상황실 AI 단일 함정 순찰 경로 추천 (웨이포인트, 거리/시간/연료 산출) 함정 선택, 구역 조건 추천 경로, 웨이포인트 목록 EnforcementPlan, RiskMap 함정 출동 (ShipAgent)
SFR-08 FleetOptimization /fleet-optimization 상황실 다함정 협력형 경로 최적화 (커버리지 시뮬레이션, 승인 워크플로) 함대 목록, 구역 조건 최적화 결과, 커버리지 비교 EnforcementPlan, PatrolRoute 함정 출동 (ShipAgent)

1.8 감시/지도 (2개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
- LiveMapView /events 상황실 실시간 해역 감시 지도 (AIS 선박 + 이벤트 경보 + 아군 함정) 실시간 AIS/이벤트 스트림 지도 마커, 이벤트 카드, 위험도 바 탐지 엔진 전체 EventList, AIAlert
- MapControl /map-control 상황실/관리자 해역 통제 관리 (해상사격 훈련구역도 No.462, 군/해경 구역) 구역 데이터 훈련구역 지도, 상태 테이블 국립해양조사원 데이터 LiveMapView (레이어)

1.9 대시보드/모니터링 (2개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
- Dashboard /dashboard 전체 종합 상황판 (KPI, 타임라인, 위험선박 TOP8, 함정 현황, 해역 위험도, 시간대별 탐지 추이) 전 시스템 데이터 집계 한눈에 보는 현황 탐지/순찰/이벤트 전체 각 상세 페이지로 드릴다운
SFR-12 MonitoringDashboard /monitoring 상황실 모니터링 및 경보 현황판 (KPI, 24시간 추이, 탐지 유형 분포, 실시간 이벤트) 경보/탐지 데이터 경보 현황 대시보드 탐지 엔진, EventList AIAlert, EnforcementPlan

1.10 이벤트/이력 (2개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
- EventList /event-list 상황실/분석관 이벤트 전체 목록 (검색/정렬/페이징/엑셀/출력), 15건+ 이벤트 필터 조건 이벤트 테이블, 엑셀 내보내기 탐지 엔진, LiveMapView EnforcementHistory, ReportManagement
SFR-11 EnforcementHistory /enforcement-history 분석관 단속/탐지 이력 관리 (AI 매칭 검증 포함) 검색 조건 이력 테이블, AI 일치 여부 EventList, 현장 단속 ReportManagement, Statistics

1.11 현장 대응 (3개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
SFR-15 MobileService /mobile-service 현장 단속요원 모바일 앱 프리뷰 (위험도/의심선박/경로추천/경보, 푸시 설정) 모바일 위치, 푸시 설정 경보 수신, 지도 조회 AIAlert, LiveMapView 현장 단속 수행
SFR-16 ShipAgent /ship-agent 현장 단속요원 함정용 Agent 관리 (배포/동기화 상태, 버전 관리) 함정 Agent 설치 Agent 상태 조회, 동기화 PatrolRoute, FleetOptimization 현장 단속 수행
SFR-17 AIAlert /ai-alert 상황실/현장 AI 탐지 알림 자동 발송 (함정/관제요원 대상, 탐지시각/좌표/유형/신뢰도 포함) 탐지 이벤트 트리거 알림 발송, 수신 확인 MonitoringDashboard, EventList MobileService, ShipAgent

1.12 통계/외부연계/보고 (3개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
SFR-13 Statistics /statistics 상황실/분석관 통계/지표/성과 분석 (월별 추이, 위반유형, KPI 달성률) 기간/유형 필터 차트, KPI 테이블, 보고서 EnforcementHistory, EventList 외부 보고, 전략 수립
SFR-14 ExternalService /external-service 관리자/외부 외부 서비스 제공 (해수부/수협/기상청 API/파일 연계, 비식별/익명화 정책) 서비스 설정 API 호출 수, 연계 상태 Statistics, 탐지 결과 외부기관
- ReportManagement /reports 분석관/상황실 증거 관리 및 보고서 생성 (사건별 자동 패키징) 사건 선택, 증거 파일 업로드 보고서 PDF, 증거 패키지 EnforcementHistory, EventList 검찰/외부기관

1.13 선박 상세 (1개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
- VesselDetail /vessel/:id 분석관/상황실 선박 상세 정보 (AIS 데이터, 항적, 입항 이력, 선원 정보, 비허가 선박 목록) 선박 ID/MMSI 상세 프로필, 지도 항적 LiveMapView, DarkVessel, EventList EnforcementPlan, ReportManagement

1.14 시스템 관리 (1개)

SFR 화면명 경로 사용자 핵심 기능 입력 출력/액션 업스트림 다운스트림
- AdminPanel /admin 관리자 시스템 인프라 관리 (서버 상태, CPU/메모리/디스크 모니터링) - 서버 상태 대시보드 - 시스템 안정성 보장

2. 업무 파이프라인 (4개)

2.1 탐지 파이프라인

불법 조업을 탐지하고 실시간 감시하여 현장 작전까지 연결하는 핵심 파이프라인.

AIS/레이더/위성 신호
      │
      ▼
  ┌─────────┐
  │ DataHub │  ← 통합데이터 허브 (VTS, AIS, V-PASS, E-Nav 수집)
  └────┬────┘
       │
       ▼
  ┌──────────────────────────────────────────────┐
  │ AI 탐지 엔진 (AIModelManagement 관리)        │
  │                                              │
  │  DarkVesselDetection ─ AIS 조작/위장/소실    │
  │  GearDetection ─────── 불법 어구 탐지        │
  │  ChinaFishing ──────── 중국어선 통합 감시    │
  │  TransferDetection ─── 환적 행위 탐지        │
  │  GearIdentification ── 어구 국적 판별        │
  └──────────────┬───────────────────────────────┘
                 │
                 ▼
  ┌──────────┐      ┌───────────────────┐
  │ RiskMap  │─────▶│ LiveMapView       │ ← 실시간 지도 감시
  └────┬─────┘      │ MonitoringDashboard│ ← 경보 현황판
       │            └───────────────────┘
       ▼
  ┌──────────────────┐
  │ EnforcementPlan  │ ← 단속 우선지역 예보
  └────────┬─────────┘
           │
           ▼
  ┌──────────────┐      ┌───────────────────┐
  │ PatrolRoute  │─────▶│ FleetOptimization │ ← 다함정 최적화
  └──────┬───────┘      └─────────┬─────────┘
         │                        │
         ▼                        ▼
  ┌──────────┐
  │ AIAlert  │ ← 함정/관제 자동 알림 발송
  └────┬─────┘
       │
       ▼
    현장 작전 (MobileService, ShipAgent)

2.2 대응 파이프라인

AI 알림 수신 후 현장 단속, 이력 기록, 보고서 생성까지의 대응 프로세스.

  ┌──────────┐
  │ AIAlert  │ ← AI 탐지 알림 자동 발송
  └────┬─────┘
       │
       ▼
  ┌──────────────────────────────────┐
  │ 현장 대응                        │
  │                                  │
  │  MobileService ── 모바일 경보 수신│
  │  ShipAgent ────── 함정 Agent 연동 │
  └──────────────┬───────────────────┘
                 │
                 ▼
          현장 단속 수행
          (정선/검문/나포/퇴거)
                 │
                 ▼
  ┌──────────────────────┐
  │ EnforcementHistory   │ ← 단속 이력 등록, AI 매칭 검증
  └──────────┬───────────┘
             │
             ▼
  ┌──────────────────────┐
  │ ReportManagement     │ ← 증거 패키징, 보고서 생성
  └──────────┬───────────┘
             │
             ▼
    검찰/외부기관 (ExternalService 통해 연계)

2.3 분석 파이프라인

축적된 데이터를 분석하여 전략적 의사결정을 지원하는 파이프라인.

  ┌─────────────┐
  │ Statistics  │ ← 월별 추이, 위반유형, KPI 달성률
  └──────┬──────┘
         │
         ▼
  ┌──────────┐
  │ RiskMap  │ ← 격자 위험도 + MTIS 해양사고 통계
  └────┬─────┘
       │
       ▼
  ┌──────────────┐
  │ VesselDetail │ ← 개별 선박 심층 분석 (항적, 이력)
  └──────┬───────┘
         │
         ▼
  ┌──────────────┐
  │ AIAssistant  │ ← 자연어 Q&A (법령 조회, 대응 절차)
  └──────┬───────┘
         │
         ▼
    전략 수립 (순찰 패턴, 탐지 규칙 조정)

2.4 관리 파이프라인

시스템 접근 제어, 환경 설정, 데이터 관리, 인프라 모니터링 파이프라인.

  ┌────────────────┐
  │ AccessControl  │ ← RBAC 역할/권한 설정
  └───────┬────────┘
          │
          ▼
  ┌────────────┐
  │ LoginPage  │ ← SSO/GPKI/비밀번호 인증
  └──────┬─────┘
         │
         ▼
  ┌──────────────────────────────────────┐
  │ 시스템 설정/관리                      │
  │                                      │
  │  SystemConfig ──── 공통코드/환경설정  │
  │  NoticeManagement ── 공지/배너/팝업  │
  │  DataHub ────────── 데이터 수집 관리  │
  │  AdminPanel ────── 서버/인프라 모니터 │
  └──────────────────────────────────────┘

3. 사용자 역할별 페이지 접근 매트릭스

시스템에 정의된 5개 역할(LoginPage의 DEMO_ACCOUNTS 및 AccessControl의 ROLES 기반)에 대한 페이지 접근 권한.

3.1 역할 정의

역할 코드 설명 인원(시뮬)
시스템 관리자 ADMIN 전체 시스템 관리 권한 3명
상황실 운영자 OPERATOR 상황판, 통계, 경보 운영 12명
분석 담당자 ANALYST AI 모델, 통계, 항적 분석 8명
현장 단속요원 FIELD 함정 Agent, 모바일 대응 45명
유관기관 열람자 VIEWER 공유 대시보드 열람 6명

3.2 접근 매트릭스

페이지 ADMIN OPERATOR ANALYST FIELD VIEWER
인증/관리
LoginPage O O O O O
AccessControl O - - - -
SystemConfig O - - - -
NoticeManagement O - - - -
AdminPanel O - - - -
데이터/AI
DataHub O - - - -
AIModelManagement O - O - -
MLOpsPage O - O - -
AIAssistant O O O - -
탐지
DarkVesselDetection O - O - -
GearDetection O - O - -
ChinaFishing O O O - -
TransferDetection O - O - -
위험도/계획
RiskMap O O O - -
EnforcementPlan O O - - -
순찰
PatrolRoute O O - - -
FleetOptimization O O - - -
감시/지도
LiveMapView O O O - -
MapControl O O - - -
대시보드
Dashboard O O O O O
MonitoringDashboard O O - - -
이벤트/이력
EventList O O O O -
EnforcementHistory O - O - -
현장 대응
MobileService O - - O -
ShipAgent O - - O -
AIAlert O O - O -
통계/보고
Statistics O O O - -
ExternalService O - - - O
ReportManagement O O O - -
선박 상세
VesselDetail O O O - -

3.3 역할별 요약

역할 접근 가능 페이지 페이지 수
시스템 관리자 (ADMIN) 전체 페이지 31
상황실 운영자 (OPERATOR) Dashboard, MonitoringDashboard, LiveMapView, MapControl, EventList, EnforcementPlan, PatrolRoute, FleetOptimization, ChinaFishing, RiskMap, Statistics, ReportManagement, AIAssistant, AIAlert, VesselDetail 15
분석 담당자 (ANALYST) Dashboard, DarkVesselDetection, GearDetection, ChinaFishing, TransferDetection, RiskMap, LiveMapView, EventList, EnforcementHistory, Statistics, ReportManagement, VesselDetail, AIAssistant, AIModelManagement, MLOpsPage 15
현장 단속요원 (FIELD) Dashboard, MobileService, ShipAgent, AIAlert, EventList 5
유관기관 열람자 (VIEWER) Dashboard, ExternalService 2

4. 페이지 간 데이터 흐름 요약

                                ┌──────────────────┐
                                │    LoginPage     │
                                │  (인증 게이트)    │
                                └────────┬─────────┘
                                         │
                    ┌────────────────────┬┴──────────────────┐
                    ▼                    ▼                    ▼
            ┌──────────────┐   ┌─────────────────┐   ┌─────────────┐
            │ 관리 파이프라인│   │ 탐지 파이프라인   │   │ 현장 대응    │
            │              │   │                 │   │             │
            │ AccessControl│   │ DataHub         │   │ MobileSvc   │
            │ SystemConfig │   │    ↓            │   │ ShipAgent   │
            │ NoticeManage │   │ AI탐지엔진      │   │ AIAlert     │
            │ DataHub      │   │  (DV/Gear/CN/TR)│   └──────┬──────┘
            │ AdminPanel   │   │    ↓            │          │
            └──────────────┘   │ RiskMap         │          │
                               │    ↓            │          ▼
                               │ EnforcementPlan │   ┌──────────────┐
                               │    ↓            │   │ 대응 파이프라인│
                               │ PatrolRoute     │   │              │
                               │ FleetOptim      │   │ Enforcement  │
                               │    ↓            │   │  History     │
                               │ LiveMapView     │   │ ReportManage │
                               │ Monitoring      │   │ ExternalSvc  │
                               └────────┬────────┘   └──────────────┘
                                        │
                                        ▼
                               ┌─────────────────┐
                               │ 분석 파이프라인   │
                               │                 │
                               │ Statistics      │
                               │ VesselDetail    │
                               │ AIAssistant     │
                               └─────────────────┘

5. 미할당 SFR 참고

현재 라우트에서 확인되는 SFR 번호 기준, 아래 기능은 기존 페이지에 통합되어 있다:

  • Dashboard: SFR 번호 미부여, 종합 상황판 (기존 유지)
  • LiveMapView: SFR 번호 미부여, 실시간 감시 지도
  • EventList: SFR-02 공통 컴포넌트 적용 대상으로 분류
  • MapControl: SFR 번호 미부여, 해역 통제 관리
  • VesselDetail: SFR 번호 미부여, 선박 상세
  • ReportManagement: SFR 번호 미부여, 증거/보고서 관리
  • AdminPanel: SFR 번호 미부여, 인프라 관리
  • GearIdentification: ChinaFishing 내 서브 컴포넌트