# 연철s 포트폴리오 어드민

개인 포트폴리오 웹사이트를 관리하기 위한 관리자 대시보드입니다. Next.js와 VisActor를 활용하여 현대적이고 직관적인 인터페이스를 제공합니다.

## 기능

- 📊 **포트폴리오 관리** - 프로젝트, 기술 스택, 경력 등 포트폴리오 콘텐츠 관리
- 📝 **콘텐츠 에디터** - 마크다운 기반의 풍부한 텍스트 에디터
- 🌗 **다크 모드** - 시스템 환경설정을 지원하는 다크/라이트 모드
- 📱 **반응형 디자인** - 모든 디바이스에서 사용 가능
- 🔒 **인증 시스템** - 관리자 로그인
- 📈 **데이터 시각화** - 포트폴리오 방문자 통계 및 분석

## 기술 스택

- [Next.js 15.0.1](https://nextjs.org/) - React 프레임워크
- [React 19.0.0-rc](https://react.dev/) - UI 라이브러리
- [TypeScript 5.5.4](https://www.typescriptlang.org/) - 타입 안정성
- [Tailwind CSS 3.4.1](https://tailwindcss.com/) - 스타일링
- [VisActor 1.12.10](https://visactor.io/) - 데이터 시각화
- [Supabase 2.49.4](https://supabase.com/) - 백엔드 및 데이터베이스
- [AWS S3 SDK 3.812.0](https://aws.amazon.com/s3/) - 파일 스토리지
- [React Hook Form 7.56.4](https://react-hook-form.com/) - 폼 관리
- [SWR 2.3.3](https://swr.vercel.app/) - 데이터 페칭
- [Jotai 2.10.1](https://jotai.org/) - 상태 관리
- [React Markdown 10.1.0](https://github.com/remarkjs/react-markdown) - 마크다운 렌더링
- [Next Themes 0.3.0](https://github.com/pacocoursey/next-themes) - 테마 관리
- [React Hot Toast 2.5.2](https://react-hot-toast.com/) - 토스트 알림
- [Radix UI 2.1.1](https://www.radix-ui.com/) - 접근성 컴포넌트
- [Lucide React 0.436.0](https://lucide.dev/) - 아이콘
- [Date-fns 3.6.0](https://date-fns.org/) - 날짜 유틸리티

## 시작하기

1. 저장소를 클론합니다

```bash
git clone https://github.com/your-username/portfolio-admin.git
cd portfolio-admin
```

2. 의존성을 설치합니다

```bash
pnpm install
```

3. 환경 변수를 설정합니다

```bash
cp .env.example .env.local
```

4. 개발 서버를 실행합니다

```bash
pnpm dev
```

5. 브라우저에서 [http://localhost:3000](http://localhost:3000)을 열어 확인합니다.

## 프로젝트 구조

```bash
src/
├── app/                    # Next.js 앱 라우터
│   ├── (auth)/            # 인증 관련 페이지
│   ├── (dashboard)/       # 대시보드 페이지
│   └── api/               # API 라우트
├── components/            # React 컴포넌트
│   ├── dashboard/        # 대시보드 컴포넌트
│   ├── editor/          # 에디터 컴포넌트
│   ├── forms/           # 폼 컴포넌트
│   └── ui/              # UI 컴포넌트
├── lib/                  # 유틸리티 함수
├── styles/              # 전역 스타일
└── types/               # TypeScript 타입
```

## 주요 기능 상세

### 포트폴리오 관리

- 프로젝트 CRUD 작업
- 마크다운 콘텐츠 미리보기
- 프로젝트 상태 관리
- 프로젝트 이미지 업로드
- 기술 스택 관리

### 콘텐츠 에디터

- 마크다운 지원
- 이미지 업로드
- 코드 하이라이팅
- 실시간 미리보기

### 데이터 시각화

- 방문자 통계
- 페이지별 조회수
- 사용자 행동 분석
- 트래픽 소스 분석

## 라이선스

이 프로젝트는 MIT 라이선스 하에 있습니다 - 자세한 내용은 [LICENSE](LICENSE) 파일을 참조하세요.


제가 작업헀던 내용을 정리하기 위해 제작한 개인 포트폴리오 사이트입니다.

Next.js

React.js

TypeScript

TailwindCSS

Node.js

JavaScript

supabase

포트폴리오 프로젝트

# 📈 Stock AI Platform 프로젝트 소개

## 📋 개요

`stock-ai-platform`은 **국내/해외 주식 데이터를 실시간으로 조회하고, AI 기반 분석 및 추천을 제공하는 대시보드형 웹 서비스**입니다.  
KIS Open API를 통해 종목 데이터를 수집하고, Groq LLM으로 뉴스 컨텍스트 기반 인사이트를 생성해 투자 판단에 참고할 수 있는 정보를 제공합니다.

---

## 🛠️ 기술 스택

### Core Technologies

- **Next.js 16.1.6 (App Router)** - 풀스택 웹 애플리케이션 프레임워크
- **React 19.2.3** - UI 컴포넌트 기반 렌더링
- **TypeScript 5.x** - 정적 타입 시스템
- **TanStack Query 5.x** - 서버 상태 캐싱/동기화

### Data & AI

- **KIS Open API** - 국내/해외 종목 시세 및 랭킹 데이터 소스
- **Groq SDK** - 종목 분석 및 추천 생성 LLM 호출
- **SerpAPI / Bing News / Yahoo Finance** - 뉴스 컨텍스트 수집(폴백 체인)
- **Supabase** - KIS 액세스 토큰 저장 및 분산 락 기반 갱신(선택 사용)

### UI & Visualization

- **Tailwind CSS 4** - 유틸리티 기반 스타일링
- **lightweight-charts** - 가격 히스토리 차트 렌더링
- **lucide-react** - 아이콘 시스템

### Testing & Quality

- **Vitest + Testing Library + jsdom** - 단위/컴포넌트 테스트
- **Playwright** - E2E 시나리오 테스트
- **ESLint 9 + eslint-config-next** - 코드 품질 관리

---

## ⚡ 주요 기능

### 1) 국내/해외 주식 대시보드

- 기본 진입 시 `/domestic`으로 리다이렉트
- 탭 기반으로 국내/해외 시장 전환
- 국내 종목은 **거래량/거래대금 기준 TOP 20** 필터 지원
- 종목 선택 시 우측 패널에서 AI 분석 결과 확인

### 2) 통합 종목 검색

- 종목명/티커 기준 `search` 페이지 제공
- 국내/해외 결과를 통합 조회
- 검색 결과에서 바로 AI 분석 실행 가능

### 3) AI 종목 분석 (Streaming)

- `POST /api/stock-analysis`를 통해 분석 결과를 스트리밍 텍스트로 수신
- 가격 히스토리 + 변동률 + 뉴스 컨텍스트를 함께 프롬프트로 전달
- 결과는 `Bullish/Bearish/Neutral`, 핵심 요약, 상승/하락 요인, 리스크 등 구조화된 JSON 포맷 기준으로 생성

### 4) AI 추천 TOP 3

- `POST /api/recommendations`에서 종목 후보군을 정량 점수로 1차 필터링
- 모멘텀/변동률 기반 `quantScore` 상위 후보 + 뉴스 컨텍스트를 결합해 추천 생성
- LLM 실패 시 정량 점수 기반 fallback 추천으로 서비스 연속성 보장
- 대시보드에서 5분 주기로 추천 자동 갱신

### 5) 안정적인 KIS 토큰 관리

- 토큰 발급/갱신 로직을 서비스 레이어로 분리
- Supabase 설정 시 `kis_tokens` 테이블 기반 분산 락으로 동시 갱신 충돌 완화
- Supabase 미설정 환경에서는 메모리 캐시 폴백으로 동작

---

## 🔌 주요 API 엔드포인트

| 엔드포인트 | 메서드 | 설명 |
| --- | --- | --- |
| `/api/stocks` | `GET` | 시장별 종목 리스트 조회 (`market`, `ranking`) |
| `/api/stocks/search` | `GET` | 종목명/티커 검색 (`q` 또는 `query`) |
| `/api/stocks/item` | `GET` | 특정 종목 상세 조회 (`id`) |
| `/api/stock-analysis` | `POST` | 단일 종목 AI 분석 스트리밍 |
| `/api/recommendations` | `POST` | 시장별 AI 추천 종목 반환 |

---

## 🔐 환경 변수

| 키 | 용도 |
| --- | --- |
| `GROQ_API_KEY` | AI 분석/추천 LLM 호출 |
| `SERPAPI_KEY` | 뉴스 컨텍스트 1순위 수집 |
| `BING_NEWS_KEY` | 뉴스 컨텍스트 2순위 수집 |
| `KIS_APP_KEY` | KIS API 인증 |
| `KIS_APP_SECRET` | KIS API 인증 |
| `KIS_BASE_URL` | KIS API Base URL |
| `SUPABASE_URL` | 토큰 저장소(Supabase) 연결 |
| `SUPABASE_SERVICE_ROLE_KEY` | Supabase 서버 권한 키 |

---

## 🧪 테스트 및 개발 경험

### 테스트 구성

- API 라우트 테스트: `src/app/api/**/*.test.ts`
- 서비스 레이어 테스트: `src/services/*.test.ts`
- UI/훅 테스트: `src/components/**/*.test.tsx`, `src/hooks/*.test.tsx`
- E2E 테스트: `e2e/stock-flows.spec.ts`

### 실행 스크립트

- `pnpm dev` - 개발 서버 실행
- `pnpm test` - Vitest 실행
- `pnpm coverage` - 커버리지 리포트 생성
- `pnpm e2e` - Playwright E2E 실행

---

## 🎯 프로젝트 가치

- 실시간 주식 데이터와 AI 인사이트를 한 화면에서 제공해 탐색 시간을 단축
- 국내/해외 시장을 통합해 비교 분석 경험을 개선
- 외부 API 실패 상황에서도 fallback 경로를 갖춘 안정적인 사용자 경험 제공


성 연 철

#JavaScript