gc/wing-ops
8
0
포크 0
코드 이슈 풀 리퀘스트 Actions 위키 활동
988cc47e9f
wing-ops/CLAUDE.md

174 lines
8.6 KiB
Markdown
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차원 권한 엔진
## 빌드/실행
```bash
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 도입 예정).
```bash
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 레이어 트리)
│ └── tabs/ 탭 단위 패키지 (@tabs/ 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/*` (공통 모듈)
- `@tabs/*` -> `src/tabs/*` (탭 패키지)
## 팀 컨벤션
`.claude/rules/` 디렉토리 참조:
- `team-policy.md` -- 보안/품질 정책
- `git-workflow.md` -- 브랜치/커밋/MR 규칙
- `code-style.md` -- TypeScript/React 코드 스타일
- `naming.md` -- 네이밍 규칙
- `testing.md` -- 테스트 규칙
- `subagent-policy.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 설정됨)
Reference in New Issue View Git Blame Copy Permalink