KRX 수급 데이터 연동 PRD

배경 (Background)

현재 주식앱은 토스증권 Open API 기반으로 가격·호가·체결·캔들만 확보한다.
토스 Open API 전체 명세(Auth / Market Data / Stock Info / Market Info / Account·Asset / Order 6개 카테고리)를 확인한 결과, 투자자별 매매 동향(외국인·기관 수급) 엔드포인트가 없다. investor / foreign / institution path가 존재하지 않는다.
추천 종목 산정은 현재 기술 모멘텀·뉴스 감성 중심이다. 외국인·기관 수급, 밸류에이션, 공매도·신용 같은 시장 미시구조 데이터가 빠져 있어 중기 시그널의 근거가 약하다.
이 데이터는 KRX 정보데이터시스템(data.krx.co.kr, MDC)에서 EOD(장 마감 기준)로 제공된다.

목표

KRX에서 외국인·기관 수급, 외국인 보유율, 밸류에이션, 공매도, 신용잔고를 전종목·일 단위로 수집·영속화한다.
수집한 데이터를 추천 종목 산정 팩터로 제공한다 (ml 추천 스코어링 입력).
KRX 스크래핑의 사이드 이펙트(차단·잠정치 노이즈·약관 리스크)를 통제한다.

요구사항

ID	요구사항	우선순위
R-01	투자자별 거래실적(개인·외국인·기관 종목별 순매수)을 일 단위로 수집·저장한다	P0
R-02	외국인 보유량·보유율·한도소진율을 일 단위로 수집·저장한다	P0
R-03	전종목 PER·PBR·배당수익률을 일 단위로 수집·저장한다	P1
R-04	공매도 거래·잔고를 일 단위로 수집·저장한다 (공시 시차 반영)	P1
R-05	신용거래 잔고를 일 단위로 수집·저장한다	P1
R-06	장 마감 후 1일 1회 배치로 전종목을 수집한다 (실시간 수집 미수행)	P0
R-06b	필요 타이밍에 수동으로 수집을 트리거하는 갱신 API를 제공한다 (멱등)	P0
R-07	KRX 호출은 OTP 토큰 발급(bld→getJsonData) 구조를 따르고, 재시도·백오프·rate 제어로 차단을 회피한다	P0
R-08	종목·기준일별 수급 팩터를 조회하는 read API를 제공한다 (추천 스코어링 소비용)	P0
R-09	추천 스코어링이 KRX 팩터를 입력으로 반영한다	P1
R-10	일부 KRX 통계 수집이 실패해도 나머지는 적재한다 (부분 실패 허용)	P1
R-11	배치 실행 결과(run별·통계별 상태·행수·소요·에러)를 영속 기록하고, 실패·부분 실패 시 Discord로 알린다	P0
R-12	수집 행수·소요·재시도 등 메트릭을 계측해, 청크 기반 배치로 전환할 임계 시그널을 관측한다	P1

사용자 시나리오

시나리오 1: 마감 후 수급 적재

장 마감 후 배치 스케줄러가 기동한다.
KRX에서 투자자별 거래실적·외국인 보유·밸류에이션·공매도·신용을 순차 수집한다.
전종목 데이터를 기준일과 함께 MySQL에 upsert한다.
일부 통계 수집이 실패하면 해당 항목만 건너뛰고 나머지를 적재한다.

시나리오 2: 수동 갱신

확정치 게시 지연·데이터 누락·당일 재수집이 필요한 상황에서 운영자가 수동 갱신 API를 호출한다.
자동 스케줄러와 동일한 수집 로직이 실행된다.
기준일(baseDate)을 지정하거나 미지정 시 직전 영업일로 수집한다.
멱등 upsert라 동일 기준일 재호출이 안전하다.

시나리오 3: 추천 산정에 수급 반영

추천 스코어링이 후보 종목의 기준일별 수급 팩터를 BE read API로 조회한다.
외국인·기관 연속 순매수, 외국인 보유율 추세, 저PER·저PBR, 공매도 잔고비중, 신용잔고 과열을 스코어 가중에 반영한다.
KRX 팩터가 없으면(미수집) 해당 가중을 제외하고 graceful하게 산정한다.

세부 정책

정책 1: 수집 주기 — 마감 후 1일 1배치

KRX 데이터는 EOD 확정치다. 장중 잠정치는 다음 날 확정치와 어긋난다.
실시간 폴링은 새 정보가 없고 차단·노이즈 리스크만 크므로 수행하지 않는다.
투자자별 거래실적 확정치 게시(보통 18~19시 KST) 이후 배치를 실행한다.

정책 2: 공매도 공시 시차

공매도 거래는 T+1, 공매도 잔고는 T+2에 공시된다.
저장 시 거래일(기준일) 과 공시일을 구분해, 수급 팩터 조회 시 거래일 기준으로 정렬한다.

정책 3: 부분 실패 허용

5종 통계 중 일부 수집이 실패해도 트랜잭션을 통째로 롤백하지 않는다.
통계 단위로 적재하고, 실패 항목은 로그로 남긴다.

정책 4: 사이드 이펙트 통제

호출 간 간격·재시도·백오프를 두고, 1배치로 끝낸다.
KRX 스크래핑은 약관 회색지대임을 인지하고 고빈도 호출을 금지한다.

정책 5: 모니터링과 청크 전환 시그널

배치 run마다 통계별 상태·행수·소요·에러를 marketflow_collect_log에 남긴다 (관측 스택과 무관하게 동작).
실패·부분 실패 시 Discord로 즉시 알린다 (마감 후 배치라 사람이 실시간으로 못 봄).
수집 행수·소요·heap·재시도를 메트릭으로 계측해 Grafana 대시보드/알람으로 추세를 관측한다.
임계(단일 통계 5만 행, 전체 5분, 단일 통계 2분, 벌크 upsert 30초, heap 압박, 잦은 부분 실패/429) 지속 초과는 Spring Batch(청크·restart·partition) 전환 신호로 본다.

범위 외

실시간 수급 수집 (정책 1)
FE 화면 표시 — 본 과제는 데이터 수집·적재·추천 입력까지. UI 노출은 별도 과제.
KRX 공식 유료 데이터벤더 연동 (스크래핑으로 시작, 차단·약관 이슈 발생 시 재검토)
프로그램매매·대차잔고 (1차 스코프 제외, 효과 확인 후 확장)

관련 문서