gc/wing-ops
8
0
포크 0
코드 이슈 풀 리퀘스트 Actions 위키 활동
ff085252b0
wing-ops/README.md
htlee 54aeb2f124 docs: Phase 1~4 리팩토링 반영 문서 최신화 
- CLAUDE.md: 프로젝트 구조 (common/, tabs/, path alias), DB 스택, 지도 라이브러리
- README.md: 프로젝트 구조 트리, 기술 스택 테이블 (OpenLayers·SQLite 제거)
- docs/README.md: 기술 스택, 프로젝트 구조 트리
- docs/MENU-TAB-GUIDE.md: 새 탭 추가 경로 (tabs/ + @common/ alias)
- App.tsx: audit/log sendBeacon URL 수정 (Phase 4 버그 수정 포함)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-28 15:24:29 +09:00

224 lines
8.1 KiB
Markdown
Raw Blame 히스토리

# WING-OPS (해양 방제 운영 지원 시스템)
해양 오염 사고 대응을 위한 방제 운영 지원 시스템.
유류/HNS 확산 예측, 역추적 분석, 구조 시나리오, 항공 방제, 자산 관리, SCAT 조사, 기상/해상 정보를 통합 제공합니다.
---
## 1. 시작하기
### 1-1. 저장소 복제
```bash
git clone https://gitea.gc-si.dev/gc/wing-ops.git
cd wing-ops
```
### 1-2. Claude Code 초기화
```bash
# Claude Code 세션 열기
claude
# 팀 워크플로우 초기화
/init-project
```
`/init-project` 실행 시 자동으로 구성되는 항목:
- `.claude/` 디렉토리 (rules, skills, scripts, settings)
- `.githooks/` (pre-commit, commit-msg 자동 검증)
- Git hooks 경로 설정 (`core.hooksPath`)
- 메모리 디렉토리 초기화
### 1-3. 의존성 설치 및 실행
```bash
# 백엔드 (터미널 1)
cd backend && npm install && npm run dev # localhost:3001
# 프론트엔드 (터미널 2)
cd frontend && npm install && npm run dev # localhost:5173
```
> 사전 요구사항: Node.js 20+ (`.node-version`, fnm 사용), PostgreSQL 16+ (운영 DB 직접 연결)
>
> 상세 설치 절차(오프라인 환경, DB 초기화 등)는 [docs/INSTALL_GUIDE.md](docs/INSTALL_GUIDE.md)를 참조하세요.
---
## 2. 개발 워크플로우
```
계획 → 브랜치 → 개발 → 커밋/푸시 → develop MR → main PR → 자동 배포
```
| 단계 | 작업 | Claude 스킬 |
|------|------|-------------|
| 1. 계획 | 3개+ 파일 수정 시 Claude가 Plan Mode 진입 | (자동) |
| 2. 브랜치 | `feature/기능명` 으로 develop에서 분기 | - |
| 3. 개발 | Claude가 코드 작성 + 타입/린트 검증 | - |
| 4. 커밋/푸시 | pre-commit 자동 검증 후 푸시 | `/push` |
| 5. develop MR | feature → develop MR 생성 | `/mr` |
| 6. 릴리즈 | develop → main PR 생성 | `/release` |
| 7. 배포 | main 머지 시 Gitea Actions 자동 배포 | - |
> 상세 워크플로우(브랜치 규칙, 커밋 형식, MR 절차, 배포 확인, 실전 예시)는 [docs/DEVELOPMENT-GUIDE.md](docs/DEVELOPMENT-GUIDE.md)를 참조하세요.
---
## 3. 탭 개발
개별 탭(기능 화면)을 개발할 때 아래 공통 기능을 활용합니다.
| 기능 | 프론트엔드 | 백엔드 | 상세 |
|------|-----------|--------|------|
| 인증/인가 | `authStore`, `api.ts` (자동 쿠키) | `requireAuth`, `requireRole` | [COMMON-GUIDE.md #1](docs/COMMON-GUIDE.md#1-인증인가) |
| 감사 로그 | 탭 이동 자동 기록 (sendBeacon) | `audit/` 모듈 | [COMMON-GUIDE.md #2](docs/COMMON-GUIDE.md#2-감사-로그-audit-log) |
| 메뉴 시스템 | `menuStore` | `menus/`, `settings/` | [COMMON-GUIDE.md #3](docs/COMMON-GUIDE.md#3-메뉴-시스템) |
| API 통신 | `api.ts` (Axios + 인터셉터) | Express 라우터 | [COMMON-GUIDE.md #4](docs/COMMON-GUIDE.md#4-api-통신-패턴) |
| 상태 관리 | Zustand, TanStack Query | - | [COMMON-GUIDE.md #5](docs/COMMON-GUIDE.md#5-상태-관리) |
> 공통 로직 전체 가이드: [docs/COMMON-GUIDE.md](docs/COMMON-GUIDE.md)
>
> 새 메뉴 탭 추가 절차 (5단계): [docs/MENU-TAB-GUIDE.md](docs/MENU-TAB-GUIDE.md)
---
## 4. 프로젝트 구조
```
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
│ └── tabs/ 탭 단위 패키지 (@tabs/ alias)
│ ├── prediction/ 확산 예측
│ ├── hns/ HNS 분석
│ ├── rescue/ 구조 시나리오
│ ├── aerial/ 항공 방제
│ ├── weather/ 해양 기상
│ ├── 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 스크립트 + 마이그레이션
├── docs/ 개발 문서
├── .claude/ 팀 워크플로우 (rules, skills, scripts)
└── .githooks/ Git hooks (pre-commit, commit-msg)
```
---
## 5. 기술 스택
| 영역 | 기술 |
|------|------|
| Frontend | React 19, Vite 7, TypeScript 5.9, Tailwind CSS 3 |
| Backend | Express 4, TypeScript, PostgreSQL (pg) |
| 상태 관리 | Zustand (클라이언트), TanStack Query (서버) |
| 지도 | Leaflet + react-leaflet |
| 실시간 | Socket.IO |
| 인증 | JWT (HttpOnly Cookie), Google OAuth |
| DB | PostgreSQL 16 + PostGIS (wing 운영DB + wing_auth 인증DB) |
| CI/CD | Gitea Actions |
---
## 6. 문서 안내
### 개발 가이드
| 문서 | 설명 | 대상 |
|------|------|------|
| [DEVELOPMENT-GUIDE.md](docs/DEVELOPMENT-GUIDE.md) | 개발 워크플로우 전체 흐름 (Plan → Branch → MR → Deploy) | 모든 개발자 |
| [COMMON-GUIDE.md](docs/COMMON-GUIDE.md) | 공통 로직 개발 가이드 (인증, 감사로그, 메뉴, API, 상태 관리) | 탭 개발자 |
| [MENU-TAB-GUIDE.md](docs/MENU-TAB-GUIDE.md) | 새 메뉴 탭 추가 절차 (5단계) | 탭 개발자 |
### 운영 가이드
| 문서 | 설명 | 대상 |
|------|------|------|
| [INSTALL_GUIDE.md](docs/INSTALL_GUIDE.md) | 설치 매뉴얼 (온라인/오프라인, DB 초기화) | 운영/인프라 |
| [CHANGELOG.md](docs/CHANGELOG.md) | 변경 이력 | 모든 개발자 |
### 코드 컨벤션 (.claude/rules/)
| 규칙 | 설명 |
|------|------|
| `team-policy.md` | 보안/품질 정책 (필수 준수) |
| `git-workflow.md` | 브랜치/커밋/MR 규칙 |
| `code-style.md` | TypeScript/React 코드 스타일 |
| `naming.md` | 네이밍 규칙 |
| `testing.md` | 테스트 규칙 |
---
## 7. 환경 변수
### 프론트엔드 (`frontend/.env`)
```
VITE_API_URL=http://localhost:3001/api
VITE_GOOGLE_CLIENT_ID=your-google-client-id
```
### 백엔드 (`backend/.env`)
```
PORT=3001
NODE_ENV=development
JWT_SECRET=your-jwt-secret
AUTH_DB_HOST=localhost
AUTH_DB_PORT=5432
AUTH_DB_NAME=wing_auth
AUTH_DB_USER=wing_auth
AUTH_DB_PASSWORD=<비밀번호>
GOOGLE_CLIENT_ID=your-google-client-id
```
---
## 8. 배포
| 항목 | 값 |
|------|---|
| 프론트엔드 | https://wing-demo.gc-si.dev |
| 백엔드 API | https://wing-demo.gc-si.dev/api/ |
| CI/CD | Gitea Actions (main 머지 시 자동 배포) |
배포 파이프라인 상세는 [docs/DEVELOPMENT-GUIDE.md #7](docs/DEVELOPMENT-GUIDE.md#7-자동-배포)을 참조하세요.
---
## 9. Claude Code 스킬
| 스킬 | 설명 |
|------|------|
| `/push` | 커밋 + 푸시 (한 번에) |
| `/mr` | 커밋 + 푸시 + develop MR (한 번에) |
| `/release` | develop → main 릴리즈 MR |
| `/create-mr` | MR만 생성 (세부 옵션) |
| `/fix-issue` | Gitea 이슈 분석 + 수정 브랜치 생성 |
| `/sync-team-workflow` | 팀 워크플로우 동기화 |
| `/changelog` | CHANGELOG.md 갱신 |
Reference in New Issue View Git Blame Copy Permalink