refactor: 重构 API 接口模块，整合为 api_wrappers 目录结构

- 将独立 API 模块 (daily, stock_basic, trade_cal) 整合至 api_wrappers/ - 重写 sync.py 使用新的 wrapper 结构，支持更多同步功能 - 更新测试文件适配新的模块结构 - 添加 pytest.ini 配置文件
2026-02-21 03:43:30 +08:00
parent e81d39ae0d
commit 9965ce5706
15 changed files with 1042 additions and 952 deletions
--- a/src/data/api_wrappers/API_INTERFACE_SPEC.md
+++ b/src/data/api_wrappers/API_INTERFACE_SPEC.md
@@ -0,0 +1,244 @@
+# 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