AlphaFuturesPro/backend/service_implementation/api_documentation.md

# 期货分析系统 API 接口文档

本文档详细描述了 `service_implementation` 模块提供的所有 RESTful API 接口，方便业务方使用。

## 1. 接口概览

| 接口路径 | 方法 | 功能描述 |
|---------|------|----------|
| `/health` | GET | 健康检查接口 |
| `/api/contracts` | GET | 获取合约列表 |
| `/api/kline` | GET | 获取K线数据 |
| `/api/analyze` | POST | 市场分析接口 |
| `/api/recommendations` | GET | 获取交易建议 |
| `/api/risk` | POST | 风险监控接口 |
| `/api/analysis/history` | GET | 获取分析历史 |

## 2. 详细接口文档

### 2.1 健康检查接口

**接口路径**：`/health`

**请求方法**：GET

**功能描述**：检查服务是否正常运行

**请求参数**：无

**响应格式**：
```json
{
  "status": "ok",
  "message": "Service is running"
}
```

**示例请求**：
```bash
GET http://localhost:5000/health
```

**示例响应**：
```json
{
  "status": "ok",
  "message": "Service is running"
}
```

### 2.2 合约数据获取接口

**接口路径**：`/api/contracts`

**请求方法**：GET

**功能描述**：获取合约列表，支持按交易所和品种过滤

**请求参数**：
| 参数名 | 类型 | 必填 | 描述 | 默认值 |
|--------|------|------|------|--------|
| `exchange` | string | 否 | 交易所代码，如 'SHFE' | 空字符串（获取所有交易所） |
| `symbol` | string | 否 | 品种代码，如 'CU' | 空字符串（获取所有品种） |

**响应格式**：
```json
{
  "status": "success",
  "data": [
    {
      "symbol": "CU2603",
      "product": "CU",
      "product_name": "铜",
      "exchange": "SHFE",
      "month": "2603"
    }
  ]
}
```

**示例请求**：
```bash
GET http://localhost:5000/api/contracts?exchange=SHFE&symbol=CU
```

**示例响应**：
```json
{
  "status": "success",
  "data": [
    {
      "symbol": "CU2603",
      "product": "CU",
      "product_name": "铜",
      "exchange": "SHFE",
      "month": "2603"
    },
    {
      "symbol": "CU2604",
      "product": "CU",
      "product_name": "铜",
      "exchange": "SHFE",
      "month": "2604"
    }
  ]
}
```

### 2.3 K线数据获取接口

**接口路径**：`/api/kline`

**请求方法**：GET

**功能描述**：获取K线数据，支持不同时间周期和数据量

**请求参数**：
| 参数名 | 类型 | 必填 | 描述 | 默认值 |
|--------|------|------|------|--------|
| `symbol` | string | 是 | 合约代码，如 'CU2603' | 无 |
| `duration` | string | 否 | 时间周期，如 '1m', '5m', '1h', '1d' | '1m' |
| `limit` | integer | 否 | 数据量限制 | 100 |

**响应格式**：
```json
{
  "status": "success",
  "data": [
    {
      "datetime": "2026-02-23T09:00:00",
      "open": 35000.0,
      "high": 35100.0,
      "low": 34900.0,
      "close": 35050.0,
      "volume": 1000,
      "open_interest": 10000
    }
  ]
}
```

**示例请求**：
```bash
GET http://localhost:5000/api/kline?symbol=CU2603&duration=1m&limit=10
```

**示例响应**：
```json
{
  "status": "success",
  "data": [
    {
      "datetime": "2026-02-23T09:00:00",
      "open": 35000.0,
      "high": 35100.0,
      "low": 34900.0,
      "close": 35050.0,
      "volume": 1000,
      "open_interest": 10000
    },
    {
      "datetime": "2026-02-23T09:01:00",
      "open": 35050.0,
      "high": 35150.0,
      "low": 35000.0,
      "close": 35100.0,
      "volume": 1200,
      "open_interest": 10200
    }
  ]
}
```

### 2.4 DeepSeek 分析接口

**接口路径**：`/api/analyze`

**请求方法**：POST

**功能描述**：使用 AI 进行市场分析，返回分析结果

**请求参数**：
| 参数名 | 类型 | 必填 | 描述 | 默认值 |
|--------|------|------|------|--------|
| `symbol` | string | 是 | 合约代码，如 'CU2603' | 无 |
| `duration` | string | 否 | 时间周期，如 '1m', '5m', '1h', '1d' | '1m' |
| `analysis_type` | string | 否 | 分析类型，如 'technical' | 'technical' |

**请求体示例**：
```json
{
  "symbol": "CU2603",
  "duration": "1h",
  "analysis_type": "technical"
}
```

**响应格式**：
```json
{
  "status": "success",
  "data": {
    "symbol": "CU2603",
    "timestamp": "2026-02-23T10:00:00",
    "trend": "up",
    "probability": 0.8,
    "direction": "buy",
    "cycle": "short",
    "atr": 120.5,
    "adx": 25.3,
    "support": 34800.0,
    "resistance": 35200.0,
    "stop_loss": 34700.0,
    "target_price": 35500.0,
    "position_size": 1.0,
    "risk_ratio": 2.0,
    "fund_flow": {},
    "signals": {}
  }
}
```

**示例请求**：
```bash
POST http://localhost:5000/api/analyze
Content-Type: application/json

{
  "symbol": "CU2603",
  "duration": "1h",
  "analysis_type": "technical"
}
```

**示例响应**：
```json
{
  "status": "success",
  "data": {
    "symbol": "CU2603",
    "timestamp": "2026-02-23T10:00:00",
    "trend": "up",
    "probability": 0.8,
    "direction": "buy",
    "cycle": "short",
    "atr": 120.5,
    "adx": 25.3,
    "support": 34800.0,
    "resistance": 35200.0,
    "stop_loss": 34700.0,
    "target_price": 35500.0,
    "position_size": 1.0,
    "risk_ratio": 2.0,
    "fund_flow": {},
    "signals": {}
  }
}
```

### 2.5 交易建议接口

**接口路径**：`/api/recommendations`

**请求方法**：GET

**功能描述**：获取交易建议列表

**请求参数**：
| 参数名 | 类型 | 必填 | 描述 | 默认值 |
|--------|------|------|------|--------|
| `symbol` | string | 是 | 合约代码，如 'CU2603' | 无 |
| `status` | string | 否 | 建议状态，如 'pending', 'executed', 'cancelled' | 空字符串（获取所有状态） |

**响应格式**：
```json
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "symbol": "CU2603",
      "timestamp": "2026-02-23T10:00:00",
      "direction": "buy",
      "entry_price": 35000.0,
      "stop_loss": 34700.0,
      "target_price": 35500.0,
      "position_size": 1.0,
      "execution_plan": "分批入场",
      "risk_tips": "注意止损",
      "status": "pending",
      "created_at": "2026-02-23T10:00:00"
    }
  ]
}
```

**示例请求**：
```bash
GET http://localhost:5000/api/recommendations?symbol=CU2603&status=pending
```

**示例响应**：
```json
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "symbol": "CU2603",
      "timestamp": "2026-02-23T10:00:00",
      "direction": "buy",
      "entry_price": 35000.0,
      "stop_loss": 34700.0,
      "target_price": 35500.0,
      "position_size": 1.0,
      "execution_plan": "分批入场",
      "risk_tips": "注意止损",
      "status": "pending",
      "created_at": "2026-02-23T10:00:00"
    }
  ]
}
```

### 2.6 风险监控接口

**接口路径**：`/api/risk`

**请求方法**：POST

**功能描述**：监控交易风险状态，返回风险评估结果

**请求参数**：
| 参数名 | 类型 | 必填 | 描述 | 默认值 |
|--------|------|------|------|--------|
| `symbol` | string | 是 | 合约代码，如 'CU2603' | 无 |
| `current_price` | number | 是 | 当前价格 | 无 |
| `entry_price` | number | 是 | 入场价格 | 无 |
| `stop_loss` | number | 是 | 止损价格 | 无 |
| `target_price` | number | 是 | 目标价格 | 无 |

**请求体示例**：
```json
{
  "symbol": "CU2603",
  "current_price": 36000.0,
  "entry_price": 35000.0,
  "stop_loss": 34500.0,
  "target_price": 37000.0
}
```

**响应格式**：
```json
{
  "status": "success",
  "data": {
    "symbol": "CU2603",
    "current_price": 36000.0,
    "entry_price": 35000.0,
    "stop_loss": 34500.0,
    "target_price": 37000.0,
    "current_profit": 1000.0,
    "risk_status": "high"
  }
}
```

**示例请求**：
```bash
POST http://localhost:5000/api/risk
Content-Type: application/json

{
  "symbol": "CU2603",
  "current_price": 36000.0,
  "entry_price": 35000.0,
  "stop_loss": 34500.0,
  "target_price": 37000.0
}
```

**示例响应**：
```json
{
  "status": "success",
  "data": {
    "symbol": "CU2603",
    "current_price": 36000.0,
    "entry_price": 35000.0,
    "stop_loss": 34500.0,
    "target_price": 37000.0,
    "current_profit": 1000.0,
    "risk_status": "high"
  }
}
```

### 2.7 分析历史接口

**接口路径**：`/api/analysis/history`

**请求方法**：GET

**功能描述**：获取历史分析结果

**请求参数**：
| 参数名 | 类型 | 必填 | 描述 | 默认值 |
|--------|------|------|------|--------|
| `symbol` | string | 是 | 合约代码，如 'CU2603' | 无 |
| `limit` | integer | 否 | 数据量限制 | 100 |

**响应格式**：
```json
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "symbol": "CU2603",
      "timestamp": "2026-02-23T10:00:00",
      "trend": "up",
      "probability": 0.8,
      "direction": "buy",
      "cycle": "short",
      "atr": 120.5,
      "adx": 25.3,
      "support": 34800.0,
      "resistance": 35200.0,
      "stop_loss": 34700.0,
      "target_price": 35500.0,
      "position_size": 1.0,
      "risk_ratio": 2.0,
      "fund_flow": {},
      "signals": {},
      "created_at": "2026-02-23T10:00:00"
    }
  ]
}
```

**示例请求**：
```bash
GET http://localhost:5000/api/analysis/history?symbol=CU2603&limit=10
```

**示例响应**：
```json
{
  "status": "success",
  "data": [
    {
      "id": 1,
      "symbol": "CU2603",
      "timestamp": "2026-02-23T10:00:00",
      "trend": "up",
      "probability": 0.8,
      "direction": "buy",
      "cycle": "short",
      "atr": 120.5,
      "adx": 25.3,
      "support": 34800.0,
      "resistance": 35200.0,
      "stop_loss": 34700.0,
      "target_price": 35500.0,
      "position_size": 1.0,
      "risk_ratio": 2.0,
      "fund_flow": {},
      "signals": {},
      "created_at": "2026-02-23T10:00:00"
    },
    {
      "id": 2,
      "symbol": "CU2603",
      "timestamp": "2026-02-23T09:00:00",
      "trend": "neutral",
      "probability": 0.5,
      "direction": "hold",
      "cycle": "short",
      "atr": 115.2,
      "adx": 18.7,
      "support": 34900.0,
      "resistance": 35100.0,
      "stop_loss": 34800.0,
      "target_price": 35300.0,
      "position_size": 0.5,
      "risk_ratio": 1.5,
      "fund_flow": {},
      "signals": {},
      "created_at": "2026-02-23T09:00:00"
    }
  ]
}
```

## 3. 错误处理

所有接口都遵循统一的错误响应格式：

```json
{
  "status": "error",
  "message": "错误信息"
}
```

常见错误码：
- `400 Bad Request`：请求参数错误
- `500 Internal Server Error`：服务器内部错误

## 4. 数据缓存机制

- **K线数据**：系统会先尝试从数据库获取，如果没有则从数据源获取并保存到数据库
- **分析结果**：所有分析结果都会保存到数据库，可通过 `/api/analysis/history` 接口查询
- **交易建议**：所有交易建议都会保存到数据库，可通过 `/api/recommendations` 接口查询

## 5. 数据源配置

系统支持从 `config.json` 文件读取数据源配置：

1. **默认数据源**：通过 `dataSource.defaultDataSource` 配置
2. **TQSDK 配置**：通过 `dataSource.tqsdk` 配置账号密码
3. **RQData 配置**：通过 `dataSource.rqdata` 配置账号密码

## 6. 启动服务

```bash
# 安装依赖
pip install -r service_implementation/requirements.txt

# 启动服务
python service_implementation/service/app.py
```

服务默认运行在 `http://0.0.0.0:5000`。

## 7. 测试接口

可以使用以下工具测试接口：
- **Postman**：图形化 API 测试工具
- **curl**：命令行工具
- **Python requests**：Python 库

### 示例：使用 curl 测试健康检查接口

```bash
curl http://localhost:5000/health
```

### 示例：使用 curl 测试合约数据接口

```bash
curl http://localhost:5000/api/contracts?exchange=SHFE&symbol=CU
```

### 示例：使用 curl 测试分析接口

```bash
curl -X POST http://localhost:5000/api/analyze \
  -H "Content-Type: application/json" \
  -d '{"symbol": "CU2603", "duration": "1h", "analysis_type": "technical"}'
```

## 8. 注意事项

1. **API 连接**：服务启动时会自动尝试连接数据源 API，如果连接失败会使用模拟数据
2. **数据格式**：所有价格数据均为浮点数，成交量和持仓量为整数
3. **时间格式**：所有时间字段均为 ISO 8601 格式
4. **错误处理**：使用过程中如遇到错误，请检查请求参数和服务日志
5. **性能优化**：对于高频调用的接口（如 K线数据），建议使用缓存机制减少重复请求

## 9. 版本信息

- **API 版本**：v1.0
- **服务版本**：1.0.0
- **更新时间**：2026-02-23

本文档由期货分析系统自动生成，如有变更请以实际接口为准。