docs(data): 沉淀能力路由矩阵契约, 同步插件接入文档

- CONTRIBUTING §4 新增「能力路由矩阵契约」: 注册表单一权威、usable 统一
  门控、能力层中立原则、独立路由禁特殊值(same_as_daily 已下线)、
  分时/depth5 边界注记
- custom-data-source: 除权因子接入示例移除 same_as_daily
- plugin-development: manifest 字段表补 homepage 可选字段
This commit is contained in:
shy3130
2026-08-30 19:05:23 +08:00
parent 6fb46b100a
commit d5582c3c8d
3 changed files with 12 additions and 1 deletions
+10
View File
@@ -129,6 +129,16 @@
- 插件加载失败、字段缺失和空数据必须有隔离测试,不能导致应用启动失败或其他数据源不可用。
- 新增数据源适配应同步更新 `docs/custom-data-source.md``docs/plugin-development.md` 中对应契约。
### 能力路由矩阵契约
能力矩阵(`backend/app/data_providers/capabilities.py` 注册表 + `/api/settings/capability-matrix`)是能力路由的单一权威,遵循以下不变量:
- 注册表集中声明每个能力的展示元数据、路由偏好字段与 TickFlow 档位要求;前端不硬编码能力清单。新增能力按既有模式扩展:注册表 + preferences getter + capability-matrix 注入 + 矩阵测试。
- 各页面能力门控统一以矩阵的 `usable` 为准(生效源当前能否真正提供该能力),不是 TickFlow 套餐视角;缺能力提示统一引导到数据源配置。
- 能力层中立:通用界面(侧栏徽章、能力路由卡、各页门控提示)不得出现 TickFlow 档位/订阅词汇;档位信息只在 TickFlow 专属详情卡展示。provider 名称作为路由事实可以出现。
- 每个能力独立路由,禁止跟随/派生特殊值(`same_as_daily` 已下线);存量非法偏好值由 preferences getter 回退默认自愈,不做迁移。
- 边界注记:分时监控由分钟能力兜底(`intraday_monitor_support`),不单设分时能力;`depth5` 已进矩阵但插件数据集白名单暂未开放,当前仅 TickFlow 提供。
## 5. 领域专项要求
### 5.1 策略
+1 -1
View File
@@ -226,7 +226,7 @@ cp docs/examples/custom-data-source/mock_source.yaml data/data_sources/mock_sour
5. 保存数据源选择:
- 日K: `mock_source`
- 除权因子: `same_as_daily``mock_source`
- 除权因子: `mock_source` (或保持默认 `tickflow`)
- 实时行情: `mock_source`
6. 触发同步或开启实时行情。
+1
View File
@@ -33,6 +33,7 @@ api_key_env: MY_SOURCE_API_KEY # (可选)声明后设置页提供 Key
hidden: false # (可选)true = 已加载但对设置页隐藏,不注册不展示
description: "数据源描述"
install_hint: "pip install xxx" # 未装依赖时显示的安装提示
homepage: "https://example.com" # (可选)官网/申请地址, 显示在设置页 Key 配置说明中
```
只声明真实提供的数据集;未声明的数据集 `provider_has_dataset` 返回 False,自动回退