kcg-ai-monitoring/docs/system-flow-guide.md

System Flow 뷰어 가이드

KCG AI Monitoring 시스템 워크플로우 플로우차트 뷰어 사용법.

개요

/system-flow.html은 snpdb 5분 원천 궤적 수집부터 prediction 분석, 이벤트 생성, 운영자 의사결정까지 시스템 전체 데이터 흐름을 노드/엣지로 시각화한 개발 단계 활용 페이지입니다.

• 115개 노드 + 133개 엣지 (manifest 현재 상태, meta.json 은 아직 v1.0.0/2026-04-07 로 미갱신)
• 메인 SPA(/)와 완전 분리된 별도 React 앱
• 메뉴/링크 노출 없음 — 직접 URL 접근만

⚠️ V030~V034 미반영 경고: 2026-04-17 V030 (algo.gear_identity_collision, storage.gear_identity_collisions, api.gear_collisions_*, ui.gear_collision, decision.gear_collision_resolve) + 2026-04-20 V032 (ui.illegal_fishing) + V033 (ui.transshipment_detection) + V034 Detection Model Registry (storage.detection_models, storage.detection_model_versions, storage.detection_model_run_outputs, storage.detection_model_metrics, infra.dag_executor, infra.shadow_runner, api.detection_models_*, ui.detection_model_management) 노드들이 아직 manifest 에 등록되지 않았다. 다음 /version 릴리즈 시 매니페스트 일괄 동기화 필요.

접근 URL

• 운영: https://kcg-ai-monitoring.gc-si.dev/system-flow.html
• 로컬 개발: http://localhost:5173/system-flow.html

별도 인증 없이 접근 가능 (개발 단계).

노드 ID 명명 규칙

<category>.<snake_case_name>

Category	Stage	예시
ingest	수집/캐시	ingest.snpdb_5min, ingest.vessel_store_cache
pipeline	파이프라인	pipeline.preprocess, pipeline.classify
algo	분석	algo.zone_classify, algo.risk_score
fleet	선단	fleet.parent_inference, fleet.gear_correlation
output	출력	output.event_generator, output.alert_dispatcher
storage	저장소	storage.prediction_events, storage.vessel_analysis_results
api	API	api.events_get, api.parent_inference_confirm
ui	화면	ui.dashboard, ui.parent_review
decision	의사결정	decision.parent_confirm, decision.enforcement_register
external	외부	external.iran_backend, external.redis

산출문서에서 노드 참조

마크다운 링크

모선 추론 후보는 [`fleet.parent_inference`](https://kcg-ai-monitoring.gc-si.dev/system-flow.html#node=fleet.parent_inference)
에서 생성되며, 운영자 확정은 [`decision.parent_confirm`](https://kcg-ai-monitoring.gc-si.dev/system-flow.html#node=decision.parent_confirm)
을 거쳐 [`storage.gear_group_parent_resolution`](https://kcg-ai-monitoring.gc-si.dev/system-flow.html#node=storage.gear_group_parent_resolution)
에 저장됩니다.

짧게 표기 (URL 생략)

이벤트 생성 단계(`output.event_generator`)에서 위반 카테고리를 포함한
`prediction_events` 레코드가 INSERT됩니다.

흐름 표기

snpdb 5분 → vessel_store → 7단계 파이프라인 → 14개 알고리즘 → 분석 결과
└─ `ingest.snpdb_5min` → `ingest.vessel_store_cache` → `pipeline.*` → `algo.*` → `storage.vessel_analysis_results`

UI 사용법

3단 레이아웃

• 좌측 (332px): 카테고리별로 그룹된 노드 목록 + 검색 결과
• 중앙 (가변): React Flow 캔버스 (노드/엣지 시각화)
• 우측 (392px): 선택된 노드/엣지의 상세 정보

헤더 컨트롤

• 검색: label, file, symbol, tags 통합 검색 (공백 무시)
• 단계 필터: 11개 stage 중 선택
• 메뉴 필터: 프론트 메뉴(대시보드/탐지/단속 등)별 필터
• 레이아웃 토글: 단계 기준 ⇄ 메뉴 기준 (노드 위치 자동 재배치)
• 상세 필터: kind/trigger/status 다중 선택 (드롭다운)

노드 시각화

• 색상: stage별 (수집=파랑, 분석=보라, 출력=주황 등)
• 모양: kind별 (algorithm=다이아몬드, decision=마름모, api=6각형 등)
• 노란 글로우: trigger=user_action 노드 (운영자 액션)
• 점선 테두리: status=planned 노드
• 반투명: status=deprecated 노드

엣지 종류

• 회색 (data): 일반 데이터 흐름
• 녹색 (trigger): 이벤트 트리거
• 노란 점선 (feedback): 피드백 루프 (예: label_input → 다음 사이클)

매니페스트 갱신 절차

노드 추가/수정 시

1. 해당 카테고리 JSON 파일 편집:
   • frontend/src/flow/manifest/01-ingest.json
   • frontend/src/flow/manifest/02-pipeline.json
   • ... 10-external.json
2. 새 엣지가 필요하면 frontend/src/flow/manifest/edges.json에 추가
3. 빌드 검증:

   cd frontend && npx tsc --noEmit && npx vite build
   

4. 로컬 확인 (http://localhost:5173/system-flow.html)

릴리즈 시 (/version 스킬과 동기화)

/version 스킬을 실행하면 Claude가 자동으로:

1. /version이 결정한 새 SemVer를 frontend/src/flow/manifest/meta.json에 반영
   • version: 새 버전 (예: "1.2.0")
   • updatedAt: 현재 ISO datetime
   • releaseDate: 오늘 날짜 (YYYY-MM-DD)
2. meta.json 변경분을 같은 커밋에 포함
3. main 머지 → CI/CD가 자동으로:
   • dist/system-flow.html 배포 (최신)
   • /deploy/kcg-ai-monitoring-archive/system-flow/v{version}_{date}/에 영구 스냅샷 보존

상세는 CLAUDE.md의 "/version 스킬 사후 처리" 섹션 참조.

노드 ID 안정성 정책

• 노드 ID는 변경 금지 — 산출문서가 ID로 참조하므로 깨지면 추적 불가
• 노드 제거 시: status: 'deprecated'로 마킹 (1~2 릴리즈 유지 후 삭제)
• 새 노드: status: 'implemented' (이미 구현) 또는 'planned' (계획)
• 부분 구현: status: 'partial'

서버 archive 위치

/deploy/kcg-ai-monitoring-archive/system-flow/
├── v1.0.0_2026-04-07/
│   ├── system-flow.html
│   ├── assets/
│   │   ├── systemFlow-XXX.js
│   │   ├── systemFlow-XXX.css
│   │   └── index-XXX.js
│   └── manifest/
│       ├── meta.json
│       ├── 01-ingest.json
│       └── ...
├── v1.1.0_2026-05-15/
└── v1.2.0_2026-06-22/

• nginx에서 노출되지 않음 (서버 로컬 영구 보존)
• 직접 접근 필요 시: ssh rocky-211 "ls /deploy/kcg-ai-monitoring-archive/system-flow/"
• 향후 특정 버전 임시 노출이 필요하면 nginx 설정 추가

향후 확장 가능

• 노드별 라이브 메트릭 (prediction 사이클 결과 fetch)
• mermaid 산출 (manifest → 정적 markdown 다이어그램)
• 노드 변경 이력 (git log 기반)
• 자동 검증 (file:symbol 실재 확인)
• 운영자 의사결정 시뮬레이션