키움 REST API 퀀트 리밸런싱 웹 UI 완성 — 실제 화면 공개 [Claude Code · 키움리밸런싱 · 9편]

Python FastAPI 키움API 퀀트전략 웹UI

키움 REST API 퀀트 리밸런싱 웹 UI 완성
— 실제 화면 공개

종목교체 설정, 미리보기, 스케줄 진단까지 — 실제 동작 화면 스크린샷

V2 웹 UI 패널 구성

V2는 V1 UI를 그대로 확장해 9개 패널로 구성됩니다. V1과 동일한 패널은 그대로 유지하고, 퀀트 전용 패널 1개를 추가했습니다.

패널	구분	주요 기능
로그인	공통	키움 API 토큰 발급, 계좌 선택
계좌 현황	강화	보유 종목 + 평가손익 색상 표시 (V2 추가)
종목교체 설정	V2 신규	목표 종목 입력, 미리보기 (A-B/A∩B/B-A)
스케줄 설정	강화	실행 진단 + 예약 실행 + 모드 전환 (V2 추가)
자동매매	공통	수동 실행, 실시간 로그
주문 현황	공통	접수/체결 현황
이력	공통	리밸런싱 이력, CSV 내보내기
대시보드	공통	TWR 수익률, 포트폴리오 차트, 배당금
알림 설정	공통	텔레그램 봇 연동

계좌 현황 — 수익률 색상 표시

V2에서 추가된 기능입니다. 보유 종목별 평가손익과 수익률을 색상으로 구분해 보여줍니다.

계좌 현황 패널 — 종목별 평가손익을 파란색(+)/빨간색(-) 색상으로 구분

총 평가손익과 수익률은 API 응답에서 직접 계산합니다.

프론트엔드에서 색상을 분기하는 이유: 백엔드에서 CSS 클래스 이름을 내려보내면 API 응답과 UI 로직이 결합됩니다. 숫자만 내려보내고 색상은 JS에서 처리하는 것이 더 유연합니다.

function _setProfitEls(amtId, rateId, amount, rate) {
  const sign = amount >= 0 ? '+' : '';
  const cls  = amount > 0 ? 'up' : amount < 0 ? 'dn' : '';
  amtEl.textContent  = sign + fmt(amount) + '원';
  amtEl.className    = 'value ' + cls;
  rateEl.textContent = sign + rate.toFixed(2) + '%';
  rateEl.className   = 'value ' + cls;
}

종목교체 설정 패널 — 목표 종목 입력 & 미리보기

V2에서 가장 핵심적인 신규 패널입니다. 텍스트 붙여넣기와 CSV 파일 업로드 두 가지 방식으로 목표 종목을 입력할 수 있습니다.

종목교체 설정 패널 — 텍스트/CSV 입력 후 A-B/A∩B/B-A 미리보기

텍스트 붙여넣기

엑셀에서 종목코드 열을 복사해 붙여넣으면 됩니다. 줄바꿈, 탭, 쉼표 모두 지원합니다.

정규식으로 6자리 숫자만 추출하는 이유: 엑셀 붙여넣기 시 종목명, 빈 행, 헤더 텍스트가 섞일 수 있습니다. r'\b\d{6}\b'로 6자리 코드만 골라냅니다.

def parse_text_input(text: str) -> list[str]:
    import re
    return re.findall(r'\b\d{6}\b', text)

CSV 파일 업로드

엑셀에서 저장한 CSV를 업로드합니다. 헤더 유무를 자동 감지하고, 한글 인코딩(CP949)도 처리합니다.

def parse_csv_input(csv_content: str) -> list[str]:
    rows = list(csv.reader(io.StringIO(csv_content)))
    # 첫 행이 숫자 6자리인지 확인 → 아니면 헤더로 간주
    has_header = not re.match(r'^\d{6}$', rows[0][0].strip()) if rows else False
    data_rows = rows[1:] if has_header else rows
    return [r[0].strip() for r in data_rows if r and re.match(r'^\d{6}$', r[0].strip())]

# FastAPI 업로드 처리 (인코딩 자동 감지)
async def upload_csv(file: UploadFile = File(...)):
    content = await file.read()
    try:
        text = content.decode("utf-8-sig")  # BOM 있는 UTF-8 우선
    except:
        text = content.decode("cp949", errors="replace")  # 엑셀 한글 인코딩

미리보기 기능

목표 종목 입력 후 [미리보기 조회] 버튼을 누르면 A-B/A∩B/B-A 분류 결과를 테이블로 보여줍니다. 실제 주문이 발생하지 않아 안전하게 계획을 확인할 수 있습니다.

스케줄 설정 — 실행 진단 기능

V2에서 추가된 실행 진단 기능은 현재 스케줄 설정으로 실제 실행이 가능한지 사전에 검사합니다.

스케줄 설정 패널 — 실행 진단으로 분할 횟수 초과 여부를 사전 검사

진단 로직은 QuantScheduleManager.diagnose()가 처리합니다.

왜 진단이 필요한가: 종목 수가 많으면 1회차에 필요한 시간(종목 수 × 10초)이 회차 간격보다 길어집니다. 이 경우 다음 회차가 아직 실행 중인 회차를 추월해 주문이 중복될 수 있습니다.

def diagnose(self, target_count: int) -> dict:
    time_per_round = target_count * OrderQueue.INTER_ORDER_SECONDS  # 종목수 × 10초
    total_exec = split * time_per_round + (split - 1) * interval  # 전체 소요 추정

    if total_exec > window:
        issues.append({
            "level": "error",
            "msg": f"전체 실행 추정({_fmt(total_exec)})이 시간 창을 초과합니다.",
            "suggestion": f"분할 횟수를 {max_safe}회 이하로 줄이세요.",
        })

진단 결과 예시
20종목 × 10초 = 200초/회차, 매도 10회차 × 12분 간격 = 총 120분 필요
매도 시간 창이 120분이면 OK, 90분이면 경고 발생

실행 방법

1

cd quant_rebalancing && pip install fastapi uvicorn httpx aiosqlite

2

config.json에 키움 App Key, Secret Key 입력 (port: 8001)

3

python main.py → 브라우저에서 http://localhost:8001 접속

4

로그인 → 종목교체 설정에서 목표 종목 입력 → 미리보기 확인 → 스케줄 설정 → 자동매매 시작

V1(포트 8000)과 V2(포트 8001)는 동시에 실행할 수 있습니다. 단, 키움 API 토큰을 공유하므로 두 앱이 동시에 토큰을 갱신하면 충돌할 수 있습니다. 동시에 주문을 실행하지 않도록 주의하세요.

마무리 — Claude Code와 함께한 V2 개발 후기

V2 개발은 V1보다 훨씬 빠르게 진행됐습니다. V1 인프라 코드를 그대로 재활용했고, Claude Code가 핵심 알고리즘 설계와 구현을 빠르게 도왔습니다.

가장 시간이 걸린 부분은 KOSDAQ 종목코드 앞 'Q' 제거 버그와 Mock 모드 데이터 불일치 진단이었습니다. 두 경우 모두 Claude Code가 진단 엔드포인트를 추가해 원인을 빠르게 찾았습니다.

V2 완성 기능 체크리스트

• ✓ 퀀트 종목교체 리밸런싱 (A-B/A∩B/B-A 집합 분류)
• ✓ 텍스트 붙여넣기 & CSV 업로드 (한글 인코딩 대응)
• ✓ 종목교체 미리보기 (실행 전 계획 확인)
• ✓ 듀얼 모드 (퀀트 / 균등배분 실시간 전환)
• ✓ 예약 실행 (날짜 + 모드 함께 저장)
• ✓ 스케줄 실행 진단 (분할 횟수 과부하 사전 검사)
• ✓ 종목별 평가손익 색상 표시
• ✓ V1 인프라 완전 호환 (동시 실행 가능)

시리즈 전체 목차
1~6편 — V1 균등배분 리밸런싱
7편 — V2 기획 & 시스템 설계
8편 — QuantEngine 집합 분류 알고리즘
9편 — 웹 UI & 실제 화면 공개