You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
309 lines
7.0 KiB
Markdown
309 lines
7.0 KiB
Markdown
# 📊 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 파일을 참조하세요. |