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

docs: Phase 1~4 리팩토링 반영 문서 최신화 #24

병합
htlee feature/docs-phase1-4-update 에서 develop 로 1 commits 를 머지했습니다 2026-02-28 15:28:08 +09:00
대화 0 커밋 1 파일 변경됨 5 +98 -55
5개의 변경된 파일과 98개의 추가작업 그리고 55개의 파일을 삭제
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

48
CLAUDE.md
파일 보기

@ -7,8 +7,9 @@
- **프로젝트 타입**: react-ts (모노레포) - **프로젝트 타입**: react-ts (모노레포)
- **Frontend**: React 19 + Vite 7 + TypeScript 5.9 + Tailwind CSS 3 - **Frontend**: React 19 + Vite 7 + TypeScript 5.9 + Tailwind CSS 3
- **Backend**: Express 4 + PostgreSQL (pg) + TypeScript - **Backend**: Express 4 + PostgreSQL (pg) + TypeScript
- **DB**: PostgreSQL 16 + PostGIS (wing 운영DB + wing_auth 인증DB)
- **상태관리**: Zustand (클라이언트), TanStack Query (서버) - **상태관리**: Zustand (클라이언트), TanStack Query (서버)
- **지도**: Leaflet - **지도**: Leaflet + react-leaflet
- **실시간**: Socket.IO - **실시간**: Socket.IO
## 빌드/실행 ## 빌드/실행
@ -49,16 +50,27 @@ wing/
├── frontend/ React 19 + Vite + TypeScript + Tailwind ├── frontend/ React 19 + Vite + TypeScript + Tailwind
│ └── src/ │ └── src/
│ ├── App.tsx 메인 (탭 라우팅, 감사 로그 자동 기록) │ ├── App.tsx 메인 (탭 라우팅, 감사 로그 자동 기록)
│ ├── components/ UI 컴포넌트 │ ├── common/ 공통 모듈 (@common/ alias)
│ │ ├── auth/ 로그인 페이지 │ │ ├── components/ auth/, layer/, layout/, map/, ui/
│ │ ├── views/ 탭별 페이지 뷰 (11개) │ │ ├── hooks/ useLayers, useSubMenu
│ │ ├── layout/ MainLayout, TopBar, LeftPanel, RightPanel │ │ ├── services/ api.ts, authApi.ts, layerService.ts
│ │ └── ... analysis, board, incidents, map, weather 등 │ │ ├── store/ authStore, menuStore (Zustand)
│ ├── hooks/ 커스텀 훅 │ │ ├── types/ backtrack, boomLine, hns, navigation
│ ├── services/ API 서비스 (api, authApi, weatherApi 등) │ │ ├── utils/ coordinates, geo, sanitize
│ ├── store/ Zustand (authStore, menuStore) │ │ ├── data/ layerData.ts (UI 레이어 트리)
│ ├── types/ 타입 정의 │ │ └── mock/ vesselMockData, backtrackMockData
│ └── utils/ 유틸리티 │ └── 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 ├── backend/ Express + TypeScript
│ └── src/ │ └── src/
│ ├── server.ts 진입점 + 라우터 등록 │ ├── server.ts 진입점 + 라우터 등록
@ -68,15 +80,23 @@ wing/
│ ├── settings/ 시스템 설정 │ ├── settings/ 시스템 설정
│ ├── menus/ 메뉴 설정 │ ├── menus/ 메뉴 설정
│ ├── audit/ 감사 로그 │ ├── audit/ 감사 로그
│ ├── hns/ HNS 물질 검색 API
│ ├── routes/ 레이어, 시뮬레이션 │ ├── routes/ 레이어, 시뮬레이션
│ ├── middleware/ 보안 (입력 살균, rate-limit) │ ├── middleware/ 보안 (입력 살균, rate-limit)
│ └── db/ DB 연결 (PostgreSQL: wing, wing_auth) │ └── db/ DB 연결 (wingDb, authDb), seed
├── database/ SQL 초기화 스크립트 ├── database/ SQL 스크립트
├── docs/ 개발 문서 (README, 가이드, 변경이력) │ ├── init.sql wing DB 초기 스키마
│ ├── auth_init.sql wing_auth DB 초기 스키마
│ └── migration/ 마이그레이션 (001_layer, 002_hns_substance)
├── docs/ 개발 문서
├── .claude/ 팀 워크플로우 (rules, skills, scripts) ├── .claude/ 팀 워크플로우 (rules, skills, scripts)
└── .githooks/ Git hooks (pre-commit, commit-msg) └── .githooks/ Git hooks (pre-commit, commit-msg)
``` ```
### Path Alias
- `@common/*` → `src/common/*` (공통 모듈)
- `@tabs/*` → `src/tabs/*` (탭 패키지)
## 팀 컨벤션 ## 팀 컨벤션
`.claude/rules/` 디렉토리 참조: `.claude/rules/` 디렉토리 참조:
- `team-policy.md` — 보안/품질 정책 - `team-policy.md` — 보안/품질 정책

40
README.md
파일 보기

@ -90,17 +90,26 @@ cd frontend && npm install && npm run dev # localhost:5173
wing/ wing/
├── frontend/ React 19 + Vite + TypeScript + Tailwind ├── frontend/ React 19 + Vite + TypeScript + Tailwind
│ └── src/ │ └── src/
│ ├── App.tsx 메인 (탭 라우팅, 감사 로그 자동 기록) │ ├── App.tsx 메인 (탭 라우팅, 감사 로그)
│ ├── components/ UI 컴포넌트 │ ├── common/ 공통 모듈 (@common/ alias)
│ │ ├── auth/ 로그인 페이지 │ │ ├── components/ auth/, layer/, layout/, map/, ui/
│ │ ├── views/ 각 탭별 페이지 뷰 (11개) │ │ ├── hooks/ useLayers, useSubMenu
│ │ ├── layout/ MainLayout, TopBar, LeftPanel, RightPanel │ │ ├── services/ api.ts, authApi.ts, layerService.ts
│ │ └── ... analysis, board, incidents, map, weather 등 │ │ ├── store/ authStore, menuStore (Zustand)
│ ├── hooks/ 커스텀 훅 │ │ ├── types/ backtrack, boomLine, hns, navigation
│ ├── services/ API 서비스 (api, authApi, weatherApi 등) │ │ └── utils/ coordinates, geo, sanitize
│ ├── store/ Zustand 상태 (authStore, menuStore) │ └── tabs/ 탭 단위 패키지 (@tabs/ alias)
│ ├── types/ 타입 정의 │ ├── prediction/ 확산 예측
│ └── utils/ 유틸리티 │ ├── hns/ HNS 분석
│ ├── rescue/ 구조 시나리오
│ ├── aerial/ 항공 방제
│ ├── weather/ 해양 기상
│ ├── incidents/ 사건/사고
│ ├── board/ 게시판
│ ├── reports/ 보고서
│ ├── assets/ 자산 관리
│ ├── scat/ Pre-SCAT
│ └── admin/ 관리자
├── backend/ Express + TypeScript ├── backend/ Express + TypeScript
│ └── src/ │ └── src/
│ ├── server.ts 진입점 + 라우터 등록 │ ├── server.ts 진입점 + 라우터 등록
@ -110,10 +119,11 @@ wing/
│ ├── settings/ 시스템 설정 │ ├── settings/ 시스템 설정
│ ├── menus/ 메뉴 설정 │ ├── menus/ 메뉴 설정
│ ├── audit/ 감사 로그 │ ├── audit/ 감사 로그
│ ├── hns/ HNS 물질 검색 API
│ ├── routes/ 레이어, 시뮬레이션 │ ├── routes/ 레이어, 시뮬레이션
│ ├── middleware/ 보안 (입력 살균, rate-limit) │ ├── middleware/ 보안 (입력 살균, rate-limit)
│ └── db/ DB 연결 (PostgreSQL, SQLite) │ └── db/ DB 연결 (wingDb, authDb), seed
├── database/ SQL 초기화 스크립트 ├── database/ SQL 스크립트 + 마이그레이션
├── docs/ 개발 문서 ├── docs/ 개발 문서
├── .claude/ 팀 워크플로우 (rules, skills, scripts) ├── .claude/ 팀 워크플로우 (rules, skills, scripts)
└── .githooks/ Git hooks (pre-commit, commit-msg) └── .githooks/ Git hooks (pre-commit, commit-msg)
@ -128,10 +138,10 @@ wing/
| Frontend | React 19, Vite 7, TypeScript 5.9, Tailwind CSS 3 | | Frontend | React 19, Vite 7, TypeScript 5.9, Tailwind CSS 3 |
| Backend | Express 4, TypeScript, PostgreSQL (pg) | | Backend | Express 4, TypeScript, PostgreSQL (pg) |
| 상태 관리 | Zustand (클라이언트), TanStack Query (서버) | | 상태 관리 | Zustand (클라이언트), TanStack Query (서버) |
| 지도 | Leaflet, OpenLayers | | 지도 | Leaflet + react-leaflet |
| 실시간 | Socket.IO | | 실시간 | Socket.IO |
| 인증 | JWT (HttpOnly Cookie), Google OAuth | | 인증 | JWT (HttpOnly Cookie), Google OAuth |
| DB | PostgreSQL 16 + PostGIS (운영 DB 직접 연결), SQLite | | DB | PostgreSQL 16 + PostGIS (wing 운영DB + wing_auth 인증DB) |
| CI/CD | Gitea Actions | | CI/CD | Gitea Actions |
--- ---

26
docs/MENU-TAB-GUIDE.md
파일 보기

@ -22,18 +22,19 @@ Frontend: menuStore.ts → TopBar.tsx (탭 렌더링)
| 순서 | 파일 | 작업 | 필수 | | 순서 | 파일 | 작업 | 필수 |
|------|------|------|------| |------|------|------|------|
| 1 | `frontend/src/components/views/XxxView.tsx` | 뷰 컴포넌트 생성 | O | | 1 | `frontend/src/tabs/{탭명}/components/XxxView.tsx` | 뷰 컴포넌트 생성 | O |
| 2 | `frontend/src/App.tsx` | MainTab 타입 + import + renderView | O | | 2 | `frontend/src/tabs/{탭명}/index.ts` | re-export 생성 | O |
| 3 | `backend/src/settings/settingsService.ts` | DEFAULT_MENU_CONFIG에 항목 추가 | O | | 3 | `frontend/src/App.tsx` | MainTab 타입 + import + renderView | O |
| 4 | `database/auth_init.sql` | menu.config 초기 JSON에 추가 | O | | 4 | `backend/src/settings/settingsService.ts` | DEFAULT_MENU_CONFIG에 항목 추가 | O |
| 5 | 관리자 UI | 메뉴 관리에서 활성화 | O | | 5 | `database/auth_init.sql` | menu.config 초기 JSON에 추가 | O |
| 6 | 관리자 UI | 메뉴 관리에서 활성화 | O |
## Step 1: 뷰 컴포넌트 생성 ## Step 1: 뷰 컴포넌트 생성
`frontend/src/components/views/` 에 새 뷰 컴포넌트를 생성합니다. `frontend/src/tabs/{탭명}/components/` 에 새 뷰 컴포넌트를 생성합니다.
```tsx ```tsx
// frontend/src/components/views/MonitoringView.tsx // frontend/src/tabs/monitoring/components/MonitoringView.tsx
export function MonitoringView() { export function MonitoringView() {
return ( return (
@ -47,7 +48,14 @@ export function MonitoringView() {
} }
``` ```
기존 뷰 컴포넌트(`OilSpillView`, `WeatherView` 등)의 레이아웃 패턴을 참고하세요. `index.ts`에서 re-export합니다:
```tsx
// frontend/src/tabs/monitoring/index.ts
export { MonitoringView } from './components/MonitoringView'
```
기존 탭(`@tabs/prediction`, `@tabs/weather` 등)의 레이아웃 패턴을 참고하세요.
공통 모듈은 `@common/` alias로 import합니다.
## Step 2: App.tsx 탭 등록 ## Step 2: App.tsx 탭 등록
@ -68,7 +76,7 @@ export type MainTab = 'prediction' | 'hns' | ... | 'monitoring' | 'admin'
### 2-2. 뷰 컴포넌트 import ### 2-2. 뷰 컴포넌트 import
```tsx ```tsx
import { MonitoringView } from './components/views/MonitoringView' import { MonitoringView } from '@tabs/monitoring'
``` ```
### 2-3. renderView switch에 case 추가 ### 2-3. renderView switch에 case 추가

36
docs/README.md
파일 보기

@ -36,10 +36,10 @@ claude
| Frontend | React 19, Vite 7, TypeScript 5.9, Tailwind CSS 3 | | Frontend | React 19, Vite 7, TypeScript 5.9, Tailwind CSS 3 |
| Backend | Express 4, TypeScript, PostgreSQL (pg) | | Backend | Express 4, TypeScript, PostgreSQL (pg) |
| 상태 관리 | Zustand (클라이언트), TanStack Query (서버) | | 상태 관리 | Zustand (클라이언트), TanStack Query (서버) |
| 지도 | Leaflet, OpenLayers | | 지도 | Leaflet + react-leaflet |
| 실시간 | Socket.IO | | 실시간 | Socket.IO |
| 인증 | JWT (HttpOnly Cookie), Google OAuth | | 인증 | JWT (HttpOnly Cookie), Google OAuth |
| DB | PostgreSQL 16 + PostGIS (wing + wing_auth) | | DB | PostgreSQL 16 + PostGIS (wing 운영DB + wing_auth 인증DB) |
| CI/CD | Gitea Actions | | CI/CD | Gitea Actions |
--- ---
@ -50,18 +50,21 @@ claude
wing/ wing/
├── frontend/ React 19 + Vite + TypeScript + Tailwind ├── frontend/ React 19 + Vite + TypeScript + Tailwind
│ └── src/ │ └── src/
│ ├── App.tsx 메인 (탭 라우팅, 감사 로그 자동 기록) │ ├── App.tsx 메인 (탭 라우팅, 감사 로그)
│ ├── components/ UI 컴포넌트 │ ├── common/ 공통 모듈 (@common/ alias)
│ │ ├── auth/ 로그인 페이지 │ │ ├── components/ auth/, layer/, layout/, map/, ui/
│ │ ├── views/ 각 탭별 페이지 뷰 (11개) │ │ ├── hooks/ useLayers, useSubMenu
│ │ ├── layout/ MainLayout, TopBar, LeftPanel, RightPanel │ │ ├── services/ api.ts, authApi.ts, layerService.ts
│ │ ├── map/ 지도 관련 │ │ ├── store/ authStore, menuStore (Zustand)
│ │ └── ... analysis, board, incidents, weather 등 │ │ ├── types/ backtrack, boomLine, hns, navigation
│ ├── hooks/ 커스텀 훅 │ │ └── utils/ coordinates, geo, sanitize
│ ├── services/ API 서비스 (api, authApi, weatherApi 등) │ └── tabs/ 탭 단위 패키지 (@tabs/ alias)
│ ├── store/ Zustand 상태 (authStore, menuStore) │ ├── prediction/ 확산 예측 (OilSpillView, LeftPanel 등)
│ ├── types/ 타입 정의 │ ├── hns/ HNS 분석 (HNSView, HNSSubstanceView 등)
│ └── utils/ 유틸리티 │ ├── rescue/ 구조 시나리오
│ ├── aerial/ 항공 방제
│ ├── weather/ 해양 기상
│ └── ... incidents, board, reports, assets, scat, admin
├── backend/ Express + TypeScript ├── backend/ Express + TypeScript
│ └── src/ │ └── src/
│ ├── server.ts 진입점 + 라우터 등록 │ ├── server.ts 진입점 + 라우터 등록
@ -71,10 +74,11 @@ wing/
│ ├── settings/ 시스템 설정 │ ├── settings/ 시스템 설정
│ ├── menus/ 메뉴 설정 │ ├── menus/ 메뉴 설정
│ ├── audit/ 감사 로그 │ ├── audit/ 감사 로그
│ ├── hns/ HNS 물질 검색 API
│ ├── routes/ 레이어, 시뮬레이션 │ ├── routes/ 레이어, 시뮬레이션
│ ├── middleware/ 보안 (입력 살균, rate-limit) │ ├── middleware/ 보안 (입력 살균, rate-limit)
│ └── db/ DB 연결 (PostgreSQL: wing, wing_auth) │ └── db/ DB 연결 (wingDb, authDb), seed
├── database/ SQL 초기화 스크립트 ├── database/ SQL 스크립트 + 마이그레이션
├── docs/ 개발 문서 ├── docs/ 개발 문서
├── .claude/ 팀 워크플로우 (rules, skills, scripts) ├── .claude/ 팀 워크플로우 (rules, skills, scripts)
└── .githooks/ Git hooks (pre-commit, commit-msg) └── .githooks/ Git hooks (pre-commit, commit-msg)

3
frontend/src/App.tsx
파일 보기

@ -46,7 +46,8 @@ function App() {
[JSON.stringify({ action: 'TAB_VIEW', detail: activeMainTab })], [JSON.stringify({ action: 'TAB_VIEW', detail: activeMainTab })],
{ type: 'text/plain' } { type: 'text/plain' }
) )
navigator.sendBeacon('/api/audit/log', blob) const apiBase = import.meta.env.VITE_API_URL || 'http://localhost:3001/api'
navigator.sendBeacon(`${apiBase}/audit/log`, blob)
}, [activeMainTab, isAuthenticated]) }, [activeMainTab, isAuthenticated])
// 세션 확인 중 스플래시 // 세션 확인 중 스플래시