127 lines
5.4 KiB
Markdown
127 lines
5.4 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 | 종목 코드 (예: "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 | 순위별 종목 리스트 |
|