aiagents-stock/docs/TDX数据源配置指南.md

# 📡 TDX数据源配置指南

## 📖 简介

AgentStock1智能盯盘系统已集成TDX股票数据API接口，为用户提供更稳定、更快速的实时行情数据获取能力。

### 数据源优先级

系统采用多数据源降级机制：
1. **TDX API**（优先）- 快速、稳定的本地化数据接口
2. **AKShare**（备选）- 免费的金融数据接口
3. **Tushare**（兜底）- 需要积分的专业数据接口

---

## 🚀 快速开始

### 1. 环境变量配置

在项目根目录的`.env`文件中添加以下配置：

```bash
# TDX股票数据API配置
TDX_ENABLED=true
TDX_BASE_URL=http://192.168.1.222:8080
```

**配置说明：**
- `TDX_ENABLED`: 是否启用TDX数据源（`true`=启用，`false`=禁用）
- `TDX_BASE_URL`: TDX API服务地址（根据实际部署地址修改）

### 2. 验证配置

启动系统后，在日志中查看以下信息：

```
TDX数据源已启用: http://192.168.1.222:8080
✅ TDX成功获取 600519 (贵州茅台) 实时行情
```

---

## 📊 TDX数据源功能

### 支持的数据类型

1. **实时行情数据**
   - 当前价、涨跌幅、涨跌额
   - 开盘价、最高价、最低价、昨收价
   - 成交量、成交额
   - 买卖五档盘口数据

2. **K线数据**
   - 日K线、周K线、月K线
   - 分钟K线（1/5/15/30/60分钟）
   - 支持最多800条历史数据

3. **技术指标**
   - 均线：MA5、MA20、MA60
   - MACD指标：DIF、DEA、MACD
   - RSI指标：RSI6、RSI12、RSI24
   - KDJ指标：K、D、J值
   - 布林带：上轨、中轨、下轨

### 数据单位说明

TDX接口返回的数据单位与系统内部使用的单位不同，系统会自动转换：

| 数据类型 | TDX返回单位 | 系统使用单位 | 转换公式 |
|---------|------------|-------------|---------|
| 价格 | 厘 | 元 | 元 = 厘 / 1000 |
| 成交量 | 手 | 手 | 无需转换 |
| 成交额 | 厘 | 元 | 元 = 厘 / 1000 |

---

## 🔧 配置示例

### 场景1：使用本地TDX服务

```bash
# .env文件配置
TDX_ENABLED=true
TDX_BASE_URL=http://127.0.0.1:8080
```

### 场景2：使用局域网TDX服务

```bash
# .env文件配置
TDX_ENABLED=true
TDX_BASE_URL=http://192.168.1.100:8080
```

### 场景3：禁用TDX，使用AKShare

```bash
# .env文件配置
TDX_ENABLED=false
# TDX_BASE_URL配置可省略
```

---

## 🎯 智能盯盘中的应用

### AI分析数据来源

当启用TDX数据源后，智能盯盘的AI分析将优先使用TDX获取：

1. **实时行情** - 用于判断当前市场状态
2. **技术指标** - 用于分析趋势和买卖点
3. **K线数据** - 用于图表展示和历史分析

### 数据刷新策略

- **交易时段**：每次分析都获取最新数据
- **非交易时段**：使用最近一个交易日的数据
- **降级机制**：TDX失败时自动切换到AKShare或Tushare

---

## 🛠️ 故障排查

### 问题1：TDX连接失败

**现象：**
```
TDX连接失败，请检查接口地址: http://192.168.1.222:8080
```

**解决方案：**
1. 检查TDX服务是否启动
2. 确认服务地址和端口是否正确
3. 测试网络连接：`curl http://192.168.1.222:8080/api/quote?code=000001`

### 问题2：TDX请求超时

**现象：**
```
TDX请求超时 600519
```

**解决方案：**
1. 检查网络状况
2. TDX服务器负载是否过高
3. 调整超时时间（在`smart_monitor_tdx_data.py`中修改`timeout`参数）

### 问题3：TDX返回数据为空

**现象：**
```
TDX未返回股票 600519 的行情数据
```

**解决方案：**
1. 确认股票代码格式正确（6位数字）
2. 检查TDX服务是否正常工作
3. 查看TDX服务日志

---

## 📈 性能优势

使用TDX数据源的优势：

| 对比项 | TDX | AKShare | Tushare |
|-------|-----|---------|---------|
| 速度 | ⚡⚡⚡ 极快 | ⚡⚡ 较快 | ⚡ 一般 |
| 稳定性 | ✅ 极高 | ⚠️ 中等 | ✅ 高 |
| IP限制 | ❌ 无 | ⚠️ 有 | ❌ 无 |
| 积分要求 | ❌ 无 | ❌ 无 | ✅ 需要 |
| 成本 | 💰 本地部署 | 🆓 免费 | 💰 积分制 |

---

## 🔄 降级机制说明

系统采用智能降级策略，确保数据获取的可靠性：

```
1. 首选TDX（如果启用）
   ↓ 失败
2. 降级到AKShare
   ↓ 失败
3. 降级到Tushare（如果配置）
   ↓ 失败
4. 返回错误，停止分析
```

**日志示例：**
```
TDX获取失败 600519，尝试降级到AKShare
AKShare获取失败 600519，尝试降级到Tushare
✅ Tushare降级成功，获取到 600519 数据
```

---

## 💡 最佳实践

### 推荐配置

```bash
# 主数据源：TDX（快速、稳定）
TDX_ENABLED=true
TDX_BASE_URL=http://192.168.1.222:8080

# 备用数据源：Tushare（需要配置Token）
TUSHARE_TOKEN=your_tushare_token_here
```

### 优化建议

1. **本地部署TDX服务** - 降低网络延迟
2. **配置Tushare Token** - 确保数据源冗余
3. **定期检查日志** - 及时发现数据源异常
4. **监控TDX服务** - 保证服务可用性

---

## 📝 技术细节

### 数据获取流程

```python
# 智能盯盘数据获取示例
from smart_monitor_data import SmartMonitorDataFetcher

# 初始化（自动读取配置）
fetcher = SmartMonitorDataFetcher()

# 获取综合数据（自动选择最优数据源）
data = fetcher.get_comprehensive_data('600519')

# 数据包含：
# - 实时行情：current_price, change_pct, volume, amount...
# - 技术指标：ma5, ma20, macd, rsi, kdj, boll...
# - 数据源标识：data_source='tdx'/'akshare'/'tushare'
```

### 手动指定数据源

```python
# 强制使用TDX
fetcher = SmartMonitorDataFetcher(use_tdx=True, tdx_base_url='http://localhost:8080')

# 禁用TDX，使用AKShare
fetcher = SmartMonitorDataFetcher(use_tdx=False)
```

---

## 🔗 相关文档

- [TDX API接口文档](../API_接口文档.md)
- [智能盯盘使用指南](./智能盯盘使用指南.md)
- [数据源冗余机制使用指南](./数据源冗余机制使用指南.md)

---

## 📞 技术支持

如有问题，请参考：
1. 查看系统日志文件
2. 检查TDX服务状态
3. 提交GitHub Issues

---

**更新日期：** 2024-11-04  
**版本：** v1.0