python_market_data_service/xysz/AmazingDataAdapter_接口文档.md

# AmazingDataAdapter 接口文档

基于银河证券星耀数智量化平台 SDK 的 Python 适配器接口文档

---

## 目录

1. [快速开始](#快速开始)
2. [枚举类型](#枚举类型)
3. [接口列表](#接口列表)
   - [基础数据接口](#基础数据接口)
   - [历史行情接口](#历史行情接口)
   - [财务数据接口](#财务数据接口)
   - [股东股本接口](#股东股本接口)
   - [融资融券接口](#融资融券接口)
   - [交易异动接口](#交易异动接口)
   - [指数数据接口](#指数数据接口)
   - [ETF数据接口](#etf数据接口)
   - [可转债数据接口](#可转债数据接口)

---

## 快速开始

```python
import asyncio
from app.adapters.amazingdata_adapter import AmazingDataAdapter, SecurityType, Market

async def main():
    # 1. 创建适配器
    adapter = AmazingDataAdapter()
    
    # 2. 连接数据源
    await adapter.connect({
        "username": "your_username",
        "password": "your_password",
        "host": "your_host",
        "port": 8600,
        "local_path": "./amazing_data_cache/",
        "use_local_cache": True
    })
    
    # 3. 获取数据
    klines = await adapter.fetch_klines(
        symbol="000001.SZ",
        start="20240101",
        end="20241231",
        freq="1d"
    )
    print(f"获取到 {len(klines)} 条K线数据")
    
    # 4. 断开连接
    await adapter.close()

asyncio.run(main())
```

---

## 枚举类型

### SecurityType - 证券类型

| 枚举值 | 说明 |
|--------|------|
| `SecurityType.STOCK_A` | 沪深A股 |
| `SecurityType.STOCK_A_SH_SZ` | 沪深A股（沪深） |
| `SecurityType.INDEX_A` | 沪深指数 |
| `SecurityType.ETF` | ETF |
| `SecurityType.FUTURE` | 期货 |
| `SecurityType.KZZ` | 可转债 |
| `SecurityType.GLRA` | 逆回购 |
| `SecurityType.HKT` | 港股通 |
| `SecurityType.ETF_OP` | ETF期权 |

### Market - 市场

| 枚举值 | 说明 |
|--------|------|
| `Market.SH` | 上海 |
| `Market.SZ` | 深圳 |
| `Market.BJ` | 北京 |

---

## 接口列表

### 基础数据接口

#### 1. fetch_klines - 获取历史K线

```python
async def fetch_klines(
    self,
    symbol: str,
    start: str,
    end: str,
    freq: str
) -> List[KLineData]
```

**参数说明：**

| 参数 | 类型 | 说明 |
|------|------|------|
| symbol | str | 标的代码，如 "000001.SZ" |
| start | str | 开始日期，格式 YYYYMMDD |
| end | str | 结束日期，格式 YYYYMMDD |
| freq | str | 周期：1m/5m/15m/30m/60m/1d/1w/1M |

**返回数据 (KLineData)：**

| 字段 | 类型 | 说明 |
|------|------|------|
| symbol | str | 标的代码 |
| time | int | Unix时间戳 |
| open | float | 开盘价 |
| high | float | 最高价 |
| low | float | 最低价 |
| close | float | 收盘价 |
| volume | int | 成交量 |
| amount | float | 成交金额 |
| trade_date | str | 交易日 (YYYY-MM-DD) |
| is_limit_up | bool | 是否涨停 |
| is_limit_down | bool | 是否跌停 |
| total_market_cap | float | 总市值（元） |
| float_market_cap | float | 流通市值（元） |
| inst_holding_ratio | float | 机构持仓占比（%） |
| trading_days | int | 可交易日数 |

---

#### 2. fetch_symbols - 获取标的列表

```python
async def fetch_symbols(
    self,
    asset_type: str
) -> List[SymbolInfo]
```

**参数说明：**

| 参数 | 类型 | 说明 |
|------|------|------|
| asset_type | str | 资产类型：stock/futures |

**返回数据 (SymbolInfo)：**

| 字段 | 类型 | 说明 |
|------|------|------|
| symbol_id | str | 标的代码 |
| name | str | 标的名称 |
| exchange | str | 交易所 |
| underlying | str | 期货品种代码 |
| contract_month | str | 合约月份 |

---

#### 3. fetch_trading_calendar - 获取交易日历

```python
async def fetch_trading_calendar(
    self,
    exchange: str,
    start: str,
    end: str
) -> List[TradeCalData]
```

**参数说明：**

| 参数 | 类型 | 说明 |
|------|------|------|
| exchange | str | 交易所代码：SH/SZ |
| start | str | 开始日期 YYYYMMDD |
| end | str | 结束日期 YYYYMMDD |

---

#### 4. get_code_info - 获取证券基本信息

```python
async def get_code_info(
    self,
    security_type: SecurityType = SecurityType.STOCK_A
) -> pd.DataFrame
```

**返回字段：**

| 字段 | 说明 |
|------|------|
| symbol | 证券简称 |
| security_status | 产品状态标志 |
| pre_close | 昨收价 |
| high_limited | 涨停价 |
| low_limited | 跌停价 |
| price_tick | 最小价格变动单位 |

---

#### 5. get_trading_calendar - 获取交易日历（列表）

```python
async def get_trading_calendar(
    self,
    market: Market = Market.SH
) -> List[int]
```

**返回：** 交易日列表，格式 [20240102, 20240103, ...]

---

#### 6. get_adj_factor - 获取单次复权因子

```python
async def get_adj_factor(
    self,
    codes: List[str],
    is_local: Optional[bool] = None
) -> pd.DataFrame
```

**参数说明：**

| 参数 | 类型 | 说明 |
|------|------|------|
| codes | List[str] | 股票代码列表 |
| is_local | bool | 是否使用本地缓存 |

**返回：** DataFrame (index: 日期, columns: 股票代码)

---

#### 7. get_backward_factor - 获取后复权因子

```python
async def get_backward_factor(
    self,
    codes: List[str],
    is_local: Optional[bool] = None
) -> pd.DataFrame
```

---

### 历史行情接口

#### 8. get_snapshot - 获取历史快照

```python
async def get_snapshot(
    self,
    codes: List[str],
    start_date: str,
    end_date: str
) -> Dict[str, pd.DataFrame]
```

**说明：** 获取Level-1行情快照数据

---

### 财务数据接口

#### 9. get_balance_sheet - 资产负债表

```python
async def get_balance_sheet(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> Dict[str, pd.DataFrame]
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| TOTAL_ASSETS | 资产总计 |
| TOTAL_CUR_ASSETS | 流动资产合计 |
| TOTAL_NONCUR_ASSETS | 非流动资产合计 |
| TOTAL_LIAB | 负债合计 |
| TOT_SHARE_EQUITY_INCL_MIN_INT | 股东权益合计 |
| CURRENCY_CAP | 货币资金 |
| NOTES_RECEIVABLE | 应收票据 |
| ACCT_RECEIVABLE | 应收账款 |
| INV | 存货 |

---

#### 10. get_cash_flow - 现金流量表

```python
async def get_cash_flow(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> Dict[str, pd.DataFrame]
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| NET_CASH_FLOWS_OPERA_ACT | 经营活动现金流净额 |
| NET_CASH_FLOWS_INV_ACT | 投资活动现金流净额 |
| NET_CASH_FLOWS_FIN_ACT | 筹资活动现金流净额 |
| NET_INCR_CASH_AND_CASH_EQU | 现金及现金等价物净增加额 |

---

#### 11. get_income_statement - 利润表

```python
async def get_income_statement(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> Dict[str, pd.DataFrame]
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| TOT_OPERA_REV | 营业总收入 |
| OPERA_REV | 营业收入 |
| TOT_OPERA_COST | 营业总成本 |
| OPERA_PROFIT | 营业利润 |
| TOTAL_PROFIT | 利润总额 |
| NET_PRO_INCL_MIN_INT_INC | 净利润 |
| BASIC_EPS | 基本每股收益 |
| DILUTED_EPS | 稀释每股收益 |
| RD_EXP | 研发费用 |

---

#### 12. get_profit_express - 业绩快报

```python
async def get_profit_express(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> pd.DataFrame
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| TOTAL_ASSETS | 总资产 |
| NET_PRO_EXCL_MIN_INT_INC | 净利润 |
| TOT_OPERA_REV | 营业总收入 |
| TOTAL_PROFIT | 利润总额 |
| OPERA_PROFIT | 营业利润 |
| EPS_BASIC | 基本每股收益 |
| ROE_WEIGHTED | 净资产收益率-加权 |
| YOY_GR_NET_PROFIT_PARENT | 同比增长率 |

---

#### 13. get_profit_notice - 业绩预告

```python
async def get_profit_notice(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> pd.DataFrame
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| P_TYPECODE | 业绩预告类型代码 |
| P_CHANGE_MAX | 预告净利润变动幅度上限 |
| P_CHANGE_MIN | 预告净利润变动幅度下限 |
| NET_PROFIT_MAX | 预告净利润上限(万元) |
| NET_PROFIT_MIN | 预告净利润下限(万元) |
| P_REASON | 业绩变动原因 |

---

### 股东股本接口

#### 14. get_top10_shareholders - 十大股东

```python
async def get_top10_shareholders(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> pd.DataFrame
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| HOLDER_NAME | 股东名称 |
| HOLDER_QUANTITY | 持股数 |
| HOLDER_PCT | 持股比例(%) |
| HOLDER_HOLDER_CATEGORY | 股东性质(1:个人, 2:公司) |
| FLOAT_QTY | 流通股数量 |

---

#### 15. get_shareholder_count - 股东户数

```python
async def get_shareholder_count(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> pd.DataFrame
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| HOLDER_TOTAL_NUM | A股、B股、H股、境外股的总户数 |
| HOLDER_NUM | A股股东户数 |

---

#### 16. get_equity_structure - 股本结构

```python
async def get_equity_structure(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> pd.DataFrame
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| TOT_SHARE | 总股本(万股) |
| FLOAT_SHARE | 流通股(万股) |
| FLOAT_A_SHARE | 流通A股(万股) |
| RESTRICTED_A_SHARE | 限售A股(万股) |
| TOT_RESTRICTED_SHARE | 限售股合计 |

---

### 融资融券接口

#### 17. get_margin_summary - 融资融券汇总

```python
async def get_margin_summary(
    self,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> pd.DataFrame
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| TRADE_DATE | 交易日期 |
| SUM_BORROW_MONEY_BALANCE | 融资余额(元) |
| SUM_PURCH_WITH_BORROW_MONEY | 融资买入额(元) |
| SUM_REPAYMENT_OF_BORROW_MONEY | 融资偿还额(元) |
| SUM_SEC_LENDING_BALANCE | 融券余额(元) |
| SUM_SALES_OF_BORROWED_SEC | 融券卖出量 |
| SUM_MARGIN_TRADE_BALANCE | 融资融券余额(元) |

---

#### 18. get_margin_detail - 个股融资融券明细

```python
async def get_margin_detail(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> Dict[str, pd.DataFrame]
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| BORROW_MONEY_BALANCE | 融资余额 |
| PURCH_WITH_BORROW_MONEY | 融资买入额 |
| REPAYMENT_OF_BORROW_MONEY | 融资偿还额 |
| SEC_LENDING_BALANCE | 融券余额 |
| SALES_OF_BORROWED_SEC | 融券卖出量 |

---

### 交易异动接口

#### 19. get_longhu_bang - 龙虎榜数据

```python
async def get_longhu_bang(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> pd.DataFrame
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| TRADE_DATE | 交易日期 |
| REASON_TYPE_NAME | 上榜原因 |
| CHANGE_RANGE | 涨跌幅(%) |
| TRADER_NAME | 营业部名称 |
| BUY_AMOUNT | 买入金额(元) |
| SELL_AMOUNT | 卖出金额(元) |
| FLOW_MARK | 买卖表示(1买入, 2卖出) |

---

#### 20. get_block_trading - 大宗交易

```python
async def get_block_trading(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> pd.DataFrame
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| TRADE_DATE | 交易日期 |
| B_SHARE_PRICE | 成交价(元) |
| B_SHARE_VOLUME | 成交量(万股) |
| B_SHARE_AMOUNT | 成交金额(万元) |
| B_BUYER_NAME | 买方营业部名称 |
| B_SELLER_NAME | 卖方营业部名称 |

---

### 指数数据接口

#### 21. get_index_constituents - 指数成分股

```python
async def get_index_constituents(
    self,
    codes: List[str],
    is_local: Optional[bool] = None
) -> Dict[str, pd.DataFrame]
```

**支持指数：**

| 代码 | 名称 |
|------|------|
| 000016.SH | 上证50 |
| 000300.SH | 沪深300 |
| 000905.SH | 中证500 |
| 000906.SH | 中证800 |
| 000852.SH | 中证1000 |

**返回字段：**

| 字段 | 说明 |
|------|------|
| INDEX_CODE | 指数代码 |
| CON_CODE | 成分股代码 |
| INDATE | 纳入日期 |
| OUTDATE | 剔除日期 |
| INDEX_NAME | 指数名称 |

---

#### 22. get_index_weights - 成分股权重

```python
async def get_index_weights(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> Dict[str, pd.DataFrame]
```

**返回字段：**

| 字段 | 说明 |
|------|------|
| INDEX_CODE | 指数代码 |
| CON_CODE | 标的代码 |
| TRADE_DATE | 生效日期 |
| WEIGHT | 权重(%) |
| CLOSE | 收盘价 |

---

### ETF数据接口

#### 23. get_etf_pcf - ETF申赎数据

```python
async def get_etf_pcf(
    self,
    codes: List[str]
) -> Tuple[pd.DataFrame, Dict[str, pd.DataFrame]]
```

**返回：** (etf_info, etf_constituents)

**etf_info字段：**

| 字段 | 说明 |
|------|------|
| creation_redemption_unit | 每个篮子对应的ETF份数 |
| max_cash_ratio | 最大现金替代比例 |
| creation | 是否允许申购 |
| redemption | 是否允许赎回 |

**etf_constituents字段：**

| 字段 | 说明 |
|------|------|
| underlying_symbol | 成份证券简称 |
| component_share | 成份证券数量 |
| substitute_flag | 现金替代标志 |

---

#### 24. get_fund_share - 基金份额

```python
async def get_fund_share(
    self,
    codes: List[str],
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    is_local: Optional[bool] = None
) -> Dict[str, pd.DataFrame]
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| FUND_SHARE | 基金份额(万份) |
| TOTAL_SHARE | 基金总份额(万份) |
| FLOAT_SHARE | 流通份额(万份) |
| CHANGE_REASON | 份额变动原因 |

---

### 可转债数据接口

#### 25. get_kzz_issuance - 可转债发行数据

```python
async def get_kzz_issuance(
    self,
    codes: List[str],
    is_local: Optional[bool] = None
) -> Dict[str, pd.DataFrame]
```

**主要字段：**

| 字段 | 说明 |
|------|------|
| STOCK_CODE | 正股代码 |
| LISTED_DATE | 上市日期 |
| PLAN_SCHEDULE | 方案进度 |
| CLAUSE_INI_CONV_PRICE | 初始转换价格 |
| LIST_ISSUE_SIZE | 发行规模(万元) |
| LIST_ISSUE_QUANTITY | 发行数量(万张) |
| TERM_YEAR | 借款期限(年) |
| COUPON_RATE | 利率(%) |

---

## 使用示例

### 示例1：获取股票K线并判断是否涨停

```python
import asyncio
from app.adapters.amazingdata_adapter import AmazingDataAdapter

async def main():
    adapter = AmazingDataAdapter()
    await adapter.connect({
        "username": "xxx", "password": "xxx",
        "host": "xxx", "port": 8600
    })
    
    # 获取K线
    klines = await adapter.fetch_klines("000001.SZ", "20240101", "20241231", "1d")
    
    for k in klines:
        print(f"日期: {k.trade_date}, 收盘: {k.close}, "
              f"涨停: {k.is_limit_up}, 跌停: {k.is_limit_down}")
    
    await adapter.close()

asyncio.run(main())
```

### 示例2：获取财务报表

```python
# 获取资产负债表
balance = await adapter.get_balance_sheet(
    codes=["000001.SZ", "600000.SH"],
    start_date="20240930",
    end_date="20240930"
)

for code, df in balance.items():
    print(f"{code} 总资产: {df['TOTAL_ASSETS'].values[0]}")
```

### 示例3：获取指数成分股

```python
# 沪深300成分股
constituents = await adapter.get_index_constituents(["000300.SH"])
df = constituents["000300.SH"]
print(f"成分股数量: {len(df)}")
print(df[["CON_CODE", "INDATE"]].head())
```

### 示例4：获取龙虎榜数据

```python
longhu = await adapter.get_longhu_bang(
    codes=["000001.SZ"],
    start_date="20240101",
    end_date="20241231"
)
print(longhu[["TRADE_DATE", "REASON_TYPE_NAME", "BUY_AMOUNT", "SELL_AMOUNT"]])
```

---

## 注意事项

1. **连接管理**: 使用前先调用 `connect()`，使用后调用 `close()`
2. **日期格式**: 支持 `YYYYMMDD`、`"YYYY-MM-DD"` 或 `date` 对象
3. **本地缓存**: 默认启用，可设置 `is_local=False` 强制从服务器获取
4. **批量处理**: 大量数据建议分批获取，每批 50-100 个代码
5. **错误处理**: 连接断开会抛出 `RuntimeError`，需做好异常处理

---

**文档版本**: 1.0  
**更新日期**: 2024-03-11