gc/wing-ops
8
0
포크 0
코드 이슈 풀 리퀘스트 Actions 위키 활동
765d3fb9d2
wing-ops/CLAUDE.md
leedano 38d931db65 refactor(mpa): 탭 디렉토리를 MPA 컴포넌트 구조로 재편 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-04-16 17:38:49 +09:00

8.8 KiB
Raw Blame 히스토리

WING-OPS (해양 방제 운영 지원 시스템)

해양 오염 사고 대응 방제 운영 지원 시스템. 유류/HNS 확산 예측, 역추적 분석, 구조 시나리오, 항공 방제, 자산 관리, SCAT 조사, 기상/해상 정보를 통합 제공한다.

  • 타입: react-ts 모노레포 (frontend + backend)
  • 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 (서버)
  • 지도: MapLibre GL JS 5.x + deck.gl 9.x (Leaflet 제거됨)
  • 실시간: Socket.IO
  • 인증: JWT (HttpOnly Cookie) + Google OAuth
  • CI/CD: Gitea Actions
  • CSS: Tailwind @layer 아키텍처 (base.css, components.css, wing.css)
  • HTTP 정책: GET/POST만 사용 (PUT/DELETE/PATCH 금지, 한국 보안취약점 점검 가이드 준수)
  • RBAC: AUTH_PERM OPER_CD (RCUD), permResolver 2차원 권한 엔진

빌드/실행

cd frontend && npm install            # Frontend
npm run dev                            # Vite dev (localhost:5173)
npm run build                          # tsc -b && vite build
npm run lint                           # ESLint

cd backend && npm install              # Backend
npm run dev                            # tsx watch (localhost:3001)
npm run build && npm start             # 프로덕션
npm run db:seed                        # DB 초기 데이터

테스트 프레임워크 미구성 (향후 Vitest + React Testing Library 도입 예정).

cd frontend && npx eslint .           # ESLint (flat config)
npx prettier --write .                # Prettier 자동 수정

프로젝트 구조

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 레이어 트리)
│       └── components/        탭 단위 패키지 (@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/             게시판 CRUD
│       ├── reports/           보고서 CRUD
│       ├── assets/            자산 관리 CRUD
│       ├── incidents/         사건/사고 CRUD
│       ├── scat/              SCAT 조사 CRUD
│       ├── prediction/        확산 예측 CRUD
│       ├── aerial/            항공 방제 CRUD
│       ├── rescue/            구조 시나리오 CRUD
│       ├── hns/               HNS 물질 검색 API
│       ├── routes/            레이어, 시뮬레이션
│       ├── middleware/        보안 (입력 살균, rate-limit, Helmet CORP cross-origin)
│       └── db/                DB 연결 (wingDb, authDb), seed
├── database/                  SQL 스크립트 + 마이그레이션 (001~016)
├── docs/                      개발 문서
├── .claude/                   팀 워크플로우 (rules, skills, scripts, agents)
└── .githooks/                 Git hooks (pre-commit, commit-msg)

Path Alias

  • @common/* -> src/common/* (공통 모듈)
  • @components/* -> src/components/* (탭 패키지)

팀 컨벤션

.claude/rules/ 디렉토리 참조:

  • team-policy.md -- 보안/품질 정책
  • git-workflow.md -- 브랜치/커밋/MR 규칙
  • code-style.md -- TypeScript/React 코드 스타일
  • naming.md -- 네이밍 규칙
  • testing.md -- 테스트 규칙
  • subagent-policy.md -- 서브에이전트 활용 정책
  • design-system.md -- AI 에이전트 UI 디자인 시스템 규칙 (영문, 실사용)
  • design-system-ko.md -- 디자인 시스템 규칙 (한국어 참고용)

개발 문서 (docs/)

  • docs/README.md -- 프로젝트 아키텍처 상세
  • docs/DEVELOPMENT-GUIDE.md -- 개발 워크플로우 전체 흐름
  • docs/COMMON-GUIDE.md -- 공통 로직 가이드 (인증, 감사로그, 메뉴, API 통신, 상태관리, RBAC, 지도, CSS)
  • docs/MENU-TAB-GUIDE.md -- 새 메뉴 탭 추가 절차 (5단계)
  • docs/CRUD-API-GUIDE.md -- CRUD API 개발 가이드 (DB -> 백엔드 -> 프론트 End-to-End)
  • docs/MOCK-TO-API-GUIDE.md -- Mock -> API 전환 프로세스
  • docs/INSTALL_GUIDE.md -- 설치 매뉴얼 (온라인/오프라인, DB 초기화)
  • docs/CHANGELOG.md -- 변경 이력

문서 최신화 규칙

  • 공통 기능을 추가/변경할 때 반드시 docs/COMMON-GUIDE.md를 최신화할 것
  • API 인터페이스 변경 시 memory/api-types.md 갱신
  • 개별 탭 개발자는 공통 가이드를 참조하여 연동 구현

진행 중 작업 (완료 후 삭제)

폰트 크기 업스케일 작업 (진행 중)

반드시 memory/font-upscale-plan.md를 읽고 Phase 진행 상황을 확인할 것.

토큰 변경 매핑 (이름 유지, 값만 변경):

  • caption/label-2/title-6: 11px → 12px (0.75rem)
  • label-1/title-5: 12px → 13px (0.8125rem)
  • body-2/title-4: 13px → 14px (0.875rem)
  • body-1/title-3: 14px → 16px (1rem)

네비게이션 클래스 교체:

  • TopBar 메인탭: text-title-4 → text-title-2 (16px)
  • SubMenuBar 서브탭: text-title-5 → text-title-4 (14px)

작업 범위:

  • Phase 1: tailwind.config.js + base.css 토큰 값 수정
  • Phase 2: components.css 하드코딩(27곳) + wing.css .wing-tab text-xs→text-caption
  • Phase 3: TopBar.tsx + SubMenuBar.tsx 클래스 교체
  • Phase 4: text-xs→text-caption, text-sm→text-body-2 스크립트 교체 (design 페이지 제외, 608건)
  • Phase 5: prediction 탭 인라인 fontSize 수정
  • Phase 6 (보류): wing-header-bar 패딩 — 폰트 변경 후 유저 확인 후 진행

디자인 시스템 폰트+색상 통일 작업

compact 후 반드시 memory/design-system-work.md를 읽고 작업 상태(완료/미완료 컴포넌트)를 확인할 것.

색상 규칙:

  • 하드코딩 색상(#ef4444, #a855f7 등) → CSS 변수 전환
  • rgba(59,130,246,...) 등 비-accent 계열 → rgba(6,182,212,...) (accent cyan)
  • 시맨틱 컬러(color-accent, color-info, color-caution 등)는 다양하게 사용 가능하되, 강조 색상은 최대 2가지로 제한
  • linear-gradient → 단색으로 단순화
  • 장식용 border-top, border-left → 제거 여부를 유저에게 확인 후 진행

폰트 규칙:

  • 하드코딩 fontSize/fontWeight → Tailwind 토큰 (text-title-2, text-caption 등)
  • fontFamily: monospace → var(--font-mono)
  • fontFamily: sans-serif / 'Noto Sans KR' → var(--font-korean)
  • 인라인 style={{ fontSize, padding }} → Tailwind 클래스 전환 (가능한 범위)

환경 설정

  • Node.js 20 (.node-version, fnm 사용)
  • npm registry: Nexus proxy (.npmrc)
  • Git hooks: .githooks/ (core.hooksPath 설정됨)