BatchuKis Shared Data Models (JSON Schema)
이 문서는 시스템 전반에서 사용되는 데이터 객체의 구조를 상세히 정의합니다. 백엔드 개발 시 이 필드명과 타입을 반드시 준수해야 합니다.
1. Enums & Types (공통 타입)
1.1 MarketType
- Type:
string
- Values:
"Domestic" (국내), "Overseas" (해외)
1.2 OrderType
- Type:
string
- Values:
"BUY" (매수), "SELL" (매도)
1.3 AiProviderType
- Type:
string
- Values:
"gemini", "openai-compatible"
2. Core Models (핵심 객체)
2.1 StockItem (종목 정보 - 확장됨)
| 필드명 |
타입 |
필수 |
설명 |
| code |
string |
Y |
종목 코드 (예: "005930", "NVDA") |
| name |
string |
Y |
종목 명칭 |
| price |
number |
Y |
현재가 |
| change |
number |
Y |
전일 대비 등락 금액 |
| changePercent |
number |
Y |
전일 대비 등락률 (%) |
| market |
MarketType |
Y |
소속 시장 |
| volume |
number |
Y |
거래량 |
| tradingValue |
number |
N |
거래대금 (발굴 페이지용) |
| buyRatio |
number |
N |
실시간 매수 비율 (0~100) |
| sellRatio |
number |
N |
실시간 매도 비율 (0~100) |
| foreignNetBuy |
number |
N |
외국인 순매수량 |
| institutionalNetBuy |
number |
N |
기관 순매수량 |
| per |
number |
N |
주가수익비율 |
| pbr |
number |
N |
주가순자산비율 |
| roe |
number |
N |
자기자본이익률 |
| marketCap |
number |
N |
시가총액 |
| dividendYield |
number |
N |
배당수익률 |
| aiScoreBuy |
number |
Y |
AI 매수 점수 (0~100) |
| aiScoreSell |
number |
Y |
AI 매도 점수 (0~100) |
| themes |
string[] |
N |
연관 테마 리스트 (JSON Array) |
2.2 ApiSettings (시스템 설정)
| 필드명 |
타입 |
필수 |
설명 |
| appKey |
string |
Y |
KIS API App Key |
| appSecret |
string |
Y |
KIS API Secret Key |
| accountNumber |
string |
Y |
계좌번호 |
| useTelegram |
boolean |
Y |
텔레그램 알림 사용 여부 |
| telegramToken |
string |
N |
텔레그램 봇 토큰 |
| telegramChatId |
string |
N |
텔레그램 채팅 ID |
| useNaverNews |
boolean |
Y |
네이버 뉴스 스크랩 여부 |
| naverClientId |
string |
N |
네이버 Client ID |
| naverClientSecret |
string |
N |
네이버 Client Secret |
| aiConfigs |
AiConfig[] |
Y |
등록된 AI 엔진 목록 |
| preferredNewsAiId |
string |
N |
뉴스 분석용 AI ID (FK) |
| preferredStockAiId |
string |
N |
종목 분석용 AI ID (FK) |
| preferredNewsJudgementAiId |
string |
N |
뉴스 판단용 AI ID (FK) |
| preferredAutoBuyAiId |
string |
N |
자동매수용 AI ID (FK) |
| preferredAutoSellAiId |
string |
N |
자동매도용 AI ID (FK) |
2.3 AiConfig (AI 프로필)
| 필드명 |
타입 |
필수 |
설명 |
| id |
string |
Y |
고유 식별자 |
| name |
string |
Y |
엔진 별칭 |
| providerType |
AiProviderType |
Y |
제공자 유형 |
| modelName |
string |
Y |
모델 명칭 (예: "gemini-3-flash-preview") |
| baseUrl |
string |
N |
API 엔드포인트 URL (Ollama 등) |
2.4 AutoTradeConfig (자동매매 로봇)
| 필드명 |
타입 |
필수 |
설명 |
| id |
string |
Y |
식별자 |
| stockCode |
string |
N |
종목 코드 (개별 종목 대상인 경우) |
| stockName |
string |
Y |
대상 명칭 |
| groupId |
string |
N |
관심 그룹 ID (그룹 대상인 경우) |
| type |
string |
Y |
"ACCUMULATION" (적립식) | "TRAILING_STOP" |
| quantity |
number |
Y |
실행 시 주문 수량 |
| frequency |
string |
Y |
"DAILY" | "WEEKLY" | "MONTHLY" |
| specificDay |
number |
N |
실행일 (0-6 요일 또는 1-31 날짜) |
| executionTime |
string |
Y |
실행 시각 ("HH:mm") |
| trailingPercent |
number |
N |
TS 사용 시 퍼센트 |
| active |
boolean |
Y |
활성화 상태 |
| market |
MarketType |
Y |
마켓 구분 |
2.5 ReservedOrder (감시 주문)
| 필드명 |
타입 |
필수 |
설명 |
| id |
string |
Y |
식별자 |
| stockCode |
string |
Y |
종목 코드 |
| stockName |
string |
Y |
종목 명칭 |
| type |
OrderType |
Y |
매수/매도 구분 |
| quantity |
number |
Y |
주문 수량 |
| monitoringType |
string |
Y |
"PRICE_TRIGGER" | "TRAILING_STOP" |
| triggerPrice |
number |
Y |
감시 기준 가격 |
| trailingType |
string |
Y |
"PERCENT" | "AMOUNT" |
| trailingValue |
number |
Y |
간격 값 |
| status |
string |
Y |
"WAITING" | "MONITORING" | "TRIGGERED" | "CANCELLED" |
| createdAt |
string |
Y |
생성 일시 (ISO 8601) |
| expiryDate |
string |
Y |
만료 일시 (ISO 8601) |
2.6 WatchlistGroup (관심 종목 그룹)
| 필드명 |
타입 |
필수 |
설명 |
| id |
string |
Y |
식별자 |
| name |
string |
Y |
그룹명 |
| codes |
string[] |
Y |
포함된 종목 코드 배열 |
| market |
MarketType |
Y |
마켓 구분 |
3. Discovery Models (종목 발굴용 전용 모델)
3.1 RankingCategory
- Type:
string
- Values:
"VOLUME" (거래량), "VALUE" (거래대금), "GAIN" (상승), "LOSS" (하락), "FOREIGN_BUY" (외인매수), "INSTITUTION_BUY" (기관매수)
3.2 DiscoveryRankingResponse
| 필드명 |
타입 |
필수 |
설명 |
| category |
RankingCategory |
Y |
랭킹 카테고리 |
| updatedAt |
string |
Y |
랭킹 갱신 시각 (ISO 8601) |
| items |
StockItem[] |
Y |
순위별 종목 리스트 |
