auto-stock/docs/API_DOCS.md

# Auto Stock Trading System - API 문서

## Backend API

### 기본 정보

- **Base URL**: `http://localhost:8000/api/v1`
- **인증**: Bearer Token (JWT)

## 엔드포인트

### 1. Trading Rules (트레이딩 규칙)

#### 규칙 목록 조회
```http
GET /api/v1/rules
```

**Query Parameters:**
- `skip` (int): 건너뛸 개수 (기본: 0)
- `limit` (int): 조회할 개수 (기본: 100)
- `is_active` (bool): 활성화 필터 (선택)

**Response:**
```json
[
  {
    "id": 1,
    "name": "기본 매수 규칙",
    "description": "RSI 30 이하이고 거래량이 평균보다 높을 때 매수",
    "rule_type": "BUY",
    "conditions": {
      "rsi_below": 30,
      "volume_above_average": 1.5
    },
    "actions": {
      "order_type": "BUY",
      "quantity_percent": 10,
      "max_amount": 1000000
    },
    "is_active": true,
    "priority": 10,
    "created_at": "2024-11-04T00:00:00",
    "updated_at": "2024-11-04T00:00:00"
  }
]
```

#### 규칙 생성
```http
POST /api/v1/rules
```

**Request Body:**
```json
{
  "name": "새 규칙",
  "description": "설명",
  "rule_type": "BUY",
  "conditions": {},
  "actions": {},
  "is_active": true,
  "priority": 10
}
```

#### 규칙 수정
```http
PUT /api/v1/rules/{rule_id}
```

#### 규칙 삭제
```http
DELETE /api/v1/rules/{rule_id}
```

#### 규칙 활성화/비활성화
```http
POST /api/v1/rules/{rule_id}/toggle
```

### 2. Trades (거래 이력)

#### 거래 이력 조회
```http
GET /api/v1/trades
```

**Query Parameters:**
- `skip`, `limit`: 페이지네이션
- `stock_code` (string): 종목 코드 필터
- `status` (string): 상태 필터 (PENDING, EXECUTED, FAILED)
- `order_type` (string): 주문 유형 (BUY, SELL)
- `days` (int): 조회 기간 (기본: 30일)

#### 거래 통계
```http
GET /api/v1/trades/stats/summary?days=30
```

**Response:**
```json
{
  "period_days": 30,
  "total_trades": 150,
  "buy_trades": 75,
  "sell_trades": 75,
  "executed_trades": 140,
  "failed_trades": 10,
  "success_rate": 0.933,
  "total_amount": 50000000
}
```

### 3. Portfolio (포트폴리오)

#### 포트폴리오 조회
```http
GET /api/v1/portfolio
```

**Response:**
```json
[
  {
    "id": 1,
    "stock_code": "005930",
    "stock_name": "삼성전자",
    "quantity": 10,
    "average_price": 70000,
    "current_price": 71000,
    "profit_loss": 10000,
    "profit_loss_rate": 1.43
  }
]
```

#### 포트폴리오 동기화
```http
GET /api/v1/portfolio/sync
```

실제 증권 계좌와 포트폴리오를 동기화합니다.

#### 포트폴리오 요약
```http
GET /api/v1/portfolio/summary
```

**Response:**
```json
{
  "total_stocks": 5,
  "total_value": 10000000,
  "total_investment": 9500000,
  "total_profit_loss": 500000,
  "total_profit_loss_rate": 5.26
}
```

### 4. Market Data (시장 데이터)

#### 주식 현재가 조회
```http
GET /api/v1/market/price/{stock_code}
```

**Response:**
```json
{
  "stock_code": "005930",
  "current_price": 71000,
  "change_rate": 1.5,
  "volume": 1000000,
  "high_price": 71500,
  "low_price": 70000,
  "open_price": 70500
}
```

#### 차트 데이터 조회
```http
GET /api/v1/market/chart/{stock_code}?period=D
```

**Query Parameters:**
- `period` (string): D (일봉), W (주봉), M (월봉)

### 5. MCP (Model Context Protocol)

#### MCP 서버 상태
```http
GET /api/v1/mcp/status
```

**Response:**
```json
{
  "status": "connected",
  "mcp_server_url": "http://mcp-server:8001",
  "details": {
    "status": "healthy",
    "claude_configured": true
  }
}
```

#### MCP 도구 목록
```http
GET /api/v1/mcp/tools
```

#### MCP 도구 호출
```http
POST /api/v1/mcp/tools/call
```

**Request Body:**
```json
{
  "tool_name": "get_market_data",
  "parameters": {
    "stock_code": "005930",
    "period": "D"
  }
}
```

#### Claude AI 분석 요청
```http
POST /api/v1/mcp/analyze
```

**Request Body:**
```json
{
  "analysis_type": "RULE_VALIDATION",
  "data": {
    "rule": {},
    "market_data": {}
  }
}
```

**Analysis Types:**
- `RULE_VALIDATION`: 규칙 검증
- `MARKET_ANALYSIS`: 시장 분석
- `RISK_ASSESSMENT`: 리스크 평가

## WebSocket

### 연결

```javascript
const ws = new WebSocket('ws://localhost:8000/ws/{client_id}')
```

### 메시지 타입

#### Market Update
```json
{
  "type": "market_update",
  "stock_code": "005930",
  "data": {
    "price": 71000,
    "change_rate": 1.5
  }
}
```

#### Trade Notification
```json
{
  "type": "trade_notification",
  "data": {
    "order_id": "ORD001",
    "status": "EXECUTED"
  }
}
```

#### MCP Status
```json
{
  "type": "mcp_status",
  "data": {
    "status": "connected"
  }
}
```

## 에러 응답

모든 에러는 다음 형식으로 반환됩니다:

```json
{
  "detail": "에러 메시지"
}
```

**상태 코드:**
- `400`: Bad Request
- `401`: Unauthorized
- `404`: Not Found
- `500`: Internal Server Error
- `504`: Gateway Timeout