# 智能期货期权分析系统 - API接口文档

## 接口规范

### 基础信息

- **协议**: HTTPS
- **数据格式**: JSON
- **字符编码**: UTF-8
- **请求方式**: RESTful

### 响应格式

```json
{
  "code": 200,
  "message": "success",
  "data": {}
}
```

### 错误码

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 行情数据接口

### 1. 获取品种列表

**接口**: `GET /api/v1/products`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category | string | 否 | 分类筛选 |
| page | number | 否 | 页码，默认1 |
| size | number | 否 | 每页数量，默认20 |

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": "1",
        "name": "原油",
        "code": "SC",
        "category": "energy",
        "price": 528.6,
        "change": 12.1,
        "changePercent": 2.35,
        "trendScore": 85,
        "successRate": 72
      }
    ],
    "total": 100,
    "page": 1,
    "size": 20
  }
}
```

### 2. 获取K线数据

**接口**: `GET /api/v1/products/{symbol}/kline`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| period | string | 是 | 周期: 1m/5m/15m/30m/1h/1d/1w |
| count | number | 否 | 返回条数，默认100 |
| startTime | string | 否 | 开始时间 ISO8601 |
| endTime | string | 否 | 结束时间 ISO8601 |

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "symbol": "SC",
    "period": "15m",
    "data": [
      {
        "time": "2025-03-03T10:00:00Z",
        "open": 525.0,
        "high": 528.5,
        "low": 524.0,
        "close": 527.5,
        "volume": 12580
      }
    ]
  }
}
```

### 3. 获取实时行情

**接口**: `GET /api/v1/products/{symbol}/tick`

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "symbol": "SC",
    "price": 528.6,
    "change": 12.1,
    "changePercent": 2.35,
    "open": 518.0,
    "high": 535.0,
    "low": 515.5,
    "volume": 285600,
    "openInterest": 125800,
    "bidPrice": 528.5,
    "askPrice": 528.7,
    "bidVolume": 125,
    "askVolume": 89,
    "timestamp": 1709452800000
  }
}
```

### 4. WebSocket实时订阅

**接口**: `wss://api.example.com/ws/v1/market`

**订阅消息**:

```json
{
  "action": "subscribe",
  "symbols": ["SC", "AU", "CU"],
  "channels": ["tick", "kline"]
}
```

**推送消息**:

```json
{
  "type": "tick",
  "symbol": "SC",
  "data": {
    "price": 528.6,
    "volume": 100,
    "timestamp": 1709452800000
  }
}
```

---

## 技术指标接口

### 5. 获取技术指标

**接口**: `GET /api/v1/products/{symbol}/indicators`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| period | string | 是 | 周期 |
| indicators | string | 是 | 指标列表，逗号分隔 |

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "symbol": "SC",
    "period": "15m",
    "indicators": {
      "macd": {
        "dif": 0.5234,
        "dea": 0.4123,
        "macd": 0.2222,
        "signal": "golden_cross"
      },
      "rsi": {
        "value": 65.5,
        "status": "normal"
      },
      "bollinger": {
        "upper": 535.0,
        "middle": 525.0,
        "lower": 515.0,
        "position": "upper"
      }
    }
  }
}
```

---

## 热点事件接口

### 6. 获取热点事件列表

**接口**: `GET /api/v1/events`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| impact | string | 否 | 影响类型: bullish/bearish/neutral |
| startDate | string | 否 | 开始日期 |
| endDate | string | 否 | 结束日期 |

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "id": "1",
        "title": "地缘政治风险升级",
        "time": "2025-03-02",
        "summary": "美以袭伊朗，海上油阀被关",
        "affectedProducts": ["原油", "黄金", "白银"],
        "impact": "bullish",
        "impactLevel": 5,
        "analysis": "地缘政治风险急剧升温...",
        "risks": ["冲突升级可能", "供应中断风险"]
      }
    ]
  }
}
```

### 7. 获取事件详情

**接口**: `GET /api/v1/events/{id}`

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "id": "1",
    "title": "地缘政治风险升级",
    "content": "详细内容...",
    "analysis": "智能分析...",
    "relatedProducts": [
      {
        "symbol": "SC",
        "name": "原油",
        "impact": "bullish",
        "confidence": 0.85
      }
    ]
  }
}
```

---

## 分析接口

### 8. 获取交易建议

**接口**: `GET /api/v1/products/{symbol}/advice`

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "symbol": "SC",
    "action": "long",
    "entryPrice": 525.0,
    "stopLoss": 518.0,
    "targetPrice": 535.0,
    "riskLevel": "medium",
    "position": "medium",
    "holdingTime": "short",
    "reason": "地缘政治风险推动，多周期共振向上",
    "confidence": 0.72
  }
}
```

### 9. 获取多周期分析

**接口**: `GET /api/v1/products/{symbol}/multi-timeframe`

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "symbol": "SC",
    "consistency": 0.75,
    "cycles": [
      {
        "period": "m5",
        "trend": "up",
        "trendStrength": 85,
        "signal": "buy"
      },
      {
        "period": "m15",
        "trend": "up",
        "trendStrength": 78,
        "signal": "buy"
      },
      {
        "period": "m30",
        "trend": "up",
        "trendStrength": 72,
        "signal": "buy"
      },
      {
        "period": "m60",
        "trend": "sideways",
        "trendStrength": 45,
        "signal": "neutral"
      }
    ]
  }
}
```

---

## 期权接口

### 10. 获取期权链

**接口**: `GET /api/v1/options/{underlying}/chain`

**请求参数**:

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| expiry | string | 否 | 到期日 |

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "underlying": "SC",
    "expiry": "2025-04-15",
    "strikes": [500, 510, 520, 530, 540],
    "calls": [
      {
        "strike": 520,
        "price": 15.5,
        "iv": 0.25,
        "delta": 0.65,
        "gamma": 0.02,
        "theta": -0.15,
        "vega": 0.35
      }
    ],
    "puts": [
      {
        "strike": 520,
        "price": 8.5,
        "iv": 0.26,
        "delta": -0.35,
        "gamma": 0.02,
        "theta": -0.12,
        "vega": 0.33
      }
    ]
  }
}
```

### 11. 期权定价计算

**接口**: `POST /api/v1/options/pricing`

**请求参数**:

```json
{
  "underlying": "SC",
  "strike": 520,
  "expiry": "2025-04-15",
  "type": "call",
  "price": 528.6,
  "volatility": 0.25,
  "riskFreeRate": 0.025
}
```

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "price": 15.52,
    "delta": 0.6523,
    "gamma": 0.0215,
    "theta": -0.1523,
    "vega": 0.3521,
    "rho": 0.1234,
    "impliedVol": 0.25
  }
}
```

---

## 用户接口

### 12. 用户注册

**接口**: `POST /api/v1/auth/register`

**请求参数**:

```json
{
  "username": "user123",
  "email": "user@example.com",
  "password": "password123",
  "phone": "13800138000"
}
```

### 13. 用户登录

**接口**: `POST /api/v1/auth/login`

**请求参数**:

```json
{
  "username": "user123",
  "password": "password123"
}
```

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "refreshToken": "eyJhbGciOiJIUzI1NiIs...",
    "expiresIn": 3600,
    "user": {
      "id": "1",
      "username": "user123",
      "email": "user@example.com"
    }
  }
}
```

### 14. 获取自选股

**接口**: `GET /api/v1/user/watchlist`

**响应示例**:

```json
{
  "code": 200,
  "message": "success",
  "data": {
    "list": [
      {
        "symbol": "SC",
        "name": "原油",
        "addTime": "2025-03-01T10:00:00Z",
        "alertPrice": 550.0
      }
    ]
  }
}
```

### 15. 添加自选股

**接口**: `POST /api/v1/user/watchlist`

**请求参数**:

```json
{
  "symbol": "SC",
  "alertPrice": 550.0
}
```

---

## 待实现接口清单

| 接口 | 说明 | 优先级 |
|------|------|--------|
| POST /api/v1/user/watchlist/{symbol} | 删除自选股 | ⭐⭐⭐ |
| GET /api/v1/user/alerts | 获取价格预警 | ⭐⭐⭐⭐ |
| POST /api/v1/user/alerts | 设置价格预警 | ⭐⭐⭐⭐ |
| GET /api/v1/user/trades | 获取交易记录 | ⭐⭐⭐ |
| POST /api/v1/user/trades | 记录模拟交易 | ⭐⭐⭐ |
| GET /api/v1/signals | 获取交易信号 | ⭐⭐⭐⭐⭐ |
| GET /api/v1/market/heatmap | 市场热力图 | ⭐⭐⭐ |
| GET /api/v1/market/breadth | 市场宽度 | ⭐⭐⭐ |
| POST /api/v1/backtest | 策略回测 | ⭐⭐⭐ |
| GET /api/v1/news | 财经新闻 | ⭐⭐⭐⭐ |