코스피 지수 시뮬레이터

전일 종가 기준 코스피 구성종목 데이터를 불러와, 특정 종목의 가격을 임의로 바꿨을 때 코스피 지수가 어떻게 변하는지 보여주는 조회 전용 시뮬레이터입니다. 로그인이나 매수/매도 기능은 없습니다.

동작 방식

1. 사용자가 "최신화" 버튼을 누르면 /api/kospi 라우트가 실행됩니다.
2. 이 라우트는 그 시점에 data.go.kr을 호출하는 얇은 프록시로, 별도의 DB·캐시· 크론 작업 없이 요청 시점의 데이터를 그대로 전달합니다.
   • 금융위원회_지수시세정보에서 최근 영업일의 실제 코스피 종가(지수)를 가져옵니다 (휴일/주말 대비 최근 10일 이내에서 데이터가 있는 날짜를 자동으로 탐색합니다).
   • 금융위원회_주식시세정보에서 같은 기준일자의 전종목 시세를 가져와 시장구분이 KOSPI인 종목만 추립니다.
   • 기준시가총액 = 전체 시가총액 / (실제 코스피 지수 / 100) 공식으로 매일 기준시가총액을 역산(캘리브레이션)합니다.
3. 브라우저는 응답받은 전종목 시세를 상태로 보관하고, 사용자가 특정 종목의 가격을 바꾸면 그 종목만 override된 시가총액으로 교체해 전체 합계와 시뮬레이션 코스피 지수를 즉시 재계산합니다. 나머지 계산은 모두 클라이언트에서 이뤄지며 서버 호출은 발생하지 않습니다.

환경변수

.env.local에 data.go.kr 일반 인증키(Decoding 값)를 설정합니다.

DATA_GO_KR_SERVICE_KEY=발급받은_디코딩_키

⚠️ 아래 두 API 모두 data.go.kr에서 개별적으로 활용신청이 되어 있어야 합니다. 같은 계정이면 서비스키는 동일하지만, API마다 활용신청 절차는 따로 필요합니다.

• 금융위원회_주식시세정보 (GetStockSecuritiesInfoService)
• 금융위원회_지수시세정보 (GetMarketIndexInfoService) — 코스피 지수 캘리브레이션에 필요

로컬 실행

npm install
npm run dev

http://localhost:3000 접속 후 "데이터 불러오기" 버튼을 누르면 API가 정상 동작하는지 확인할 수 있습니다.

배포 (Vercel)

1. GitHub 저장소를 Vercel 프로젝트로 연결합니다.
2. Vercel 프로젝트 설정 → Environment Variables에 DATA_GO_KR_SERVICE_KEY를 등록합니다. (클라이언트에 노출되지 않는 서버 전용 환경변수입니다.)
3. 별도의 DB, Blob/KV 스토리지, Cron Job 설정은 필요하지 않습니다.

알려진 제약

• data.go.kr 개발계정은 하루 10,000건 트래픽 제한이 있습니다. "최신화" 클릭 1회당 API 호출이 여러 번(지수 1회 + 종목 시세 페이지네이션 수회) 발생하므로, 트래픽이 늘어나면 운영계정 전환이나 클릭 디바운스를 검토해야 합니다.
• 데이터는 전일 종가 기준이며 장중 실시간 시세가 아닙니다.
• mrktCtg가 KOSPI인 전종목을 지수 구성종목으로 간주하는 근사치이며, KRX의 공식 지수 산출 방법론(우선주/제외종목 처리 등)과 완전히 일치하지 않을 수 있습니다. 투자 판단에 사용할 수 없는 교육·시뮬레이션 목적의 도구입니다.