# 数据集与数据源依赖说明

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

---

## 一、数据集总览

项目目前定义 **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()` 通过且提供该能力的数据源。