# 快速入门：统一数据获取接口

## 5分钟快速上手

### 1. 安装依赖

```bash
pip install pandas yfinance tushare
```

### 2. 配置 Tushare Token

在项目根目录的 `.env` 文件中添加：

```env
TUSHARE_TOKEN=your_token_here
```

如果没有 token，前往 [Tushare](https://tushare.pro/) 注册获取。

### 3. 第一个示例

```python
from core.datasource.universal_fetcher import fetch_kline

# 获取沪深300指数最近3个月的数据
df = fetch_kline("000300.SH", "2024-01-01", "2024-03-31")

print(f"获取到 {len(df)} 条数据")
print(df.tail())
```

### 4. 批量获取

```python
from core.datasource.universal_fetcher import UniversalDataFetcher

codes = [
    "000300.SH",  # 沪深300
    "510300.SH",  # 沪深300ETF
    "NDX",        # 纳斯达克100
    "HSI",        # 恒生指数
]

fetcher = UniversalDataFetcher()
with fetcher:
    results = fetcher.fetch_multiple(codes, "2024-01-01", "2024-03-31")

for code, df in results.items():
    if df is not None:
        print(f"✓ {code}: {len(df)} 条")
```

## 常用代码速查表

### A股指数

| 代码 | 名称 |
|------|------|
| `000300.SH` | 沪深300 |
| `000016.SH` | 上证50 |
| `399006.SZ` | 创业板指 |
| `000905.SH` | 中证500 |
| `H30269.CSI` | 中证红利低波 |

### A股ETF

| 代码 | 名称 |
|------|------|
| `510300.SH` | 沪深300ETF |
| `159915.SZ` | 创业板ETF |
| `510500.SH` | 中证500ETF |
| `513100.SH` | 纳指ETF |

### 全球指数

| 代码 | 名称 |
|------|------|
| `NDX` | 纳斯达克100 |
| `SPX` | 标普500 |
| `HSI` | 恒生指数 |
| `N225` | 日经225 |
| `GDAXI` | 德国DAX |

### 期货 & 加密资产

| 代码 | 名称 |
|------|------|
| `AU.SHF` | 黄金期货 |
| `BTC` | 比特币 |
| `ETH` | 以太坊 |

## 常见问题

### 获取数据失败怎么办？

1. **检查网络连接**：YFinance 可能需要科学上网
2. **检查 Token**：确保 `.env` 文件中配置了 `TUSHARE_TOKEN`
3. **检查代码格式**：使用 `detect_asset_type()` 检测代码是否正确

```python
from core.datasource.universal_fetcher import detect_asset_type

print(detect_asset_type("000300.SH"))  # 应输出 'china_index'
```

### 如何配置SSH隧道？

```python
ssh_config = {
    "enabled": True,
    "host": "your-server.com",
    "port": 22,
    "username": "root",
    "key_path": "/path/to/key.pem",
    "local_port": 1080,
}

fetcher = UniversalDataFetcher(ssh_config=ssh_config)
with fetcher:
    df = fetcher.fetch("NDX", "2024-01-01", "2024-03-31")
```

## 下一步

- 查看 [完整文档](./universal_fetcher_README.md)
- 运行 [测试脚本](../../tests/test_universal_fetcher.py)
- 学习 [使用示例](../../examples/universal_fetcher_examples.py)