# amazingData SDK 集成任务

**项目**: 期货股票数据统一平台 (20260330_kline_system)  
**创建时间**: 2026-04-03  
**协调者**: coordinator  
**优先级**: 🔴 高

---

## 📋 任务概述

将银河证券星耀数智量化平台 SDK (amazingData) 集成到项目中，实现真实的期货/股票数据接入。

---

## 🔐 账号配置信息

| 配置项 | 值 |
|--------|-----|
| 账号 | 11200008169 |
| 密码 | 11200008169@2026 |
| Host | 140.206.44.234 |
| 端口 | 8600 |
| 环境 | production |

**配置文件已更新**:
- `.env` - 环境变量
- `backend/app/config.py` - 应用配置

---

## 📁 SDK 位置

**SDK 目录**: `/app/share_data/xysz/`

**核心文件**:
- `AmazingData/` - SDK 主目录
- `amazing_data_adapter.py` - 数据适配器封装
- `amazing_data_examples.py` - 使用示例
- `tgw-1.0.8.5-py3-none-any.whl` - SDK wheel 包

**参考文档**:
- `AmazingData_SDK 接口调用说明.md`
- `AmazingData 开发手册.md`
- `接口文档.md`

---

## ✅ 集成任务清单

### 1. SDK 安装与导入
- [ ] 安装 SDK: `pip install /app/share_data/xysz/tgw-1.0.8.5-py3-none-any.whl`
- [ ] 复制 adapter 到项目：`backend/app/services/amazing_data_adapter.py`
- [ ] 更新 requirements.txt

### 2. 数据服务层开发
- [ ] 创建 `backend/app/services/amazing_data_service.py`
  - [ ] 登录/登出管理（⚠️ 必须调用 logout 避免连接数超限）
  - [ ] K 线数据获取（股票/期货）
  - [ ] 实时行情订阅
  - [ ] 交易日历查询
  - [ ] 证券代码列表

### 3. API 接口对接
- [ ] 更新 `backend/app/api/kline.py` - 接入真实数据源
- [ ] 更新 `backend/app/api/realtime.py` - 接入实时行情
- [ ] 新增 `backend/app/api/market.py` - 市场数据接口

### 4. 数据同步任务
- [ ] 创建 `backend/app/tasks/sync_kline_data.py`
  - [ ] 定时同步 K 线数据
  - [ ] 缓存到 TimescaleDB
  - [ ] 错误重试机制

### 5. 前端对接
- [ ] 更新前端 API 调用
- [ ] 测试真实数据显示

### 6. 测试与验证
- [ ] 单元测试
- [ ] 连接测试
- [ ] 数据准确性验证

---

## 🔧 SDK 使用示例

```python
from AmazingData import login, logout, BaseData, MarketData

# 登录
ret = login(
    username='11200008169',
    password='11200008169@2026',
    host='140.206.44.234',
    port=8600
)

if ret:
    # 获取数据
    base = BaseData()
    codes = base.get_code_list('EXTRA_FUTURE')  # 期货代码列表
    
    # 获取 K 线数据
    market = MarketData()
    kline = market.get_kline_data(
        code_list=['AG2605.SHF'],
        period='min5',
        start_time=20260326090000,
        end_time=20260326150000
    )
    
    # ⚠️ 重要：必须登出
    logout('11200008169')
```

---

## ⚠️ 注意事项

1. **必须调用 logout()** - 否则会导致 -98 连接数超限错误
2. **连接管理** - 使用连接池或单例模式管理连接
3. **错误处理** - 处理网络异常、登录失败等情况
4. **数据缓存** - 建议缓存到 TimescaleDB 减少 API 调用
5. **限流** - 注意 API 调用频率限制

---

## 📊 验收标准

- [ ] SDK 正常登录/登出
- [ ] K 线数据可正常获取
- [ ] 实时行情可正常订阅
- [ ] 数据存入 TimescaleDB
- [ ] 前端可显示真实数据
- [ ] 单元测试通过率 100%

---

## 📝 完成后的操作

1. 更新此文件，标记完成状态
2. 通知协调者进行验证测试
3. 更新项目文档