htlee
a6f6003c5f
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>
129 lines
5.6 KiB
Markdown
129 lines
5.6 KiB
Markdown
# KCG AI Monitoring (모노레포)
|
|
|
|
해양경찰청 AI 기반 불법어선 탐지 및 단속 지원 플랫폼
|
|
|
|
## 모노레포 구조
|
|
|
|
```
|
|
kcg-ai-monitoring/
|
|
├── frontend/ # React 19 + TypeScript + Vite (UI)
|
|
├── backend/ # Spring Boot 3.x + Java 21 (인증/권한/감사 + 분석 API)
|
|
├── prediction/ # Python 3.9 + FastAPI (AIS 분석 엔진, 5분 주기)
|
|
├── database/ # PostgreSQL 마이그레이션 (Flyway V001~V013)
|
|
│ └── migration/
|
|
├── deploy/ # 배포 가이드 + 서버 설정 문서
|
|
├── docs/ # 프로젝트 문서 (SFR, 아키텍처)
|
|
├── .gitea/ # Gitea Actions CI/CD (프론트 자동배포)
|
|
├── .claude/ # Claude Code 워크플로우
|
|
├── .githooks/ # Git hooks
|
|
└── Makefile # 통합 dev/build 명령
|
|
```
|
|
|
|
## 시스템 구성
|
|
|
|
```
|
|
[Frontend Vite :5173] ──→ [Backend Spring :8080] ──→ [PostgreSQL kcgaidb]
|
|
↑ write
|
|
[Prediction FastAPI :8001] ──────┘ (5분 주기 분석 결과 저장)
|
|
↑ read ↑ read
|
|
[SNPDB PostgreSQL] (AIS 원본) [Iran Backend] (레거시 프록시, 선택)
|
|
```
|
|
|
|
- **자체 백엔드**: 인증/권한/감사로그/관리자 + 운영자 의사결정 (확정/제외/학습)
|
|
- **iran 백엔드 프록시**: 분석 결과 read-only 참조 (vessel_analysis, group_polygons, correlations)
|
|
- **신규 DB (kcgaidb)**: 자체 생산 데이터만 저장, prediction 분석 테이블은 미복사
|
|
|
|
## 명령어
|
|
|
|
```bash
|
|
make install # 전체 의존성 설치
|
|
make dev # 프론트 + 백엔드 동시 실행
|
|
make dev-all # 프론트 + 백엔드 + prediction 동시 실행
|
|
make dev-frontend # 프론트만
|
|
make dev-backend # 백엔드만
|
|
make dev-prediction # prediction 분석 엔진만 (FastAPI :8001)
|
|
make build # 전체 빌드
|
|
make lint # 프론트 lint
|
|
make format # 프론트 prettier
|
|
```
|
|
|
|
## 기술 스택
|
|
|
|
### Frontend (`frontend/`)
|
|
- React 19, TypeScript 5.9, Vite 8
|
|
- Tailwind CSS 4 + CVA
|
|
- MapLibre GL 5 + deck.gl 9 (지도)
|
|
- ECharts 6 (차트)
|
|
- Zustand 5 (상태관리)
|
|
- i18next (ko/en)
|
|
- React Router 7
|
|
- ESLint 10 + Prettier
|
|
|
|
### Prediction (`prediction/`) — 분석 엔진
|
|
- Python 3.11+, FastAPI, APScheduler
|
|
- 14개 알고리즘 (어구 추론, 다크베셀, 스푸핑, 환적, 위험도 등)
|
|
- 7단계 분류 파이프라인 (전처리→행동→리샘플→특징→분류→클러스터→계절)
|
|
- AIS 원본: SNPDB (5분 증분), 결과: kcgaidb (직접 write)
|
|
- prediction과 backend는 DB만 공유 (HTTP 호출 X)
|
|
|
|
### Backend (`backend/`)
|
|
- Spring Boot 3.x + Java 21
|
|
- Spring Security + JWT
|
|
- PostgreSQL + Flyway
|
|
- Caffeine (권한 캐싱)
|
|
- 트리 기반 RBAC (wing 패턴)
|
|
|
|
### Database (`kcgaidb`)
|
|
- PostgreSQL
|
|
- 사용자: `kcg-app`
|
|
- 스키마: `kcg`
|
|
|
|
## 배포 환경
|
|
|
|
| 서비스 | 서버 (SSH) | 포트 | 관리 |
|
|
|---|---|---|---|
|
|
| 프론트엔드 | rocky-211 | nginx 443 | Gitea Actions 자동배포 |
|
|
| 백엔드 | rocky-211 | 18080 | `systemctl restart kcg-ai-backend` |
|
|
| prediction | redis-211 | 18092 | `systemctl restart kcg-ai-prediction` |
|
|
|
|
- **URL**: https://kcg-ai-monitoring.gc-si.dev
|
|
- **배포 상세**: `deploy/README.md` 참조
|
|
- **CI/CD**: `.gitea/workflows/deploy.yml` (프론트만 자동, 백엔드/prediction 수동)
|
|
|
|
## 권한 체계
|
|
|
|
좌측 탭(메뉴) = 권한 그룹, 내부 패널/액션 = 자식 자원, CRUD 단위 개별 제어.
|
|
상세는 `.claude/plans/vast-tinkering-knuth.md` 참조.
|
|
|
|
## 팀 컨벤션
|
|
|
|
- 팀 규칙: `.claude/rules/`
|
|
- 커밋: Conventional Commits (한국어), `.githooks/commit-msg` 검증
|
|
- pre-commit: `frontend/` 디렉토리 기준 TypeScript + ESLint 검증
|
|
|
|
## System Flow 뷰어 (개발 단계용)
|
|
|
|
- **URL**: https://kcg-ai-monitoring.gc-si.dev/system-flow.html (메인 SPA와 별개)
|
|
- **소스**: `frontend/system-flow.html` + `frontend/src/systemFlowMain.tsx` + `frontend/src/flow/`
|
|
- **매니페스트**: `frontend/src/flow/manifest/` (10개 카테고리 JSON + meta.json + edges.json)
|
|
- **노드 ID 명명**: `<category>.<snake_case>` (예: `output.event_generator`, `ui.parent_review`)
|
|
- **딥링크**: `/system-flow.html#node=<node_id>` — 산출문서에서 노드 직접 참조
|
|
- **가이드**: `docs/system-flow-guide.md` 참조
|
|
|
|
### `/version` 스킬 사후 처리 (필수)
|
|
|
|
`/version` 스킬을 실행하여 새 SemVer 버전이 결정되면, Claude는 이어서 다음 작업을 **자동으로** 수행한다 (`/version` 스킬 자체는 팀 공통 파일이라 직접 수정하지 않음):
|
|
|
|
1. **manifest 동기화**: `/version`이 결정한 새 버전을 `frontend/src/flow/manifest/meta.json`에 반영
|
|
- `version`: 새 SemVer (예: `"1.2.0"`)
|
|
- `updatedAt`: 현재 ISO datetime (`new Date().toISOString()`)
|
|
- `releaseDate`: 오늘 날짜 (`YYYY-MM-DD`)
|
|
2. **같은 커밋에 포함**: `frontend/src/flow/manifest/meta.json`을 `/version` 스킬이 만든 커밋에 amend하거나, `docs: VERSION-HISTORY 갱신 + system-flow manifest 동기화`로 통합 커밋
|
|
3. **서버 archive는 CI/CD가 자동 처리**: 별도 작업 불필요. main 머지 후 Gitea Actions가 빌드 + dist 배포 + `/deploy/kcg-ai-monitoring-archive/system-flow/v{version}_{date}/`에 스냅샷 영구 보존
|
|
|
|
### 노드 ID 안정성
|
|
|
|
- **노드 ID는 절대 변경 금지** (산출문서가 참조하므로 깨짐)
|
|
- 노드 제거 시 `status: 'deprecated'`로 마킹 (1~2 릴리즈 유지 후 삭제)
|
|
- 새 노드 추가 시 `status: 'implemented'` 또는 `'planned'`
|