# System Flow 뷰어 가이드

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

## 개요

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

- 102개 노드 + 133개 엣지 (v1.0.0 기준)
- 메인 SPA(`/`)와 완전 분리된 별도 React 앱
- 메뉴/링크 노출 없음 — 직접 URL 접근만

## 접근 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` |

## 산출문서에서 노드 참조

### 마크다운 링크

```markdown
모선 추론 후보는 [`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 생략)

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

### 흐름 표기

```markdown
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. 빌드 검증:
   ```bash
   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 실재 확인)
- 운영자 의사결정 시뮬레이션