# 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 검증