문서작업

2026-02-02 23:13:28 +09:00
parent 84746d41b8
commit 6d673e06ce
8 changed files with 531 additions and 179 deletions
--- a/backend/ReadMe.md
+++ b/backend/ReadMe.md
@@ -1,19 +1,123 @@
-# BatchuKis 백엔드 독립 실행 엔진 및 API 통합 사양서 (v1.6)
+# BatchuKis 백엔드 독립 실행 엔진 및 API 통합 사양서 (v1.7)

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

-## 1. 시스템 아키텍처
+---

-### 1.1 Headless Execution Engine
-1. **Batch Engine**: 매 1분마다 `auto_trade_configs`를 스캔하여 예약된 시각에 주문 실행.
-2. **Monitoring Engine**: WebSocket 시세를 수신하여 `reserved_orders` 조건 감시 및 자동 매매.
-3. **Market Index Collector**: 
-   - **조회**: 매 5분마다 주요 시장 지수(KOSPI, KOSDAQ, NASDAQ, S&P500, USD/KRW) 수신.
-   - **기록**: 1시간마다 해당 시점의 최종 데이터를 `market_index_history` 테이블에 기록(Upsert).
-   - **프론트 연동**: 프론트엔드는 DB에 저장된 최신 데이터를 5분 단위로 폴링하여 대시보드 업데이트.
-4. **AI Proxy**: API 보안을 위해 AI 분석 및 뉴스 요청 중계.
+## 1. 개발 및 실행 환경 (Development Environment)

-## 2. 상세 명세 가이드
- **DB 스키마**: [tables.md](./tables.md) 참조.
- **API 엔드포인트**: [api.md](./api.md) 참조.
- **데이터 구조(JSON)**: [models.md](./models.md) 참조.
+- **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. 상세 설계 명세서
+
+백엔드 구현 시 아래 세 문서를 바이블로 삼아 개발을 진행하십시오.
+
+- 🏗️ **[DB 스키마 정의서](./tables.md)**: SQLite 테이블 구조 및 관계 정의.
+- 📡 **[API 인터페이스 명세](./api.md)**: REST API 엔드포인트 및 WebSocket 토픽 정의.
+- 📦 **[통합 데이터 모델](./models.md)**: API와 DB에서 공통으로 사용하는 JSON 구조 및 엔티티 정의.
+
+---
+
+## 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)
+3. **KIS API 인증**: 
+   - 저장된 키로 **REST API Access Token** 발급 요청 (수명 24시간).
+   - (성공 시) **Base URL**로 실시간 **WebSocket Approval Key** 발급 요청 (수명 1회성/무제한).
+4. **텔레그램 핸드쉐이크**:
+   - 봇 토큰이 유효한 경우, 관리자에게 _"System Online: BatchuKis Engine Started"_ 메시지 발송.
+
+### Phase 3: 데이터 동기화 (Data Sync)
+5. **마스터 데이터 갱신**: 
+   - `master_stocks` 테이블이 비어있거나, 마지막 갱신일이 어제인 경우 KIS로부터 전 종목 코드 다운로드.
+6. **실시간 감시 복구**:
+   - `reserved_orders`에서 'MONITORING' 상태인 주문을 조회하여 실시간 시세 수신(WebSocket) 재구독.
+
+### Phase 4: 오토파일럿 가동 (Autopilot Engage)
+7. **스케줄러 시작**:
+   - `Auto-Trading Scanner` (1분 주기) 가동.
+   - `Data Persistence Worker` (메모리 캐시 DB 저장) 가동.
+   - `News Scraper` (10분 주기) 가동.
+8. **서버 준비 완료**: REST API(`:80`) 및 정적 파일 호스팅 시작.