# 📊 Stock Oracle Frontend

React + Next.js로 구축된 Stock Oracle 웹 프론트엔드입니다.

## ✨ 주요 기능

### 🏠 대시보드
- 실시간 시스템 상태 모니터링
- 데이터베이스 통계 요약
- 빠른 액션 버튼
- 데이터 품질 개요

### 🔍 데이터 조회
- 주식 종목별 재무 데이터 검색
- 분기별/연간/전체 기간 조회
- 실제 vs 추정 데이터 표시
- 재무 지표 계산 결과 포함

### 💾 DB 상태
- 데이터베이스 현황 실시간 모니터링
- 회사, 재무 데이터, 주가 데이터 통계
- 데이터 소스별 분포
- 데이터 품질 분석

### ⚙️ 설정
- API URL 설정
- 자동 새로고침 옵션
- UI 테마 선택
- 시스템 정보 확인

## 🚀 빠른 시작

### 로컬 개발 환경

```bash
# 의존성 설치
cd frontend
npm install

# 환경 변수 설정
cp .env.example .env.local

# 개발 서버 시작
npm run dev
```

웹 브라우저에서 `http://localhost:3000` 접속

### Docker로 실행

```bash
# 이미지 빌드
docker build -t stock-oracle-frontend .

# 컨테이너 실행
docker run -p 3000:3000 -e NEXT_PUBLIC_API_URL=http://localhost:18001/api/v1 stock-oracle-frontend
```

### Portainer로 전체 스택 배포

```bash
# 전체 스택 배포 (API + Frontend + DB + Nginx)
docker-compose -f portainer/docker-compose.full-stack.yml up -d
```

접속 URL: `https://localhost` (Nginx를 통한 통합 접속)

## 🛠️ 기술 스택

### Frontend Framework
- **Next.js 14** - React 메타 프레임워크
- **React 18** - UI 라이브러리
- **TypeScript** - 타입 안전성

### Styling & UI
- **Tailwind CSS** - 유틸리티 CSS 프레임워크
- **Lucide React** - 아이콘 라이브러리
- **Responsive Design** - 모바일 친화적 디자인

### Data Management
- **Axios** - HTTP 클라이언트
- **React Query** - 서버 상태 관리
- **SWR 패턴** - 데이터 페칭 전략

### Charts & Visualization
- **Recharts** - React 차트 라이브러리
- **Date-fns** - 날짜 처리

## 📁 프로젝트 구조

```
frontend/
├── components/          # 재사용 가능한 컴포넌트
│   ├── Layout.tsx      # 메인 레이아웃
│   ├── StockQuery.tsx  # 주식 데이터 조회
│   └── DatabaseStats.tsx # DB 상태 모니터링
├── lib/                # 유틸리티 및 설정
│   └── api.ts          # API 클라이언트 및 타입
├── pages/              # Next.js 페이지
│   ├── index.tsx       # 대시보드
│   ├── query.tsx       # 데이터 조회
│   ├── database.tsx    # DB 상태
│   └── settings.tsx    # 설정
├── styles/             # 스타일시트
│   └── globals.css     # 글로벌 CSS
└── public/             # 정적 파일
```

## 🔧 환경 변수

### .env.local 설정

```bash
# API 설정
NEXT_PUBLIC_API_URL=http://localhost:18001/api/v1

# 애플리케이션 설정
NEXT_PUBLIC_APP_NAME=Stock Oracle
NEXT_PUBLIC_APP_VERSION=1.0.0

# 기능 플래그
NEXT_PUBLIC_ENABLE_ANALYTICS=false
NEXT_PUBLIC_ENABLE_PWA=false
```

### 프로덕션 환경

```bash
# Docker 환경에서 자동 설정
NEXT_PUBLIC_API_URL=http://api:8000/api/v1
NODE_ENV=production
```

## 📊 API 연동

### API 클라이언트

`lib/api.ts`에서 모든 API 호출을 관리합니다:

```typescript
// 재무 데이터 조회
const data = await stockApi.getFinancialData({
  ticker: 'AAPL',
  start_date: '2024-01-01',
  end_date: '2024-12-31',
  period_type: 'quarterly',
  include_metrics: true
});

// 데이터베이스 통계 조회
const stats = await stockApi.getDatabaseStats();
```

### 주요 API 엔드포인트

- `POST /api/v1/financial/data` - 재무 데이터 조회
- `POST /api/v1/price/data` - 주가 데이터 조회
- `GET /api/v1/database/stats` - DB 통계
- `GET /api/v1/tickers` - 사용 가능한 종목 목록

## 🎨 UI/UX 특징

### 반응형 디자인
- **Desktop First**: 대형 화면 우선 설계
- **Mobile Optimized**: 모바일 기기 완벽 지원
- **Tablet Friendly**: 태블릿 환경 최적화

### 사용자 경험
- **직관적 네비게이션**: 명확한 메뉴 구조
- **실시간 피드백**: 로딩 상태 및 에러 처리
- **데이터 시각화**: 차트와 그래프로 이해하기 쉬운 표현

### 접근성
- **키보드 네비게이션**: 키보드만으로 모든 기능 접근
- **Screen Reader**: 스크린 리더 지원
- **고대비 모드**: 시각적 접근성 고려

## 🔍 주요 컴포넌트

### Layout 컴포넌트
```typescript
// 전체 레이아웃 및 네비게이션
<Layout title="Stock Oracle - 대시보드">
  {children}
</Layout>
```

### StockQuery 컴포넌트
```typescript
// 주식 데이터 조회 폼 및 결과 표시
<StockQuery />
```

### DatabaseStats 컴포넌트
```typescript
// 데이터베이스 통계 및 상태 모니터링
<DatabaseStats />
```

## 🧪 개발 도구

### 개발 서버
```bash
npm run dev     # 개발 서버 시작
npm run build   # 프로덕션 빌드
npm run start   # 프로덕션 서버 시작
npm run lint    # ESLint 실행
```

### 타입 체크
```bash
npx tsc --noEmit  # TypeScript 타입 체크
```

## 🚀 배포

### Vercel 배포
```bash
# Vercel CLI로 배포
vercel --prod
```

### Docker 배포
```bash
# 이미지 빌드 및 배포
docker build -t stock-oracle-frontend .
docker run -p 3000:3000 stock-oracle-frontend
```

### Portainer 통합 배포
```bash
# 전체 스택 배포
./portainer/quick-deploy.sh
```

## 📱 브라우저 지원

- **Chrome** 90+
- **Firefox** 88+
- **Safari** 14+
- **Edge** 90+

## 🔒 보안 고려사항

### API 통신
- **HTTPS Only**: 프로덕션에서 HTTPS 강제
- **CORS 설정**: 적절한 CORS 정책
- **Rate Limiting**: API 호출 제한

### 데이터 보호
- **입력 검증**: 모든 사용자 입력 검증
- **XSS 방지**: React의 기본 XSS 보호
- **CSRF 방지**: SameSite 쿠키 설정

## 🐛 문제 해결

### 일반적인 문제

#### API 연결 실패
```bash
# API 서버 상태 확인
curl http://localhost:18001/api/v1/database/stats

# 환경 변수 확인
echo $NEXT_PUBLIC_API_URL
```

#### 빌드 실패
```bash
# 캐시 클리어
rm -rf .next node_modules
npm install
npm run build
```

#### Docker 실행 문제
```bash
# 포트 충돌 확인
netstat -tlnp | grep 3000

# 컨테이너 로그 확인
docker logs stock-oracle-frontend
```

## 📈 성능 최적화

### 이미지 최적화
- **Next.js Image**: 자동 이미지 최적화
- **WebP 지원**: 최신 이미지 포맷 사용

### 코드 분할
- **Dynamic Import**: 필요할 때만 컴포넌트 로드
- **Tree Shaking**: 사용하지 않는 코드 제거

### 캐싱 전략
- **Static Generation**: 정적 페이지 생성
- **API Cache**: React Query로 API 응답 캐싱

## 🤝 기여 가이드

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

## 📄 라이선스

MIT License - 자세한 내용은 LICENSE 파일을 참조하세요.