WING-OPS

해양 오염 사고 대응을 위한 방제 운영 지원 시스템. 유류/HNS 확산 예측, 역추적 분석, 구조 시나리오, 항공 방제, 자산 관리, SCAT 조사, 기상/해상 정보를 통합 제공한다.

---

시작하기

# 1. 저장소 복제
git clone https://gitea.gc-si.dev/gc/wing-ops.git && cd wing-ops

# 2. Claude Code 초기화 (.claude/, .githooks/, 메모리 디렉토리 자동 구성)
claude
/init-project

# 3. 백엔드 (터미널 1)
cd backend && npm install && npm run dev    # localhost:3001

# 4. 프론트엔드 (터미널 2)
cd frontend && npm install && npm run dev   # localhost:5173

사전 요구사항: Node.js 20+ (.node-version, fnm 사용), PostgreSQL 16+ (원격 DB 직접 연결)

상세 설치 절차: docs/INSTALL_GUIDE.md

빌드 및 검증

cd frontend && npm run build     # tsc -b && vite build
cd frontend && npx eslint .      # ESLint 검증
cd backend && npm run build      # tsc
cd backend && npm run db:seed    # DB 초기 데이터

---

개발 워크플로우

계획 -> 브랜치 -> 개발 -> 커밋/푸시 -> develop MR -> main PR -> 자동 배포

단계	작업	Claude 스킬
계획	3개+ 파일 수정 시 Plan Mode 자동 진입	(자동)
브랜치	feature/기능명으로 develop에서 분기	-
개발	코드 작성 + 타입/린트 검증	-
커밋/푸시	pre-commit 자동 검증 후 푸시	/push
develop MR	feature -> develop MR 생성	/mr
릴리즈	develop -> main PR 생성	/release
배포	main 머지 시 Gitea Actions 자동 배포	-

상세 워크플로우: docs/DEVELOPMENT-GUIDE.md

---

탭 개발

11개 탭: prediction, hns, rescue, aerial, weather, incidents, board, reports, assets, scat, admin

기능	프론트엔드	백엔드	상세
인증/인가	authStore, api.ts (자동 쿠키)	requireAuth, requireRole	COMMON-GUIDE.md #1
감사 로그	탭 이동 자동 기록 (sendBeacon)	audit/ 모듈	COMMON-GUIDE.md #2
메뉴 시스템	menuStore	menus/, settings/	COMMON-GUIDE.md #3
API 통신	api.ts (Axios + 인터셉터)	Express 라우터 (GET/POST only)	COMMON-GUIDE.md #4
상태 관리	Zustand, TanStack Query	-	COMMON-GUIDE.md #5

• 새 메뉴 탭 추가 (5단계): docs/MENU-TAB-GUIDE.md
• CRUD API 개발: docs/CRUD-API-GUIDE.md
• HTTP 정책: GET/POST만 사용 (PUT/DELETE/PATCH 금지, 보안취약점 가이드 준수)

---

프로젝트 구조

Path Alias: @common/* -> src/common/*, @tabs/* -> src/tabs/*

wing/
├── frontend/                 React 19 + Vite 7 + TypeScript + Tailwind
│   └── src/
│       ├── App.tsx            메인 (탭 라우팅, 감사 로그 자동 기록)
│       ├── index.css          @tailwind + @import 엔트리포인트
│       ├── common/            공통 모듈 (@common/ alias)
│       │   ├── components/    auth/, layer/, layout/, map/, ui/
│       │   ├── hooks/         useLayers, useSubMenu, useFeatureTracking
│       │   ├── services/      api.ts, authApi.ts, layerService.ts
│       │   ├── store/         authStore, menuStore (Zustand)
│       │   ├── styles/        base.css, components.css, wing.css
│       │   ├── constants/     featureIds.ts
│       │   ├── types/         backtrack, boomLine, hns, navigation
│       │   ├── utils/         coordinates, geo, sanitize, cn.ts
│       │   └── data/          layerData.ts (UI 레이어 트리)
│       └── tabs/              탭 단위 패키지 (@tabs/ alias)
│           ├── prediction/    확산 예측 (OilSpillView, 역추적, 오일붐)
│           ├── hns/           HNS 분석 (시나리오, 물질 DB, 재계산)
│           ├── rescue/        구조 시나리오
│           ├── aerial/        항공 방제 (위성영상, 드론)
│           ├── weather/       해양 기상 (KHOA API, 오버레이)
│           ├── incidents/     사건/사고 관리
│           ├── board/         게시판
│           ├── reports/       보고서
│           ├── assets/        자산 관리 (기관, 장비, 선박보험)
│           ├── scat/          Pre-SCAT 해안조사
│           └── admin/         관리자 (사용자/역할/권한/메뉴/설정)
├── backend/                   Express + TypeScript
│   └── src/
│       ├── server.ts          진입점 + 라우터 등록
│       ├── auth/              인증 (JWT, OAuth, 미들웨어)
│       ├── users/, roles/     사용자, 역할/권한 (permResolver)
│       ├── settings/, menus/  시스템 설정, 메뉴 설정
│       ├── audit/             감사 로그
│       ├── board/, reports/   게시판, 보고서 CRUD
│       ├── assets/, incidents/, scat/    자산, 사건/사고, SCAT CRUD
│       ├── prediction/, aerial/, rescue/ 예측, 항공, 구조 CRUD
│       ├── hns/               HNS 물질 검색 API
│       ├── routes/            레이어, 시뮬레이션
│       ├── middleware/        보안 (입력 살균, rate-limit)
│       └── db/                DB 연결 (wingDb, authDb), seed
├── database/                  SQL 스크립트 + 마이그레이션 (001~016)
├── docs/                      개발 문서
├── .claude/                   팀 워크플로우 (rules, skills, scripts, agents)
└── .githooks/                 Git hooks (pre-commit, commit-msg)

---

기술 스택

영역	기술
Frontend	React 19, Vite 7.3, TypeScript 5.9, Tailwind CSS 3
CSS 아키텍처	Tailwind @layer (base.css, components.css, wing.css), cn() 유틸리티
상태 관리	Zustand (클라이언트), TanStack Query (서버)
지도	MapLibre GL JS 5.x + @vis.gl/react-maplibre 8.1 + deck.gl 9.x
실시간	Socket.IO Client 4.8
UI	lucide-react, @dnd-kit, emoji-mart
Backend	Express 4, TypeScript, pg (PostgreSQL)
보안	Helmet, CORS, Rate-limit, Input sanitization
인증	JWT (HttpOnly Cookie WING_SESSION), bcrypt, Google OAuth
DB	PostgreSQL 16 + PostGIS (wing 운영DB + wing_auth 인증DB)
CI/CD	Gitea Actions (.gitea/workflows/deploy.yml)

---

문서 안내

문서	설명	대상
docs/README.md	프로젝트 아키텍처 상세	모든 개발자
docs/DEVELOPMENT-GUIDE.md	개발 워크플로우 전체 흐름	모든 개발자
docs/COMMON-GUIDE.md	공통 로직 가이드 (인증, 감사로그, 메뉴, API, 상태 관리)	탭 개발자
docs/MENU-TAB-GUIDE.md	새 메뉴 탭 추가 절차 (5단계)	탭 개발자
docs/CRUD-API-GUIDE.md	CRUD API 개발 가이드	탭 개발자
docs/MOCK-TO-API-GUIDE.md	Mock -> API 전환 프로세스	탭 개발자
docs/INSTALL_GUIDE.md	설치 매뉴얼 (온라인/오프라인, DB 초기화)	운영/인프라
docs/CHANGELOG.md	변경 이력	모든 개발자

코드 컨벤션 (.claude/rules/)

규칙	설명
team-policy.md	보안/품질 정책 (필수 준수)
git-workflow.md	브랜치/커밋/MR 규칙
code-style.md	TypeScript/React 코드 스타일
naming.md	네이밍 규칙
testing.md	테스트 규칙
subagent-policy.md	서브에이전트 활용 정책

---

환경 변수

프론트엔드 (frontend/.env)

VITE_API_URL=http://localhost:3001/api
VITE_GOOGLE_CLIENT_ID=your-google-client-id

백엔드 (backend/.env)

PORT=3001
NODE_ENV=development
JWT_SECRET=your-jwt-secret
AUTH_DB_HOST=localhost
AUTH_DB_PORT=5432
AUTH_DB_NAME=wing_auth
AUTH_DB_USER=wing_auth
AUTH_DB_PASSWORD=<비밀번호>
GOOGLE_CLIENT_ID=your-google-client-id

---

배포

항목	값
프론트엔드	https://wing-demo.gc-si.dev
백엔드 API	https://wing-demo.gc-si.dev/api/
CI/CD	Gitea Actions (main 머지 시 자동 배포)
Gitea	https://gitea.gc-si.dev/gc/wing-ops
보호 브랜치	main, develop (MR 필수)

---

Claude Code 스킬

스킬	설명
/push	커밋 + 푸시 (한 번에)
/mr	커밋 + 푸시 + develop MR (한 번에)
/release	develop -> main 릴리즈 MR
/create-mr	MR만 생성 (세부 옵션)
/fix-issue	Gitea 이슈 분석 + 수정 브랜치 생성
/sync-team-workflow	팀 워크플로우 동기화
/changelog	CHANGELOG.md 갱신
/init-project	프로젝트 초기 설정