# Backend Implementation Roadmap (TODO.md)

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

---

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

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

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

## Phase 4: 내부 서비스 (Internal Services)
- [x] **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` 경유 필수
- [x] **Realtime Manager (웹소켓)**
    - `KisWebSocket` 클라이언트: Approval Key 발급 및 연결
    - `OPS` (실전) / `VOPS` (모의) 자동 전환
    - **Subscription**: 종목 등록/해제 (`H0STCNT0` 등)
    - **PINGPONG**: 자동 응답 처리
    - **Data Handler**: 수신 데이터 파싱 및 DB/Cache 업데이트 (암호화 `AES256` 해독 포함)
- [x] **AI Orchestrator**
    - `AIFactory`: Provider(Gemini/Ollama/OpenAI) 추상화 및 인스턴스 생성
    - `AIOrchestrator`: DB 설정(`AiConfig`) 기반 최적 모델 자동 선택 및 실행 요청

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

## Phase 6: 스케줄러 및 자동화 (Automation)
- [x] **Startup Sequence**
    - DB 체크 -> 토큰 로드 -> Telegram 알림 -> 스케줄러 시작
- [x] **Background Workers**
    - `PersistenceWorker`: 메모리 내 시세 데이터 DB 주기적 저장 (Passive)
    - `NewsScraper`: 네이버 뉴스 주기적 수집
    - `AutoTradingScanner`: 1분 단위 예약 주문 감시

## Phase 7: 통합 및 배포 (Integration)
- [x] **Frontend 연동**
    - React 빌드 (`npm run build`) -> backend/static 복사
    - 단일 포트(80) 서빙 테스트
- [x] **Docker 빌드**
    - `docker-compose up` 테스트
    - Dokploy 배포 및 볼륨 마운트 확인

---

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