market_sync/docs/DATASETS_AND_SOURCES.md

数据集与数据源依赖说明

本文档列出项目同步的全部数据集、各数据集依赖的数据源及优先级， 以及数据集之间的上下游依赖关系。

---

一、数据集总览

项目目前定义 12 个同步数据集，按类型分为原始源（依赖外部 API）和衍生源（本地计算）。

1.1 原始源

数据集 ID	目标表	说明	数据源与优先级
stock_basic	market_data.stocks	全市场 A 股代码/名称/交易所/上市状态 + 股本快照（雪球）	Baostock query_stock_basic（主）→ 麦蕊 /hslt/list（备）
kline_daily	market_data.kline_stock	全市场日 K OHLCV	QMT Bridge /kline?period=1d（主）→ 麦蕊 hsstock/history/*/d/n → 雪球 kline → 新浪 getKLineData，per-stock 逐级 fallback
kline_index	market_data.kline_index + indices	上证/深证/创业板/沪深300/中证500/中证1000 日线	QMT Bridge /kline?period=1d（主）→ 麦蕊 hsindex/history → 新浪 指数日 K
kline_5min	market_data.kline_5min	全市场 5 分钟 K 线	QMT Bridge /kline?period=5m（主）→ 麦蕊 hsstock/history/*/5/n（备）
tick_trade	market_data.tick_trade	当天逐笔成交（每日 21:00 发布）	麦蕊 hsrl/zbjy（唯一）
moneyflow	market_data.moneyflow	个股资金流（每日 21:30 发布，21:35 触发）	麦蕊 hsstock/history/transaction（唯一）
longhubang	market_data.longhubang_daily + longhubang_seat	龙虎榜聚合层 + 席位层（每日 22:00 触发）	akshare stock_lhb_detail_em + stock_lhb_stock_detail_em（东方财富封装，无替代源）
stock_node	market_data.node_categories + nodes + stock_node_map	股票-指数/行业/概念映射（每周六 11:30）	麦蕊 /hszg/{list,gg,zg}（唯一）
mairui_indicators	market_data.kline_stock_macd_daily + kdj_daily + boll_daily	MACD/KDJ/BOLL 日频技术指标（每日 16:40 增量）	麦蕊 /hsstock/history/{macd,kdj,boll}/{symbol}/d/n（唯一）
share_snapshot	market_data.stocks.total_share/float_share + share 表	全市场股本快照（雪球 quote_detail，需 XUEQIU_TOKEN）	雪球 quote_detail（唯一）

1.2 衍生源（本地计算，无外部接口）

数据集 ID	目标表	说明	上游依赖
market_regime	market_data.market_regime_daily	涨跌家数 / advance_ratio / 恐慌标记	kline_daily（本地 kline_stock 聚合）
mairui_ma_daily	market_data.kline_stock_ma_daily	MA5/10/20/60 均线	kline_daily（本地 kline_stock.close 计算）

注：mairui_ma_daily 本可走麦蕊 /hsdata 端点，但免费 licence 返回"数据不存在"，故改为本地计算。

---

二、数据源总览

项目注册了 6 个数据源，各有 credential 要求和提供的能力。

数据源 Key	名称	需凭证	提供能力	特性
datasource_qmt_bridge	QMT Bridge（本地行情桥）	否	kline_daily, kline_5min, index_daily	本地 xtquant HTTP 桥，免限速，低延迟，局域网
datasource_mairui	麦蕊智数（mairui.club）	需 MAIRUI_LICENCE	kline_daily, kline_5min, index_daily, stock_basic, moneyflow, tick_trade, stock_node, indicator_daily	数据最全，免费 licence 1 分钟 300 次
datasource_xinlang	新浪财经	否	kline_daily, index_daily	免费，RPS 3/s 限流
datasource_baostock	Baostock	否	kline_daily, stock_basic, industry	免费，基础信息 + 行业映射
datasource_xueqiu	雪球	需 XUEQIU_TOKEN	kline_daily, share	股本快照 + K 线复核
datasource_akshare_lhb	akshare 龙虎榜（东方财富）	否	longhubang_daily, longhubang_seat	龙虎榜唯一源

---

三、数据依赖关系

3.1 依赖拓扑图

stock_basic (Baostock + 雪球)
├── kline_daily (QMT Bridge → 麦蕊 → 雪球 → 新浪)
│   ├── market_regime (衍生：本地 kline_stock 聚合)
│   └── mairui_ma_daily (衍生：本地 kline_stock.close 计算)
├── kline_5min (QMT Bridge → 麦蕊)
├── tick_trade (麦蕊)
├── moneyflow (麦蕊)
├── longhubang (akshare/东财)
├── stock_node (麦蕊)
└── share_snapshot (雪球)

kline_index (QMT Bridge → 麦蕊 → 新浪) — 独立，无上游依赖

3.2 依赖表

数据集	直接上游依赖	依赖说明
stock_basic	无	根任务，提供股票代码列表
kline_daily	stock_basic	依赖股票列表决定拉取范围
kline_index	无	独立运行，不依赖股票列表
kline_5min	stock_basic	依赖股票列表决定拉取范围
tick_trade	stock_basic	同上
moneyflow	stock_basic	同上
longhubang	stock_basic	同上
stock_node	stock_basic	同上
mairui_indicators	stock_basic	同上
share_snapshot	stock_basic	同上
market_regime	kline_daily	需 kline_stock 数据完整
mairui_ma_daily	kline_daily	需 kline_stock.close 数据完整

---

四、默认调度时间（工作日）

时间	数据集	备注
09:00	stock_basic	开盘前刷新
15:30	kline_index	指数日线
15:40	kline_daily	个股日线
16:00	kline_5min	5 分钟线
15:15	market_regime	市场情绪
16:30	mairui_ma_daily	MA 均线
16:40	mairui_indicators	MACD/KDJ/BOLL
21:35	moneyflow	资金流（等 21:30 发布）
22:00	longhubang	龙虎榜
周六 11:30	stock_node	节点映射
周六 11:30	share_snapshot	股本快照（周度）

---

五、数据回填级联规则

上游数据被回填或修复后，下游依赖它的衍生数据集必须手动/自动重跑， 否则会出现"上游新、下游旧"的不一致。

上游任务/表	触发条件	必须重跑的下游任务
kline_daily / kline_stock	回填历史 K 线、修复错误日线、补充漏掉的股票/日期	market_regime、mairui_ma_daily
stock_basic / stocks	新上市/退市、代码变更、上市状态修正	kline_daily、kline_5min、tick_trade、moneyflow、longhubang、stock_node、share_snapshot
kline_stock（任意核心字段修复）	close/volume 等核心字段修正	market_regime、mairui_ma_daily

操作建议：

• 单次少量回填（如几只股票、几天）：用 CLI 参数指定 codes / start / end，然后按上表手动触发下游。
• 大量回填（如全市场、多月/多年历史）：先跑上游，再按依赖链顺序跑下游；必要时禁用当日独立 timer，避免与 runall 并发。
• 每日巡检 bin/daily_sync_check.py 已增加数据一致性检查：对比 kline_stock 与 kline_stock_ma_daily、market_regime_daily 的最新日期与缺失行数，发现缺口即告警。

---

六、数据源降级策略

各同步任务在代码中定义了具体的降级逻辑：

任务	降级链	降级触发条件
kline_daily	QMT Bridge → 麦蕊 → 雪球 → 新浪	per-stock 逐级 fallback，雪球失败自动降级到麦蕊/新浪
kline_index	QMT Bridge → 麦蕊 → 新浪	选第一个 is_source_ready 通过的源
kline_5min	QMT Bridge → 麦蕊	bridge 不可用时检查 mairui 是否就绪
tick_trade	仅麦蕊	外层 FETCH_HARD_TIMEOUT=120s 防止永久挂起
moneyflow	仅麦蕊	唯一源
longhubang	仅 akshare	唯一源，无替代
stock_node	仅麦蕊	唯一源
stock_basic	Baostock（主）→ 麦蕊（备）	Baostock 失败时切换
mairui_indicators	仅麦蕊	唯一源

---

七、数据源健康检查

系统通过 app/core/datasource/registry.py 维护数据源健康状态：

• 周期检查：后台线程每 30 分钟对所有注册数据源执行一次 health_check()。
• is_source_ready()：综合判断凭证是否配置 + is_available() 是否通过 + 最近健康检查是否成功，返回 (bool, reason)。
• pick_source(capability)：遍历注册表，返回第一个 is_source_ready() 通过且提供该能力的数据源。