From 6d72efc6242af8589e8c3add6a3dd0524f99ecc2 Mon Sep 17 00:00:00 2001 From: shy3130 <415333856@qq.com> Date: Mon, 31 Aug 2026 16:50:38 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E6=8C=87=E6=95=B0=E5=9B=BA=E5=AE=9A?= =?UTF-8?q?=E6=B8=85=E5=8D=95=E5=A5=91=E7=BA=A6=20+=20=E8=87=AA=E5=AE=9A?= =?UTF-8?q?=E4=B9=89=E6=BA=90=E6=8C=87=E6=95=B0=E8=A1=A5=E5=85=85=E5=8D=8F?= =?UTF-8?q?=E8=AE=AE?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - CONTRIBUTING 能力路由矩阵小节: 实时指数为产品级固定契约不走路由矩阵 (index_const 单一权威, 指数页固定四只, 指数偏好已删, 监控标的不受限); 自定义源 get_realtime_indices 可选协议与 fuyao 连坐语义注记 - plugin-development: get_realtime_indices 方法契约与软失败语义 --- CONTRIBUTING.md | 2 ++ docs/plugin-development.md | 6 ++++++ 2 files changed, 8 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 88944c0..0b44732 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -139,6 +139,8 @@ - 能力层中立：通用界面（侧栏徽章、能力路由卡、各页门控提示）不得出现 TickFlow 档位/订阅词汇；档位信息只在 TickFlow 专属详情卡展示。provider 名称作为路由事实可以出现。 - 每个能力独立路由，禁止跟随/派生特殊值（`same_as_daily` 已下线）；存量非法偏好值由 preferences getter 回退默认自愈，不做迁移。 - 边界注记：分时监控由分钟能力兜底（`intraday_monitor_support`），不单设分时能力；`depth5` 已进矩阵但插件数据集白名单暂未开放，当前仅 TickFlow 提供。 +- 实时指数为产品级固定契约，不走路由矩阵：展示层（侧栏指数条、市场总览）固定核心四只（`backend/app/services/index_const.py` 单一权威：上证/深成/创业板/科创综指），后端各消费方与前端 Layout 引用同一份定义不建副本；指数页保留但标的固定为核心四只（无全指数搜索/浏览，`/api/index/list`、`/api/index/search` 已下线）；侧栏指数多选配置已下线，相关偏好（`realtime_index_symbols`/`sidebar_index_symbols`/`indices_nav_pinned`/`realtime_pull_index`/`realtime_index_mode`）已删除。监控规则的指数标的不受限——quote_service 把核心四只 + 启用规则的指数并入显式拉取。 +- 自定义源指数补充协议：A 股快照普遍不含指数（fuyao 实测无指数，指数在其独立端点）。provider 可实现可选方法 `get_realtime_indices(symbols) -> list[dict]`（record 结构与 realtime 一致），quote_service 在自定义源分支鸭子类型调用补拉；未实现的源指数缓存为空，由本地日K兜底接管。fuyao 指数快照有连坐语义——请求混入未知代码整批失败，插件侧必须先行过滤不支持的后缀（如 `.BJ`）。 ## 5. 领域专项要求 diff --git a/docs/plugin-development.md b/docs/plugin-development.md index 9e1ccc9..cf2bc2b 100644 --- a/docs/plugin-development.md +++ b/docs/plugin-development.md @@ -152,6 +152,11 @@ class MyProvider: def get_realtime(self) -> list[dict]: """全市场实时快照 → list[dict]。失败软返回 [], 不抛异常(不阻断轮询线程)。""" + def get_realtime_indices(self, symbols: list[str]) -> list[dict]: + """(可选)指数实时快照 → list[dict], 行字段与 get_realtime 一致。 + A 股快照普遍不含指数(fuyao 的指数在独立端点); 声明 realtime 的源 + 强烈建议实现本方法, 否则指数行情冻结在本地日K兜底。失败软返回 []。""" + def get_financials(self, table, symbols, latest_only=False) -> pl.DataFrame: """财务数据(声明 financial 数据集时实现, table 见 financial_sync 调用)。""" @@ -184,6 +189,7 @@ class MyProvider: | 方法 | 失败行为 | | --- | --- | | `get_realtime` | **软失败**: 返回 `[]` + warning 日志, 保证轮询线程不中断 | +| `get_realtime_indices` | **软失败**: 返回 `[]` + warning 日志; 指数缓存为空走日K兜底 | | `get_minute` | 抛异常时调用方自动回退 TickFlow 重试 | | `get_daily` / `get_adj_factors` / `get_financials` | 异常由上层同步流程捕获记录; 无数据返回空 DataFrame |