python_market_data_service/xysz/README_AmazingDataAdapter.md

# AmazingData 数据源适配器

基于中国银河证券星耀数智量化平台 SDK 的封装，提供统一、简洁的金融数据获取接口。

## 功能特性

- **简洁的API设计**: 封装复杂的SDK接口，提供直观的数据获取方法
- **类型安全**: 使用Python类型注解，IDE友好的代码提示
- **灵活的配置**: 支持本地缓存、参数自定义等配置选项
- **全面的数据覆盖**: 支持行情、财务、股本、融资融券等多类金融数据

## 安装依赖

```bash
# 安装 AmazingData SDK (需从银河证券获取)
pip install tgw-1.*.*-py3-none-any.whl
pip install AmazingData-1.*.*-cp3x-none-any.whl

# 安装其他依赖
pip install pandas
```

## 快速开始

```python
from amazing_data_adapter import create_adapter, SecurityType, Period

# 1. 创建适配器
adapter = create_adapter(
    username='your_username',
    password='your_password', 
    host='your_host',
    port=8080,
    local_path='./data_cache/',  # 本地缓存路径
    use_local_cache=True          # 是否使用本地缓存
)

# 2. 连接数据源
if adapter.connect():
    # 3. 获取数据
    codes = adapter.get_code_list(SecurityType.STOCK_A)
    kline = adapter.get_kline(
        codes=['000001.SZ'],
        start_date='20240101',
        end_date='20241231',
        period=Period.DAILY
    )
    
    # 4. 断开连接
    adapter.disconnect()
```

## 功能模块

### 1. 基础数据

| 方法 | 说明 |
|------|------|
| `get_code_list(security_type)` | 获取代码列表 |
| `get_code_info(security_type)` | 获取证券基本信息 |
| `get_trading_calendar(market)` | 获取交易日历 |
| `get_adj_factor(codes)` | 获取单次复权因子 |
| `get_backward_factor(codes)` | 获取后复权因子 |

### 2. 历史行情数据

| 方法 | 说明 |
|------|------|
| `get_kline(codes, start_date, end_date, period)` | 获取K线数据 |
| `get_snapshot(codes, start_date, end_date)` | 获取历史快照 |

**支持的周期 (Period)**:
- `Period.MIN1` - 1分钟
- `Period.MIN5` - 5分钟
- `Period.MIN15` - 15分钟
- `Period.MIN30` - 30分钟
- `Period.MIN60` - 60分钟
- `Period.DAILY` - 日线
- `Period.WEEKLY` - 周线
- `Period.MONTHLY` - 月线

### 3. 财务数据

| 方法 | 说明 |
|------|------|
| `get_balance_sheet(codes, start_date, end_date)` | 资产负债表 |
| `get_cash_flow(codes, start_date, end_date)` | 现金流量表 |
| `get_income_statement(codes, start_date, end_date)` | 利润表 |
| `get_profit_express(codes, start_date, end_date)` | 业绩快报 |
| `get_profit_notice(codes, start_date, end_date)` | 业绩预告 |

### 4. 股东股本数据

| 方法 | 说明 |
|------|------|
| `get_top10_shareholders(codes, start_date, end_date)` | 十大股东 |
| `get_shareholder_count(codes, start_date, end_date)` | 股东户数 |
| `get_equity_structure(codes, start_date, end_date)` | 股本结构 |

### 5. 融资融券数据

| 方法 | 说明 |
|------|------|
| `get_margin_summary(start_date, end_date)` | 融资融券汇总 |
| `get_margin_detail(codes, start_date, end_date)` | 个股融资融券明细 |

### 6. 交易异动数据

| 方法 | 说明 |
|------|------|
| `get_longhu_bang(codes, start_date, end_date)` | 龙虎榜数据 |
| `get_block_trading(codes, start_date, end_date)` | 大宗交易 |

### 7. 指数数据

| 方法 | 说明 |
|------|------|
| `get_index_constituents(codes)` | 指数成分股 |
| `get_index_weights(codes, start_date, end_date)` | 成分股权重 |

**支持的指数**:
- `000016.SH` - 上证50
- `000300.SH` - 沪深300
- `000905.SH` - 中证500
- `000906.SH` - 中证800
- `000852.SH` - 中证1000

### 8. ETF数据

| 方法 | 说明 |
|------|------|
| `get_etf_pcf(codes)` | ETF申赎数据 |
| `get_fund_share(codes, start_date, end_date)` | 基金份额 |

### 9. 可转债数据

| 方法 | 说明 |
|------|------|
| `get_kzz_issuance(codes)` | 可转债发行数据 |

## 证券类型枚举

```python
from amazing_data_adapter import 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期权
```

## 使用示例

### 获取历史K线数据

```python
# 获取多只股票日线数据
kline_data = adapter.get_kline(
    codes=['000001.SZ', '600000.SH'],
    start_date='20240101',
    end_date='20241231',
    period=Period.DAILY
)

for code, df in kline_data.items():
    print(f"{code}: {len(df)} 条数据")
    print(df.head())
```

### 获取财务报表

```python
# 获取资产负债表
balance_sheet = adapter.get_balance_sheet(
    codes=['000001.SZ', '600000.SH'],
    start_date=20240101,
    end_date=20241231
)

for code, df in balance_sheet.items():
    print(f"\n{code} 资产负债表:")
    print(df[['REPORTING_PERIOD', 'TOTAL_ASSETS', 'TOTAL_CUR_ASSETS']])
```

### 获取指数成分股

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

### 批量数据处理

```python
# 获取所有A股代码
all_codes = adapter.get_code_list(SecurityType.STOCK_A)

# 分批处理避免超时
batch_size = 50
for i in range(0, len(all_codes), batch_size):
    batch_codes = all_codes[i:i+batch_size]
    data = adapter.get_balance_sheet(batch_codes)
    # 处理数据...
```

### 结合复权因子计算真实价格

```python
# 获取K线和复权因子
kline = adapter.get_kline(['000001.SZ'], '20240101', '20241231')
adj_factor = adapter.get_backward_factor(['000001.SZ'])

df = kline['000001.SZ']
# 合并并计算复权价格
df['trade_date'] = df.index.strftime('%Y%m%d').astype(int)
df = df.merge(adj_factor[['000001.SZ']].reset_index(), 
              left_on='trade_date', right_on='index')
df['adj_close'] = df['close'] * df['000001.SZ']
```

## 数据缓存

适配器支持本地数据缓存，可大幅提升重复查询的速度：

```python
adapter = create_adapter(
    username='xxx',
    password='xxx',
    host='xxx',
    port=8080,
    local_path='./my_data_cache/',  # 缓存目录
    use_local_cache=True              # 默认启用缓存
)

# 强制从服务器获取最新数据
adapter.get_kline(codes, start_date, end_date, is_local=False)
```

## 注意事项

1. **账号权限**: 使用本适配器需要先向中国银河证券申请开通星耀数智平台权限

2. **日期格式**: 支持多种日期格式：
   - `int`: 20240101
   - `str`: "2024-01-01" 或 "20240101"
   - `date`: datetime.date(2024, 1, 1)

3. **错误处理**: 所有方法在连接断开会抛出 `RuntimeError`，建议在外层做好异常处理

4. **资源释放**: 使用完毕后请调用 `adapter.disconnect()` 断开连接

## 文件说明

- `amazing_data_adapter.py` - 适配器主代码
- `amazing_data_examples.py` - 详细使用示例
- `README.md` - 本文档

## API参考

详细的SDK接口文档请参考银河证券提供的《AmazingData开发手册》。