문서작업

2026-02-02 23:13:28 +09:00
parent 84746d41b8
commit 6d673e06ce
8 changed files with 531 additions and 179 deletions
--- a/backend/api.md
+++ b/backend/api.md
@@ -1,91 +1,150 @@
 # BatchuKis API Specification

 이 문서는 프론트엔드와 백엔드 간의 통신을 위한 API 인터페이스 명세서입니다. 
-**데이터 모델(JSON 구조)의 상세 정의는 [models.md](./models.md)를 참조하십시오.**

 ---

-## 1. 설정 및 시스템 (Settings)
+## 1. 설정 및 시스템 (Settings & System)

-### 1.1 전체 설정 가져오기
- **URL**: `GET /api/settings`
- **Response**: `ApiSettings` (See models.md)
+### 1.1 전체 설정 (Global Settings)
+- **URL**: `GET /api/settings` / `POST /api/settings`
+- **Description**: KIS API 키, 서비스 활성화 여부 등 전체 앱의 사용자 설정을 관리합니다.
+- **Body (POST)**: `ApiSettings` object.

-### 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 }`
+### 1.2 AI 엔진 관리 (AI Configurations)
+- **URL**: `GET /api/settings/ai-configs` / `POST /api/settings/ai-configs`
+- **Description**: 사용자 지정 AI 프로필(Gemini, Ollama 등) 목록을 관리합니다.
+- **PUT/DELETE**: `PUT /api/settings/ai-configs/:id`, `DELETE /api/settings/ai-configs/:id`

 ---

-## 2. 자산 및 잔고 (Portfolio)
+## 2. 계좌 및 자산 (Account & Portfolio)

-### 2.1 보유 종목 리스트
+### 2.1 계좌 요약 (Account Summary)
+- **URL**: `GET /api/account/summary`
+- **Response**: `{ "totalAssets": number, "buyingPower": number, "dailyProfit": number, "dailyProfitRate": number }`
+
+### 2.2 보유 자산 (Holdings)
 - **URL**: `GET /api/holdings`
 - **Query**: `?market=Domestic|Overseas`
 - **Response**: `HoldingItem[]`

-### 2.2 계좌 요약 (자산/예수금)
- **URL**: `GET /api/account/summary`
- **Response**: `{ "totalAssets": number, "buyingPower": number }`
+---
+
+## 3. 관심종목 관리 (Watchlist)
+
+### 3.1 그룹 관리 (Watchlist Groups)
+- **URL**: `GET /api/watchlists` / `POST /api/watchlists`
+- **PUT/DELETE**: `PUT /api/watchlists/:id` (그룹명 수정 및 종목 코드 리스트 업데이트), `DELETE /api/watchlists/:id`
+- **Response**: `WatchlistGroup[]`

 ---

-## 3. 자동매매 전략 (Auto Trading)
+## 4. 종목 및 시세 (Market Data)

-### 3.1 로봇 리스트 조회
- **URL**: `GET /api/auto-trades`
- **Response**: `AutoTradeConfig[]`
+### 4.1 종목 검색 및 마스터 (Stock Discovery)
+- **URL**: `GET /api/stocks/search?query=...`
+- **URL**: `GET /api/kis/master-stocks?market=...` (로컬 검색성능을 위한 대량 데이터 수동 동기화용)

-### 3.2 로봇 등록/수정
- **URL**: `POST /api/auto-trades`
- **Body**: `AutoTradeConfig` (ID가 없으면 생성, 있으면 수정)
- **Response**: `{ "id": string }`
+### 4.2 시세 및 차트 (Quotes & Charts)
+- **URL**: `GET /api/kis/quotes/:code` (현재가 및 호가)
+- **URL**: `GET /api/kis/ticks/:code?limit=...` (차트용 틱 데이터)
+
+### 4.3 발견 및 랭킹 (Market Discovery)
+- **URL**: `GET /api/discovery/rankings?market=...&category=...` (거래량, 상승률 등)

 ---

-## 4. 실시간 감시 주문 (Reserved Orders)
+## 5. 뉴스 및 AI 분석 (News & AI Intelligence)

-### 4.1 감시 목록 조회
- **URL**: `GET /api/reserved-orders`
- **Response**: `ReservedOrder[]`
+### 5.1 뉴스 스크랩 (News Feed)
+- **URL**: `GET /api/news?query=...`
+- **Description**: 네이버 API 등을 통해 실시간 금융 뉴스를 가져옵니다.

-### 4.2 감시 등록
- **URL**: `POST /api/reserved-orders`
- **Body**: `Omit<ReservedOrder, 'id' | 'status' | 'createdAt'>`
- **Response**: `{ "id": string }`
+### 5.2 AI 뉴스 분석 (AI News Briefing)
+- **URL**: `POST /api/ai/analyze-news`
+- **Body**: `{ "aiConfigId": string, "headlines": string[] }`
+- **Response**: `{ "report": string, "sentimentMetadata": any[] }`
+
+### 5.3 AI 종목 분석 (AI Stock Deep-Dive)
+- **URL**: `POST /api/ai/analyze-stock`
+- **Body**: `{ "aiConfigId": string, "stockCode": string, "context": any }`

 ---

-## 5. 종목 및 시세 (Market Data & Discovery)
+## 6. 주문 및 거래 (Trading & History)

-### 5.1 마스터 종목 리스트 (동기화용)
- **URL**: `GET /api/kis/master-stocks`
- **Query**: `?market=Domestic|Overseas`
- **Response**: `StockItem[]`
+### 6.1 수동 주문 (Manual Trading)
+- **URL**: `POST /api/trade/order`
+- **Body**: `{ "code": string, "type": "BUY"|"SELL", "quantity": number, "price": number, "orderType": "MARKET"|"LIMIT" }`

-### 5.2 개별 종목 시세 차트 데이터
- **URL**: `GET /api/kis/ticks/:code`
- **Query**: `?limit=100`
- **Response**: `StockTick[]`
+### 6.2 예약/감시 주문 (Reserved Orders)
+- **URL**: `GET /api/reserved-orders` / `POST /api/reserved-orders`
+- **DELETE**: `DELETE /api/reserved-orders/:id`

-### 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) 및 수급 데이터가 포함됩니다.
+### 6.3 자동매매 전략 (Auto Trading)
+- **URL**: `GET /api/auto-trades` / `POST /api/auto-trades`
+- **Description**: AI 전략 로봇 등록 및 상태 관리.

-### 5.4 [NEW] 실시간 커뮤니티 심리 요약 (AI 전용)
- **URL**: `GET /api/discovery/sentiment/:code`
- **Response**: `{ "insights": string[], "sentimentScore": number }`
- **설명**: 특정 종목에 대한 AI의 실시간 커뮤니티/뉴스 요약 정보를 반환합니다.
+### 6.4 거래 기록 (Execution History)
+- **URL**: `GET /api/history/orders`
+- **Query**: `?page=...&limit=...&stockCode=...&startDate=...&endDate=...`
+- **Response**: `TradeOrder[]`
+
+---
+
+## 7. 실시간 데이터 (Real-time Data - WebSockets)
+
+백엔드는 KIS 실시간 시세 서버와 웹소켓을 유지하며, 프론트엔드에게 가공된 데이터를 스트리밍합니다.
+
+### 7.1 실시간 체결가 (Real-time Price)
+- **Topic**: `/ws/market/price/:code`
+- **Data**: 현재가, 등락률, 거래량 등
+
+### 7.2 실시간 주문 알림 (Order Notifications)
+- **Topic**: `/ws/trade/events`
+- **Data**: 자신의 계좌에서 발생하는 체결 알림, 미체결 취소 알림 등
+
+---
+
+## 8. 내부 서비스 인터페이스 (Internal Engine Services)
+
+프론트엔드에 노출되지 않지만, 백엔드 엔진 내부 모듈 간의 협업 또는 외부 API 래핑을 위한 서비스 인터페이스입니다.
+
+### 8.1 BrokerageInterface (증권사 서버 통신)
+- **`PlaceOrder(stockCode, side, qty, price, type)`**: KIS 서버로 최종 주문 패킷 전송. (Returns: `orderNo`)
+- **`GetRealtimeApprovalKey()`**: 실시간 웹소켓 접속용 **Approval Key** 발급 및 갱신.
+- **`FetchHoldings()`**: 계좌 내 전 종목 보유 및 평단가 수집.
+
+### 8.2 RealtimeManager (웹소켓 데이터 관리)
+- **`AddSubscription(code, source)`**: 구독 요청 (`source`: 'HOLDING' | 'FRONTEND').
+  - **Logic**: 해당 종목의 Reference Count 증가. `Count == 1`이 되는 순간 KIS 웹소켓 구독 전송.
+- **`RemoveSubscription(code, source)`**: 구독 해제 요청.
+  - **Logic**: Reference Count 감소. `Count == 0`이 되면 KIS 웹소켓 구독 해제(자원 절약).
+- **`OnStreamReceived(data)`**: 수신된 로우 데이터를 파싱하여 필요 모듈(`AutoTrader`, `FrontendWS`)로 브로드캐스팅.
+
+### 8.3 AiOrchestrator (AI 엔진 처리 핸들러)
+- **`RequestAnalysis(aiConfigId, prompt)`**: 지정된 엔진 프로필을 사용하여 원격 AI API 호출.
+- **`ApplySentiment(newsId, result)`**: 분석된 심리 결과를 DB(`news_cache`)에 업데이트 및 프론트 전송.
+
+### 8.4 Scheduler (배치 작업 제어)
+- **`SyncMasterStocks()`**: 매일 새벽 종목 명칭 및 코드 리스트 동기화.
+- **`PersistMarketDataCache()`**: 메모리에 수신된 실시간 현재가를 주기적으로 DB에 영구 저장 (API 호출 없음).
+- **`RefreshNaverNews()`**: 10분 단위 키워드별 뉴스 스크랩 및 분석 트리거.
+
+---
+
+## 9. KIS API Integration Map (증권사 연동 맵)
+
+`BrokerageInterface`가 실제 호출해야 할 한국투자증권(KIS) Open API 엔드포인트 매핑입니다.
+
+| Category | Internal Function | Domestic API (국내) | Overseas API (해외) | Note |
+| :--- | :--- | :--- | :--- | :--- |
+| **Auth** | `GetAuthToken` | `/oauth2/tokenP` | (Common) | OAuth2 Access Token |
+| **Auth** | `GetWebsocketKey` | `/oauth2/approval` | (Common) | WebSocket Approval Key |
+| **Order** | `PlaceOrder` | `/uapi/domestic-stock/v1/trading/order-cash` | `/uapi/overseas-stock/v1/trading/order` | 현금 매수/매도 |
+| **Order** | `ModifyOrder` | `/uapi/domestic-stock/v1/trading/order-rvsecncl` | `/uapi/overseas-stock/v1/trading/order-rvsecncl` | 정정/취소 |
+| **Price** | `GetCurrentPrice` | `/uapi/domestic-stock/v1/quotations/inquire-price` | `/uapi/overseas-stock/v1/quotations/price` | 현재가 조회 |
+| **Price** | `GetDailyChart` | `/uapi/domestic-stock/v1/quotations/inquire-daily-price` | `/uapi/overseas-stock/v1/quotations/daily-price` | 일봉 데이터 |
+| **Balance** | `FetchHoldings` | `/uapi/domestic-stock/v1/trading/inquire-balance` | `/uapi/overseas-stock/v1/trading/inquire-balance` | 잔고 조회 |
+| **Socket** | `RealtimePrice` | `/tryit/H0STCNT0` (H0STCNT0) | `/tryit/HDFSCNT0` (HDFSCNT0) | 실시간 체결가 |