From 9586cd04eb20fa7fd61d911f96ada8c4d3d5dca5 Mon Sep 17 00:00:00 2001 From: htlee Date: Sat, 28 Feb 2026 12:56:59 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20=EA=B0=9C=EB=B0=9C=20=EA=B0=80=EC=9D=B4?= =?UTF-8?q?=EB=93=9C=20=EC=A0=95=EB=B9=84=20=EB=B0=8F=20Docker=20=EA=B4=80?= =?UTF-8?q?=EB=A0=A8=20=EB=82=B4=EC=9A=A9=20=EC=A0=9C=EA=B1=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - README.md를 프로젝트 진입점으로 전면 개편 (시작 → 워크플로우 → 탭개발 → 문서 안내 흐름) - Docker 관련 코드/문서 전면 제거 (운영 PostgreSQL 직접 연결) - docker-compose.yml 삭제 - CLAUDE.md, docs/README.md, docs/INSTALL_GUIDE.md Docker 참조 정리 Co-Authored-By: Claude Opus 4.6 --- CLAUDE.md | 70 +++++----- README.md | 221 ++++++++++++++++++++++++++++--- docker-compose.yml | 40 ------ docs/INSTALL_GUIDE.md | 57 +++----- docs/README.md | 298 +++++++++++++++++++++++++++--------------- 5 files changed, 450 insertions(+), 236 deletions(-) delete mode 100755 docker-compose.yml diff --git a/CLAUDE.md b/CLAUDE.md index 62b880a..29f527d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -33,11 +33,6 @@ npm start # 프로덕션 실행 npm run db:seed # DB 초기 데이터 ``` -### Docker -```bash -docker-compose up -d # PostgreSQL 16 + PostGIS + pgAdmin -``` - ## 테스트 테스트 프레임워크 미구성. 향후 Vitest + React Testing Library 도입 예정. @@ -51,35 +46,35 @@ npx prettier --write . # Prettier 자동 수정 ## 프로젝트 구조 ``` wing/ -├── frontend/ React 19 + Vite + TypeScript + Tailwind +├── frontend/ React 19 + Vite + TypeScript + Tailwind │ └── src/ -│ ├── App.tsx 메인 (MainTab 라우팅, 11개 탭) -│ ├── components/ UI 컴포넌트 (13개 서브디렉토리) -│ │ ├── analysis/ HNS/Oil/Rescue 분석 시나리오 -│ │ ├── board/ 게시판 -│ │ ├── incidents/ 사건/사고 관리 -│ │ ├── layer/ 레이어 트리 -│ │ ├── layout/ MainLayout, TopBar, LeftPanel, RightPanel -│ │ ├── map/ MapView, BacktrackReplay -│ │ ├── reports/ 보고서 -│ │ ├── views/ 각 탭별 페이지 뷰 -│ │ └── weather/ 해양/기상 시각화 -│ ├── hooks/ 커스텀 훅 (useLayers, useOceanForecast 등) -│ ├── services/ API 서비스 (api, khoaApi, weatherApi 등) -│ ├── store/ Zustand 상태관리 -│ ├── types/ 타입 정의 -│ └── utils/ 유틸리티 (coordinates, geo, sanitize) -├── backend/ Express + better-sqlite3 +│ ├── App.tsx 메인 (탭 라우팅, 감사 로그 자동 기록) +│ ├── components/ UI 컴포넌트 +│ │ ├── auth/ 로그인 페이지 +│ │ ├── views/ 탭별 페이지 뷰 (11개) +│ │ ├── layout/ MainLayout, TopBar, LeftPanel, RightPanel +│ │ └── ... analysis, board, incidents, map, weather 등 +│ ├── hooks/ 커스텀 훅 +│ ├── services/ API 서비스 (api, authApi, weatherApi 등) +│ ├── store/ Zustand (authStore, menuStore) +│ ├── types/ 타입 정의 +│ └── utils/ 유틸리티 +├── backend/ Express + TypeScript │ └── src/ -│ ├── server.ts Express 진입점 -│ ├── routes/ layers, simulation -│ ├── middleware/ security (입력 살균, rate-limit) -│ └── db/ database, seed -├── database/ SQL 초기화 스크립트 -├── docs/ 문서 -├── .claude/ 팀 워크플로우 (rules, skills, scripts) -├── .githooks/ Git hooks (pre-commit, commit-msg, post-checkout) -└── docker-compose.yml PostgreSQL + PostGIS + pgAdmin +│ ├── server.ts 진입점 + 라우터 등록 +│ ├── auth/ 인증 (JWT, OAuth, 미들웨어) +│ ├── users/ 사용자 관리 +│ ├── roles/ 역할/권한 관리 +│ ├── settings/ 시스템 설정 +│ ├── menus/ 메뉴 설정 +│ ├── audit/ 감사 로그 +│ ├── routes/ 레이어, 시뮬레이션 +│ ├── middleware/ 보안 (입력 살균, rate-limit) +│ └── db/ DB 연결 (PostgreSQL, SQLite) +├── database/ SQL 초기화 스크립트 +├── docs/ 개발 문서 (README, 가이드, 변경이력) +├── .claude/ 팀 워크플로우 (rules, skills, scripts) +└── .githooks/ Git hooks (pre-commit, commit-msg) ``` ## 팀 컨벤션 @@ -90,8 +85,15 @@ wing/ - `naming.md` — 네이밍 규칙 - `testing.md` — 테스트 규칙 -## 공통 기능 문서 -- `docs/COMMON-GUIDE.md` — 공통 로직 개발 가이드 (인증, 감사로그, 메뉴, API 등) +## 개발 문서 (`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`를 최신화할 것 - 개별 탭 개발자는 이 문서를 참조하여 공통 영역과의 연동을 구현 diff --git a/README.md b/README.md index 9da9cad..7832a3e 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,213 @@ -# WING-OPS +# WING-OPS (해양 방제 운영 지원 시스템) -해양 방제 운영 지원 시스템 +해양 오염 사고 대응을 위한 방제 운영 지원 시스템. +유류/HNS 확산 예측, 역추적 분석, 구조 시나리오, 항공 방제, 자산 관리, SCAT 조사, 기상/해상 정보를 통합 제공합니다. -## 구조 +--- -``` -frontend/ React 19 + Vite 7 + TypeScript + Tailwind -backend/ Express + better-sqlite3 + TypeScript -database/ SQL 초기화 스크립트 -docs/ 설치 가이드, 문서 -``` +## 1. 시작하기 -## 실행 +### 1-1. 저장소 복제 ```bash -# frontend -cd frontend && npm install && npm run dev - -# backend -cd backend && npm install && npm run dev +git clone https://gitea.gc-si.dev/gc/wing-ops.git +cd wing-ops ``` -## 환경 설정 +### 1-2. Claude Code 초기화 ```bash -cp frontend/.env.example frontend/.env -cp backend/.env.example backend/.env -# .env 파일에 API 키 입력 +# 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 메인 (탭 라우팅, 감사 로그 자동 기록) +│ ├── components/ UI 컴포넌트 +│ │ ├── auth/ 로그인 페이지 +│ │ ├── views/ 각 탭별 페이지 뷰 (11개) +│ │ ├── layout/ MainLayout, TopBar, LeftPanel, RightPanel +│ │ └── ... analysis, board, incidents, map, weather 등 +│ ├── hooks/ 커스텀 훅 +│ ├── services/ API 서비스 (api, authApi, weatherApi 등) +│ ├── store/ Zustand 상태 (authStore, menuStore) +│ ├── types/ 타입 정의 +│ └── utils/ 유틸리티 +├── backend/ Express + TypeScript +│ └── src/ +│ ├── server.ts 진입점 + 라우터 등록 +│ ├── auth/ 인증 (JWT, OAuth, 미들웨어) +│ ├── users/ 사용자 관리 +│ ├── roles/ 역할/권한 관리 +│ ├── settings/ 시스템 설정 +│ ├── menus/ 메뉴 설정 +│ ├── audit/ 감사 로그 +│ ├── routes/ 레이어, 시뮬레이션 +│ ├── middleware/ 보안 (입력 살균, rate-limit) +│ └── db/ DB 연결 (PostgreSQL, SQLite) +├── 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, better-sqlite3 (레이어), pg (인증) | +| 상태 관리 | Zustand (클라이언트), TanStack Query (서버) | +| 지도 | Leaflet, OpenLayers | +| 실시간 | Socket.IO | +| 인증 | JWT (HttpOnly Cookie), Google OAuth | +| DB | PostgreSQL 16 + PostGIS (운영 DB 직접 연결), SQLite | +| 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 갱신 | diff --git a/docker-compose.yml b/docker-compose.yml deleted file mode 100755 index 888a5b3..0000000 --- a/docker-compose.yml +++ /dev/null @@ -1,40 +0,0 @@ -version: '3.8' - -services: - postgres: - image: postgis/postgis:16-3.4 - container_name: wing-db - restart: unless-stopped - environment: - POSTGRES_DB: wing - POSTGRES_USER: wing_admin - POSTGRES_PASSWORD: wing_secure_2026 - TZ: Asia/Seoul - ports: - - "5432:5432" - volumes: - - wing_data:/var/lib/postgresql/data - - ./database/auth_init.sql:/docker-entrypoint-initdb.d/00-auth-init.sql - - ./database/database_init.sql:/docker-entrypoint-initdb.d/01-init.sql - healthcheck: - test: ["CMD-SHELL", "pg_isready -U wing_admin -d wing"] - interval: 10s - timeout: 5s - retries: 5 - - pgadmin: - image: dpage/pgadmin4:latest - container_name: wing-pgadmin - restart: unless-stopped - environment: - PGADMIN_DEFAULT_EMAIL: admin@wing.kr - PGADMIN_DEFAULT_PASSWORD: admin1234 - ports: - - "5050:80" - depends_on: - postgres: - condition: service_healthy - -volumes: - wing_data: - driver: local diff --git a/docs/INSTALL_GUIDE.md b/docs/INSTALL_GUIDE.md index 5c9b75f..227bcd9 100755 --- a/docs/INSTALL_GUIDE.md +++ b/docs/INSTALL_GUIDE.md @@ -6,7 +6,6 @@ |-----------|----------|------|---------| | Node.js | v20 이상 (권장 v25) | 프론트엔드/백엔드 실행 | https://nodejs.org | | npm | v10 이상 | 패키지 관리 | Node.js에 포함 | -| Docker Desktop | v4.0 이상 | PostgreSQL + pgAdmin 실행 | https://www.docker.com/products/docker-desktop | > **오프라인 환경**: 인터넷이 안 되는 망에서는 `node_modules`가 포함된 압축 파일을 사용하세요 (아래 "오프라인 설치" 참고). @@ -29,14 +28,12 @@ wing/ │ ├── src/ │ │ ├── routes/ # API 라우트 │ │ ├── middleware/ # 미들웨어 (보안 등) -│ │ ├── db/ # DB 시드 데이터 +│ │ ├── db/ # DB 연결 │ │ └── server.ts # 서버 엔트리 │ └── package.json -├── database/ # DB 초기화 SQL -│ ├── database_init.sql -│ └── init.sql -├── docker-compose.yml # PostgreSQL + pgAdmin 컨테이너 -└── INSTALL_GUIDE.md # 이 파일 +└── database/ # DB 초기화 SQL + ├── database_init.sql + └── auth_init.sql ``` --- @@ -55,16 +52,20 @@ cd ../backend npm install ``` -### 3-2. 데이터베이스 실행 (Docker) +### 3-2. 데이터베이스 설정 + +운영 PostgreSQL에 직접 연결합니다. `backend/.env` 파일에서 DB 연결 정보를 설정하세요. ```bash -cd wing -docker compose up -d +# backend/.env +AUTH_DB_HOST= +AUTH_DB_PORT=5432 +AUTH_DB_NAME=wing_auth +AUTH_DB_USER=wing_auth +AUTH_DB_PASSWORD=<비밀번호> ``` -실행 확인: -- PostgreSQL: `localhost:5432` (ID: `wing_admin` / PW: `wing_secure_2026`) -- pgAdmin: `http://localhost:5050` (ID: `admin@wing.kr` / PW: `admin1234`) +> 신규 DB 초기화가 필요한 경우 `database/auth_init.sql`을 실행하세요. ### 3-3. 백엔드 실행 @@ -105,24 +106,9 @@ tar -xzf wing_full.tar.gz - Windows: `node-v25.x.x-x64.msi` - macOS: `node-v25.x.x.pkg` -### 4-3. Docker 이미지 (선택) +### 4-3. DB 연결 설정 -DB를 Docker로 실행하려면 이미지를 미리 저장해서 가져갑니다. - -**원래 PC에서 내보내기:** -```bash -docker pull postgis/postgis:16-3.4 -docker pull dpage/pgadmin4:latest -docker save postgis/postgis:16-3.4 dpage/pgadmin4:latest -o wing_docker_images.tar -``` - -**대상 PC에서 불러오기:** -```bash -docker load -i wing_docker_images.tar -docker compose up -d -``` - -> Docker 없이도 PostgreSQL을 직접 설치하여 `database/database_init.sql`을 실행하면 됩니다. +`backend/.env` 파일에서 연결 가능한 PostgreSQL 정보를 설정합니다. ### 4-4. 실행 @@ -146,8 +132,7 @@ npm run dev |--------|-----|------| | 프론트엔드 (WING) | http://localhost:5173 | Vite dev server | | 백엔드 API | http://localhost:3001 | Express | -| PostgreSQL | localhost:5432 | DB: `wing`, User: `wing_admin` | -| pgAdmin | http://localhost:5050 | Email: `admin@wing.kr` | +| PostgreSQL | 운영 DB 직접 연결 | `.env` 설정 참조 | --- @@ -165,12 +150,6 @@ cd backend && npm run db:seed # TypeScript 타입 체크 cd frontend && npx tsc --noEmit - -# Docker 중지 -docker compose down - -# Docker 데이터 포함 삭제 -docker compose down -v ``` --- @@ -181,6 +160,6 @@ docker compose down -v |------|------| | `npm run dev` 실행 시 포트 충돌 | `lsof -i :5173` 또는 `lsof -i :3001`로 확인 후 프로세스 종료 | | `EACCES` 권한 오류 | `sudo chown -R $(whoami) wing/` | -| Docker 컨테이너 안 뜸 | `docker compose logs` 로 로그 확인 | | 프론트엔드에서 API 호출 실패 | 백엔드(`localhost:3001`)가 실행 중인지 확인 | +| DB 연결 실패 | `backend/.env`의 DB 연결 정보 확인, PostgreSQL 접근 가능 여부 확인 | | `MODULE_NOT_FOUND` 오류 | `npm install` 재실행 (온라인) 또는 node_modules 포함 압축본 사용 | diff --git a/docs/README.md b/docs/README.md index 1b8d7f5..f077b30 100755 --- a/docs/README.md +++ b/docs/README.md @@ -1,153 +1,243 @@ -# Wing - 해양 레이어 관리 시스템 +# WING-OPS (해양 방제 운영 지원 시스템) + +해양 오염 사고 대응을 위한 방제 운영 지원 시스템. +유류/HNS 확산 예측, 역추적 분석, 구조 시나리오, 항공 방제, 자산 관리, SCAT 조사, 기상/해상 정보를 통합 제공합니다. + +--- + +## 빠른 시작 + +```bash +# 1. 저장소 복제 +git clone https://gitea.gc-si.dev/gc/wing-ops.git +cd wing-ops + +# 2. Claude Code 세션 열기 +claude + +# 3. 팀 워크플로우 초기화 +/init-project +``` + +`/init-project` 실행 시 자동으로 구성되는 항목: +- `.claude/` 디렉토리 (rules, skills, scripts, settings) +- `.githooks/` (pre-commit, commit-msg 자동 검증) +- Git hooks 경로 설정 (`core.hooksPath`) +- 메모리 디렉토리 초기화 + +> 상세 설치 절차(Docker, DB, 오프라인 환경 등)는 [INSTALL_GUIDE.md](INSTALL_GUIDE.md)를 참조하세요. + +--- + +## 기술 스택 + +| 영역 | 기술 | +|------|------| +| Frontend | React 19, Vite 7, TypeScript 5.9, Tailwind CSS 3 | +| Backend | Express 4, TypeScript, better-sqlite3 (레이어), pg (인증) | +| 상태 관리 | Zustand (클라이언트), TanStack Query (서버) | +| 지도 | Leaflet, OpenLayers | +| 실시간 | Socket.IO | +| 인증 | JWT (HttpOnly Cookie), Google OAuth | +| DB | PostgreSQL 16 + PostGIS (운영 DB 직접 연결), SQLite | +| CI/CD | Gitea Actions | + +--- ## 프로젝트 구조 ``` wing/ -├── backend/ # Express + SQLite 백엔드 -│ ├── src/ -│ │ ├── db/ # 데이터베이스 설정 및 시드 -│ │ ├── routes/ # API 라우트 -│ │ └── server.ts # 메인 서버 -│ └── data/ # SQLite 데이터베이스 파일 -├── frontend/ # React + Vite 프론트엔드 +├── frontend/ React 19 + Vite + TypeScript + Tailwind │ └── src/ -│ ├── components/ -│ ├── data/ # 레이어 데이터 타입 -│ ├── hooks/ # React Query 훅 -│ └── services/ # API 클라이언트 -└── LayerList.csv # 원본 레이어 데이터 +│ ├── App.tsx 메인 (탭 라우팅, 감사 로그 자동 기록) +│ ├── components/ UI 컴포넌트 +│ │ ├── auth/ 로그인 페이지 +│ │ ├── views/ 각 탭별 페이지 뷰 (11개) +│ │ ├── layout/ MainLayout, TopBar, LeftPanel, RightPanel +│ │ ├── map/ 지도 관련 +│ │ └── ... analysis, board, incidents, weather 등 +│ ├── hooks/ 커스텀 훅 +│ ├── services/ API 서비스 (api, authApi, weatherApi 등) +│ ├── store/ Zustand 상태 (authStore, menuStore) +│ ├── types/ 타입 정의 +│ └── utils/ 유틸리티 +├── backend/ Express + TypeScript +│ └── src/ +│ ├── server.ts 진입점 + 라우터 등록 +│ ├── auth/ 인증 (JWT, OAuth, 미들웨어) +│ ├── users/ 사용자 관리 +│ ├── roles/ 역할/권한 관리 +│ ├── settings/ 시스템 설정 +│ ├── menus/ 메뉴 설정 +│ ├── audit/ 감사 로그 +│ ├── routes/ 레이어, 시뮬레이션 +│ ├── middleware/ 보안 (입력 살균, rate-limit) +│ └── db/ DB 연결 (PostgreSQL, SQLite) +├── database/ SQL 초기화 스크립트 +├── docs/ 개발 문서 +├── .claude/ 팀 워크플로우 (rules, skills, scripts) +└── .githooks/ Git hooks (pre-commit, commit-msg) ``` -## 설치 및 실행 +--- -### 1. 백엔드 설정 +## 개발 환경 실행 + +### 사전 요구사항 +- Node.js 20+ (`.node-version`, fnm 사용) +- PostgreSQL 16+ (운영 DB에 직접 연결) + +### 실행 ```bash -cd backend +# 백엔드 (터미널 1) +cd backend && npm install && npm run dev # localhost:3001 -# 의존성 설치 -npm install - -# 데이터베이스 시드 (CSV를 DB로 변환) -npm run db:seed - -# 개발 서버 실행 -npm run dev +# 프론트엔드 (터미널 2) +cd frontend && npm install && npm run dev # localhost:5173 ``` -백엔드 서버는 `http://localhost:3001`에서 실행됩니다. - -### 2. 프론트엔드 설정 +### 빌드/검증 ```bash -cd frontend +# TypeScript 타입 체크 +cd frontend && npx tsc --noEmit +cd backend && npx tsc --noEmit -# 의존성 설치 (아직 안 했다면) -npm install +# ESLint +cd frontend && npx eslint . -# 개발 서버 실행 -npm run dev +# 프로덕션 빌드 +cd frontend && npm run build # dist/ 생성 +cd backend && npm run build # dist/ 생성 ``` -프론트엔드는 `http://localhost:5173`에서 실행됩니다. +--- -## API 엔드포인트 +## 개발 워크플로우 -### 레이어 관리 - -- `GET /api/layers` - 모든 레이어 조회 -- `GET /api/layers/:id` - 특정 레이어 조회 -- `GET /api/layers/tree/all` - 계층 구조 레이어 트리 조회 -- `GET /api/layers/wms/all` - WMS 레이어만 조회 -- `GET /api/layers/level/:level` - 특정 레벨의 레이어 조회 -- `GET /api/layers/children/:parentId` - 특정 부모의 자식 레이어 조회 - -## 데이터베이스 스키마 - -```sql -CREATE TABLE layers ( - cmn_cd TEXT PRIMARY KEY, -- 레이어 코드 - up_cmn_cd TEXT, -- 부모 레이어 코드 - cmn_cd_full_nm TEXT NOT NULL, -- 전체 이름 - cmn_cd_nm TEXT NOT NULL, -- 레이어 이름 - cmn_cd_level INTEGER NOT NULL, -- 레벨 (1-7) - clnm TEXT, -- WMS 레이어 이름 - FOREIGN KEY (up_cmn_cd) REFERENCES layers(cmn_cd) -); +``` +계획 → 브랜치 → 개발 → 커밋/푸시 → develop MR → main PR → 자동 배포 ``` -## 프론트엔드에서 사용하기 +### Claude Code 기반 개발 절차 -### React Query 훅 사용 +| 단계 | 작업 | 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 자동 배포 | - | -```typescript -import { useLayers, useWMSLayers } from './hooks/useLayers' +> 상세 워크플로우는 [DEVELOPMENT-GUIDE.md](DEVELOPMENT-GUIDE.md)를 참조하세요. -function MyComponent() { - const { data: layers, isLoading, error } = useLayers() - const { data: wmsLayers } = useWMSLayers() +--- - if (isLoading) return
로딩 중...
- if (error) return
오류: {error.message}
+## 문서 안내 - return ( -
- {layers?.map(layer => ( -
{layer.name}
- ))} -
- ) -} -``` +### 개발 가이드 -### API 직접 호출 +| 문서 | 설명 | 대상 | +|------|------|------| +| [DEVELOPMENT-GUIDE.md](DEVELOPMENT-GUIDE.md) | 개발 워크플로우 전체 흐름 (Plan → Branch → MR → Deploy) | 모든 개발자 | +| [COMMON-GUIDE.md](COMMON-GUIDE.md) | 공통 로직 개발 가이드 (인증, 감사로그, 메뉴, API 통신, 상태 관리) | 탭 개발자 | +| [MENU-TAB-GUIDE.md](MENU-TAB-GUIDE.md) | 새 메뉴 탭 추가 절차 (5단계) | 탭 개발자 | -```typescript -import { fetchAllLayers, fetchWMSLayers } from './services/api' +### 운영 가이드 -async function loadLayers() { - const layers = await fetchAllLayers() - const wmsLayers = await fetchWMSLayers() - console.log(layers, wmsLayers) -} -``` +| 문서 | 설명 | 대상 | +|------|------|------| +| [INSTALL_GUIDE.md](INSTALL_GUIDE.md) | 설치 매뉴얼 (온라인/오프라인, DB 초기화) | 운영/인프라 | +| [CHANGELOG.md](CHANGELOG.md) | 변경 이력 | 모든 개발자 | -## CSV 데이터 업데이트 +### 코드 컨벤션 (.claude/rules/) -LayerList.csv 파일을 수정한 후: +| 규칙 | 설명 | +|------|------| +| `team-policy.md` | 보안/품질 정책 (필수 준수) | +| `git-workflow.md` | 브랜치/커밋/MR 규칙 | +| `code-style.md` | TypeScript/React 코드 스타일 | +| `naming.md` | 네이밍 규칙 | +| `testing.md` | 테스트 규칙 | -```bash -cd backend -npm run db:seed -``` +--- -이렇게 하면 데이터베이스가 새 CSV 데이터로 업데이트됩니다. +## 공통 기능 요약 -## 기술 스택 +개별 탭 개발 시 아래 공통 기능을 활용합니다. +상세 사용법은 [COMMON-GUIDE.md](COMMON-GUIDE.md)를 참조하세요. -### 백엔드 -- Node.js + TypeScript -- Express.js -- Better-SQLite3 +| 기능 | 프론트엔드 | 백엔드 | 상세 | +|------|-----------|--------|------| +| 인증/인가 | `authStore`, `api.ts` (자동 쿠키) | `requireAuth`, `requireRole` | [COMMON-GUIDE.md #1](COMMON-GUIDE.md#1-인증인가) | +| 감사 로그 | 탭 이동 자동 기록 (sendBeacon) | `audit/` 모듈 | [COMMON-GUIDE.md #2](COMMON-GUIDE.md#2-감사-로그-audit-log) | +| 메뉴 시스템 | `menuStore` | `menus/`, `settings/` | [COMMON-GUIDE.md #3](COMMON-GUIDE.md#3-메뉴-시스템) | +| API 통신 | `api.ts` (Axios + 인터셉터) | Express 라우터 | [COMMON-GUIDE.md #4](COMMON-GUIDE.md#4-api-통신-패턴) | +| 상태 관리 | Zustand, TanStack Query | - | [COMMON-GUIDE.md #5](COMMON-GUIDE.md#5-상태-관리) | -### 프론트엔드 -- React 19 -- TypeScript -- Vite -- React Query (TanStack Query) -- Axios -- Leaflet (지도) -- Tailwind CSS +--- + +## Claude Code 스킬 + +| 스킬 | 설명 | +|------|------| +| `/push` | 커밋 + 푸시 (한 번에) | +| `/mr` | 커밋 + 푸시 + develop MR (한 번에) | +| `/release` | develop → main 릴리즈 MR | +| `/create-mr` | MR만 생성 (세부 옵션) | +| `/fix-issue` | Gitea 이슈 분석 + 수정 브랜치 생성 | +| `/sync-team-workflow` | 팀 워크플로우 동기화 | +| `/changelog` | CHANGELOG.md 갱신 | + +--- ## 환경 변수 ### 프론트엔드 (.env) ``` VITE_API_URL=http://localhost:3001/api +VITE_GOOGLE_CLIENT_ID=your-google-client-id ``` -### 백엔드 +### 백엔드 (.env) ``` -PORT=3001 # 기본값 +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=WingAuth!2026 +GOOGLE_CLIENT_ID=your-google-client-id +``` + +--- + +## 배포 + +| 항목 | 값 | +|------|---| +| 프론트엔드 | https://wing-demo.gc-si.dev | +| 백엔드 API | https://wing-demo.gc-si.dev/api/ | +| CI/CD | Gitea Actions (main 머지 시 자동 배포) | + +배포 파이프라인 상세는 [DEVELOPMENT-GUIDE.md #7](DEVELOPMENT-GUIDE.md#7-자동-배포)을 참조하세요. + +--- + +## 문서 최신화 규칙 + +공통 기능(인증, 감사로그, 메뉴 시스템, API 통신 등)을 추가/변경할 때: +1. 해당 기능 코드 구현 +2. `docs/COMMON-GUIDE.md` 최신화 (필수) +3. 필요 시 `CLAUDE.md` 프로젝트 구조 갱신 + +매 기능 개발 완료 시: +``` +Claude에게: "memory 파일 최신화해줘" ```