gc/kcg-ai-monitoring
7
0
포크 0
코드 이슈 풀 리퀘스트 Actions 위키 활동
9c74459acc
kcg-ai-monitoring/docs/system-flow-guide.md
htlee a6f6003c5f feat: System Flow 뷰어 추가 (system-flow.html) — 102 노드, 133 엣지 
iran 프로젝트의 gear-parent-flow 패턴을 차용하여 시스템 전체 데이터 흐름을
노드/엣지로 시각화하는 별도 React 앱 추가. 메인 SPA와 완전 분리.

## 인프라
- @xyflow/react 추가
- frontend/system-flow.html (별도 entry HTML)
- frontend/src/systemFlowMain.tsx (React entry)
- vite.config.ts: rollupOptions.input에 systemFlow 추가
- 빌드 산출물: dist/system-flow.html + dist/assets/systemFlow-*.js (231kB, 메인과 분리)

## 매니페스트 (frontend/src/flow/manifest/)
카테고리별 JSON 분할 + 빌드 시 병합:
- 01-ingest.json (6) — snpdb, vessel_store, refresh
- 02-pipeline.json (7) — 7단계 분류 파이프라인
- 03-algorithms.json (12) — zone/dark/spoofing/risk/transship 등
- 04-fleet.json (9) — fleet_tracker, polygon_builder, gear_correlation, parent_inference
- 05-output.json (8) — event/violation/kpi/stats/alert/redis
- 06-storage.json (18) — 핵심 DB 테이블
- 07-backend.json (15) — Spring Boot 컨트롤러 + endpoint
- 08-frontend.json (17) — 프론트 화면 (menu 매핑 포함)
- 09-decision.json (8) — 운영자 의사결정 액션
- 10-external.json (2) — iran, redis
- edges.json (133) — data/trigger/feedback 분류

## 뷰어 컴포넌트
- SystemFlowViewer.tsx — 3단 레이아웃 + React Flow + 상태 관리
- components/FilterBar.tsx — 검색/단계/메뉴/상세필터 + 레이아웃 토글
- components/NodeListSidebar.tsx — 좌측 카테고리별 노드 리스트
- components/NodeDetailPanel.tsx — 우측 선택 정보 + incoming/outgoing 흐름
- components/nodeShapes.ts — kind별 모양/색상 헬퍼
- SystemFlowViewer.css — 전용 다크 테마 스타일

## 기능
- stage(단계) ⇄ menu(메뉴) 두 가지 그룹화 토글
- 통합 검색 (label/file/symbol/tag)
- 다중 필터 (kind/trigger/status)
- 노드 모양: kind별 (algorithm=다이아몬드, decision=마름모, api=6각형 등)
- 엣지 색상: data=회색, trigger=녹색, feedback=노란 점선
- 딥링크: /system-flow.html#node=<id> (산출문서에서 직접 참조)

## /version 스킬 통합
- CLAUDE.md에 "/version 스킬 사후 처리" 섹션 추가
  Claude가 /version 호출 후 자동으로 manifest.meta version/updatedAt/releaseDate 갱신
- .gitea/workflows/deploy.yml에 archive 보존 단계 추가
  /deploy/kcg-ai-monitoring-archive/system-flow/v{version}_{date}/ 영구 누적
  (nginx 노출 X, 서버 로컬 보존)
- docs/system-flow-guide.md 작성 (URL, 노드 ID 명명, 산출문서 참조법, 갱신 절차)

## URL
- 운영: https://kcg-ai-monitoring.gc-si.dev/system-flow.html
- 메인 SPA에 링크 노출 없음 (개발 단계 페이지)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-04-07 17:10:22 +09:00

156 lines
6.0 KiB
Markdown
Raw Blame 히스토리

# 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 실재 확인)
- 운영자 의사결정 시뮬레이션
Reference in New Issue View Git Blame Copy Permalink