数据源中心 · 能力路由矩阵
tick-stock-panel 数据源与能力路由：免费能用到什么程度
官方 tiers.yaml 是给程序读的配置，docs/custom-data-source.md 是面向插件开发者的契约文档。本页把它们合成一张可读的图：哪些数据免费、哪些需要档位、想接自己的数据源要满足什么契约、以及接错了会出现什么现象。
五档能力与免费边界：tick-stock-panel 不付费能用到什么程度？
下表把官方文档的档位说明与 tiers.yaml 的能力声明合并成一张读得懂的表。“免费否”一列只说明能力归属，不代表价格承诺。
| 能力档位 | 历史日 K | 实时行情 | 分钟 K / 全量分钟 | 财务数据 | 免费否 |
|---|---|---|---|---|---|
| none（无 key / 无效 key） | ✅ 走 free-api，含批量 | ❌ | ❌ | ❌ | 完全免费 |
| free（免费有效 key） | ✅ 同 none（free-api） | ⚠️ 自选页前 5 个标的监控 | ❌ | ❌ | 免费（需注册） |
| starter | ✅ 走付费端点 | ✅ 全市场 | ❌ | ❌ | 付费（以定价页为准） |
| pro | ✅ | ✅ 含盘口 | ✅ 分钟 K + 盘口 | ❌ | 付费（以定价页为准） |
| expert | ✅ | ✅ WebSocket | ✅ 全量分钟 | ✅ | 付费（以定价页为准） |
tick-stock-panel 的六类数据集，各自要求什么字段？
自定义数据源只需满足六类集中你真正提供的那几类，不存在的集不要写。深度盘口目前没有自定义契约，这一点官方写得很明确。
| 数据集（配置名） | 必填字段 | 请求约定 | 常见误区 |
|---|---|---|---|
日 K daily | symbol / date / OHLC / volume / amount | POST 发 JSON body：symbols、start_time、end_time；按 batch 切分标的 | 把复权后价格当不复权传入，会与系统自己的前复权叠加 |
除权因子 adj_factor | symbol / trade_date / ex_factor | 同上，按 batch 切分 | 缺了这一集就没有前复权，指标与回测口径会与付费源不一致 |
实时行情 realtime | symbol / last_price / prev_close / OHLC / volume | 必须是全市场快照接口，不支持逐个 symbol 拉 | 当成单标接口来写，盘中增量会跑不起来 |
分钟 K minute | symbol / datetime / OHLC / volume / amount | GET 发 symbols=000001.SZ,600000.SH；可选 asset_type_param / freq_param | datetime 回 UTC 而非北京时间墙钟，分钟信号全错位 |
全量分钟 full_minute | 同 minute | 仅修复轮语义（当日窗口批量），节奏下限 60s | 把它当成能拉全量历史分钟；它只管当日增量落盘 |
财务 financial | symbol | 一个配置覆盖全部财务表，表名作为参数传给上游 | 字段由数据源决定；没映射出 symbol 就整表进不来 |
| 深度盘口 depth5 | —（无契约） | 目前不支持自定义源，仍由 TickFlow 提供 | 误以为六类之外还能接第七类 |
接一个自建数据源要走哪几步？
下面是官方联调流程的顺序，建议先用官方 mock 源把流程跑通再接真实接口。
把 YAML 放到运行数据目录
路径是 data/data_sources/*.yaml；Docker 部署下宿主目录会挂载为容器内 /app/data，也可用 DATA_DIR 覆盖。放错地方是最常见的「列表里没有 custom 源」原因。
写最小配置：name / auth / datasets
每个数据集至少要有 url、method、response_path、field_map；需要切批的加 batch，需要限速的加 rpm，日期格式不同就在 transforms 里用 parse_date(value, '%Y%m%d') 转。
在面板里重新加载
「设置 → 数据源」点「重新加载」，或调 POST /api/settings/data-sources/reload。注意这只是让配置生效，还没把数据源设为当前使用者。
用「试拉测试」先验证映射
试拉直接使用当前表单内容，新建或未保存的修改也能测。重点看三件事：行数是不是 0、必填字段是否报 missing mapped fields、日期列是不是全空。
官方 mock 源可以直接对拍
docs/examples/custom-data-source/ 提供了 mock_server.py 加 mock_source.yaml：本地起 mock 源后把配置拷到 data/data_sources/，就能先把「配置 → 映射 → 试拉」这一段跑通，再去接真实接口。
确认后再把数据集路由到该源
日 K / 除权因子 / 实时行情各自选一个源，可以完全混组合。路由完成后再跑一次盘后管道，看 enriched 表是否正常重算。
单位与鉴权约定：为什么未声明单位会被拒？
这是 tick-stock-panel 最值得学的一处设计：它不猜数值单位，而是要求源头声明。
| 字段 | 官方行为 | 为什么这样设计 |
|---|---|---|
change_pct / amplitude / turnover_rate 未声明单位 | 请求体里加 pct_unit: decimal；不声明时 change_pct 按截面中位数归一，amplitude / turnover_rate 直接置 None 并记 WARNING | 数值无法区分 0.05 是 0.05% 还是 5%，宁可拒写也不猜 |
| 上游返回百分数值 | 必须显式声明 pct_unit: percent，声明后三列无条件 ÷100 | 只能由源告诉系统，不能靠数值自动推断 |
已给某列配了 transforms | 视为你已接管该列单位，原样透传 | 避免“自动归一”与“手写转换”叠加造成双重换算 |
auth | 支持 none / bearer / header / query，Token 从 token_env 指定的环境变量或 .env 读 | Key 不落 YAML，避免误提交 |
timeout | 每个数据集单独配，默认 30 秒，可配范围 >0 且 ≤300 秒，对同步与试拉都生效 | 历史回补单次可能很慢，30 秒会被误判成数据源故障 |
| 出站请求标识 | 默认带 User-Agent: tsp/<版本> 与 X-TSP-Client: tick-stock-panel；自定义同名头优先 | 供对端识别来源，也方便你在上游日志里定位请求 |
历史回补怎么做？怎么防止当日数据污染整条历史？
这一段写给手里有历史数据、想接进来做因子与回测的人。
为什么需要历史回补
tick-stock-panel 里 timeseries 模式的表（如人气排行）默认只能从开启拉取之日逐日累积，而信号、因子与回测都需要按日对齐的历史序列。
开启方式：配一个日期参数名
在拉取配置里填 date_param（如 date），接口支持按日查询时，面板就会出现「历史回补」入口。
按本地交易日逐日请求并写分区
它会逐日发 ?date=YYYY-MM-DD 并写入对应分区，已有分区自动跳过（幂等），单次上限 120 天，单日失败不中断并逐项列出原因。
防污染契约：符合就写，不符合就拒
如果接口忽略了日期参数、直接返回当日数据，系统会以响应行的 date 字段校验，不符合就拒绝写入并计入失败清单。否则当日值会静默污染整个历史时序。
接口侧需要满足三个条件
传日期参数返回该日数据；无数据时返回空数组或 404（两者都视为该日无数据，计入 empty 跳过）；每行带 date 字段。不传参数时保持当日语义，以向后兼容旧接口。
回补完成后立即可用
落盘的历史数据会立即进入信号、因子与回测的按日对齐通道；不需要额外重算，也不需要改策略代码。
官方在限频上写了哪些操作纪律？
限颟不是小事：一旦触发，轻则当天数据缺口，重则影响整条回测链路的可信度。
| 能力 / 机制 | 官方行为 | 对使用者的含义 |
|---|---|---|
| 非路由数据集直连 | 龙虎榜、盘前风向标、交易日历等 fuyao 专有能力不进路由矩阵，由独立服务直连消费 | 这些数据无法用自定义源替代，没有 fuyao Key 时相应页面会给引导提示 |
| 缓存策略 | 按日 JSON 缓存（历史不可变），交易日回退，四态降级 | 历史数据不会因为重启变化；但当日数据不缓存，刷新就是重拉 |
| 幂等写入 | unique(symbol, datetime) 幂等合并，分钟与盘后同写一个分区不冲突 | 重复跑盘后管道不会产生重复行 |
| 令牌桶限流 | 适配各档位 rpm / batch，批量合并 + 增量拉取 | 不用自己算限频，但也不能无限制并发跑大批量同步 |
| 进程内安全系数 0.8 | 实际发送 rpm 为名义值 × 0.8（向下取整），但它只管单个 Python 进程 | 多容器 / 多进程共用一个账号时，理论聚合使用率会超过 80%，官方的建议是错峰 |
| 错峰建议 | 盘中优先其他任务；大批量同步建议 16:00 之后；禁止全市场一年分钟一次性回填 | 官方文档直接把这三条写成操作纪律 |
| 429 与 fallback | 任一 429 / fallback 应记入证据链，禁止静默混源 | 混源会让同一策略在不同日期用不同数据源，回测结果就不可信了 |
tick-stock-panel 接数据源失败，常见原因有哪些？
下表是官方文档里明确给出的现象与处理，加上本站从契约推出的几条易错项。
| 现象 | 可能原因 | 处理 |
|---|---|---|
| 列表里没有自建源 | YAML 没放在 data/data_sources/，或没点重新加载 | 检查路径（注意 Docker 下宿主目录才是宿主目录）→ 重新加载 → 刷新页面 |
| errors 报 missing mapped fields | field_map 没映射到必填内部字段 | 对照本页数据集契约表，把缺的字段补上 |
| 试拉 rows 为 0 | response_path 没指到数组 | 先看原始返回的结构，把路径写成 data.list 这种形式 |
| 日期列全为空 | parse_date 的格式与返回值不一致 | 比如返回 20260828 就要用 '%Y%m%d' |
| 实时行情不刷新 | 实时源未保存为 custom，或接口不是全市场快照 | 确认数据源选择已保存为自建源；单标接口无法做盘中企稳增量 |
| 分钟信号全部不触发 | datetime 返回的是 UTC 而非北京时间墙钟 | 修正源端时区；系统会纠偏特征帧，但契约仍要求源头写对 |
| 盘中拉数报 429 | 同一账号下多个进程并发，放大了实际 rpm | 减少并发；把大批量同步措到 16:00 后 |
| 换源后选股结果变了 | 两个源的复权口径或字段单位不同 | 先比除权因子与单位声明，再比同一天的 enriched 值 |
能力路由与数据源常见问题
以下答案基于官方仓库与文档的核验结果；涉及版本、数据源口径与许可条款的内容一律以官方仓库与官方文档为准。tick-stock-panel 不付费能用吗？
能用一部分。TICKFLOW_API_KEY 留空时处于 None 模式，通过 free-api 可用历史日 K（含批量），足够体验选股与回测主流程；当日数据在盘后 1-2 小时可用。实时行情、分钟 K、全量分钟与财务数据需要更高档位。具体档位权益与价格以 tickflow.org 定价页为准，本站不复制具体价格数字，也不用仓库内 tiers.yaml 自标为「推断」的限频数值当承诺。
能不能用自己的数据源，比如 Tushare？
可以，但要满足契约：你的服务负责取数与整理，系统只把返回结果映射成内部标准字段，然后复用现有存储、指标、enriched、策略与前端展示逻辑。日 K、除权因子、实时行情、分钟 K、全量分钟、财务六类里，你能提供哪几类就写哪几类，不存在的不要写。官方提供了 mock 源与试拉测试，可以先把流程跑通。
为什么我的涨跌幅数据被置空了？
因为 tick-stock-panel 不猜数值单位。上游若返回百分数值（如 3.66 表示 3.66%），必须在 realtime 数据集上显式声明 pct_unit: percent；未声明时 change_pct 会按截面中位数归一，而 amplitude 与 turnover_rate 直接置 None 并记一条 WARNING。这是有意为之的失败关闭：0.05 既可能是 0.05% 也可能是 5%，数值上无法区分，拼错一次就会误导整段回测。
换了数据源之后，选股与回测口径会变吗？
官方的设计目标就是「换源不换口径」：各数据集按源声明能力独立路由，指标与回测口径保持不变。但这只能保证系统侧的计算口径，不能保证两个源的原始数据本身一致——复权方式、成交额口径、停牌处理都可能不同。真要做对比实验，建议先比同一天的 enriched 值再比策略结果。
深度盘口能不能接自己的源？
目前不能。官方文档明确写着深度盘口（depth5）暂无数据集契约，仍由 TickFlow 提供，这是六类自定义数据集之外的例外。与它类似的还有龙虎榜、盘前风向标与交易日历，这些 fuyao 专有能力不进路由矩阵，而是由独立服务直连消费，没配 Key 时页面会给引导提示。
历史回补一次能回多久？有什么风险？
单次上限 120 天，按本地交易日逐日请求并写分区，已有分区会自动跳过（幂等，可重复执行），单日失败不中断并逐项列出原因。真正需要防的是污染：如果你的接口忽略了日期参数、永远返回当日数据，系统会校验响应行的 date 字段，不符合就拒绝写入并计入失败清单——否则当日值会静默污染整个历史时序。
tick-stock-panel 的 stock-sdk 插件为什么默认不可用？
因为合规原因。官方在 Dockerfile 与部署文档里写明：stock-sdk 本质是抓取第三方财经网站（如东方财富）的行情接口，未经对方授权，可能违反服务条款并涉及交易所行情版权，因此默认 INCLUDE_STOCKSDK=0，镜像里不包含它。确需启用需自己构建时传 --build-arg INCLUDE_STOCKSDK=1，并自行承担合规责任。官方建议优先使用正规授权数据源。