인증 흐름: 로그인 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. 설치

npm install

5-3. 환경변수 설정

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

cp .env.example .env.local

Windows 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. 로컬 실행

npm run dev

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

5-5. 점검 명령

npm run lint
npm run build
npm run start

6) 종목 인덱스 동기화

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

npm run sync:stocks

검증만 하고 싶으면:

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) 프로젝트 구조

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는 운영 환경에 맞게 보완이 필요합니다.