goldenChart/frontend_golden/ENVIRONMENT_SETUP.md

# 프론트엔드 환경 설정 가이드

## 📋 환경별 설정

### 1. 로컬 개발 환경 (Development)

**실행 방법:**
```bash
npm start
# 또는 Windows에서
npm run start:win
```

**접속 URL:**
- 프론트엔드: `http://localhost:3100`

**자동 연결되는 서비스:**
- 백엔드 API: `http://localhost:8083/api` (로컬 Docker)
- Market Data WebSocket: `wss://exdev.co.kr/market-data/ws/chart` (서버)
- Backend WebSocket: `ws://localhost:8083/ws` (로컬 Docker)

**환경 변수 파일:** `.env.development`, `.env.local`

**특징:**
- Hot Reload 지원 (코드 수정 시 자동 새로고침)
- 소스맵 포함 (디버깅 용이)
- 개발자 도구 활성화
- **WebSocket Data Service는 서버(exdev.co.kr)에서 실행 중**

---

### 2. 로컬 프로덕션 빌드 (Local Production Build)

**빌드 방법:**
```bash
npm run build
```

**실행 방법:**
```bash
# serve 패키지 설치 (한 번만)
npm install -g serve

# 빌드된 파일 서빙 (포트 3100)
serve -s build -l 3100
```

**접속 URL:**
- 프론트엔드: `http://localhost:3100`

**자동 연결되는 서비스:**
- 백엔드 API: `http://localhost:8083/api` (로컬 Docker)
- Market Data WebSocket: `wss://exdev.co.kr/market-data/ws/chart` (서버)
- Backend WebSocket: `ws://localhost:8083/ws` (로컬 Docker)

**환경 변수 파일:** `.env.production.local` (없으면 코드에서 자동 감지)

**특징:**
- 최적화된 프로덕션 빌드
- 코드 압축 및 난독화
- **WebSocket Data Service는 서버(exdev.co.kr)에서 실행 중**

---

### 3. 서버 배포 환경 (Production on Server)

**빌드 방법:**
```bash
npm run build
```

**배포 방법:**
```bash
# Docker 이미지 빌드 및 배포
docker-compose build frontend
docker-compose up -d frontend
```

**접속 URL:**
- 프론트엔드: `https://exdev.co.kr` (HTTPS, 포트 443)
- 또는: `http://exdev.co.kr` (HTTP, 포트 80)

**nginx 프록시를 통해 연결되는 서비스:**
- 백엔드 API: `https://exdev.co.kr/api` → `backend:8083/api`
- Market Data WebSocket: `wss://exdev.co.kr/market-data/ws/chart` → `market-data-system:8086/ws/chart`
- Backend WebSocket: `wss://exdev.co.kr/ws` → `backend:8083/ws`

**환경 변수 파일:** `.env.production`

**특징:**
- nginx 리버스 프록시 사용
- SSL/TLS 암호화 (HTTPS)
- 모든 서비스가 443 포트를 통해 접근
- 외부 네트워크에서 접근 가능

---

## 🔧 환경 감지 로직

### API Base URL (`apiConfig.ts`)

```typescript
export const getApiBaseUrl = (): string => {
  const isLocalhost = window.location.hostname === 'localhost' || 
                      window.location.hostname === '127.0.0.1' ||
                      window.location.hostname === '';
  
  if (isLocalhost) {
    // 로컬: 직접 연결
    return 'http://localhost:8083/api';
  }
  
  // 서버: nginx 프록시 (상대 경로)
  return '/api';
};
```

### Market Data WebSocket URL (`useMarketDataWebSocket.ts`)

```typescript
const getMarketDataUrl = (): string => {
  const isLocalhost = window.location.hostname === 'localhost' || 
                      window.location.hostname === '127.0.0.1' ||
                      window.location.hostname === '';
  
  if (isLocalhost) {
    // 로컬: 직접 연결
    return 'http://localhost:8086';
  }
  
  // 서버: nginx 프록시
  const protocol = window.location.protocol === 'https:' ? 'https:' : 'http:';
  return `${protocol}//${window.location.host}/market-data`;
};
```

**핵심:** `window.location.hostname`을 기준으로 자동 감지하므로, 환경 변수 없이도 동작합니다!

---

## 📁 환경 변수 파일 우선순위

React는 다음 순서로 환경 변수 파일을 로드합니다:

1. `.env.development.local` (개발 환경, git 무시)
2. `.env.production.local` (프로덕션 환경, git 무시)
3. `.env.local` (모든 환경, git 무시)
4. `.env.development` (개발 환경)
5. `.env.production` (프로덕션 환경)
6. `.env` (모든 환경)

**현재 프로젝트:**
- `.env` - 기본 포트 설정
- `.env.local` - 로컬 개발 설정
- `.env.development` - 개발 환경 설정
- `.env.production` - 프로덕션 환경 설정 (주석만, 실제로는 코드에서 자동 감지)

---

## 🚀 시나리오별 사용법

### 시나리오 1: 로컬에서 개발

```bash
# 1. 백엔드 서비스 실행 (Docker)
docker-compose up -d backend market-data-system

# 2. 프론트엔드 개발 서버 실행
cd frontend
npm start

# 3. 브라우저에서 접속
# http://localhost:3100
```

### 시나리오 2: 로컬에서 프로덕션 빌드 테스트

```bash
# 1. 백엔드 서비스 실행 (Docker)
docker-compose up -d backend market-data-system

# 2. 프론트엔드 빌드
cd frontend
npm run build

# 3. 빌드된 파일 서빙
serve -s build -l 3100

# 4. 브라우저에서 접속
# http://localhost:3100
```

### 시나리오 3: 서버에 배포

```bash
# 1. 전체 서비스 빌드 및 배포
docker-compose build
docker-compose up -d

# 2. 외부에서 접속
# https://exdev.co.kr
```

---

## 🔍 트러블슈팅

### 문제: 로컬에서 API 연결 안 됨

**확인 사항:**
1. 백엔드 서비스가 실행 중인지 확인
   ```bash
   docker-compose ps
   ```

2. 포트가 열려있는지 확인
   ```bash
   # Windows
   netstat -ano | findstr :8083
   netstat -ano | findstr :8086
   ```

3. 브라우저 콘솔에서 URL 확인
   ```
   [API Config] 로컬 환경 감지: http://localhost:8083/api
   [Market Data] WebSocket URL: ws://localhost:8086/ws/chart
   ```

### 문제: 서버에서 WebSocket 연결 안 됨

**확인 사항:**
1. nginx 설정 확인
   ```bash
   docker-compose exec frontend nginx -t
   ```

2. nginx 로그 확인
   ```bash
   docker-compose logs frontend
   ```

3. 브라우저 콘솔에서 URL 확인
   ```
   [Market Data] WebSocket URL: wss://exdev.co.kr/market-data/ws/chart
   ```

### 문제: Mixed Content 오류 (HTTP/HTTPS)

**원인:** HTTPS 페이지에서 HTTP 리소스 로드 시도

**해결:**
- 로컬: `http://localhost` 사용 (HTTPS 불필요)
- 서버: 모든 연결이 HTTPS/WSS로 자동 변환됨

---

## 📝 체크리스트

### 로컬 개발 시작 전
- [ ] Docker Desktop 실행 중
- [ ] `docker-compose up -d backend market-data-system` 실행
- [ ] `npm install` 완료
- [ ] 포트 3100, 8083, 8086 사용 가능

### 서버 배포 전
- [ ] 프로덕션 빌드 테스트 완료
- [ ] nginx 설정 확인
- [ ] SSL 인증서 유효
- [ ] 방화벽 443 포트 오픈

---

## 🎯 요약

| 환경 | 접속 URL | 백엔드 API | Market Data WS | 특징 |
|------|---------|-----------|----------------|------|
| **로컬 개발** | `http://localhost:3100` | `http://localhost:8083` | `wss://exdev.co.kr/market-data` | Hot Reload, 서버 WS |
| **로컬 빌드** | `http://localhost:3100` | `http://localhost:8083` | `wss://exdev.co.kr/market-data` | 최적화 빌드, 서버 WS |
| **서버 배포** | `https://exdev.co.kr` | `https://exdev.co.kr/api` | `wss://exdev.co.kr/market-data` | nginx 프록시 |

**핵심:** 
- 백엔드 API는 로컬/서버 환경에 따라 자동 감지
- **WebSocket Data Service는 항상 서버(exdev.co.kr) 사용** 🚀
- 별도 설정 없이 어디서든 동작합니다!