tick-stock-panel/docs/custom-data-source.md

自定义数据源接入

本项目默认使用 TickFlow。自定义数据源是一个可选扩展: 外部 HTTP 服务负责取数和整理, 本项目只把返回结果映射成内部标准字段, 然后复用现有存储、指标、enriched、策略和前端展示逻辑。

支持范围

当前自定义源支持三类数据:

数据集	配置名	说明
日K	daily	批量返回一组股票在指定区间内的日K
除权因子	adj_factor	批量返回一组股票的复权因子
实时行情	realtime	返回全市场快照,用于盘中 enriched 增量计算

分钟K、财务、深度盘口暂时仍走 TickFlow。

配置位置

把 YAML 放到运行数据目录下:

data/data_sources/*.yaml

在桌面版中,data/ 位于程序目录旁;在开发环境中,通常是项目根目录的 data/。

修改 YAML 后可在「设置 -> 数据源」点击「重新加载」,或调用:

curl -X POST http://127.0.0.1:3018/api/settings/data-sources/reload

最小 YAML

name: mock_source
display_name: "Mock 自定义数据源"
auth:
  type: none

datasets:
  daily:
    url: http://127.0.0.1:3021/daily
    method: POST
    batch: 100
    rpm: 200
    response_path: data
    field_map:
      ts_code: symbol
      trade_date: date
      open: open
      high: high
      low: low
      close: close
      vol: volume
      amt: amount
    transforms:
      date: "parse_date(value, '%Y-%m-%d')"

  adj_factor:
    url: http://127.0.0.1:3021/adj_factor
    method: POST
    batch: 100
    rpm: 200
    response_path: data
    field_map:
      ts_code: symbol
      trade_date: trade_date
      factor: ex_factor
    transforms:
      trade_date: "parse_date(value, '%Y-%m-%d')"

  realtime:
    url: http://127.0.0.1:3021/realtime
    method: GET
    rpm: 60
    response_path: data
    field_map:
      ts_code: symbol
      name: name
      last: last_price
      pre_close: prev_close
      open: open
      high: high
      low: low
      vol: volume
      amt: amount
      pct: change_pct
      amount_change: change_amount
      amplitude: amplitude
      turnover: turnover_rate

字段契约

daily 必填

内部字段	含义
symbol	标准代码,如 000001.SZ
date	交易日
open / high / low / close	不复权 OHLC
volume	成交量
amount	成交额

adj_factor 必填

内部字段	含义
symbol	标准代码
trade_date	除权日期
ex_factor	复权因子

realtime 必填

内部字段	含义
symbol	标准代码
last_price	最新价
prev_close	昨收
open / high / low	当日 OHLC
volume	成交量

建议实时接口额外提供 amount、change_pct、change_amount、amplitude、turnover_rate、name。缺失时部分字段会由 pipeline 回算,但精度取决于可用输入。

change_pct 和 amplitude 使用小数制,例如 0.0366 表示 3.66%。

请求约定

• daily / adj_factor 会按 batch 切分 symbols。
• POST 请求会发送 JSON body: symbols、start_time、end_time。
• GET 请求会发送 query 参数: symbols=000001.SZ,600000.SH。
• realtime 必须是全市场快照接口,不支持逐个 symbol 拉实时行情。

可通过这些字段改参数名:

symbols_param: symbols
start_param: start_time
end_param: end_time

鉴权

支持三种简单鉴权:

auth:
  type: bearer
  token_env: MY_DATA_TOKEN

auth:
  type: header
  header: X-Token
  token_env: MY_DATA_TOKEN

auth:
  type: query
  param: token
  token_env: MY_DATA_TOKEN

Token 可以放在系统环境变量或项目 .env 中。

联调流程

1. 启动 mock 数据源:

cd docs/examples/custom-data-source
python mock_server.py

2. 复制示例配置:

mkdir -p data/data_sources
cp docs/examples/custom-data-source/mock_source.yaml data/data_sources/mock_source.yaml

3. 在「设置 -> 数据源」点击「重新加载」。

4. 使用「试拉测试」选择 mock_source 和 daily / adj_factor / realtime。

5. 保存数据源选择:

• 日K: mock_source
• 除权因子: same_as_daily 或 mock_source
• 实时行情: mock_source

6. 触发同步或开启实时行情。

常见错误

现象	处理
列表里没有 custom 源	检查 YAML 是否放在 data/data_sources/ 并点击重新加载
errors 提示 missing mapped fields	field_map 没映射到必填内部字段
试拉 rows 为 0	检查 response_path 是否指向数组
日期列全为空	检查 parse_date 的格式是否和返回值一致
实时行情没刷新	确认实时数据源已保存为 custom,且返回全市场快照