# Universal Data Fetcher API 文档

## 概述

提供统一的 RESTful API 接口，支持获取各类资产的 K 线数据（OHLCV）。

## 支持的资产类型

- **A股指数**: `000300.SH`, `399006.SZ`, `H30269.CSI`
- **A股ETF**: `510300.SH`, `159915.SZ`, `513100.SH`
- **A股股票**: `600000.SH`, `000001.SZ`
- **港股指数**: `HSI`, `HSTECH.HK`
- **美股指数**: `NDX`, `SPX`, `DJI`, `N225`, `GDAXI`
- **美股股票**: `AAPL`, `MSFT`, `GOOGL`, `AMZN`, `TSLA`
- **期货合约**: `AU.SHF`, `CU.SHF`
- **加密货币**: `BTC`, `ETH`

## 快速开始

### 1. 启动服务

```bash
# 基础启动（仅支持A股）
./start_flask_server.sh

# 启用 SSH 隧道（支持港美股）
./start_flask_server.sh --with-ssh

# 指定端口
./start_flask_server.sh --port 8080 --with-ssh

# 调试模式
./start_flask_server.sh --debug --with-ssh
```

### 2. 测试 API

```bash
# 健康检查
curl http://localhost:5000/health

# 获取K线数据
curl 'http://localhost:5000/api/v1/ohlcv?code=000300.SH&start=2024-01-01&end=2024-03-31'

# 批量获取
curl -X POST http://localhost:5000/api/v1/ohlcv/batch \
  -H "Content-Type: application/json" \
  -d '{
    "codes": ["000300.SH", "NDX", "HSI"],
    "start": "2024-01-01",
    "end": "2024-03-31"
  }'
```

## API 端点

### 1. 健康检查

```http
GET /health
```

**响应**:
```json
{
  "status": "healthy",
  "timestamp": "2024-01-15T10:30:00",
  "ssh_configured": true
}
```

### 2. 检测资产类型

```http
GET /api/v1/asset-type?code={code}
```

**参数**:
- `code` (required): 标的代码

**响应**:
```json
{
  "code": "000300.SH",
  "asset_type": "china_index",
  "description": "A股指数"
}
```

**示例**:
```bash
curl 'http://localhost:5000/api/v1/asset-type?code=000300.SH'
curl 'http://localhost:5000/api/v1/asset-type?code=NDX'
curl 'http://localhost:5000/api/v1/asset-type?code=BTC'
```

### 3. 获取K线数据

```http
GET /api/v1/ohlcv?code={code}&start={start}&end={end}&retry={retry}
```

**参数**:
- `code` (required): 标的代码
- `start` (optional): 开始日期，格式 `YYYY-MM-DD`，默认90天前
- `end` (optional): 结束日期，格式 `YYYY-MM-DD`，默认今天
- `retry` (optional): 重试次数，默认3

**响应**:
```json
{
  "code": "000300.SH",
  "asset_type": "china_index",
  "data": [
    {
      "date": "2024-01-02",
      "open": 3538.7244,
      "high": 3542.9624,
      "low": 3502.7866,
      "close": 3502.7866,
      "volume": 128626763.0,
      "code": "000300.SH"
    },
    ...
  ],
  "count": 58,
  "date_range": {
    "start": "2024-01-02",
    "end": "2024-03-29"
  },
  "columns": ["date", "open", "high", "low", "close", "volume", "code"]
}
```

**示例**:
```bash
# 获取沪深300指数
curl 'http://localhost:5000/api/v1/ohlcv?code=000300.SH&start=2024-01-01&end=2024-03-31'

# 获取纳斯达克100指数（需要SSH隧道）
curl 'http://localhost:5000/api/v1/ohlcv?code=NDX&start=2024-01-01&end=2024-03-31'

# 获取黄金期货
curl 'http://localhost:5000/api/v1/ohlcv?code=AU.SHF&start=2024-01-01&end=2024-03-31'
```

### 4. 批量获取K线数据

```http
POST /api/v1/ohlcv/batch
```

**请求体**:
```json
{
  "codes": ["000300.SH", "NDX", "HSI"],
  "start": "2024-01-01",
  "end": "2024-03-31",
  "retry": 3
}
```

**响应**:
```json
{
  "results": {
    "000300.SH": {
      "code": "000300.SH",
      "asset_type": "china_index",
      "data": [...],
      "count": 58,
      "date_range": {...}
    },
    "NDX": {
      "code": "NDX",
      "asset_type": "us_index",
      "data": [...],
      "count": 61,
      "date_range": {...}
    },
    "HSI": {
      "code": "HSI",
      "asset_type": "hk_index",
      "error": "No data available",
      "data": [],
      "count": 0
    }
  },
  "success_count": 2,
  "failed_count": 1,
  "total": 3,
  "start": "2024-01-01",
  "end": "2024-03-31"
}
```

**示例**:
```bash
curl -X POST http://localhost:5000/api/v1/ohlcv/batch \
  -H "Content-Type: application/json" \
  -d '{
    "codes": ["000300.SH", "510300.SH", "NDX", "HSI", "AU.SHF"],
    "start": "2024-01-01",
    "end": "2024-03-31"
  }'
```

### 5. 获取支持的代码示例

```http
GET /api/v1/supported-codes
```

**响应**:
```json
{
  "china_index": {
    "description": "A股指数",
    "examples": ["000300.SH", "399006.SZ", "000016.SH", "H30269.CSI"]
  },
  "china_etf": {
    "description": "A股ETF",
    "examples": ["510300.SH", "159915.SZ", "510500.SH", "513100.SH"]
  },
  ...
}
```

## Python 客户端

### 安装

```bash
pip install requests
```

### 使用示例

```python
import requests

# 基础配置
BASE_URL = "http://localhost:5000"

# 1. 健康检查
response = requests.get(f"{BASE_URL}/health")
print(response.json())

# 2. 获取单只标的
def get_ohlcv(code, start, end):
    response = requests.get(
        f"{BASE_URL}/api/v1/ohlcv",
        params={"code": code, "start": start, "end": end}
    )
    return response.json()

# 获取沪深300
data = get_ohlcv("000300.SH", "2024-01-01", "2024-03-31")
print(f"获取到 {data['count']} 条数据")

# 3. 批量获取
def batch_ohlcv(codes, start, end):
    response = requests.post(
        f"{BASE_URL}/api/v1/ohlcv/batch",
        json={"codes": codes, "start": start, "end": end}
    )
    return response.json()

# 批量获取
results = batch_ohlcv(
    ["000300.SH", "NDX", "HSI"],
    "2024-01-01",
    "2024-03-31"
)

for code, result in results['results'].items():
    if 'error' not in result:
        print(f"✓ {code}: {result['count']} 条")
    else:
        print(f"✗ {code}: {result['error']}")
```

## 错误处理

### 错误响应格式

```json
{
  "error": "错误描述",
  "code": "000300.SH",
  "start": "2024-01-01",
  "end": "2024-03-31"
}
```

### 常见错误码

| HTTP 状态码 | 说明 | 解决方案 |
|------------|------|---------|
| 400 | 参数错误 | 检查请求参数格式 |
| 404 | 数据不存在 | 检查代码是否正确，日期范围是否合理 |
| 500 | 服务器内部错误 | 查看服务器日志 |

### 常见错误

**1. 代码不存在**
```json
{
  "error": "No data available for the specified code and date range",
  "code": "INVALID",
  "start": "2024-01-01",
  "end": "2024-03-31"
}
```

**2. 日期格式错误**
```json
{
  "error": "Invalid date format. Use YYYY-MM-DD",
  "start": "2024-01-01",
  "end": "2024/03/31"
}
```

**3. 缺少必需参数**
```json
{
  "error": "Missing required parameter: code",
  "example": "/api/v1/ohlcv?code=000300.SH&start=2024-01-01&end=2024-03-31"
}
```

## 环境配置

### 必需环境变量

```bash
# Tushare Token（获取A股数据必需）
export TUSHARE_TOKEN=your_token_here
```

### 可选环境变量（SSH隧道）

```bash
# 启用 SSH 隧道（支持港美股）
export SSH_ENABLED=true
export SSH_HOST=8.218.167.69
export SSH_PORT=22
export SSH_USERNAME=root
export SSH_KEY_PATH=hk_ecs.pem
export SSH_LOCAL_PORT=1080
```

### .env 文件示例

```env
# Tushare
TUSHARE_TOKEN=your_tushare_token_here

# SSH 隧道（可选）
SSH_ENABLED=true
SSH_HOST=8.218.167.69
SSH_PORT=22
SSH_USERNAME=root
SSH_KEY_PATH=hk_ecs.pem
SSH_LOCAL_PORT=1080
```

## 性能说明

### 响应时间

- A股数据: ~500ms/只
- 港美股数据: ~1-2s/只（通过SSH隧道）
- 批量获取: 并发处理，总体时间取决于最慢的数据源

### 限流说明

- Tushare: 受 API 频率限制
- YFinance: 建议添加延迟避免限流
- 批量获取: 自动添加 0.5s 延迟

## 注意事项

1. **SSH 隧道**: 获取港美股数据需要配置 SSH 隧道
2. **Tushare Token**: 获取A股数据需要有效的 Tushare Token
3. **日期范围**: 建议单次查询不超过 1 年数据
4. **网络环境**: 中国大陆直接访问 YFinance 可能受限

## 示例代码

查看完整示例:
- [Python 客户端](../examples/flask_api_client.py)
- [API 测试](../tests/test_flask_api.py)

## 更新日志

### v1.0.0 (2024-XX-XX)

- 初始版本
- 支持8种资产类型
- RESTful API 接口
- Python 客户端
- SSH 隧道支持