# WING 해양환경 위기대응 통합시스템 - 설치 매뉴얼

## 1. 필수 소프트웨어

| 소프트웨어 | 최소 버전 | 용도 | 다운로드 |
|-----------|----------|------|---------|
| Node.js | v20 이상 (권장 v25) | 프론트엔드/백엔드 실행 | https://nodejs.org |
| npm | v10 이상 | 패키지 관리 | Node.js에 포함 |

> **오프라인 환경**: 인터넷이 안 되는 망에서는 `node_modules`가 포함된 압축 파일을 사용하세요 (아래 "오프라인 설치" 참고).

---

## 2. 프로젝트 구조

```
wing/
├── frontend/          # React + Vite 프론트엔드 (포트 5173)
│   ├── src/
│   │   ├── components/   # UI 컴포넌트
│   │   ├── data/         # 정적 데이터
│   │   ├── hooks/        # 커스텀 훅
│   │   ├── types/        # TypeScript 타입 정의
│   │   ├── utils/        # 유틸리티 함수
│   │   └── store/        # 상태관리
│   └── package.json
├── backend/           # Express 백엔드 API (포트 3001)
│   ├── src/
│   │   ├── routes/       # API 라우트
│   │   ├── middleware/    # 미들웨어 (보안 등)
│   │   ├── db/           # DB 연결
│   │   └── server.ts     # 서버 엔트리
│   └── package.json
└── database/          # DB 초기화 SQL
    ├── database_init.sql
    └── auth_init.sql
```

---

## 3. 온라인 설치 (인터넷 가능한 환경)

### 3-1. 의존성 설치

```bash
# 프론트엔드
cd wing/frontend
npm install

# 백엔드
cd ../backend
npm install
```

### 3-2. 데이터베이스 설정

운영 PostgreSQL에 직접 연결합니다. `backend/.env` 파일에서 DB 연결 정보를 설정하세요.

```bash
# backend/.env
AUTH_DB_HOST=<PostgreSQL 호스트>
AUTH_DB_PORT=5432
AUTH_DB_NAME=wing_auth
AUTH_DB_USER=wing_auth
AUTH_DB_PASSWORD=<비밀번호>
```

> 신규 DB 초기화가 필요한 경우 `database/auth_init.sql`을 실행하세요.

### 3-3. 백엔드 실행

```bash
cd wing/backend
npm run dev
```

→ `http://localhost:3001` 에서 API 서버 시작

### 3-4. 프론트엔드 실행

```bash
cd wing/frontend
npm run dev
```

→ `http://localhost:5173` 에서 웹 앱 시작

---

## 4. 오프라인 설치 (폐쇄망/다른 망)

인터넷이 안 되는 환경에서는 `npm install`이 불가능합니다.
이 경우 **node_modules 포함 압축 파일**을 사용하세요.

### 4-1. 압축 해제

```bash
# wing_full.tar.gz 파일을 작업 폴더에 복사한 뒤:
tar -xzf wing_full.tar.gz
```

### 4-2. Node.js 설치

대상 PC에 Node.js가 없으면 오프라인 설치 파일(.msi 또는 .pkg)을 미리 준비하여 설치합니다.

- Windows: `node-v25.x.x-x64.msi`
- macOS: `node-v25.x.x.pkg`

### 4-3. DB 연결 설정

`backend/.env` 파일에서 연결 가능한 PostgreSQL 정보를 설정합니다.

### 4-4. 실행

node_modules가 이미 포함되어 있으므로 바로 실행 가능합니다.

```bash
# 터미널 1 - 백엔드
cd wing/backend
npm run dev

# 터미널 2 - 프론트엔드
cd wing/frontend
npm run dev
```

---

## 5. 접속 정보 요약

| 서비스 | URL | 비고 |
|--------|-----|------|
| 프론트엔드 (WING) | http://localhost:5173 | Vite dev server |
| 백엔드 API | http://localhost:3001 | Express |
| PostgreSQL | 운영 DB 직접 연결 | `.env` 설정 참조 |

---

## 6. 주요 명령어

```bash
# 프론트엔드 빌드 (배포용)
cd frontend && npm run build    # dist/ 폴더에 정적 파일 생성

# 백엔드 빌드
cd backend && npm run build     # dist/ 폴더에 JS 생성

# DB 시드 데이터 입력
cd backend && npm run db:seed

# TypeScript 타입 체크
cd frontend && npx tsc --noEmit
```

---

## 7. 트러블슈팅

| 증상 | 해결 |
|------|------|
| `npm run dev` 실행 시 포트 충돌 | `lsof -i :5173` 또는 `lsof -i :3001`로 확인 후 프로세스 종료 |
| `EACCES` 권한 오류 | `sudo chown -R $(whoami) wing/` |
| 프론트엔드에서 API 호출 실패 | 백엔드(`localhost:3001`)가 실행 중인지 확인 |
| DB 연결 실패 | `backend/.env`의 DB 연결 정보 확인, PostgreSQL 접근 가능 여부 확인 |
| `MODULE_NOT_FOUND` 오류 | `npm install` 재실행 (온라인) 또는 node_modules 포함 압축본 사용 |