문서작업

backend/models.md

@@ -23,26 +23,32 @@
 ### 2.1 StockItem (종목 정보 - 확장됨)
 | 필드명 | 타입 | 필수 | 설명 |
 | :--- | :--- | :--- | :--- |
-| code | string | Y | 종목 코드 (예: "005930", "NVDA") |
+| code | string | Y | 종목 코드 |
 | name | string | Y | 종목 명칭 |
 | price | number | Y | 현재가 |
 | change | number | Y | 전일 대비 등락 금액 |
 | changePercent | number | Y | 전일 대비 등락률 (%) |
 | market | MarketType | Y | 소속 시장 |
 | volume | number | Y | 거래량 |
-| tradingValue | number | N | 거래대금 (발굴 페이지용) |
+| 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 | 자기자본이익률 |
+| 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) |
-| themes | string[] | N | 연관 테마 리스트 (JSON Array) |
+| 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 (시스템 설정)
 | 필드명 | 타입 | 필수 | 설명 |
@@ -56,6 +62,8 @@
 | 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) |
@@ -69,20 +77,20 @@
 | id | string | Y | 고유 식별자 |
 | name | string | Y | 엔진 별칭 |
 | providerType | AiProviderType | Y | 제공자 유형 |
-| modelName | string | Y | 모델 명칭 (예: "gemini-3-flash-preview") |
-| baseUrl | string | N | API 엔드포인트 URL (Ollama 등) |
+| modelName | string | Y | 모델 명칭 |
+| baseUrl | string | N | API 엔드포인트 URL |
 
 ### 2.4 AutoTradeConfig (자동매매 로봇)
 | 필드명 | 타입 | 필수 | 설명 |
 | :--- | :--- | :--- | :--- |
 | id | string | Y | 식별자 |
-| stockCode | string | N | 종목 코드 (개별 종목 대상인 경우) |
+| stockCode | string | N | 종목 코드 |
 | stockName | string | Y | 대상 명칭 |
-| groupId | string | N | 관심 그룹 ID (그룹 대상인 경우) |
-| type | string | Y | "ACCUMULATION" (적립식) \| "TRAILING_STOP" |
-| quantity | number | 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 날짜) |
+| specificDay | number | N | 실행일 |
 | executionTime | string | Y | 실행 시각 ("HH:mm") |
 | trailingPercent | number | N | TS 사용 시 퍼센트 |
 | active | boolean | Y | 활성화 상태 |
@@ -100,11 +108,53 @@
 | 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 WatchlistGroup (관심 종목 그룹)
+### 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 | 식별자 |
@@ -112,11 +162,11 @@
 | codes | string[] | Y | 포함된 종목 코드 배열 |
 | market | MarketType | Y | 마켓 구분 |
 
-## 3. Discovery Models (종목 발굴용 전용 모델)
+## 3. Discovery & AI Models (특수 목적 모델)
 
 ### 3.1 RankingCategory
 - **Type**: `string`
-- **Values**: `"VOLUME"` (거래량), `"VALUE"` (거래대금), `"GAIN"` (상승), `"LOSS"` (하락), `"FOREIGN_BUY"` (외인매수), `"INSTITUTION_BUY"` (기관매수)
+- **Values**: `"VOLUME"`, `"VALUE"`, `"GAIN"`, `"LOSS"`, `"FOREIGN_BUY"`, `"INSTITUTION_BUY"`
 
 ### 3.2 DiscoveryRankingResponse
 | 필드명 | 타입 | 필수 | 설명 |
@@ -124,3 +174,14 @@
 | 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[]
+}
+```