# 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 엔드포인트 연동
    - 모든 호출은 `Rate Limiter` 경유 필수
- [ ] **Realtime Manager (웹소켓)**
    - `KisWebSocket` 클라이언트: Approval Key 발급 및 연결
    - **Reference Counting**: `Subscribe(code)`, `Unsubscribe(code)` 구현
    - 수신 데이터 파싱 및 Event Bus 전파
- [ ] **AI Orchestrator**
    - Gemini/OpenAI API 연동 핸들러

## Phase 5: API 엔드포인트 구현 (Endpoints)
- [ ] **Settings API** (`/api/settings`)
    - API Key, Rate Limit 설정 조회/수정
- [ ] **Stock/Market API** (`/api/kis/...`)
    - 시세 조회, 차트 데이터, 관심종목 관리
- [ ] **Trading API** (`/api/trade/...`)
    - 주문 전송, 잔고 조회, 예약 주문(감시) 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` 비동기 처리.