From d647773ff6f7fc745abcebc805a749488befb925 Mon Sep 17 00:00:00 2001
From: Lxy <windsdreaming@163.com>
Date: Fri, 20 Feb 2026 23:03:59 +0800
Subject: [PATCH] =?UTF-8?q?feat:=20=E5=A2=9E=E5=8A=A0=E5=90=88=E7=BA=A6?=
 =?UTF-8?q?=E6=95=B0=E6=8D=AE=E8=8E=B7=E5=8F=96=E9=80=BB=E8=BE=91=E6=96=87?=
 =?UTF-8?q?=E6=A1=A3?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/开发文档/合约数据获取逻辑.md | 82 +++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 docs/开发文档/合约数据获取逻辑.md

diff --git a/docs/开发文档/合约数据获取逻辑.md b/docs/开发文档/合约数据获取逻辑.md
new file mode 100644
index 0000000..3d32fb1
--- /dev/null
+++ b/docs/开发文档/合约数据获取逻辑.md
@@ -0,0 +1,82 @@
+# 合约数据获取逻辑
+
+## 核心流程
+
+系统启动后，根据合约数据使用配置的数据源获取合约具体数据的整体逻辑如下：
+
+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. **工厂模式**：使用工厂模式管理数据源实例，提高代码可维护性
+2. **接口隔离**：通过接口定义数据源行为，便于扩展新的数据源类型
+3. **容错机制**：实现了数据源故障自动切换，提高系统可靠性
+4. **配置驱动**：数据源配置通过配置文件管理，便于运维和部署
+5. **模块化设计**：将数据获取逻辑与API接口分离，提高代码可读性
\ No newline at end of file