initial commit

2026-01-31 22:34:57 +09:00
commit f1301de543
875 changed files with 196598 additions and 0 deletions
--- a/backend/ReadMe.md
+++ b/backend/ReadMe.md
@@ -0,0 +1,15 @@
+# BatchuKis 백엔드 독립 실행 엔진 및 API 통합 사양서 (v1.6)
+
+본 문서는 BatchuKis 플랫폼의 백엔드 시스템 아키텍처 및 독립 실행형 매매 엔진 로직을 정의합니다.
+
+## 1. 시스템 아키텍처
+
+### 1.1 Headless Execution Engine
+1. **Batch Engine**: 매 1분마다 `auto_trade_configs`를 스캔하여 예약된 시각에 주문 실행.
+2. **Monitoring Engine**: WebSocket 시세를 수신하여 `reserved_orders` 조건 감시 및 자동 매매.
+3. **AI Proxy**: API 보안을 위해 AI 분석 및 뉴스 요청 중계.
+
+## 2. 상세 명세 가이드
+- **DB 스키마**: [tables.md](./tables.md) 참조.
+- **API 엔드포인트**: [api.md](./api.md) 참조.
+- **데이터 구조(JSON)**: [models.md](./models.md) 참조.
--- a/backend/api.md
+++ b/backend/api.md
@@ -0,0 +1,91 @@
+# BatchuKis API Specification
+
+이 문서는 프론트엔드와 백엔드 간의 통신을 위한 API 인터페이스 명세서입니다. 
+**데이터 모델(JSON 구조)의 상세 정의는 [models.md](./models.md)를 참조하십시오.**
+
+---
+
+## 1. 설정 및 시스템 (Settings)
+
+### 1.1 전체 설정 가져오기
+- **URL**: `GET /api/settings`
+- **Response**: `ApiSettings` (See models.md)
+
+### 1.2 전체 설정 저장하기
+- **URL**: `POST /api/settings`
+- **Body**: `ApiSettings`
+- **Response**: `{ "success": boolean, "message": string }`
+
+### 1.3 AI 엔진 풀(Pool) 관리
+#### 1.3.1 등록된 AI 엔진 목록 조회
+- **URL**: `GET /api/settings/ai-configs`
+- **Response**: `AiConfig[]`
+
+#### 1.3.2 신규 AI 엔진 추가
+- **URL**: `POST /api/settings/ai-configs`
+- **Body**: `Omit<AiConfig, 'id'>`
+- **Response**: `{ "id": string, "success": true }`
+
+---
+
+## 2. 자산 및 잔고 (Portfolio)
+
+### 2.1 보유 종목 리스트
+- **URL**: `GET /api/holdings`
+- **Query**: `?market=Domestic|Overseas`
+- **Response**: `HoldingItem[]`
+
+### 2.2 계좌 요약 (자산/예수금)
+- **URL**: `GET /api/account/summary`
+- **Response**: `{ "totalAssets": number, "buyingPower": number }`
+
+---
+
+## 3. 자동매매 전략 (Auto Trading)
+
+### 3.1 로봇 리스트 조회
+- **URL**: `GET /api/auto-trades`
+- **Response**: `AutoTradeConfig[]`
+
+### 3.2 로봇 등록/수정
+- **URL**: `POST /api/auto-trades`
+- **Body**: `AutoTradeConfig` (ID가 없으면 생성, 있으면 수정)
+- **Response**: `{ "id": string }`
+
+---
+
+## 4. 실시간 감시 주문 (Reserved Orders)
+
+### 4.1 감시 목록 조회
+- **URL**: `GET /api/reserved-orders`
+- **Response**: `ReservedOrder[]`
+
+### 4.2 감시 등록
+- **URL**: `POST /api/reserved-orders`
+- **Body**: `Omit<ReservedOrder, 'id' | 'status' | 'createdAt'>`
+- **Response**: `{ "id": string }`
+
+---
+
+## 5. 종목 및 시세 (Market Data & Discovery)
+
+### 5.1 마스터 종목 리스트 (동기화용)
+- **URL**: `GET /api/kis/master-stocks`
+- **Query**: `?market=Domestic|Overseas`
+- **Response**: `StockItem[]`
+
+### 5.2 개별 종목 시세 차트 데이터
+- **URL**: `GET /api/kis/ticks/:code`
+- **Query**: `?limit=100`
+- **Response**: `StockTick[]`
+
+### 5.3 [NEW] 종목 발굴 랭킹 데이터
+- **URL**: `GET /api/discovery/rankings`
+- **Query**: `?market=Domestic|Overseas&category=VOLUME|VALUE|GAIN|LOSS|FOREIGN_BUY|INSTITUTION_BUY`
+- **Response**: `DiscoveryRankingResponse` (See models.md)
+- **설명**: 토스증권 스타일의 발굴 페이지에 데이터를 공급합니다. 거래비율(buyRatio/sellRatio) 및 수급 데이터가 포함됩니다.
+
+### 5.4 [NEW] 실시간 커뮤니티 심리 요약 (AI 전용)
+- **URL**: `GET /api/discovery/sentiment/:code`
+- **Response**: `{ "insights": string[], "sentimentScore": number }`
+- **설명**: 특정 종목에 대한 AI의 실시간 커뮤니티/뉴스 요약 정보를 반환합니다.
--- a/backend/models.md
+++ b/backend/models.md
@@ -0,0 +1,126 @@
+# 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 | 순위별 종목 리스트 |
--- a/backend/tables.md
+++ b/backend/tables.md
@@ -0,0 +1,71 @@
+# BatchuKis Database Schema Definition
+
+이 문서는 데이터베이스 설계를 위한 테이블 명세서입니다. 모든 컬럼명은 [models.md](./models.md)의 필드명과 일치해야 합니다.
+
+## 1. api_settings (사용자 및 API 설정)
+- 단일 사용자 환경이므로 `id=1` 레코드만 사용.
+- `aiConfigs`는 별도의 `ai_configs` 테이블과 Join하여 처리.
+
+## 2. ai_configs (AI 엔진 프로필)
+- `id`: TEXT (PK)
+- `name`: TEXT
+- `providerType`: TEXT (gemini | openai-compatible)
+- `modelName`: TEXT
+- `baseUrl`: TEXT (Nullable)
+
+## 3. holdings (현재 보유 종목)
+- `code`: TEXT (PK)
+- `name`: TEXT
+- `avgPrice`: REAL
+- `quantity`: INTEGER
+- `market`: TEXT (Domestic | Overseas)
+
+## 4. auto_trade_configs (자동매매 로봇)
+- `id`: TEXT (PK)
+- `stockCode`: TEXT (Nullable)
+- `stockName`: TEXT
+- `groupId`: TEXT (Nullable)
+- `type`: TEXT (ACCUMULATION | TRAILING_STOP)
+- `quantity`: INTEGER
+- `frequency`: TEXT (DAILY | WEEKLY | MONTHLY)
+- `specificDay`: INTEGER
+- `executionTime`: TEXT
+- `trailingPercent`: REAL
+- `active`: BOOLEAN
+- `market`: TEXT
+
+## 5. reserved_orders (실시간 감시/예약 주문)
+- `id`: TEXT (PK)
+- `stockCode`: TEXT
+- `stockName`: TEXT
+- `type`: TEXT (BUY | SELL)
+- `quantity`: INTEGER
+- `monitoringType`: TEXT
+- `triggerPrice`: REAL
+- `trailingType`: TEXT
+- `trailingValue`: REAL
+- `status`: TEXT
+- `createdAt`: DATETIME
+- `expiryDate`: DATETIME
+
+## 6. watchlist_groups (관심 종목 그룹)
+- `id`: TEXT (PK)
+- `name`: TEXT
+- `codes`: TEXT (JSON String Array - e.g. '["005930", "NVDA"]')
+- `market`: TEXT
+
+## 7. [NEW] discovery_rank_cache (발굴 랭킹 캐시)
+- `category`: TEXT (PK - VOLUME, VALUE 등)
+- `market`: TEXT (PK)
+- `rank_json`: TEXT (JSON String - StockItem 리스트 보관)
+- `updated_at`: DATETIME
+- **용도**: 랭킹 연산은 리소스가 많이 들므로 1~5분 단위로 배치 처리 후 캐시된 데이터를 API로 제공.
+
+## 8. [NEW] stock_stats (종목별 확장 통계)
+- `code`: TEXT (PK)
+- `tradingValue`: REAL
+- `buyRatio`: INTEGER
+- `sellRatio`: INTEGER
+- `foreignNetBuy`: INTEGER
+- `institutionalNetBuy`: INTEGER
+- **용도**: `StockItem` 테이블을 직접 확장하거나 별도 통계 테이블로 관리하여 발굴 데이터 조회 성능 최적화.