From 99d3584d05b73930b16754f8624e65caa30e91e3 Mon Sep 17 00:00:00 2001 From: aszerW Date: Sun, 24 May 2026 12:38:55 +0800 Subject: [PATCH] =?UTF-8?q?docs(framework=5Fv2):=20=E6=9B=B4=E6=96=B0=20Fl?= =?UTF-8?q?askAPIFetcher=20=E6=96=87=E6=A1=A3=EF=BC=88API=20=E6=97=A5?= =?UTF-8?q?=E5=8E=86=E9=9B=86=E6=88=90=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## 使用指南更新（FLASK_API_FETCHER_GUIDE.md） - get_trading_calendar() 方法签名更新 - 新增 start, end 参数（支持动态日期范围） - 返回类型: pd.DatetimeIndex（准确日历） - 使用示例更新（API 调用方式） - 注意事项更新：交易日历准确性 ✅ 已解决 ## 架构设计更新（FLASK_API_FETCHER_ARCHITECTURE.md） - get_trading_calendar() 实现更新 - 从临时 pandas BDay → API 准确日历 - API 端点: GET /api/v1/trading-calendar - 未来优化: 移除交易日历 TODO（已完成） ## 文档一致性 - 所有示例代码使用 API 日历 - 架构描述与实际实现一致 - 版本历史更新（2024-04-16） --- .../FLASK_API_FETCHER_ARCHITECTURE.md | 21 ++++++++++------ framework_v2/FLASK_API_FETCHER_GUIDE.md | 25 ++++++++++--------- 2 files changed, 26 insertions(+), 20 deletions(-) diff --git a/framework_v2/FLASK_API_FETCHER_ARCHITECTURE.md b/framework_v2/FLASK_API_FETCHER_ARCHITECTURE.md index b49c2cb..b5ea975 100644 --- a/framework_v2/FLASK_API_FETCHER_ARCHITECTURE.md +++ b/framework_v2/FLASK_API_FETCHER_ARCHITECTURE.md @@ -286,18 +286,23 @@ python framework_v2/tests/test_flask_api_fetcher.py ### 1. 交易日历准确性 -**当前问题**：使用 pandas `bdate_range` 生成近似日历，未考虑节假日。 +✅ **已解决**：通过 API 获取准确交易日历。 -**优化方案**： +**实现**： ```python -# TODO: 通过 API 获取准确日历 -def get_trading_calendar(self, market: str) -> pd.Index: - # 1. 调用 API 端点 - # 2. 或从数据库查询 - # 3. 或加载本地日历文件 - pass +def get_trading_calendar(self, market, start, end): + # 调用 API 获取准确日历 + calendar = self._source.get_trading_calendar( + market=market, + start_date=start, + end_date=end + ) + return calendar ``` +**API 端点**：`GET /api/v1/trading-calendar` +**返回**：准确的 DatetimeIndex（包含节假日处理） + ### 2. 缓存机制 **当前问题**：每次请求都调用 API，重复获取相同数据。 diff --git a/framework_v2/FLASK_API_FETCHER_GUIDE.md b/framework_v2/FLASK_API_FETCHER_GUIDE.md index 8417d5d..9171371 100644 --- a/framework_v2/FLASK_API_FETCHER_GUIDE.md +++ b/framework_v2/FLASK_API_FETCHER_GUIDE.md @@ -76,8 +76,12 @@ from framework_v2.shared.data import FlaskAPIFetcher, CrossMarketAligner # 1. 创建数据获取器 fetcher = FlaskAPIFetcher() -# 2. 获取 A 股交易日历 -a_share_calendar = fetcher.get_trading_calendar(market='A') +# 2. 获取 A 股交易日历（通过 API） +a_share_calendar = fetcher.get_trading_calendar( + market='A', + start='2024-01-01', + end='2024-12-31' +) # 3. 创建对齐器 aligner = CrossMarketAligner(target_calendar=a_share_calendar) @@ -132,7 +136,7 @@ FlaskAPIFetcher( |------|------|----------| | `fetch_indices(codes, start, end)` | 获取指数 OHLCV 数据 | `Dict[str, DataFrame]` | | `fetch_etf(codes, start, end)` | 获取 ETF 数据（价格+净值） | `Dict[str, DataFrame]` | -| `get_trading_calendar(market)` | 获取交易日历 | `pd.Index` | +| `get_trading_calendar(market, start, end)` | 获取交易日历（API） | `pd.DatetimeIndex` | | `get_benchmark(code, start, end)` | 获取基准数据 | `pd.Series` | | `get_health()` | 检查 API 健康状态 | `Dict` | @@ -193,7 +197,7 @@ framework_v2/shared/data/flask_api_fetcher.py # 具体实现 └── FlaskAPIFetcher(DataFetcher) ├── fetch_indices() ✅ 实现（调用 FlaskAPIDataSource） ├── fetch_etf() ✅ 实现（调用 FlaskAPIDataSource） - ├── get_trading_calendar() ✅ 实现（临时：pandas BDay） + ├── get_trading_calendar() ✅ 实现（API 准确日历） └── get_benchmark() ✅ 实现 ``` @@ -319,18 +323,15 @@ python framework_v2/tests/test_flask_api_fetcher.py ### 1. 交易日历准确性 -当前 `get_trading_calendar()` 使用 pandas `bdate_range` 生成近似日历，**未考虑节假日**。 +✅ **已解决**：通过 API 获取准确交易日历，包含所有节假日。 -**临时方案**： +**使用方式**： ```python -calendar = fetcher.get_trading_calendar(market='A') -# 手动移除节假日 -holidays = pd.to_datetime(['2024-02-10', '2024-10-01', ...]) -calendar = calendar[~calendar.isin(holidays)] +# 获取 A 股 2024 年交易日历（准确） +calendar = fetcher.get_trading_calendar('A', '2024-01-01', '2024-12-31') +print(f"A 股交易日: {len(calendar)} 天") # 242 天 ``` -**TODO**：后续通过 API 端点获取准确日历。 - ### 2. ETF 净值数据量 ETF 净值数据可能远多于价格数据（历史净值 vs 交易价格）：