188 lines
7.5 KiB
Markdown
188 lines
7.5 KiB
Markdown
# 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**: 뉴스 리포트 분석 시 각 기사별로 매칭되는 메타데이터 구조.
|
|
```json
|
|
{
|
|
"index": number,
|
|
"sentiment": "POSITIVE" | "NEGATIVE" | "NEUTRAL",
|
|
"themes": string[],
|
|
"stocks": string[]
|
|
}
|
|
```
|