문서작업

2026-02-02 23:13:28 +09:00
parent 84746d41b8
commit 6d673e06ce
8 changed files with 531 additions and 179 deletions
--- a/backend/tables.md
+++ b/backend/tables.md
@@ -2,78 +2,107 @@

 이 문서는 데이터베이스 설계를 위한 테이블 명세서입니다. 모든 컬럼명은 [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)
+## 1. System & Config (설정 제어)

-## 3. holdings (현재 보유 종목)
- `code`: TEXT (PK)
- `name`: TEXT
- `avgPrice`: REAL
- `quantity`: INTEGER
- `market`: TEXT (Domestic | Overseas)
+### 1.1 `api_settings` (전체 시스템 설정)
+- **Primary Key**: `id` (INTEGER, ALWAYS 1)
+- **Columns**:
+    - `appKey`, `appSecret`, `accountNumber`: TEXT
+    - `useTelegram`, `useNaverNews`: BOOLEAN
+    - `telegramToken`, `telegramChatId`: TEXT
+    - `naverClientId`, `naverClientSecret`: TEXT
+    - `kisApiDelayMs`, `newsScrapIntervalMin`: INTEGER
+    - `preferredNewsAiId`, `preferredStockAiId`, `preferredNewsJudgementAiId`, `preferredAutoBuyAiId`, `preferredAutoSellAiId`: TEXT (FK to `ai_configs.id`)

-## 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
+### 1.2 `ai_configs` (AI 엔진 프로필 저장소)
+- **Primary Key**: `id` (TEXT)
+- **Columns**: `name`, `providerType`, `modelName`, `baseUrl` (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
+## 2. Account & Portfolio (자산 데이터)

-## 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로 제공.
+### 2.1 `account_status` (계좌 요약 정보)
+- **Primary Key**: `id` (INTEGER, ALWAYS 1)
+- **Columns**: `totalAssets`, `buyingPower`, `dailyProfit`, `dailyProfitRate` (REAL)
+- **Update Frequency**: API 동기화 마다 갱신.

-## 8. [NEW] stock_stats (종목별 확장 통계)
- `code`: TEXT (PK)
- `tradingValue`: REAL
- `buyRatio`: INTEGER
- `sellRatio`: INTEGER
- `foreignNetBuy`: INTEGER
- `institutionalNetBuy`: INTEGER
- **용도**: `StockItem` 테이블을 직접 확장하거나 별도 통계 테이블로 관리하여 발굴 데이터 조회 성능 최적화.
-## 9. market_index_history (시장 지수 이력)
- `index_id`: TEXT (PK - KOSPI, KOSDAQ, NASDAQ, SP500, USDKRW 등)
- `timestamp`: DATETIME (PK - 1시간 단위 정규화된 시각)
- `value`: REAL
- `change`: REAL
- `change_percent`: REAL
- `updated_at`: DATETIME (실제 마지막 갱신 시각)
- **용도**: 트렌드 분석 및 대시보드 인덱스 카드 표시용. 백엔드가 5분 단위로 조회하되, DB에는 1시간 단위로 마지막 데이터를 Upsert 하여 누적.
+### 2.2 `holdings` (보유 자산 목록)
+- **Primary Key**: `stockCode` (TEXT)
+- **Columns**: `stockName` (TEXT), `quantity` (INTEGER), `avgPrice`, `currentPrice`, `profit`, `profitRate`, `marketValue` (REAL)
+
+---
+
+## 3. Market & Discovery (시세 및 탐색 데이터)
+
+### 3.1 `master_stocks` (전체 종목 마스터)
+- **Primary Key**: `code` (TEXT)
+- **Columns**: 
+    - `name`, `market` (TEXT)
+    - `per`, `pbr`, `roe`, `marketCap`, `dividendYield` (REAL)
+    - `memo` (TEXT), `isHidden` (BOOLEAN)
+- **용도**: 종목 검색, 메타데이터 제공 및 사용자 설정(메모/숨김) 저장.
+
+### 3.2 `news_cache` (뉴스 및 분석 캐시)
+- **Primary Key**: `news_id` (TEXT - URL 해시 등)
+- **Columns**: 
+    - `title`, `description`, `link`, `pubDate`: TEXT
+    - `sentiment`: TEXT
+    - `relatedThemes`, `relatedStocks`: TEXT (JSON Array)
+- **용도**: 동일 뉴스에 대한 중복 AI 분석 방지 및 히스토리 제공.
+
+### 3.3 `discovery_ranking_cache` (발굴 랭킹 데이터)
+- **Primary Key**: `category` + `market` (Composite)
+- **Columns**: `updated_at` (DATETIME), `items_json` (TEXT - `StockItem[]` JSON)
+
+### 3.4 `stock_stats` (종목별 확장 통계)
+- **Primary Key**: `code` (TEXT)
+- **Columns**: 
+    - `tradingValue` (REAL)
+    - `buyRatio`, `sellRatio`, `foreignNetBuy`, `institutionalNetBuy` (INTEGER)
+    - `aiScoreBuy`, `aiScoreSell` (INTEGER)
+- **용도**: `StockItem` 확장을 위한 분석/수급 데이터 저장.
+
+---
+
+## 4. Watchlist (보관함)
+
+### 4.1 `watchlist_groups` (그룹 정의)
+- **Primary Key**: `id` (TEXT)
+- **Columns**: `name` (TEXT), `market` (TEXT)
+
+### 4.2 `watchlist_items` (그룹별 포함 종목)
+- **Primary Key**: `group_id` + `stock_code` (Composite)
+- **Columns**: `added_at` (DATETIME)
+- **Relationship**: `group_id` -> `watchlist_groups.id`
+
+---
+
+## 5. Trading & Automation (거래 및 자동화)
+
+### 5.1 `trade_history` (전체 체결 내역)
+- **Primary Key**: `id` (TEXT)
+- **Columns**: 
+    - `stockCode`, `stockName`, `type` (TEXT)
+    - `quantity` (INTEGER), `price` (REAL)
+    - `timestamp` (DATETIME), `status` (TEXT)
+
+### 5.2 `auto_trade_robots` (자동매매 전략 로봇)
+- **Primary Key**: `id` (TEXT)
+- **Columns**: 
+    - `stockCode`, `stockName`, `groupId`, `type`, `frequency`, `executionTime`, `market`: TEXT
+    - `quantity`, `specificDay`: INTEGER
+    - `trailingPercent`: REAL
+    - `active`: BOOLEAN
+
+### 5.3 `reserved_orders` (실시간 감시 주문)
+- **Primary Key**: `id` (TEXT)
+- **Columns**: 
+    - `stockCode`, `stockName`, `type`, `monitoringType`, `trailingType`, `status`, `market`: TEXT
+    - `quantity`: INTEGER
+    - `triggerPrice`, `trailingValue`, `stopLossValue`, `highestPrice`, `lowestPrice`: REAL
+    - `useStopLoss`, `sellAll`: BOOLEAN
+    - `stopLossType`: TEXT
+    - `createdAt`, `expiryDate`: DATETIME