stock-oracle/frontend

📊 Stock Oracle Frontend

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

✨ 주요 기능

🏠 대시보드

• 실시간 시스템 상태 모니터링
• 데이터베이스 통계 요약
• 빠른 액션 버튼
• 데이터 품질 개요

🔍 데이터 조회

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

💾 DB 상태

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

⚙️ 설정

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

🚀 빠른 시작

로컬 개발 환경

# 의존성 설치
cd frontend
npm install

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

# 개발 서버 시작
npm run dev

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

Docker로 실행

# 이미지 빌드
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로 전체 스택 배포

# 전체 스택 배포 (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 설정

# 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

프로덕션 환경

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

📊 API 연동

API 클라이언트

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

// 재무 데이터 조회
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 컴포넌트

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

StockQuery 컴포넌트

// 주식 데이터 조회 폼 및 결과 표시
<StockQuery />

DatabaseStats 컴포넌트

// 데이터베이스 통계 및 상태 모니터링
<DatabaseStats />

🧪 개발 도구

개발 서버

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

타입 체크

npx tsc --noEmit  # TypeScript 타입 체크

🚀 배포

Vercel 배포

# Vercel CLI로 배포
vercel --prod

Docker 배포

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

Portainer 통합 배포

# 전체 스택 배포
./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 연결 실패

# API 서버 상태 확인
curl http://localhost:18001/api/v1/database/stats

# 환경 변수 확인
echo $NEXT_PUBLIC_API_URL

빌드 실패

# 캐시 클리어
rm -rf .next node_modules
npm install
npm run build

Docker 실행 문제

# 포트 충돌 확인
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 파일을 참조하세요.