Merge pull request 'release: 2026-02-28 (11건 커밋) [skip ci]' (#20) from develop into main

Reviewed-on: #20
2026-02-28 13:00:36 +09:00 · 2026-02-28 13:00:36 +09:00 · e1297465c2
--- 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`를 최신화할 것
 - 개별 탭 개발자는 이 문서를 참조하여 공통 영역과의 연동을 구현

--- 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 갱신 |
--- a/docker-compose.yml
+++ b/docker-compose.yml
@ -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
--- 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=<PostgreSQL 호스트>
+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 포함 압축본 사용 |
--- 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 <div>로딩 중...</div>
-  if (error) return <div>오류: {error.message}</div>
+## 문서 안내

-  return (
-    <div>
-      {layers?.map(layer => (
-        <div key={layer.id}>{layer.name}</div>
-      ))}
-    </div>
-  )
-}
-```
+### 개발 가이드

-### 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 파일 최신화해줘"
 ```