initial commit

backend/api.md

@@ -0,0 +1,91 @@
+# BatchuKis API Specification
+
+이 문서는 프론트엔드와 백엔드 간의 통신을 위한 API 인터페이스 명세서입니다. 
+**데이터 모델(JSON 구조)의 상세 정의는 [models.md](./models.md)를 참조하십시오.**
+
+---
+
+## 1. 설정 및 시스템 (Settings)
+
+### 1.1 전체 설정 가져오기
+- **URL**: `GET /api/settings`
+- **Response**: `ApiSettings` (See models.md)
+
+### 1.2 전체 설정 저장하기
+- **URL**: `POST /api/settings`
+- **Body**: `ApiSettings`
+- **Response**: `{ "success": boolean, "message": string }`
+
+### 1.3 AI 엔진 풀(Pool) 관리
+#### 1.3.1 등록된 AI 엔진 목록 조회
+- **URL**: `GET /api/settings/ai-configs`
+- **Response**: `AiConfig[]`
+
+#### 1.3.2 신규 AI 엔진 추가
+- **URL**: `POST /api/settings/ai-configs`
+- **Body**: `Omit<AiConfig, 'id'>`
+- **Response**: `{ "id": string, "success": true }`
+
+---
+
+## 2. 자산 및 잔고 (Portfolio)
+
+### 2.1 보유 종목 리스트
+- **URL**: `GET /api/holdings`
+- **Query**: `?market=Domestic|Overseas`
+- **Response**: `HoldingItem[]`
+
+### 2.2 계좌 요약 (자산/예수금)
+- **URL**: `GET /api/account/summary`
+- **Response**: `{ "totalAssets": number, "buyingPower": number }`
+
+---
+
+## 3. 자동매매 전략 (Auto Trading)
+
+### 3.1 로봇 리스트 조회
+- **URL**: `GET /api/auto-trades`
+- **Response**: `AutoTradeConfig[]`
+
+### 3.2 로봇 등록/수정
+- **URL**: `POST /api/auto-trades`
+- **Body**: `AutoTradeConfig` (ID가 없으면 생성, 있으면 수정)
+- **Response**: `{ "id": string }`
+
+---
+
+## 4. 실시간 감시 주문 (Reserved Orders)
+
+### 4.1 감시 목록 조회
+- **URL**: `GET /api/reserved-orders`
+- **Response**: `ReservedOrder[]`
+
+### 4.2 감시 등록
+- **URL**: `POST /api/reserved-orders`
+- **Body**: `Omit<ReservedOrder, 'id' | 'status' | 'createdAt'>`
+- **Response**: `{ "id": string }`
+
+---
+
+## 5. 종목 및 시세 (Market Data & Discovery)
+
+### 5.1 마스터 종목 리스트 (동기화용)
+- **URL**: `GET /api/kis/master-stocks`
+- **Query**: `?market=Domestic|Overseas`
+- **Response**: `StockItem[]`
+
+### 5.2 개별 종목 시세 차트 데이터
+- **URL**: `GET /api/kis/ticks/:code`
+- **Query**: `?limit=100`
+- **Response**: `StockTick[]`
+
+### 5.3 [NEW] 종목 발굴 랭킹 데이터
+- **URL**: `GET /api/discovery/rankings`
+- **Query**: `?market=Domestic|Overseas&category=VOLUME|VALUE|GAIN|LOSS|FOREIGN_BUY|INSTITUTION_BUY`
+- **Response**: `DiscoveryRankingResponse` (See models.md)
+- **설명**: 토스증권 스타일의 발굴 페이지에 데이터를 공급합니다. 거래비율(buyRatio/sellRatio) 및 수급 데이터가 포함됩니다.
+
+### 5.4 [NEW] 실시간 커뮤니티 심리 요약 (AI 전용)
+- **URL**: `GET /api/discovery/sentiment/:code`
+- **Response**: `{ "insights": string[], "sentimentScore": number }`
+- **설명**: 특정 종목에 대한 AI의 실시간 커뮤니티/뉴스 요약 정보를 반환합니다.