# 合约数据获取逻辑

## 核心流程

系统启动后，根据合约数据使用配置的数据源获取合约具体数据的整体逻辑如下：

1. **系统初始化**：
   - 后端服务启动时加载配置文件（`config.ts`）
   - 注册市场相关API路由（`market.ts`）

2. **数据源管理**：
   - 通过`DataSourceFactory`创建和管理数据源实例
   - 支持多种数据源类型：TQSDK（实盘数据）、测试数据源（模拟数据）

3. **数据获取流程**：
   - 客户端请求市场数据时，`marketService`中的方法被调用
   - 方法首先检查数据源配置，确定使用哪个数据源
   - 尝试使用配置的数据源获取合约数据
   - 如果主数据源失败，自动切换到备用数据源
   - 处理数据并返回给客户端

4. **合约数据处理**：
   - 使用预定义的合约列表（`futuresList`）作为基础
   - 为每个合约构建完整的合约符号（如`SHFE.rb2505`）
   - 调用数据源的方法获取实时行情、K线等数据
   - 转换数据格式为前端需要的结构

## 代码位置

### 数据源管理
- **数据源工厂**：`backend/src/services/datasource/DataSourceFactory.ts`
  - 负责创建和管理数据源实例
  - 支持数据源的初始化、切换和关闭

- **数据源接口**：`backend/src/services/datasource/DataSource.ts`
  - 定义了数据源必须实现的方法，如获取合约列表、合约详情、K线数据等

- **TQSDK数据源实现**：`backend/src/services/datasource/TQDataSource.ts`
  - 基于TQSDK库实现的实盘数据源
  - 提供获取合约数据的具体方法

### 数据服务
- **市场服务**：`backend/src/services/marketService.ts`
  - 实现了获取市场概览、品种详情、K线数据等方法
  - 处理数据源的选择和切换逻辑
  - 提供数据转换和错误处理

### API接口
- **市场API**：`backend/src/api/market.ts`
  - 提供RESTful API接口，如`/api/market/overview`、`/api/market/detail/:symbol`等
  - 调用市场服务的方法获取数据并返回给客户端

### 配置管理
- **配置文件**：`backend/src/config/index.ts`
  - 存储数据源配置信息，如TQSDK的启用状态和参数

## 数据源切换机制

系统实现了智能的数据源切换机制：
1. 优先使用配置的主数据源（如TQSDK）
2. 如果主数据源失败，自动尝试使用备用数据源（如测试数据源）
3. 如果所有数据源都不可用，返回友好的错误提示

## 数据获取示例

以获取市场概览为例：
1. 客户端请求 `/api/market/overview`
2. `marketService.fetchMarketOverview()` 被调用
3. 检查数据源配置，确定使用TQSDK还是测试数据源
4. 如果使用TQSDK，创建TQSDK数据源实例并初始化
5. 遍历合约列表，为每个合约构建完整符号
6. 调用数据源的 `getTickData()` 方法获取实时行情
7. 处理数据并返回给客户端
8. 如果TQSDK失败，自动切换到测试数据源

## 主力合约获取

### 核心流程

1. **主力合约获取机制**：
   - 系统通过TQSDK的`query_quotes()`方法获取主力合约数据
   - 支持实盘数据和模拟数据两种模式
   - 实现了异常处理和超时机制，确保获取过程稳定

2. **数据处理**：
   - 从TQSDK获取主力合约列表
   - 提取品种代码和对应的主力合约代码
   - 转换为主力合约映射表，便于查询

3. **API接口**：
   - 提供`/api/main-contracts`接口，返回主力合约数据
   - 接口返回格式包含品种代码、品种名称和主力合约代码

### 代码位置

- **TQSDK适配器**：`backend/service_implementation/qihuo_analyzer/data/api_adapters/tqsdk_adapter.py`
  - 实现了`get_main_contracts()`方法，使用TQSDK获取主力合约数据
  - 提供了模拟数据作为fallback

- **数据获取器**：`backend/service_implementation/qihuo_analyzer/data/data_fetcher.py`
  - 实现了`get_main_contracts()`方法，作为适配器方法的包装
  - 提供了统一的主力合约获取接口

- **API服务**：`backend/service_implementation/service/app.py`
  - 添加了`/api/main-contracts`接口，返回主力合约数据
  - 处理数据格式转换和错误处理

### 使用方法

1. **通过API接口获取**：
   ```
   GET http://localhost:5000/api/main-contracts
   ```

2. **在代码中获取**：
   ```python
   from qihuo_analyzer.data.data_fetcher import DataFetcher
   
   data_fetcher = DataFetcher()
   data_fetcher.connect()
   main_contracts = data_fetcher.get_main_contracts()
   print(main_contracts)  # 输出：{'AU': 'AU2603', 'AG': 'AG2603', ...}
   ```

### 技术实现细节

- **TQSDK接口**：使用`query_quotes(ins_class='FUTURE')`获取主力合约数据
- **数据处理**：通过`get_quote()`获取合约详细信息，提取`underlying_symbol`和`instrument_id`
- **异常处理**：实现了多层异常捕获，确保系统稳定性
- **模拟数据**：当TQSDK不可用时，使用预定义的模拟数据

## 技术特点

1. **工厂模式**：使用工厂模式管理数据源实例，提高代码可维护性
2. **接口隔离**：通过接口定义数据源行为，便于扩展新的数据源类型
3. **容错机制**：实现了数据源故障自动切换，提高系统可靠性
4. **配置驱动**：数据源配置通过配置文件管理，便于运维和部署
5. **模块化设计**：将数据获取逻辑与API接口分离，提高代码可读性
6. **主力合约支持**：实现了主力合约的自动获取和管理，方便用户快速访问主要交易合约