AlphaFuturesPro/backend/python_service/README.md

# Python TQAPI 服务

## 功能说明

Python TQAPI 服务是 AI 期货分析系统的一个组件，负责与天勤量化（TQSDK）进行交互，为系统提供期货市场数据。

## 集成说明

### 自动启动

Python TQAPI 服务已集成到 Node.js 后端服务中，当满足以下条件时会自动启动：

1. 配置文件中 `defaultDataSource` 设置为 `tqsdk`
2. 或配置文件中 `tqsdk.enabled` 设置为 `true`

### 手动启动

如果需要手动启动 Python 服务，可以执行以下命令：

```bash
cd backend/python_service
python main.py
```

## 依赖安装

### Python 依赖

在 `backend/python_service` 目录下执行：

```bash
pip install -r requirements.txt
```

### 依赖包说明

- **tqsdk**：天勤量化 SDK，用于获取期货市场数据
- **fastapi**：高性能的 Python Web 框架，用于提供 API 接口
- **uvicorn**：ASGI 服务器，用于运行 FastAPI 应用
- **pandas**：数据分析库，用于处理和分析数据

## API 端点

| 端点 | 方法 | 功能 |
|------|------|------|
| `/api/connect` | POST | 连接到天勤量化服务 |
| `/api/contracts` | GET | 获取合约列表 |
| `/api/contract/{symbol}` | GET | 获取单个合约详情 |
| `/api/klines/{symbol}` | GET | 获取K线数据 |
| `/api/tick/{symbol}` | GET | 获取Tick数据 |
| `/health` | GET | 健康检查 |

## 配置说明

### 天勤量化账号配置

在 `config.json` 文件中配置天勤量化账号：

```json
{
  "dataSource": {
    "tqsdk": {
      "enabled": true,
      "username": "你的天勤账号",
      "password": "你的天勤密码"
    }
  }
}
```

### 服务端口配置

服务默认运行在端口 8000，可以在 `main.py` 文件中修改：

```python
if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)  # 修改端口号
```

## 故障排查

### 常见问题

1. **Python 服务启动失败**
   - 检查 Python 是否安装
   - 检查依赖包是否安装完整
   - 检查天勤量化账号是否正确

2. **连接天勤服务器失败**
   - 检查网络连接
   - 检查天勤量化账号密码是否正确
   - 检查天勤量化服务是否正常

3. **数据获取失败**
   - 检查合约代码是否正确
   - 检查网络连接
   - 检查天勤量化服务状态

### 日志查看

Python 服务的日志会输出到 Node.js 后端服务的控制台中，可以通过查看控制台日志来排查问题。

## 技术实现

- **FastAPI**：提供 RESTful API 接口
- **TqApi**：与天勤量化服务交互
- **异步处理**：提高并发性能
- **错误处理**：确保服务稳定性