GoogleAIBuilder/KisStock
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
86c1c54126e65ebbbb7f535fab6a171088f34b52
KisStock/backend/ReadMe.md
LGram16 6d673e06ce 문서작업
2026-02-02 23:13:28 +09:00

7.0 KiB
Raw Blame History

BatchuKis 백엔드 독립 실행 엔진 및 API 통합 사양서 (v1.7)

본 문서는 BatchuKis 플랫폼의 백엔드 시스템 아키텍처, 독립 실행형 매매 엔진 로직 및 개발 환경을 정의합니다.

1. 개발 및 실행 환경 (Development Environment)

  • Runtime: Docker Container (Python 3.8+ Base Image)
  • Deployment: Dokploy (Self-hosted PaaS)
  • Framework: FastAPI (비동기 처리) or Flask
  • Database: SQLite (Volume Mounting for Persistence)
  • Frontend Hosting: Python 백엔드가 React 빌드 결과물(dist)을 정적 파일로 서빙 (Single Container Monolith).

1.1 Production Configuration (배포 설정)

  • Domain: kis.tindevil.com
  • Security Check:
    • ALLOWED_HOSTS: ["kis.tindevil.com", "localhost", "127.0.0.1"] 추가 필수.
    • CORS: 프론트엔드가 동일 도메인에서 서빙되므로 기본적으로 불필요하나, 로컬 개발/외부 연동 시 ALLOW_ORIGINS 설정 필요.
    • Cookie/Session: SameSite=Lax, Secure=True (HTTPS proxy behind Dokploy/Traefik).

2. 시스템 아키텍처 및 주요 모듈

2.1 Monolithic Architecture

  • Single Entry Point: 사용자는 하나의 URL/포트로 접속.
  • Routing:
    • /api/*: REST API 요청 처리
    • /ws/*: WebSocket 요청 처리
    • /*: React SPA 정적 파일(index.html, js, css) 반환

2.2 Headless Execution Engine (매매 엔진)

  • API 서버와 동일한 프로세스 내에서 백그라운드 스레드(Async Task)로 동작.
  1. Auto-Trading Scanner: 매 1분마다 auto_trade_robots 설정을 스캔하여 로직(적립식, TS 등)에 따라 주문 생성.
  2. Order Monitoring Engine: 실시간 시세를 수신하여 reserved_orders의 발동 조건을 감시하고 즉시 주문 집행.

2.3 Data Infrastructure (데이터 인프라)

  1. Dynamic Real-time Subscription (Reference Counting):
    • Strategy: 불필요한 트래픽 방지를 위해 **"필요할 때만 구독"**하는 레퍼런스 카운팅 방식을 사용.
    • Source 1 (Permanent): **보유 종목(Holdings)**은 앱 실행 시 무조건 구독 (Ref +1).
    • Source 2 (Transient): 프론트엔드에서 특정 종목 페이지 진입 시 구독 요청 (Ref +1), 이탈 시 해제 (Ref -1).
    • Decision: Reference Count > 0일 때만 KIS WebSocket 연결 유지. 0이 되면 즉시 구독 해제.
  2. AI Analysis Proxy: 프론트엔드의 AI 분석 요청을 수신하여 전용 API 터널을 통해 외부 AI 엔진과 통신 및 결과 JSON 파싱.

2.4 Token Lifecycle Management (인증 토큰 관리)

  • Token Storage: 발급된 Access Token과 만료 시각(expiry)을 메모리 및 DB에 저장.
  • Proactive Refresh: API 호출 전 현재 시각이 만료 시각(통상 6~24시간)에 근접했는지 확인하여 선제적 갱신.
  • Reactive Refresh (Auto-Retry): API 호출 중 401 Unauthorized 또는 EXPIRED_TOKEN 오류 발생 시,
    1. 즉시 토큰 재발급을 수행.
    2. 실패했던 원래 요청을 새 토큰으로 자동 재시도(Retry).
    3. 프론트엔드나 상위 로직에는 오류를 전파하지 않고 처리를 완료함.

2.5 Rate Limiting & Throttling (속도 제한 및 조절)

  • Centralized Request Queue: 모든 KIS API 호출은 단일 큐(Blocking Queue)를 통과해야 함.
  • Throttling Logic:
    • 각 호출 사이에는 설정된 간격(kisApiDelayMs, 기본 250ms)만큼 강제 대기(Delay) 수행.
    • 연속된 주문이나 조회 요청이 발생해도 초당 4회 이하로 전송 속도를 물리적으로 제한하여 증권사 서버 차단을 방지.
  • Configurable Intervals:
    • kisApiDelayMs: API 호출 최소 간격 (기본 250ms)
    • newsScrapIntervalMin: 뉴스 수집 주기 (기본 10분)

2.6 Market Schedule Awareness (장 운영시간 인지)

백엔드는 **국내(Domestic)**와 해외(Overseas) 시장의 개장 시간을 독립적으로 관리하며, 장이 닫힌 동안에는 불필요한 API 호출과 자동매매 스캔을 중단(Sleep Mode)합니다.

  • Check Logic: 모든 자동화 로직은 실행 전 IsMarketOpen(marketType)을 확인해야 함.
  • Domestic (KST): 09:00 ~ 15:30 (평일, 공휴일 제외)
  • Overseas (US): 22:30 ~ 06:00 (썸머타임 적용 시 변동, 주말 제외)
  • Action:
    • Open: 실시간 시세 수신, 감시 주문 체크, 적립식 매수 실행.
    • Closed: 단순 데이터 수집(뉴스) 외 트레이딩 로직 일시 정지.

3. 상세 설계 명세서

백엔드 구현 시 아래 세 문서를 바이블로 삼아 개발을 진행하십시오.

4. 운영 사이클 (Operational Cycle)

작업명 주기 주요 내용
자동매매 스캔 1분 예약된 시각의 적립식 매수 및 전략 조건 확인
시세 감시 실시간 감시가 도달 시 즉시 주문 전송
관심종목 갱신 Event WebSocket 체결가 수신 시 즉시 DB 캐시 업데이트
마스터 동기화 일 1회 신규 상장/상폐 종목 리스트 업데이트
뉴스 수집 10분 실시간 금융 뉴스 스크랩 및 AI 분석 준비

5. 시작 시퀀스 (Startup Sequence)

백엔드 컨테이너 실행 시(Initial Boot), 시스템은 다음 순서대로 스스로 초기화를 수행하며 완전 자동화 모드로 진입합니다.

Phase 1: 시스템 초기화

  1. DB 연결 및 마이그레이션: SQLite 파일(kis_stock.db) 존재 여부 확인 및 테이블 생성.
  2. 설정 로드: api_settings 테이블에서 KIS AppKey, Secret, Telegram Token 등을 메모리에 로드.

Phase 2: 외부망 연결 (Connectivity)

  1. KIS API 인증:
    • 저장된 키로 REST API Access Token 발급 요청 (수명 24시간).
    • (성공 시) Base URL로 실시간 WebSocket Approval Key 발급 요청 (수명 1회성/무제한).
  2. 텔레그램 핸드쉐이크:
    • 봇 토큰이 유효한 경우, 관리자에게 "System Online: BatchuKis Engine Started" 메시지 발송.

Phase 3: 데이터 동기화 (Data Sync)

  1. 마스터 데이터 갱신:
    • master_stocks 테이블이 비어있거나, 마지막 갱신일이 어제인 경우 KIS로부터 전 종목 코드 다운로드.
  2. 실시간 감시 복구:
    • reserved_orders에서 'MONITORING' 상태인 주문을 조회하여 실시간 시세 수신(WebSocket) 재구독.

Phase 4: 오토파일럿 가동 (Autopilot Engage)

  1. 스케줄러 시작:
    • Auto-Trading Scanner (1분 주기) 가동.
    • Data Persistence Worker (메모리 캐시 DB 저장) 가동.
    • News Scraper (10분 주기) 가동.
  2. 서버 준비 완료: REST API(:80) 및 정적 파일 호스팅 시작.
Reference in New Issue View Git Blame Copy Permalink