gc/kcg-ai-monitoring
7
0
포크 0
코드 이슈 풀 리퀘스트 Actions 위키 활동
a8ce9a4ea9
kcg-ai-monitoring/docs/system-flow-guide.md
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

161 lines
6.4 KiB
Markdown
Raw Blame 히스토리

# 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 미반영 경고**: 2026-04-17 V030 로 추가된 GEAR_IDENTITY_COLLISION 파이프라인 (
> `algo.gear_identity_collision`, `storage.gear_identity_collisions`, `api.gear_collisions_*`,
> `ui.gear_collision`, `decision.gear_collision_resolve`) 노드가 아직 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` |
## 산출문서에서 노드 참조
### 마크다운 링크
```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