python_market_data_service/GET_HISTORY_STOCK_STATUS.md

# get_history_stock_status 接口实现

## 接口说明

`get_history_stock_status` 是 AmazingData SDK 提供的历史股票状态查询接口，用于获取股票的历史涨停/跌停价、ST状态、停牌状态等信息。

## 实现位置

### 1. 内部接口层
**文件**: `app/adapters/internal_data_service.py`

```python
class _InfoDataInternal:
    def get_history_stock_status(
        self,
        code_list: List[str],
        local_path: str,
        is_local: bool,
        begin_date: Optional[int] = None,
        end_date: Optional[int] = None
    ) -> Dict[str, pd.DataFrame]:
        """获取历史股票状态数据
        
        包含字段：
        - TRADE_DATE: 交易日期
        - UP_LIMIT: 涨停价
        - DOWN_LIMIT: 跌停价
        - MAX_UP_DOWN: 最大涨跌幅限制
        - IS_ST: 是否ST
        - IS_SUSPEND: 是否停牌
        """
```

### 2. 对外接口层
**文件**: `app/adapters/amazingdata_adapter.py`

```python
class AmazingDataAdapter(DataSourceAdapter):
    async def get_history_stock_status(
        self,
        codes: List[str],
        start_date: Optional[str] = None,
        end_date: Optional[str] = None,
        is_local: Optional[bool] = None
    ) -> Dict[str, pd.DataFrame]:
        """获取历史股票状态数据"""
```

## 返回字段说明

| 字段名 | 类型 | 说明 |
|--------|------|------|
| TRADE_DATE | int | 交易日期 (YYYYMMDD) |
| UP_LIMIT | float | 涨停价 |
| DOWN_LIMIT | float | 跌停价 |
| MAX_UP_DOWN | float | 最大涨跌幅限制(%) |
| IS_ST | bool/int | 是否ST股 |
| IS_SUSPEND | bool/int | 是否停牌 |

## 使用示例

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

adapter = AmazingDataAdapter()
await adapter.connect({
    "username": "your_username",
    "password": "your_password",
    "host": "your_host",
    "port": 8600
})

# 获取股票历史状态
result = await adapter.get_history_stock_status(
    codes=["000001.SZ", "600519.SH"],
    start_date="20240301",
    end_date="20240310"
)

# 处理结果
for symbol, df in result.items():
    print(f"股票: {symbol}")
    print(df[["TRADE_DATE", "UP_LIMIT", "DOWN_LIMIT", "IS_ST"]])
```

## 调用链

```
AmazingDataAdapter.get_history_stock_status (async)
└── _InfoDataInternal.get_history_stock_status (sync)
    └── SDK: _info_data.get_history_stock_status()
```

## SDK 调用统计

| 层次 | 调用次数 | 说明 |
|------|----------|------|
| 对外接口 | 1 | async 包装 |
| 内部接口 | 1 | 错误处理 |
| SDK | 1 | 实际数据获取 |

**总计**: 1 次 SDK 调用（单次查询）

## 应用场景

1. **涨跌停分析** - 获取历史涨停/跌停价格
2. **ST股票跟踪** - 监控股票ST状态变化
3. **停牌监控** - 获取股票停牌状态
4. **策略回测** - 基于历史涨跌停限制进行回测

## 与其他接口的关系

| 接口 | 用途 | 区别 |
|------|------|------|
| `get_history_stock_status` | 获取历史状态（涨停/跌停/ST/停牌） | 返回每日状态数据 |
| `get_code_info` | 获取当前代码信息 | 返回最新静态信息 |
| `fetch_klines` | 获取K线数据 | 包含涨跌停判断逻辑 |

## 文档更新

以下文档已更新：
- `INTERNAL_INTERFACES.md` - 内部接口层文档
- `AMAZINGDATA_ADAPTER_INTERFACES_V3.md` - 接口调用关系文档