# 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[]
}
```