goldenChat base source add

2026-05-23 15:11:48 +09:00
commit a4ea7762b5
2081 changed files with 1155760 additions and 0 deletions
@@ -0,0 +1,284 @@
+# 프론트엔드 환경 설정 가이드
+
+## 📋 환경별 설정
+
+### 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) 사용** 🚀
+- 별도 설정 없이 어디서든 동작합니다!