ProStock/src/data/api_wrappers/API_INTERFACE_SPEC.md

# ProStock 数据接口封装规范

## 1. 概述

本文档定义了新增 Tushare API 接口封装的标准规范。所有非特殊接口必须遵循此规范，确保：
- 代码风格统一
- 自动 sync 支持
- 增量更新逻辑一致
- 减少存储写入压力

## 2. 接口分类

### 2.1 特殊接口（不参与统一 sync）

以下接口有独立的同步逻辑，不参与自动 sync 机制：

| 接口类型 | 示例 | 说明 |
|---------|------|------|
| 交易日历 | `trade_cal` | 全局数据，按日期范围获取 |
| 股票基础信息 | `stock_basic` | 一次性全量获取，CSV 存储 |
| 辅助数据 | 行业分类、概念分类 | 低频更新，独立管理 |

### 2.2 标准接口（必须遵循本规范）

所有按股票或按日期获取的因子数据、行情数据、财务数据等，必须遵循本规范。

## 3. 文件结构要求

### 3.1 文件命名

```
{data_type}.py
```

示例：`daily.py`、`moneyflow.py`、`limit_list.py`

### 3.2 文件位置

所有接口文件必须位于 `src/data/` 目录下。

### 3.3 导出要求

新接口必须在 `src/data/__init__.py` 中导出：

```python
from src.data.{module_name} import get_{data_type}

__all__ = [
    # ... 其他导出 ...
    "get_{data_type}",
]
```

## 4. 接口设计规范

### 4.1 数据获取函数签名要求

函数必须返回 `pd.DataFrame`，参数必须包含以下之一：

#### 4.1.1 按日期获取的接口（优先）

适用于：涨跌停、龙虎榜、筹码分布等。

**函数签名要求**：

```python
def get_{data_type}(
    trade_date: Optional[str] = None,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    ts_code: Optional[str] = None,
    # 其他可选参数...
) -> pd.DataFrame:
```

**要求**：
- 优先使用 `trade_date` 获取单日全市场数据
- 支持 `start_date + end_date` 获取区间数据
- `ts_code` 作为可选过滤参数

#### 4.1.2 按股票获取的接口

适用于：日线行情、资金流向等。

**函数签名要求**：

```python
def get_{data_type}(
    ts_code: str,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    # 其他可选参数...
) -> pd.DataFrame:
```

### 4.2 文档字符串要求

函数必须包含 Google 风格的完整文档字符串，包含：
- 函数功能描述
- `Args` 部分：所有参数说明
- `Returns` 部分：返回的 DataFrame 包含的字段说明
- `Example` 部分：使用示例

### 4.3 日期格式要求

- 所有日期参数和返回值使用 `YYYYMMDD` 字符串格式
- 统一使用 `trade_date` 作为日期字段名
- 如果 API 返回其他日期字段名（如 `date`、`end_date`），必须在返回前重命名为 `trade_date`

### 4.4 股票代码要求

- 统一使用 `ts_code` 作为股票代码字段名
- 格式：`{code}.{exchange}`，如 `000001.SZ`、`600000.SH`

### 4.5 令牌桶限速要求

所有 API 调用必须通过 `TushareClient`，自动满足令牌桶限速要求。

## 5. Sync 集成规范

### 5.1 DATASET_CONFIG 注册要求

新接口必须在 `DataSync.DATASET_CONFIG` 中注册，配置项：

```python
"{new_data_type}": {
    "api_name": "{tushare_api_name}",  # Tushare API 名称
    "fetch_by": "date",  # "date" 或 "stock"
    "date_field": "trade_date",
    "key_fields": ["ts_code", "trade_date"],  # 用于去重的主键
}
```

### 5.2 fetch_by 取值规则

- **优先使用 `"date"`**：如果 API 支持按日期获取全市场数据
- 仅当 API 不支持按日期获取时才使用 `"stock"`

### 5.3 sync 方法要求

必须实现对应的 sync 方法或复用通用方法：

```python
def sync_{data_type}(self, force_full: bool = False) -> pd.DataFrame:
    """Sync {数据描述}。"""
    return self.sync_dataset("{data_type}", force_full)
```

同时提供便捷函数：

```python
def sync_{data_type}(force_full: bool = False) -> pd.DataFrame:
    """Sync {数据描述}。"""
    sync_manager = DataSync()
    return sync_manager.sync_{data_type}(force_full)
```

### 5.4 增量更新要求

- 必须实现增量更新逻辑（自动检查本地最新日期）
- 使用 `force_full` 参数支持强制全量同步

## 6. 存储规范

### 6.1 存储方式

所有数据通过 `Storage` 类进行 HDF5 存储。

### 6.2 写入策略

**要求**：所有数据在请求完成后**一次性写入**，而非逐条写入。

### 6.3 去重要求

使用 `key_fields` 配置的字段进行去重，默认使用 `["ts_code", "trade_date"]`。

## 7. 测试规范

### 7.1 测试文件要求

必须创建对应的测试文件：`tests/test_{data_type}.py`

### 7.2 测试覆盖要求

- 测试按日期获取
- 测试按股票获取（如果支持）
- 必须 mock `TushareClient`
- 测试覆盖正常和异常情况

## 8. 新增接口完整流程

### 8.1 创建接口文件

1. 在 `src/data/` 下创建 `{data_type}.py`
2. 实现数据获取函数，遵循第 4 节规范

### 8.2 注册 sync 支持

1. 在 `sync.py` 的 `DataSync.DATASET_CONFIG` 中注册
2. 实现对应的 sync 方法
3. 提供便捷函数

### 8.3 更新导出

在 `src/data/__init__.py` 中导出接口函数。

### 8.4 创建测试

创建 `tests/test_{data_type}.py`，覆盖关键场景。

## 9. 检查清单

### 9.1 文件结构
- [ ] 文件位于 `src/data/{data_type}.py`
- [ ] 已更新 `src/data/__init__.py` 导出公共接口
- [ ] 已创建 `tests/test_{data_type}.py` 测试文件

### 9.2 接口实现
- [ ] 数据获取函数使用 `TushareClient`
- [ ] 函数包含完整的 Google 风格文档字符串
- [ ] 日期参数使用 `YYYYMMDD` 格式
- [ ] 返回的 DataFrame 包含 `ts_code` 和 `trade_date` 字段
- [ ] 优先实现按日期获取的接口（如果 API 支持）

### 9.3 Sync 集成
- [ ] 已在 `DataSync.DATASET_CONFIG` 中注册
- [ ] 正确设置 `fetch_by`（"date" 或 "stock"）
- [ ] 正确设置 `date_field` 和 `key_fields`
- [ ] 已实现对应的 sync 方法或复用通用方法
- [ ] 增量更新逻辑正确（检查本地最新日期）

### 9.4 存储优化
- [ ] 所有数据一次性写入（非逐条）
- [ ] 使用 `storage.save(mode="append")` 进行增量保存
- [ ] 去重字段配置正确

### 9.5 测试
- [ ] 已编写单元测试
- [ ] 已 mock TushareClient
- [ ] 测试覆盖正常和异常情况

---

**最后更新**: 2026-02-01