htlee 7f35103c60 docs: 프로젝트 문서 최신화 (2026-04-08)

## 메모리 갱신 (Claude 내부)
- project-snapshot.md: 48테이블, V001~V016, prediction e2e 정상, System Flow 뷰어, 데모계정 5종
- project-history.md: 2026-04-07~08 릴리즈 이력 요약 (MR #3~#15)
- next-task: 1순위를 UI/표기 다듬기로 전환
- api-types: /api/stats/hourly + V014~V016 보조 테이블 추가
- debugging: 최근 해결된 11개 이슈 패턴 정리
- 구버전 참고 파일 정리 (data-analysis, refactoring-decisions)

## 리포지토리 문서
- docs/RELEASE-NOTES.md: Unreleased 섹션에 prediction e2e 수정, System Flow 포커스 모드,
  hourly API, V014~V016, mock 정리, KST 통일, DemoQuickLogin hostname 등 추가
- CLAUDE.md: database/ 설명 V001~V016, 48 테이블로 갱신

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

2026-04-08 07:10:22 +09:00

5.6 KiB

Raw Blame 히스토리

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~V016, 48 테이블)
│   └── 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 분석 테이블은 미복사

명령어

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 스킬 자체는 팀 공통 파일이라 직접 수정하지 않음):

manifest 동기화: /version이 결정한 새 버전을 frontend/src/flow/manifest/meta.json에 반영
- version: 새 SemVer (예: "1.2.0")
- updatedAt: 현재 ISO datetime (new Date().toISOString())
- releaseDate: 오늘 날짜 (YYYY-MM-DD)
같은 커밋에 포함: frontend/src/flow/manifest/meta.json을 /version 스킬이 만든 커밋에 amend하거나, docs: VERSION-HISTORY 갱신 + system-flow manifest 동기화로 통합 커밋
서버 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'

5.6 KiB Raw Blame 히스토리