python_market_data_service/AMAZINGDATA_ADAPTER_INTERFACES_V3.md

# AmazingData Adapter 接口调用关系 (完整修正版)

## 一、接口调用次数汇总表

| 序号 | 接口方法 | SDK 调用次数 | 调用的 SDK 方法 | 复杂度 |
|------|----------|-------------|----------------|--------|
| 1 | `fetch_klines` | **4-6次** | `query_kline` + `get_code_info` + `get_equity_structure` + `get_calendar` + `get_list_date`(内部) | ⭐⭐⭐⭐ |
| 2 | `fetch_stock_basic_info` | **2+N次** | `get_code_list` + `get_code_info` + N×`get_equity_structure` | ⭐⭐⭐⭐⭐ |
| 3 | `fetch_symbols` (stock) | **2次** | `get_code_list` + `get_code_info` | ⭐⭐ |
| 4 | `fetch_symbols` (futures) | **1次** | `get_future_code_list` | ⭐ |
| 5 | `fetch_trading_calendar` | **1次** | `get_calendar` | ⭐ |
| 6 | `fetch_kline_quote` | **2次** | `query_kline` + `get_code_info` | ⭐⭐ |
| 7 | `fetch_kline_finance` | **2次** | `get_equity_structure` + `query_kline` | ⭐⭐ |
| 8 | `fetch_kline_base` | **1次** | `query_kline` | ⭐ |
| 9 | 其他所有数据接口 | **1次** | 对应单个 SDK 方法 | ⭐ |

---

## 二、复杂接口详细调用链

### 2.1 fetch_klines (4-6次SDK调用)

```python
fetch_klines (async)
└── _fetch_klines_sync (sync)
    ├── _market_data.query_kline()              # [第1次] 获取K线数据
    ├── _base_data.get_code_info()              # [第2次] 获取涨跌停价
    ├── _info_data.get_equity_structure()       # [第3次] 获取股本结构
    ├── _base_data.get_calendar()               # [第4次] 获取交易日历
    └── _get_list_date()                        # [内部方法]
        ├── _base_data.get_code_info()          # [第5次，可选] 尝试获取上市日期
        └── _base_data.get_hist_code_list()     # [第6次，可选] 备选方案
```

**实际调用**: 最少4次，最多6次（取决于 `_get_list_date` 的执行路径）

---

### 2.2 fetch_stock_basic_info (2+N次SDK调用)

```python
fetch_stock_basic_info (async)
└── _fetch_stock_basic_info_sync (sync)
    ├── _base_data.get_code_list()              # [第1次] 获取所有股票代码
    ├── _base_data.get_code_info()              # [第2次] 获取股票名称
    └── for code in codes:                      # [循环N次，N=股票数量]
        └── _info_data.get_equity_structure()   # [第3~2+N次] 每个股票调用一次！
```

**⚠️ 警告**: 如果获取全市场5000+只股票，将触发 2+5000 = **5002次** SDK 调用！

**建议**: 使用 `codes` 参数限制股票数量，避免全量查询。

---

### 2.3 fetch_symbols (股票 - 2次SDK调用)

```python
fetch_symbols (async)
└── _fetch_symbols_sync (sync)
    ├── _base_data.get_code_list()              # [第1次] 获取代码列表
    └── _base_data.get_code_info()              # [第2次] 获取代码信息(名称)
```

---

### 2.4 fetch_symbols (期货 - 1次SDK调用)

```python
fetch_symbols (async)
└── _fetch_symbols_sync (sync)
    └── _base_data.get_future_code_list()       # [第1次] 获取期货代码
    # 注意: 期货没有调用 get_future_info，交易所通过代码解析
```

**修正**: 之前文档错误地写为2次调用，实际只有1次。

---

## 三、新增分表接口调用链

### 3.1 fetch_kline_base (1次SDK调用)

```python
fetch_kline_base (async)
└── _fetch_kline_base_sync (sync)
    └── _market_data.query_kline()              # [第1次] 仅基础K线
```

---

### 3.2 fetch_kline_quote (2次SDK调用)

```python
fetch_kline_quote (async)
└── _fetch_kline_quote_sync (sync)
    ├── _market_data.query_kline()              # [第1次] 扩展日期范围
    └── _base_data.get_code_info()              # [第2次] 涨跌停价
```

---

### 3.3 fetch_kline_finance (2次SDK调用)

```python
fetch_kline_finance (async)
└── _fetch_kline_finance_sync (sync)
    ├── _info_data.get_equity_structure()       # [第1次] 股本结构
    └── _market_data.query_kline()              # [第2次] 价格数据
```

---

## 四、单次SDK调用的接口

以下接口都只进行 **1次** SDK 调用：

| 接口 | SDK 方法 |
|------|----------|
| `connect` | `_market_data.login()` |
| `health_check` | `_market_data.is_login()` |
| `fetch_trading_calendar` | `_base_data.get_calendar()` |
| `get_adj_factor` | `_base_data.get_adj_factor()` |
| `get_backward_factor` | `_base_data.get_backward_factor()` |
| `get_snapshot` | `_market_data.query_snapshot()` |
| `get_balance_sheet` | `_info_data.get_balance_sheet()` |
| `get_cash_flow` | `_info_data.get_cash_flow()` |
| `get_income_statement` | `_info_data.get_income()` |
| `get_profit_express` | `_info_data.get_profit_express()` |
| `get_profit_notice` | `_info_data.get_profit_notice()` |
| `get_top10_shareholders` | `_info_data.get_share_holder()` |
| `get_shareholder_count` | `_info_data.get_holder_num()` |
| `get_equity_structure` | `_info_data.get_equity_structure()` |
| `get_index_constituents` | `_info_data.get_index_constituent()` |
| `get_index_weights` | `_info_data.get_index_weight()` |
| `get_margin_summary` | `_info_data.get_margin_summary()` |
| `get_margin_detail` | `_info_data.get_margin_detail()` |
| `get_longhu_bang` | `_info_data.get_long_hu_bang()` |
| `get_block_trading` | `_info_data.get_block_trading()` |
| `get_etf_pcf` | `_base_data.get_etf_pcf()` |
| `get_fund_share` | `_info_data.get_fund_share()` |
| `get_kzz_issuance` | `_info_data.get_kzz_issuance()` |
| `get_history_stock_status` | `_info_data.get_history_stock_status()` |
| `get_code_info` | `_base_data.get_code_info()` |
| `get_trading_calendar` | `_base_data.get_calendar()` |

---

## 五、SDK 对象方法汇总

### _market_data (市场数据)
| 方法 | 使用场景 | 调用次数 |
|------|----------|----------|
| `login()` | connect | 1 |
| `query_kline()` | K线数据 | 频繁 |
| `query_snapshot()` | get_snapshot | 按需 |
| `is_login()` | health_check | 1 |

### _base_data (基础数据)
| 方法 | 使用场景 | 调用次数 |
|------|----------|----------|
| `get_code_list()` | fetch_symbols(stock) | 频繁 |
| `get_future_code_list()` | fetch_symbols(futures) | 按需 |
| `get_code_info()` | 多个接口 | **最频繁** |
| `get_calendar()` | 交易日历 | 多次 |
| `get_adj_factor()` | 复权因子 | 按需 |
| `get_backward_factor()` | 后复权因子 | 按需 |
| `get_etf_pcf()` | ETF数据 | 按需 |
| `get_hist_code_list()` | 备选上市日期 | 可选 |

### _info_data (信息数据)
| 方法 | 使用场景 | 调用次数 |
|------|----------|----------|
| `get_equity_structure()` | 股本/上市日期 | **最频繁** |
| `get_share_holder()` | 股东数据 | 按需 |
| `get_income()` | 利润表 | 按需 |
| `get_balance_sheet()` | 资产负债表 | 按需 |
| `get_cash_flow()` | 现金流量表 | 按需 |
| `get_profit_express()` | 业绩预告 | 按需 |
| `get_profit_notice()` | 业绩快报 | 按需 |
| `get_holder_num()` | 股东户数 | 按需 |
| `get_margin_summary()` | 融资融券汇总 | 按需 |
| `get_margin_detail()` | 融资融券明细 | 按需 |
| `get_long_hu_bang()` | 龙虎榜 | 按需 |
| `get_block_trading()` | 大宗交易 | 按需 |
| `get_index_constituent()` | 指数成分股 | 按需 |
| `get_index_weight()` | 指数权重 | 按需 |
| `get_fund_share()` | 基金份额 | 按需 |
| `get_kzz_issuance()` | 可转债发行 | 按需 |
| `get_history_stock_status()` | 历史股票状态（涨停/跌停/ST/停牌） | 按需 |

---

## 六、修正说明

### 6.1 与V2版文档的差异

| 接口 | V2版文档 | V3版文档(修正) | 差异说明 |
|------|----------|----------------|----------|
| `fetch_symbols` (futures) | 2次调用 | **1次调用** | 期货实际只调用`get_future_code_list`，没有调用`get_future_info` |
| `fetch_stock_basic_info` | 2+N次 | **2+N次** | 确认正确，N=股票数量 |
| `fetch_klines` | 4-6次 | **4-6次** | 确认正确 |

### 6.2 风险提示

**⚠️ 高危接口**: `fetch_stock_basic_info`
- 获取全市场股票时会产生 **5000+** 次 SDK 调用
- 可能导致性能问题或触发限流
- **建议**: 始终使用 `codes` 参数限制查询范围

```python
# ❌ 不推荐: 获取全市场
all_stocks = await adapter.fetch_stock_basic_info()

# ✅ 推荐: 只查询指定股票
specific_stocks = await adapter.fetch_stock_basic_info(
    codes=["000001.SZ", "600519.SH"]
)
```

---

## 七、接口统计

| 类别 | 接口数量 |
|------|----------|
| 核心适配器接口 | 6 |
| 基础数据接口 | 4 |
| 财务/股东数据接口 | 8 |
| 市场数据接口 | 9 |
| 基金/可转债接口 | 3 |
| 新增分表数据接口 | 4 |
| **总计** | **34** |

**复杂度分级**:
- ⭐ 简单 (1次): 26个接口
- ⭐⭐ 中等 (2次): 3个接口 (`fetch_symbols` stock, `fetch_kline_quote`, `fetch_kline_finance`)
- ⭐⭐⭐⭐ 复杂 (4-6次): 1个接口 (`fetch_klines`)
- ⭐⭐⭐⭐⭐ 极复杂 (2+N次): 1个接口 (`fetch_stock_basic_info`)