225 lines
9.2 KiB
Markdown
225 lines
9.2 KiB
Markdown
# WING-OPS
|
|
|
|
해양 오염 사고 대응을 위한 방제 운영 지원 시스템.
|
|
유류/HNS 확산 예측, 역추적 분석, 구조 시나리오, 항공 방제, 자산 관리, SCAT 조사, 기상/해상 정보를 통합 제공한다.
|
|
|
|
---
|
|
|
|
## 시작하기
|
|
|
|
```bash
|
|
# 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](docs/INSTALL_GUIDE.md)
|
|
|
|
### 빌드 및 검증
|
|
|
|
```bash
|
|
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](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](docs/COMMON-GUIDE.md#1-인증인가) |
|
|
| 감사 로그 | 탭 이동 자동 기록 (sendBeacon) | `audit/` 모듈 | [COMMON-GUIDE.md #2](docs/COMMON-GUIDE.md#2-감사-로그-audit-log) |
|
|
| 메뉴 시스템 | `menuStore` | `menus/`, `settings/` | [COMMON-GUIDE.md #3](docs/COMMON-GUIDE.md#3-메뉴-시스템) |
|
|
| API 통신 | `api.ts` (Axios + 인터셉터) | Express 라우터 (GET/POST only) | [COMMON-GUIDE.md #4](docs/COMMON-GUIDE.md#4-api-통신-패턴) |
|
|
| 상태 관리 | Zustand, TanStack Query | - | [COMMON-GUIDE.md #5](docs/COMMON-GUIDE.md#5-상태-관리) |
|
|
|
|
- 새 메뉴 탭 추가 (5단계): [docs/MENU-TAB-GUIDE.md](docs/MENU-TAB-GUIDE.md)
|
|
- CRUD API 개발: [docs/CRUD-API-GUIDE.md](docs/CRUD-API-GUIDE.md)
|
|
- HTTP 정책: GET/POST만 사용 (PUT/DELETE/PATCH 금지, 보안취약점 가이드 준수)
|
|
|
|
---
|
|
|
|
## 프로젝트 구조
|
|
|
|
Path Alias: `@common/*` -> `src/common/*`, `@components/*` -> `src/components/*`
|
|
|
|
```
|
|
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/ 탭 단위 패키지 (@components/ 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/README.md) | 프로젝트 아키텍처 상세 | 모든 개발자 |
|
|
| [docs/DEVELOPMENT-GUIDE.md](docs/DEVELOPMENT-GUIDE.md) | 개발 워크플로우 전체 흐름 | 모든 개발자 |
|
|
| [docs/COMMON-GUIDE.md](docs/COMMON-GUIDE.md) | 공통 로직 가이드 (인증, 감사로그, 메뉴, API, 상태 관리) | 탭 개발자 |
|
|
| [docs/MENU-TAB-GUIDE.md](docs/MENU-TAB-GUIDE.md) | 새 메뉴 탭 추가 절차 (5단계) | 탭 개발자 |
|
|
| [docs/CRUD-API-GUIDE.md](docs/CRUD-API-GUIDE.md) | CRUD API 개발 가이드 | 탭 개발자 |
|
|
| [docs/MOCK-TO-API-GUIDE.md](docs/MOCK-TO-API-GUIDE.md) | Mock -> API 전환 프로세스 | 탭 개발자 |
|
|
| [docs/INSTALL_GUIDE.md](docs/INSTALL_GUIDE.md) | 설치 매뉴얼 (온라인/오프라인, DB 초기화) | 운영/인프라 |
|
|
| [docs/CHANGELOG.md](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` | 프로젝트 초기 설정 |
|