auto-trade/README.md

# auto-trade

한국투자증권(KIS) Open API와 Supabase 인증을 연결한 국내주식 트레이딩 대시보드입니다.  
사용자는 로그인 후 API 키를 검증하고, 종목 검색/상세/차트/호가/체결/주문 화면을 한 곳에서 사용할 수 있습니다.

## 1) 핵심 기능

- 인증: Supabase 이메일/소셜 로그인, 비밀번호 재설정, 세션 타임아웃 자동 로그아웃
- KIS 연결: 실전/모의 모드 선택, API 키 검증, 웹소켓 승인키 발급
- 트레이드 화면: 종목 검색, 종목 개요, 캔들 차트, 실시간 호가/체결, 현금 주문
- 종목 검색 인덱스: `korean-stocks.json` 기반 고속 검색 + 자동 갱신 스크립트

## 2) 기술 스택

- 프레임워크: Next.js 16 (App Router), React 19, TypeScript
- 상태관리: Zustand
- 서버 상태: TanStack Query (React Query)
- 인증/백엔드: Supabase (`@supabase/ssr`, `@supabase/supabase-js`)
- UI: Tailwind CSS v4, Radix UI, Sonner
- 차트: `lightweight-charts`

## 3) 화면/라우트

- `/`: 서비스 랜딩 페이지
- `/login`, `/signup`, `/forgot-password`, `/reset-password`: 인증 페이지
- `/dashboard`: 로그인 전용(현재 플레이스홀더)
- `/settings`: KIS API 키 연결/해제
- `/trade`: 실제 트레이딩 대시보드

## 4) UI 흐름 (중요)

- 인증 흐름: 로그인 UI -> `features/auth/actions.ts` -> Supabase Auth -> 세션 쿠키 반영 -> 보호 라우트 접근 허용
- KIS 연결 흐름: 설정 UI -> `/api/kis/validate` -> 토큰 발급 성공 확인 -> `use-kis-runtime-store`에 검증 상태 저장
- 실시간 흐름: 트레이드 UI -> `/api/kis/ws/approval` -> `useKisTradeWebSocket` 구독 -> 체결/호가 파싱 -> 차트/호가창 반영
- 검색 흐름: 검색 UI -> `/api/kis/domestic/search` -> `korean-stocks.json` 메모리 검색 -> 결과 목록 반영

## 5) 빠른 시작

### 5-1. 요구 사항

- Node.js 20 이상
- npm 10 이상 권장

### 5-2. 설치

```bash
npm install
```

### 5-3. 환경변수 설정

`.env.example`을 복사해서 `.env.local`을 만듭니다.

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

Windows PowerShell:

```powershell
Copy-Item .env.example .env.local
```

필수 값은 아래를 먼저 채우면 됩니다.

- `NEXT_PUBLIC_SUPABASE_URL`
- `NEXT_PUBLIC_SUPABASE_ANON_KEY`

KIS는 `.env`에 저장하지 않고 `/settings` 입력 폼에서 직접 입력합니다.

- 앱키/시크릿/계좌번호는 사용자 브라우저에서만 관리
- 서버 API는 로그인 세션 + 요청 헤더로 전달된 키가 있어야 동작
- `NEXT_PUBLIC_BASE_URL` (선택, 배포 도메인 사용 시 권장)

### 5-4. 로컬 실행

```bash
npm run dev
```

- 개발 서버: `http://localhost:3001`
- Turbopack 적용: `package.json`의 `dev` 스크립트에 `--turbopack` 포함

### 5-5. 점검 명령

```bash
npm run lint
npm run build
npm run start
```

## 6) 종목 인덱스 동기화

`features/trade/data/korean-stocks.json`은 수동 편집용 파일이 아닙니다.  
KIS 마스터 파일(KOSPI/KOSDAQ)에서 자동 생성합니다.

```bash
npm run sync:stocks
```

검증만 하고 싶으면:

```bash
npm run sync:stocks:check
```

상세 문서: `docs/trade-stock-sync.md`

## 7) API 엔드포인트 요약

- 인증/연결
- `POST /api/kis/validate`: API 키 검증
- `POST /api/kis/revoke`: 토큰 폐기
- `POST /api/kis/ws/approval`: 웹소켓 승인키 발급

- 국내주식
- `GET /api/kis/domestic/search?q=...`: 종목 검색(로컬 인덱스)
- `GET /api/kis/domestic/overview?symbol=...`: 종목 개요
- `GET /api/kis/domestic/orderbook?symbol=...`: 호가
- `GET /api/kis/domestic/chart?symbol=...&timeframe=...`: 차트
- `POST /api/kis/domestic/order-cash`: 현금 주문

## 8) 프로젝트 구조

```text
app/
  (home)/            랜딩
  (auth)/            로그인/회원가입/비밀번호 재설정
  (main)/            로그인 후 화면(dashboard/trade/settings)
  api/kis/           KIS 연동 API 라우트
features/
  auth/              인증 UI/액션/상수
  settings/          KIS 키 설정 UI + 런타임 스토어
  trade/             검색/차트/호가/주문/웹소켓
lib/kis/             KIS REST/WS 공통 로직
scripts/
  sync-korean-stocks.mjs
utils/supabase/      서버/클라이언트/미들웨어 클라이언트
```

## 9) 트러블슈팅

- KIS 검증 실패
- 입력한 앱키/시크릿, 실전/모의 모드가 맞는지 확인
- KIS Open API 앱 권한과 IP 허용 설정 확인

- 실시간 체결/호가가 안 들어옴
- `/settings`에서 검증 상태가 유지되는지 확인
- 장 구간(장중/동시호가/시간외)에 따라 데이터가 달라질 수 있음
- 브라우저 콘솔 디버그가 필요하면 `localStorage.KIS_WS_DEBUG = "1"` 설정

- 검색 결과가 기대와 다름
- 검색은 KIS 실시간 검색 API가 아니라 로컬 인덱스(`korean-stocks.json`) 기반
- 최신 종목 반영이 필요하면 `npm run sync:stocks` 실행

## 10) 운영 주의사항

- 현재 KIS 입력값과 검증 상태 일부는 브라우저 로컬 스토리지(localStorage, 브라우저 저장소)에 저장됩니다.
- 실전 운영 시에는 민감정보 보관 정책(암호화, 만료, 서버 보관 방식)을 반드시 따로 설계하세요.
- 주문은 계좌번호가 필요합니다. 계좌번호 입력/검증 UX는 운영 환경에 맞게 보완이 필요합니다.