htlee
6fbb3fc249
Phase 6(MapLibre+deck.gl), CSS 리팩토링, RBAC, 10탭 API 전환 등 현재 시스템 상태를 정확히 반영하여 모든 문서를 처음부터 재작성. - README.md: 기술 스택(MapLibre+deck.gl), 빌드, 구조, 스킬 갱신 - CLAUDE.md: CSS @layer, RBAC, HTTP 정책, 백엔드 모듈 반영 - docs/README.md: 아키텍처 상세 (3-Layer, 인증, 권한, CSS) - docs/DEVELOPMENT-GUIDE.md: 워크플로우 전체 흐름 + 실전 예시 - docs/INSTALL_GUIDE.md: 온라인/오프라인 설치 매뉴얼 - docs/COMMON-GUIDE.md: 공통 로직 9개 섹션 (인증~CSS) - docs/MENU-TAB-GUIDE.md: 새 탭 추가 5단계 + 예시 - docs/CRUD-API-GUIDE.md: End-to-End CRUD API 패턴 - docs/MOCK-TO-API-GUIDE.md: Mock→API 전환 10단계 프로세스 - docs/_backup_20260301/: 기존 문서 백업 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
124 lines
5.6 KiB
Markdown
124 lines
5.6 KiB
Markdown
# WING-OPS (해양 방제 운영 지원 시스템)
|
|
|
|
## 프로젝트 개요
|
|
해양 오염 사고 대응을 위한 방제 운영 지원 시스템.
|
|
유류/HNS 확산 예측, 역추적 분석, 구조 시나리오, 항공 방제, 자산 관리, SCAT 조사, 기상/해상 정보를 통합 제공한다.
|
|
|
|
- **프로젝트 타입**: react-ts (모노레포)
|
|
- **Frontend**: React 19 + Vite 7 + TypeScript 5.9 + Tailwind CSS 3
|
|
- **Backend**: Express 4 + PostgreSQL (pg) + TypeScript
|
|
- **DB**: PostgreSQL 16 + PostGIS (wing 운영DB + wing_auth 인증DB)
|
|
- **상태관리**: Zustand (클라이언트), TanStack Query (서버)
|
|
- **지도**: Leaflet + react-leaflet
|
|
- **실시간**: Socket.IO
|
|
|
|
## 빌드/실행
|
|
|
|
### Frontend
|
|
```bash
|
|
cd frontend
|
|
npm install
|
|
npm run dev # 개발 서버 (Vite, localhost:5173)
|
|
npm run build # 프로덕션 빌드 (tsc -b && vite build)
|
|
npm run lint # ESLint 검증
|
|
npm run preview # 빌드 미리보기
|
|
```
|
|
|
|
### Backend
|
|
```bash
|
|
cd backend
|
|
npm install
|
|
npm run dev # 개발 서버 (tsx watch, localhost:3001)
|
|
npm run build # TypeScript 컴파일 (tsc)
|
|
npm start # 프로덕션 실행
|
|
npm run db:seed # DB 초기 데이터
|
|
```
|
|
|
|
## 테스트
|
|
테스트 프레임워크 미구성. 향후 Vitest + React Testing Library 도입 예정.
|
|
|
|
## Lint/Format
|
|
```bash
|
|
cd frontend && npx eslint . # ESLint (flat config)
|
|
npx prettier --check . # Prettier 검증
|
|
npx prettier --write . # Prettier 자동 수정
|
|
```
|
|
|
|
## 프로젝트 구조
|
|
```
|
|
wing/
|
|
├── frontend/ React 19 + Vite + TypeScript + Tailwind
|
|
│ └── src/
|
|
│ ├── App.tsx 메인 (탭 라우팅, 감사 로그 자동 기록)
|
|
│ ├── common/ 공통 모듈 (@common/ alias)
|
|
│ │ ├── components/ auth/, layer/, layout/, map/, ui/
|
|
│ │ ├── hooks/ useLayers, useSubMenu
|
|
│ │ ├── services/ api.ts, authApi.ts, layerService.ts
|
|
│ │ ├── store/ authStore, menuStore (Zustand)
|
|
│ │ ├── types/ backtrack, boomLine, hns, navigation
|
|
│ │ ├── utils/ coordinates, geo, sanitize
|
|
│ │ ├── data/ layerData.ts (UI 레이어 트리)
|
|
│ │ └── mock/ vesselMockData, backtrackMockData
|
|
│ └── tabs/ 탭 단위 패키지 (@tabs/ alias)
|
|
│ ├── prediction/ 확산 예측 (OilSpillView, LeftPanel 등)
|
|
│ ├── hns/ HNS 분석 (HNSView, HNSSubstanceView 등)
|
|
│ ├── rescue/ 구조 시나리오
|
|
│ ├── aerial/ 항공 방제
|
|
│ ├── weather/ 해양 기상 (오버레이, hooks, services)
|
|
│ ├── incidents/ 사건/사고 관리
|
|
│ ├── board/ 게시판
|
|
│ ├── reports/ 보고서
|
|
│ ├── assets/ 자산 관리
|
|
│ ├── scat/ Pre-SCAT 조사
|
|
│ └── admin/ 관리자 (사용자/권한/메뉴/설정)
|
|
├── backend/ Express + TypeScript
|
|
│ └── src/
|
|
│ ├── server.ts 진입점 + 라우터 등록
|
|
│ ├── auth/ 인증 (JWT, OAuth, 미들웨어)
|
|
│ ├── users/ 사용자 관리
|
|
│ ├── roles/ 역할/권한 관리
|
|
│ ├── settings/ 시스템 설정
|
|
│ ├── menus/ 메뉴 설정
|
|
│ ├── audit/ 감사 로그
|
|
│ ├── hns/ HNS 물질 검색 API
|
|
│ ├── routes/ 레이어, 시뮬레이션
|
|
│ ├── middleware/ 보안 (입력 살균, rate-limit)
|
|
│ └── db/ DB 연결 (wingDb, authDb), seed
|
|
├── database/ SQL 스크립트
|
|
│ ├── init.sql wing DB 초기 스키마
|
|
│ ├── auth_init.sql wing_auth DB 초기 스키마
|
|
│ └── migration/ 마이그레이션 (001_layer, 002_hns_substance)
|
|
├── docs/ 개발 문서
|
|
├── .claude/ 팀 워크플로우 (rules, skills, scripts)
|
|
└── .githooks/ Git hooks (pre-commit, commit-msg)
|
|
```
|
|
|
|
### Path Alias
|
|
- `@common/*` → `src/common/*` (공통 모듈)
|
|
- `@tabs/*` → `src/tabs/*` (탭 패키지)
|
|
|
|
## 팀 컨벤션
|
|
`.claude/rules/` 디렉토리 참조:
|
|
- `team-policy.md` — 보안/품질 정책
|
|
- `git-workflow.md` — 브랜치/커밋/MR 규칙
|
|
- `code-style.md` — TypeScript/React 코드 스타일
|
|
- `naming.md` — 네이밍 규칙
|
|
- `testing.md` — 테스트 규칙
|
|
|
|
## 개발 문서 (`docs/`)
|
|
- `docs/README.md` — 프로젝트 개요, 초기 세팅, 워크플로우 요약, 문서 안내
|
|
- `docs/DEVELOPMENT-GUIDE.md` — 개발 워크플로우 전체 흐름 (Plan → Branch → MR → Deploy)
|
|
- `docs/COMMON-GUIDE.md` — 공통 로직 개발 가이드 (인증, 감사로그, 메뉴, API 통신, 상태 관리)
|
|
- `docs/MENU-TAB-GUIDE.md` — 새 메뉴 탭 추가 절차 (5단계)
|
|
- `docs/INSTALL_GUIDE.md` — 설치 매뉴얼 (온라인/오프라인, DB)
|
|
- `docs/CHANGELOG.md` — 변경 이력
|
|
|
|
### 문서 최신화 규칙
|
|
- 공통 기능(인증, 감사로그, 메뉴 시스템, API 통신 등)을 추가/변경할 때 반드시 `docs/COMMON-GUIDE.md`를 최신화할 것
|
|
- 개별 탭 개발자는 이 문서를 참조하여 공통 영역과의 연동을 구현
|
|
|
|
## 환경 설정
|
|
- Node.js 20 (`.node-version`, fnm 사용)
|
|
- npm registry: Nexus proxy (`.npmrc`)
|
|
- Git hooks: `.githooks/` (core.hooksPath 설정됨)
|