wing-ops/docs/README.md

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를 참조하세요.

---

문서 안내

개발 가이드

문서	설명	대상
DEVELOPMENT-GUIDE.md	개발 워크플로우 전체 흐름 (Plan → Branch → MR → Deploy)	모든 개발자
COMMON-GUIDE.md	공통 로직 개발 가이드 (인증, 감사로그, 메뉴, API 통신, 상태 관리)	탭 개발자
MENU-TAB-GUIDE.md	새 메뉴 탭 추가 절차 (5단계)	탭 개발자

운영 가이드

문서	설명	대상
INSTALL_GUIDE.md	설치 매뉴얼 (온라인/오프라인, DB 초기화)	운영/인프라
CHANGELOG.md	변경 이력	모든 개발자

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

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

---

공통 기능 요약

개별 탭 개발 시 아래 공통 기능을 활용합니다. 상세 사용법은 COMMON-GUIDE.md를 참조하세요.

기능	프론트엔드	백엔드	상세
인증/인가	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 라우터	COMMON-GUIDE.md #4
상태 관리	Zustand, TanStack Query	-	COMMON-GUIDE.md #5

---

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

---

배포

항목	값
프론트엔드	https://wing-demo.gc-si.dev
백엔드 API	https://wing-demo.gc-si.dev/api/
CI/CD	Gitea Actions (main 머지 시 자동 배포)

배포 파이프라인 상세는 DEVELOPMENT-GUIDE.md #7을 참조하세요.

---

문서 최신화 규칙

공통 기능(인증, 감사로그, 메뉴 시스템, API 통신 등)을 추가/변경할 때:

1. 해당 기능 코드 구현
2. docs/COMMON-GUIDE.md 최신화 (필수)
3. 필요 시 CLAUDE.md 프로젝트 구조 갱신

매 기능 개발 완료 시:

Claude에게: "memory 파일 최신화해줘"