# 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의 실시간 커뮤니티/뉴스 요약 정보를 반환합니다.