# 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 | 순위별 종목 리스트 |
