gc/wing-ops
8
0
포크 0
코드 이슈 풀 리퀘스트 Actions 위키 활동
6fbb3fc249
wing-ops/docs/_backup_20260301/ROOT_CLAUDE.md
htlee 6fbb3fc249 docs: 전체 프로젝트 문서 최신 기준 신규 작성 
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>
2026-03-01 14:03:08 +09:00

5.6 KiB
Raw Blame 히스토리

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

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

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

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 설정됨)