amazing-data-service/docs/API.md

# AmazingData 金融数据服务平台 - API 开发文档

## 一、API 概述

### 1.1 基本信息

- **Base URL**: `http://localhost:8000/api/v1`
- **认证方式**: JWT Bearer Token
- **数据格式**: JSON
- **编码**: UTF-8

### 1.2 认证说明

除登录接口外，所有接口都需要在请求头中携带 JWT Token：

```
Authorization: Bearer {access_token}
```

---

## 二、认证接口

### 2.1 用户登录

**接口**: `POST /auth/login`

**功能**: 用户登录获取 JWT Token

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| username | string | 是 | 用户名 |
| password | string | 是 | 密码 |

**请求示例**:

```json
{
  "username": "admin",
  "password": "admin123"
}
```

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| code | int | 状态码 (200成功) |
| message | string | 消息 |
| data.access_token | string | JWT Token |
| data.token_type | string | Token类型 (bearer) |
| data.expires_in | int | 有效期(秒) |

**响应示例**:

```json
{
  "code": 200,
  "message": "登录成功",
  "data": {
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "token_type": "bearer",
    "expires_in": 86400
  }
}
```

**调用示例**:

```python
import requests

response = requests.post(
    'http://localhost:8000/api/v1/auth/login',
    json={'username': 'admin', 'password': 'admin123'}
)
token = response.json()['data']['access_token']
```

---

### 2.2 获取当前用户信息

**接口**: `GET /auth/me`

**功能**: 获取当前登录用户信息

**请求参数**: 无

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.id | int | 用户ID |
| data.username | string | 用户名 |
| data.email | string | 邮箱 |
| data.role | string | 角色 |
| data.is_active | bool | 是否激活 |

**调用示例**:

```python
headers = {'Authorization': f'Bearer {token}'}
response = requests.get('http://localhost:8000/api/v1/auth/me', headers=headers)
user_info = response.json()['data']
```

---

## 三、SDK配置接口

### 3.1 获取SDK配置列表

**接口**: `GET /configs/sdk`

**功能**: 获取所有SDK配置列表

**请求参数**: 无

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.items | array | 配置列表 |
| data.total | int | 总数 |

**调用示例**:

```python
response = requests.get('http://localhost:8000/api/v1/configs/sdk', headers=headers)
configs = response.json()['data']['items']
```

---

### 3.2 创建SDK配置

**接口**: `POST /configs/sdk`

**功能**: 创建新的SDK配置

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| name | string | 是 | 配置名称 |
| username | string | 是 | SDK用户名 |
| password | string | 是 | SDK密码 |
| host | string | 是 | 服务器地址 |
| port | int | 否 | 端口号 (默认8600) |
| local_path | string | 否 | 本地路径 |
| is_default | bool | 否 | 是否默认配置 |

**请求示例**:

```json
{
  "name": "生产环境SDK",
  "username": "your_username",
  "password": "your_password",
  "host": "140.206.44.234",
  "port": 8600,
  "is_default": true
}
```

**调用示例**:

```python
response = requests.post(
    'http://localhost:8000/api/v1/configs/sdk',
    headers=headers,
    json={
        'name': '生产环境SDK',
        'username': 'your_username',
        'password': 'your_password',
        'host': '140.206.44.234',
        'port': 8600,
        'is_default': True
    }
)
```

---

### 3.3 测试SDK连接

**接口**: `POST /configs/sdk/{id}/test`

**功能**: 测试指定SDK配置的连接

**请求参数**: 无

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.success | bool | 是否成功 |
| data.message | string | 消息 |
| data.response_time | float | 响应时间(秒) |

**调用示例**:

```python
response = requests.post(
    'http://localhost:8000/api/v1/configs/sdk/1/test',
    headers=headers,
    timeout=60
)
result = response.json()['data']
```

---

## 四、基础数据接口

### 4.1 获取代码列表

**接口**: `GET /base/codes`

**功能**: 获取指定类型的证券代码列表

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| security_type | string | 是 | 证券类型 |

**证券类型**:
- `EXTRA_STOCK_A`: 沪深A股
- `EXTRA_FUTURE`: 期货
- `EXTRA_ETF`: ETF
- `EXTRA_INDEX_A`: 指数

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data | array | 代码列表 |

**调用示例**:

```python
response = requests.get(
    'http://localhost:8000/api/v1/base/codes',
    params={'security_type': 'EXTRA_STOCK_A'},
    headers=headers
)
codes = response.json()['data']
```

---

### 4.2 获取交易日历

**接口**: `GET /base/calendar`

**功能**: 获取指定市场的交易日历

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| market | string | 是 | 市场代码 (SH, SZ, CFE) |
| start_date | string | 否 | 开始日期 (YYYYMMDD) |
| end_date | string | 否 | 结束日期 (YYYYMMDD) |

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data | array | 交易日列表 |

**调用示例**:

```python
response = requests.get(
    'http://localhost:8000/api/v1/base/calendar',
    params={
        'market': 'SH',
        'start_date': '20240101',
        'end_date': '20240131'
    },
    headers=headers
)
trading_days = response.json()['data']
```

---

### 4.3 获取证券信息

**接口**: `GET /base/codes/{code}/info`

**功能**: 获取指定代码的证券信息

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| code | string | 是 | 证券代码 (URL路径参数) |

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.code | string | 代码 |
| data.name | string | 名称 |
| data.market | string | 市场 |
| data.type | string | 类型 |

**调用示例**:

```python
response = requests.get(
    'http://localhost:8000/api/v1/base/codes/600000.SH/info',
    headers=headers
)
info = response.json()['data']
```

---

## 五、股票数据接口

### 5.1 获取股票K线数据

**接口**: `GET /stock/kline`

**功能**: 获取股票K线数据

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| codes | string | 是 | 代码列表 (逗号分隔) |
| start_date | string | 是 | 开始日期 (YYYYMMDD) |
| end_date | string | 是 | 结束日期 (YYYYMMDD) |
| period | string | 否 | 周期 (daily, min1, min5等) |

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.{code} | array | K线数据列表 |
| data.{code}[].trade_date | string | 交易日期 |
| data.{code}[].open | float | 开盘价 |
| data.{code}[].high | float | 最高价 |
| data.{code}[].low | float | 最低价 |
| data.{code}[].close | float | 收盘价 |
| data.{code}[].volume | int | 成交量 |
| data.{code}[].amount | float | 成交额 |

**调用示例**:

```python
response = requests.get(
    'http://localhost:8000/api/v1/stock/kline',
    params={
        'codes': '600000.SH,000001.SZ',
        'start_date': '20240101',
        'end_date': '20240131',
        'period': 'daily'
    },
    headers=headers
)
kline_data = response.json()['data']
```

---

### 5.2 获取股票K线图表数据

**接口**: `GET /stock/kline/{code}/chart`

**功能**: 获取股票K线图表数据 (ECharts格式)

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| code | string | 是 | 股票代码 (URL路径参数) |
| start_date | string | 是 | 开始日期 |
| end_date | string | 是 | 结束日期 |
| period | string | 否 | 周期 |

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.categoryData | array | 日期列表 |
| data.values | array | K线值 [open, close, low, high, volume] |
| data.volumes | array | 成交量数据 |

**调用示例**:

```python
response = requests.get(
    'http://localhost:8000/api/v1/stock/kline/600000.SH/chart',
    params={
        'start_date': '20240101',
        'end_date': '20240131',
        'period': 'daily'
    },
    headers=headers
)
chart_data = response.json()['data']
```

---

### 5.3 批量获取股票K线

**接口**: `POST /stock/kline/batch`

**功能**: 批量获取多个股票的K线数据

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| codes | array | 是 | 代码列表 |
| start_date | string | 是 | 开始日期 |
| end_date | string | 是 | 结束日期 |
| period | string | 否 | 周期 |

**请求示例**:

```json
{
  "codes": ["600000.SH", "000001.SZ", "000002.SZ"],
  "start_date": "20240101",
  "end_date": "20240131",
  "period": "daily"
}
```

**调用示例**:

```python
response = requests.post(
    'http://localhost:8000/api/v1/stock/kline/batch',
    headers=headers,
    json={
        'codes': ['600000.SH', '000001.SZ'],
        'start_date': '20240101',
        'end_date': '20240131',
        'period': 'daily'
    }
)
```

---

## 六、期货数据接口

### 6.1 获取期货K线数据

**接口**: `GET /future/kline`

**功能**: 获取期货K线数据

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| codes | string | 是 | 代码列表 (逗号分隔) |
| start_date | string | 是 | 开始日期 |
| end_date | string | 是 | 结束日期 |
| period | string | 否 | 周期 |

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.{code} | array | K线数据 |
| data.{code}[].trade_date | string | 交易日期 |
| data.{code}[].open | float | 开盘价 |
| data.{code}[].high | float | 最高价 |
| data.{code}[].low | float | 最低价 |
| data.{code}[].close | float | 收盘价 |
| data.{code}[].volume | int | 成交量 |
| data.{code}[].settle | float | 结算价 |
| data.{code}[].open_interest | int | 持仓量 |

**调用示例**:

```python
response = requests.get(
    'http://localhost:8000/api/v1/future/kline',
    params={
        'codes': 'IF2401.CFE',
        'start_date': '20240101',
        'end_date': '20240131',
        'period': 'daily'
    },
    headers=headers
)
```

---

### 6.2 获取期货品种列表

**接口**: `GET /cache/future-varieties`

**功能**: 获取所有期货品种列表

**请求参数**: 无

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.varieties | array | 品种列表 |

**调用示例**:

```python
response = requests.get(
    'http://localhost:8000/api/v1/cache/future-varieties',
    headers=headers
)
varieties = response.json()['data']['varieties']
```

---

### 6.3 获取主力合约

**接口**: `GET /cache/main-contracts`

**功能**: 获取所有品种的主力合约

**请求参数**: 无

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.main_contracts | object | {品种: 主力合约} |

**调用示例**:

```python
response = requests.get(
    'http://localhost:8000/api/v1/cache/main-contracts',
    headers=headers
)
main_contracts = response.json()['data']['main_contracts']
```

---

## 七、缓存管理接口

### 7.1 一键检测所有数据

**接口**: `POST /cache/detect-all-missing`

**功能**: 检测所有数据的缺失情况

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| security_type | string | 是 | 证券类型 (stock, future) |
| period_type | string | 否 | 周期类型 (daily) |
| start_date | string | 是 | 开始日期 |
| end_date | string | 是 | 结束日期 |
| contract_type | string | 否 | 合约类型 (all, main) |

**请求示例**:

```json
{
  "security_type": "stock",
  "period_type": "daily",
  "start_date": "20240101",
  "end_date": "20240131",
  "contract_type": "all"
}
```

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.task_id | int | 任务ID |
| data.status | string | 任务状态 |
| data.total_count | int | 检测总数 |
| data.complete_count | int | 完整数量 |
| data.missing_count | int | 缺失数量 |
| data.error_count | int | 错误数量 |
| data.daily_stats | object | 每日统计 |
| data.missing_codes | array | 缺失代码列表 |

**调用示例**:

```python
response = requests.post(
    'http://localhost:8000/api/v1/cache/detect-all-missing',
    headers=headers,
    json={
        'security_type': 'stock',
        'period_type': 'daily',
        'start_date': '20240101',
        'end_date': '20240131',
        'contract_type': 'all'
    }
)
result = response.json()['data']
```

---

### 7.2 一键缓存所有数据

**接口**: `POST /cache/cache-all-missing`

**功能**: 缓存所有数据 (异步执行)

**请求参数**: 同检测接口

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.task_id | int | 任务ID |
| data.status | string | 任务状态 |
| data.total_count | int | 总数 |
| data.progress | float | 进度 |

**调用示例**:

```python
response = requests.post(
    'http://localhost:8000/api/v1/cache/cache-all-missing',
    headers=headers,
    json={
        'security_type': 'stock',
        'period_type': 'daily',
        'start_date': '20240101',
        'end_date': '20240131'
    }
)
task_id = response.json()['data']['task_id']
```

---

### 7.3 一键补齐缺失数据

**接口**: `POST /cache/fill-missing`

**功能**: 只补齐检测到的缺失数据 (异步执行)

**请求参数**: 同检测接口

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.task_id | int | 任务ID |
| data.missing_count | int | 缺失代码数量 |
| data.status | string | 任务状态 |

**调用示例**:

```python
response = requests.post(
    'http://localhost:8000/api/v1/cache/fill-missing',
    headers=headers,
    json={
        'security_type': 'stock',
        'period_type': 'daily',
        'start_date': '20240101',
        'end_date': '20240131'
    }
)
```

---

### 7.4 获取任务进度

**接口**: `GET /cache/tasks/{task_id}`

**功能**: 获取缓存任务进度

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| task_id | int | 是 | 任务ID (URL路径参数) |

**响应参数**:

| 参数名 | 类型 | 说明 |
|--------|------|------|
| data.task.id | int | 任务ID |
| data.task.status | string | 状态 |
| data.task.progress | float | 进度 |
| data.task.total_count | int | 总数 |
| data.task.success_count | int | 成功数 |
| data.task.error_count | int | 错误数 |

**调用示例**:

```python
response = requests.get(
    f'http://localhost:8000/api/v1/cache/tasks/{task_id}',
    headers=headers
)
task_status = response.json()['data']['task']
```

---

### 7.5 获取任务列表

**接口**: `GET /cache/tasks`

**功能**: 获取缓存任务列表

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| page | int | 否 | 页码 (默认1) |
| page_size | int | 否 | 每页数量 (默认20) |

**调用示例**:

```python
response = requests.get(
    'http://localhost:8000/api/v1/cache/tasks',
    params={'page': 1, 'page_size': 10},
    headers=headers
)
tasks = response.json()['data']['items']
```

---

## 八、财务数据接口

### 8.1 获取资产负债表

**接口**: `GET /finance/balance-sheet`

**功能**: 获取资产负债表数据

**请求参数**:

| 参数名 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| codes | string | 是 | 代码列表 |
| start_date | string | 是 | 开始日期 |
| end_date | string | 是 | 结束日期 |

**调用示例**:

```python
response = requests.get(
    'http://localhost:8000/api/v1/finance/balance-sheet',
    params={
        'codes': '600000.SH',
        'start_date': '20230101',
        'end_date': '20231231'
    },
    headers=headers
)
```

---

### 8.2 获取利润表

**接口**: `GET /finance/income`

**功能**: 获取利润表数据

**请求参数**: 同资产负债表

**调用示例**:

```python
response = requests.get(
    'http://localhost:8000/api/v1/finance/income',
    params={
        'codes': '600000.SH',
        'start_date': '20230101',
        'end_date': '20231231'
    },
    headers=headers
)
```

---

### 8.3 获取现金流量表

**接口**: `GET /finance/cash-flow`

**功能**: 获取现金流量表数据

**请求参数**: 同资产负债表

**调用示例**:

```python
response = requests.get(
    'http://localhost:8000/api/v1/finance/cash-flow',
    params={
        'codes': '600000.SH',
        'start_date': '20230101',
        'end_date': '20231231'
    },
    headers=headers
)
```

---

## 九、错误码说明

| 错误码 | 说明 |
|--------|------|
| 200 | 成功 |
| 400 | 请求参数错误 |
| 401 | 未授权 (Token无效或过期) |
| 403 | 禁止访问 |
| 404 | 资源不存在 |
| 500 | 服务器内部错误 |

---

## 十、最佳实践

### 10.1 Token 管理

```python
class AmazingDataClient:
    def __init__(self, base_url, username, password):
        self.base_url = base_url
        self.token = None
        self.login(username, password)
    
    def login(self, username, password):
        response = requests.post(
            f'{self.base_url}/auth/login',
            json={'username': username, 'password': password}
        )
        self.token = response.json()['data']['access_token']
    
    def get_headers(self):
        return {'Authorization': f'Bearer {self.token}'}
    
    def request(self, method, path, **kwargs):
        kwargs['headers'] = self.get_headers()
        return requests.request(method, f'{self.base_url}{path}', **kwargs)
```

### 10.2 批量数据处理

```python
# 分批处理大量代码
codes = ['600000.SH', '000001.SZ', ...]  # 大量代码
batch_size = 50

for i in range(0, len(codes), batch_size):
    batch = codes[i:i+batch_size]
    response = client.request('POST', '/stock/kline/batch', json={
        'codes': batch,
        'start_date': '20240101',
        'end_date': '20240131'
    })
```

### 10.3 异步任务轮询

```python
import time

def wait_for_task(client, task_id, timeout=300):
    start_time = time.time()
    while time.time() - start_time < timeout:
        response = client.request('GET', f'/cache/tasks/{task_id}')
        task = response.json()['data']['task']
        
        if task['status'] == 'completed':
            return task
        elif task['status'] == 'failed':
            raise Exception(task['error_message'])
        
        time.sleep(2)
    
    raise Exception('任务超时')

# 使用
response = client.request('POST', '/cache/fill-missing', json={...})
task_id = response.json()['data']['task_id']
result = wait_for_task(client, task_id)
```

---

## 十一、联系与支持

如有问题，请联系技术支持团队。