htlee
04d4b12c50
Phase 0-1/0-2/0-3 + Phase 1-1 V034 반영 + Phase 1-2 재개 포인트 명시. ### 변경 - architecture.md — 27→29 보호 경로, /illegal-fishing + /transshipment 라우트 추가 - sfr-traceability.md - Flyway V001~V030 → V001~V034 (34 마이그레이션) - Database 51 → 56 테이블 (V034 detection_model_* 5종 + 뷰 1, 반영 대기) - Prediction 섹션에 stage_runner 사이클 에러 경계 (Phase 0-1) 추가 - SFR-09: TransshipmentDetection(V033/PR #86) 페이지 추가 - SFR-10: IllegalFishingPattern(V032/PR #85) 페이지 추가 - 부록 A: 신규 화면 파일 경로 반영 - sfr-user-guide.md — SFR-10 하위에 "불법 조업 이벤트" + "환적 의심 탐지" 2개 신규 페이지 사용자 가이드 섹션 신설 - system-flow-guide.md — V030 미반영 경고를 V030~V034 노드 일괄 미반영으로 확장 (detection_models / detection_model_versions / detection_model_run_outputs / detection_model_metrics / dag_executor / shadow_runner / api.detection_models_* / ui.illegal_fishing / ui.transshipment_detection / ui.detection_model_management) - prediction-analysis.md — P1 권고 4건 중 3건 완료 표시 - ✅ 사이클 스테이지 에러 경계 (PR #83) - 🟡 임계값 외부화 (V034 스키마 머지, Phase 1-2 대기) - ✅ ILLEGAL_FISHING_PATTERN 전용 페이지 (PR #85) - ✅ 환적 전용 페이지 (PR #86) - 변경 이력에 2026-04-20 행 추가 ### 범위 밖 - memory/* 는 세션 로컬 경로, 저장소 외 - prediction/backend 코드 변경 없음 — 문서만
166 lines
6.8 KiB
Markdown
166 lines
6.8 KiB
Markdown
# 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` |
|
|
|
|
## 산출문서에서 노드 참조
|
|
|
|
### 마크다운 링크
|
|
|
|
```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 실재 확인)
|
|
- 운영자 의사결정 시뮬레이션
|