WING-OPS (해양 방제 운영 지원 시스템)
해양 오염 사고 대응을 위한 방제 운영 지원 시스템.
유류/HNS 확산 예측, 역추적 분석, 구조 시나리오, 항공 방제, 자산 관리, SCAT 조사, 기상/해상 정보를 통합 제공합니다.
빠른 시작
# 1. 저장소 복제
git clone https://gitea.gc-si.dev/gc/wing-ops.git
cd wing-ops
# 2. Claude Code 세션 열기
claude
# 3. 팀 워크플로우 초기화
/init-project
/init-project 실행 시 자동으로 구성되는 항목:
.claude/ 디렉토리 (rules, skills, scripts, settings).githooks/ (pre-commit, commit-msg 자동 검증)- Git hooks 경로 설정 (
core.hooksPath)
- 메모리 디렉토리 초기화
상세 설치 절차(Docker, DB, 오프라인 환경 등)는 INSTALL_GUIDE.md를 참조하세요.
기술 스택
| 영역 |
기술 |
| Frontend |
React 19, Vite 7, TypeScript 5.9, Tailwind CSS 3 |
| Backend |
Express 4, TypeScript, better-sqlite3 (레이어), pg (인증) |
| 상태 관리 |
Zustand (클라이언트), TanStack Query (서버) |
| 지도 |
Leaflet, OpenLayers |
| 실시간 |
Socket.IO |
| 인증 |
JWT (HttpOnly Cookie), Google OAuth |
| DB |
PostgreSQL 16 + PostGIS (운영 DB 직접 연결), SQLite |
| CI/CD |
Gitea Actions |
프로젝트 구조
wing/
├── frontend/ React 19 + Vite + TypeScript + Tailwind
│ └── src/
│ ├── App.tsx 메인 (탭 라우팅, 감사 로그 자동 기록)
│ ├── components/ UI 컴포넌트
│ │ ├── auth/ 로그인 페이지
│ │ ├── views/ 각 탭별 페이지 뷰 (11개)
│ │ ├── layout/ MainLayout, TopBar, LeftPanel, RightPanel
│ │ ├── map/ 지도 관련
│ │ └── ... analysis, board, incidents, weather 등
│ ├── hooks/ 커스텀 훅
│ ├── services/ API 서비스 (api, authApi, weatherApi 등)
│ ├── store/ Zustand 상태 (authStore, menuStore)
│ ├── types/ 타입 정의
│ └── utils/ 유틸리티
├── backend/ Express + TypeScript
│ └── src/
│ ├── server.ts 진입점 + 라우터 등록
│ ├── auth/ 인증 (JWT, OAuth, 미들웨어)
│ ├── users/ 사용자 관리
│ ├── roles/ 역할/권한 관리
│ ├── settings/ 시스템 설정
│ ├── menus/ 메뉴 설정
│ ├── audit/ 감사 로그
│ ├── routes/ 레이어, 시뮬레이션
│ ├── middleware/ 보안 (입력 살균, rate-limit)
│ └── db/ DB 연결 (PostgreSQL, SQLite)
├── database/ SQL 초기화 스크립트
├── docs/ 개발 문서
├── .claude/ 팀 워크플로우 (rules, skills, scripts)
└── .githooks/ Git hooks (pre-commit, commit-msg)
개발 환경 실행
사전 요구사항
- Node.js 20+ (
.node-version, fnm 사용)
- PostgreSQL 16+ (운영 DB에 직접 연결)
실행
# 백엔드 (터미널 1)
cd backend && npm install && npm run dev # localhost:3001
# 프론트엔드 (터미널 2)
cd frontend && npm install && npm run dev # localhost:5173
빌드/검증
# TypeScript 타입 체크
cd frontend && npx tsc --noEmit
cd backend && npx tsc --noEmit
# ESLint
cd frontend && npx eslint .
# 프로덕션 빌드
cd frontend && npm run build # dist/ 생성
cd backend && npm run build # dist/ 생성
개발 워크플로우
계획 → 브랜치 → 개발 → 커밋/푸시 → develop MR → main PR → 자동 배포
Claude Code 기반 개발 절차
| 단계 |
작업 |
Claude 스킬 |
| 1. 계획 |
3개+ 파일 수정 시 Claude가 Plan Mode 진입 |
(자동) |
| 2. 브랜치 |
feature/기능명 으로 develop에서 분기 |
- |
| 3. 개발 |
Claude가 코드 작성 + 타입/린트 검증 |
- |
| 4. 커밋/푸시 |
pre-commit 자동 검증 후 푸시 |
/push |
| 5. develop MR |
feature → develop MR 생성 |
/mr |
| 6. 릴리즈 |
develop → main PR 생성 |
/release |
| 7. 배포 |
main 머지 시 Gitea Actions 자동 배포 |
- |
상세 워크플로우는 DEVELOPMENT-GUIDE.md를 참조하세요.
문서 안내
개발 가이드
운영 가이드
코드 컨벤션 (.claude/rules/)
| 규칙 |
설명 |
team-policy.md |
보안/품질 정책 (필수 준수) |
git-workflow.md |
브랜치/커밋/MR 규칙 |
code-style.md |
TypeScript/React 코드 스타일 |
naming.md |
네이밍 규칙 |
testing.md |
테스트 규칙 |
공통 기능 요약
개별 탭 개발 시 아래 공통 기능을 활용합니다.
상세 사용법은 COMMON-GUIDE.md를 참조하세요.
Claude Code 스킬
| 스킬 |
설명 |
/push |
커밋 + 푸시 (한 번에) |
/mr |
커밋 + 푸시 + develop MR (한 번에) |
/release |
develop → main 릴리즈 MR |
/create-mr |
MR만 생성 (세부 옵션) |
/fix-issue |
Gitea 이슈 분석 + 수정 브랜치 생성 |
/sync-team-workflow |
팀 워크플로우 동기화 |
/changelog |
CHANGELOG.md 갱신 |
환경 변수
프론트엔드 (.env)
VITE_API_URL=http://localhost:3001/api
VITE_GOOGLE_CLIENT_ID=your-google-client-id
백엔드 (.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=WingAuth!2026
GOOGLE_CLIENT_ID=your-google-client-id
배포
배포 파이프라인 상세는 DEVELOPMENT-GUIDE.md #7을 참조하세요.
문서 최신화 규칙
공통 기능(인증, 감사로그, 메뉴 시스템, API 통신 등)을 추가/변경할 때:
- 해당 기능 코드 구현
docs/COMMON-GUIDE.md 최신화 (필수)- 필요 시
CLAUDE.md 프로젝트 구조 갱신
매 기능 개발 완료 시:
Claude에게: "memory 파일 최신화해줘"
htlee
9586cd04eb