KisStock/backend/models.md

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	종목 코드
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	PER
pbr	number	N	PBR
roe	number	N	ROE
marketCap	number	N	시가총액
dividendYield	number	N	배당수익률
aiScoreBuy	number	Y	AI 매수 점수 (0~100)
aiScoreSell	number	Y	AI 매도 점수 (0~100)
openPrice	number	N	시가
highPrice	number	N	고가
lowPrice	number	N	저가
themes	string[]	N	연관 테마
memo	string	N	사용자 메모
aiAnalysis	string	N	AI 분석 리포트 전문
isHidden	boolean	N	숨김 여부

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
kisApiDelayMs	number	N	KIS API 호출 간격 (ms, 기본 250)
newsScrapIntervalMin	number	N	뉴스 수집 주기 (분, 기본 10)
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	모델 명칭
baseUrl	string	N	API 엔드포인트 URL

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	실행일
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	간격 값
useStopLoss	boolean	N	손절 기능 사용 여부
stopLossType	string	N	"PERCENT" | "AMOUNT"
stopLossValue	number	N	손절 기준값
sellAll	boolean	N	전량 매도 여부
highestPrice	number	N	감시 시작 후 최고가(Trailing용)
lowestPrice	number	N	감시 시작 후 최저가(Trailing용)
market	MarketType	Y	마켓 구분
status	string	Y	"WAITING" | "MONITORING" | "TRIGGERED" | "CANCELLED"
createdAt	string	Y	생성 일시 (ISO 8601)
expiryDate	string	Y	만료 일시 (ISO 8601)

2.6 NewsItem (뉴스 정보)

필드명	타입	필수	설명
title	string	Y	뉴스 제목
description	string	Y	뉴스 요약 내용
link	string	Y	원문 링크 URL
pubDate	string	Y	발행 일시 (ISO 8601)
sentiment	string	N	AI 분석 심리 ("POSITIVE" | "NEGATIVE" | "NEUTRAL")
relatedThemes	string[]	N	AI 추출 연관 테마
relatedStocks	string[]	N	AI 추출 연관 종목명/코드

2.7 TradeOrder (체결 기록 / 주문)

필드명	타입	필수	설명
id	string	Y	고유 식별자
stockCode	string	Y	종목 코드
stockName	string	Y	종목 명칭
type	string	Y	"BUY" | "SELL"
quantity	number	Y	체결 수량
price	number	Y	체결 단가
timestamp	string	Y	체결 시각 (ISO 8601)
status	string	Y	"COMPLETED" | "CANCELLED" | "FAILED"

2.8 HoldingItem (보유 잔고 종목)

필드명	타입	필수	설명
stockCode	string	Y	종목 코드
stockName	string	Y	종목 명칭
quantity	number	Y	보유 수량
avgPrice	number	Y	평균 매입가
currentPrice	number	Y	현재가
profit	number	Y	평가 손익
profitRate	number	Y	수익률 (%)
marketValue	number	Y	평가 금액

2.9 WatchlistGroup (관심 종목 그룹)

필드명	타입	필수	설명
id	string	Y	식별자
name	string	Y	그룹명
codes	string[]	Y	포함된 종목 코드 배열
market	MarketType	Y	마켓 구분

3. Discovery & AI 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	순위별 종목 리스트

3.3 AiAnalysisMetadata

• Description: 뉴스 리포트 분석 시 각 기사별로 매칭되는 메타데이터 구조.

{
  "index": number,
  "sentiment": "POSITIVE" | "NEGATIVE" | "NEUTRAL",
  "themes": string[],
  "stocks": string[]
}