KisStock/backend/TODO.md

Backend Implementation Roadmap (TODO.md)

이 문서는 BatchuKis 백엔드 개발을 위한 단계별 구현 체크리스트입니다. 사양서(ReadMe.md, api.md, tables.md, models.md)를 기반으로 작성되었습니다.

---

Phase 1: 프로젝트 스캐폴딩 (Scaffolding)

• 디렉토리 구조 생성
  • app/core (설정, 인증, 유틸)
  • app/db (데이터베이스 연결, 모델)
  • app/api (End-points)
  • app/services (비즈니스 로직, 외부 통신)
  • app/workers (백그라운드 스케줄러)
• 환경 설정 (config.py)
  • Pydantic BaseSettings 활용
  • .env 파일 연동 (APP_KEY, SECRET 등)
  • Docker 환경 변수 처리
  • Domain Config: ALLOWED_HOSTS=["kis.tindevil.com", ...] 설정 추가
• FastAPI 기본 앱 작성 (main.py)
  • CORS 설정
  • Health Check 엔드포인트 (/health)
  • Static Files Mount (Frontend dist 폴더 연결 준비)

Phase 2: 데이터베이스 구현 (Database)

• SQLite 연동 (database.py)
  • SQLAlchemy sessionmaker 설정 (비동기 AsyncSession 권장)
• ORM 모델 정의 (db/models.py)
  • ApiSettings (설정)
  • StockItem (관심/보유 종목)
  • ReservedOrder (감시 주문)
  • TradeOrder (매매 기록)
  • CacheTable (지수, 뉴스 등 임시 데이터)
• 마이그레이션 및 초기화
  • init_db() 함수 구현: 앱 시작 시 테이블 자동 생성 (Base.metadata.create_all)

Phase 3: 코어 인프라 (Core Infrastructure)

• Rate Limiter (속도 제한 큐)
  • RateLimiter 클래스: asyncio.Queue 기반 중앙 제어
  • TokenBucket 또는 단순 Delay (250ms) 로직 구현
• Token Manager (인증 관리)
  • KisAuth 클래스: Access Token 발급/저장/갱신
  • Auto-Retry: 401 에러 인터셉터 및 재발급 로직
• Market Schedule (장 운영시간)
  • MarketCalendar 유틸: 현재 국내/해외 장 운영 여부 판단 (IsMarketOpen)

Phase 4: 내부 서비스 (Internal Services)

• Brokerage Service (증권사 통신)
  • 파일: app/services/kis_client.py
  • 구현: api.md의 Section 9. Integration Map에 정의된 API 엔드포인트 연동
  • 참고 샘플 (KIS Samples):
    • Auth: examples_llm/auth/auth_token/method.py (토큰 발급)
    • Domestic:
      • 주문: domestic_stock/order_cash/order_cash.py
      • 시세: domestic_stock/inquire_price/inquire_price.py
      • 잔고: domestic_stock/inquire_balance/inquire_balance.py
    • Overseas:
      • 주문: overseas_stock/order/order.py
      • 시세: overseas_stock/price/price.py
      • 잔고: overseas_stock/inquire_balance/inquire_balance.py
  • 모든 호출은 Rate Limiter 경유 필수
• Realtime Manager (웹소켓)
  • KisWebSocket 클라이언트: Approval Key 발급 및 연결
  • OPS (실전) / VOPS (모의) 자동 전환
  • Subscription: 종목 등록/해제 (H0STCNT0 등)
  • PINGPONG: 자동 응답 처리
  • Data Handler: 수신 데이터 파싱 및 DB/Cache 업데이트 (암호화 AES256 해독 포함)
• AI Orchestrator
  • AIFactory: Provider(Gemini/Ollama/OpenAI) 추상화 및 인스턴스 생성
  • AIOrchestrator: DB 설정(AiConfig) 기반 최적 모델 자동 선택 및 실행 요청

Phase 5: API 엔드포인트 구현 (Endpoints)

• Settings API (/api/settings)
  • API Key, Rate Limit 설정 조회/수정
• Stock/Market API (/api/kis/...)
  • 시세 조회, 차트 데이터, 관심종목 관리
• Trading API (/api/kis/order, /api/kis/balance)
  • 주문 전송, 잔고 조회, 예약 주문(감시) CRUD
• Real-time API (Frontend WebSocket)
  • /ws/client: 프론트엔드와 연결, KIS 데이터 중계

Phase 6: 스케줄러 및 자동화 (Automation)

• Startup Sequence
  • DB 체크 -> 토큰 로드 -> Telegram 알림 -> 스케줄러 시작
• Background Workers
  • PersistenceWorker: 메모리 내 시세 데이터 DB 주기적 저장 (Passive)
  • NewsScraper: 네이버 뉴스 주기적 수집
  • AutoTradingScanner: 1분 단위 예약 주문 감시

Phase 7: 통합 및 배포 (Integration)

• Frontend 연동
  • React 빌드 (npm run build) -> backend/static 복사
  • 단일 포트(80) 서빙 테스트
• Docker 빌드
  • docker-compose up 테스트
  • Dokploy 배포 및 볼륨 마운트 확인

---

🎯 개발 규칙 (Rules)

1. No Active Polling: 시세는 반드시 웹소켓으로 수신 (관심/보유 종목 한정).
2. Fail-Safe: API 호출 실패 시 재시도 하되, 전체 장애로 번지지 않도록 예외 처리.
3. Async First: 모든 I/O(DB, Network)는 async/await 비동기 처리.