91 lines
4.0 KiB
Markdown
91 lines
4.0 KiB
Markdown
# 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` 비동기 처리.
|