kcg-monitoring/CLAUDE.md

프로젝트 개요

• 이름: KCG 모니터링 대시보드 (kcg-monitoring)
• 구조: 모노레포 (Frontend + Backend + Prediction)
• 도메인: https://kcg.gc-si.dev
• Gitea: https://gitea.gc-si.dev/gc/kcg-monitoring

기술 스택

패키지	스택	비고
Frontend	React 19 + TypeScript + Vite 7 + Tailwind CSS 4	i18n(ko/en), 테마(dark/light)
Backend	Spring Boot 3.2.5 + Java 17 + PostgreSQL	Google OAuth + JWT 인증
Prediction	FastAPI (Python)	향후 해양 분석
DB	PostgreSQL 16 (211.208.115.83:5432/kcgdb, 스키마: kcg)
CI/CD	Gitea Actions → nginx + systemd	main merge 시 자동 배포

빌드 및 실행

Frontend

cd frontend
npm install
npm run dev      # 개발서버 (포트 5173)
npm run build    # 프로덕션 빌드
npm run lint     # ESLint 검증

Backend

cd backend
# 최초: application-local.yml 설정 필요
cp src/main/resources/application-local.yml.example src/main/resources/application-local.yml
mvn spring-boot:run -Dspring-boot.run.profiles=local  # 개발서버 (포트 8080)
mvn compile      # 컴파일 검증
mvn package      # JAR 빌드 (target/kcg.jar)

Database

psql -h 211.208.115.83 -U kcg_app -d kcgdb -f database/init.sql
psql -h 211.208.115.83 -U kcg_app -d kcgdb -f database/migration/001_initial_schema.sql

프로젝트 구조

frontend/                     # React 19 + Vite 7 + Tailwind CSS 4
├── src/
│   ├── components/           # 28개 컴포넌트 (맵 레이어, UI 패널, 인증)
│   ├── hooks/                # useReplay, useMonitor, useTheme, useAuth
│   ├── services/             # API 서비스 (ships, opensky, osint, authApi 등)
│   ├── styles/               # tokens.css (테마 토큰), tailwind.css
│   ├── i18n/                 # i18next (ko/en)
│   ├── data/                 # 정적 데이터 (공항, 유전시설, 샘플)
│   └── App.tsx               # 인증 가드 → LoginPage / AuthenticatedApp
├── package.json
└── vite.config.ts            # Vite + 프록시 (/api/kcg → backend, /signal-batch → wing)

backend/                      # Spring Boot 3.2 + Java 17
├── src/main/java/gc/mda/kcg/
│   ├── auth/                 # Google OAuth + JWT (gcsc.co.kr 제한)
│   ├── config/               # CORS, Security, AppProperties
│   ├── collector/            # 수집기 placeholder (GDELT, GoogleNews, CENTCOM)
│   └── domain/               # event, news, osint, aircraft (placeholder)
├── src/main/resources/
│   ├── application.yml       # 공통 설정
│   ├── application-local.yml.example
│   └── application-prod.yml.example
└── pom.xml

database/                     # PostgreSQL
├── init.sql                  # CREATE SCHEMA kcg
└── migration/001_initial_schema.sql  # events, news, osint, users, login_history

prediction/                   # FastAPI placeholder
deploy/                       # systemd + nginx 배포 설정
.gitea/workflows/deploy.yml   # CI/CD (main merge → 자동 빌드/배포)

팀 스킬 사용 지침

중요: 스킬 실행 시 반드시 따라야 할 규칙

/push, /mr, /release 스킬은 SKILL.md에 정의된 절차를 순서대로 엄격히 따라야 한다.

특히 다음 단계를 절대 건너뛰지 말 것:

1. Step 0.5 해시 비교: 서버 해시와 로컬 해시를 실제로 bash 실행하여 비교. 불일치 시 /sync-team-workflow 자동 실행 후 원래 작업 계속.
2. AskUserQuestion 사용자 확인: 커밋 메시지, MR 타겟, 릴리즈 노트 초안을 반드시 사용자에게 보여주고 승인/수정/취소를 물어야 한다. 자의적으로 진행하지 말 것.
3. API 응답 검증: MR 생성, 봇 승인, 머지 API 호출 후 반드시 상태를 확인. 실패 시 사용자에게 알리고 중단.

스킬 목록

• /push — 커밋 + 푸시 (해시 비교 → 커밋 메시지 확인 → 푸시)
• /mr — 커밋 + 푸시 + MR 생성 (릴리즈 노트 갱신 포함)
• /release — develop → main 릴리즈 MR (릴리즈 노트 날짜 전환)
• /version — VERSION-HISTORY.md 생성
• /create-mr — MR 생성만 (세부 옵션)
• /fix-issue — 이슈 기반 작업 브랜치 생성

환경변수

• GITEA_TOKEN: .claude/settings.local.json의 env에 설정 (gitignored)
• CLAUDE_BOT_TOKEN: .claude/settings.json의 env에 설정 (gitignored by .claude/ rule)

배포

• 도메인: https://kcg.gc-si.dev
• 서버: rocky-211 (SSH 접속, Gitea Actions 러너 = 배포 서버)
• Frontend: /deploy/kcg/ (nginx 정적 파일 서빙)
• Backend: /deploy/kcg-backend/kcg.jar (systemd kcg-backend 서비스, JDK 17, 2~4GB 힙)
• nginx: /etc/nginx/conf.d/kcg.conf (SSL + SPA + API 프록시)
• DB: 211.208.115.83:5432/kcgdb (유저: kcg_app)

팀 규칙

• 코드 스타일: .claude/rules/code-style.md
• 네이밍: .claude/rules/naming.md
• 테스트: .claude/rules/testing.md
• Git 워크플로우: .claude/rules/git-workflow.md
• 팀 정책: .claude/rules/team-policy.md
• 릴리즈 노트 가이드: .claude/rules/release-notes-guide.md
• 서브에이전트 정책: .claude/rules/subagent-policy.md