xiaobai-review/xiaobai-datahub/datahub/source_catalog.py

"""Minimal, read-only source directory (HEL-543).

Registers what already exists: providers, their concrete interfaces, what
capability/dataset each interface serves, and whether the provider plays a
primary or backup role. This module only *describes* the current adapters
and datasets already wired in `datahub/hub.py`, `datahub/serving.py`, and
`datahub/realtime_serve.py`; it does not add a way to configure or add a new
source without code, and it never changes routing, retries, or fallback
order.

Every ``interfaces`` entry below is a docs-as-code mirror of a real call
site, cross-referenced in comments so a reviewer can verify each row is
accurate rather than aspirational:

- tushare interfaces mirror ``datahub/serving.py``'s ``_official_meta``/``source=``
  strings and ``datahub/steward.py``'s live/published dataset table.
- eastmoney/tencent interfaces mirror the ``observability.observe(...)``
  call sites added in ``datahub/realtime_serve.py`` for HEL-543.
- ifind interfaces mirror ``datahub/steward.py``'s ``IFIND_APIS`` table.
"""

from __future__ import annotations

from typing import Any

CATALOG: list[dict[str, Any]] = [
    {
        "provider": "tushare",
        "label": "Tushare",
        "role": "official_primary",
        "credential_key": "tushare_token",
        "status_source": "src_health (legacy, kept) + provider_health (unified, HEL-543)",
        "interfaces": [
            {"interface": "trade_cal", "capability": "交易日历", "datasets": ["calendar"]},
            {"interface": "stock_basic", "capability": "股票主档", "datasets": ["stocks"]},
            {"interface": "daily", "capability": "个股日K", "datasets": ["daily"]},
            {"interface": "adj_factor", "capability": "复权因子", "datasets": ["daily"]},
            {"interface": "daily_basic", "capability": "估值", "datasets": ["valuation"]},
            {"interface": "index_daily", "capability": "指数日K", "datasets": ["index_daily"]},
            {"interface": "moneyflow", "capability": "资金流", "datasets": ["moneyflow"]},
            {"interface": "stk_auction", "capability": "集合竞价", "datasets": ["auction"]},
            {"interface": "limit_list_d", "capability": "涨跌停池", "datasets": ["limit_events"]},
            {"interface": "ths_hot", "capability": "同花顺人气榜", "datasets": ["popularity"]},
            {"interface": "dc_hot", "capability": "东方财富人气榜", "datasets": ["popularity"]},
            {"interface": "hm_detail", "capability": "龙虎榜游资明细", "datasets": ["dragon_tiger"]},
            {"interface": "ths_daily", "capability": "同花顺概念行情", "datasets": ["sector_daily"]},
            {"interface": "dc_index", "capability": "东方财富板块行情", "datasets": ["sector_daily"]},
            {"interface": "sw_daily", "capability": "申万行业行情", "datasets": ["sector_daily"]},
        ],
    },
    {
        "provider": "eastmoney",
        "label": "东方财富",
        "role": "provisional_primary",
        "credential_key": None,
        "status_source": "provider_health (unified, HEL-543)",
        "interfaces": [
            {"interface": "indices", "capability": "指数实时报价", "datasets": ["index_quotes"]},
            {"interface": "market_quotes", "capability": "全市场实时快照", "datasets": ["quotes_latest"]},
            {"interface": "named_quotes", "capability": "指定个股实时报价", "datasets": ["quotes_latest"]},
            {"interface": "sector_quote", "capability": "申万板块实时报价(单个)", "datasets": ["sectors_quote"]},
            {"interface": "sector_quotes_batch", "capability": "申万板块批量报价(预热)", "datasets": ["sectors_quote"]},
            {"interface": "limit_pool", "capability": "涨停/炸板池(盘中)", "datasets": ["limit_pool"]},
            {"interface": "intraday", "capability": "分时走势", "datasets": ["intraday_points"]},
        ],
    },
    {
        "provider": "tencent",
        "label": "腾讯行情",
        "role": "provisional_backup",
        "credential_key": None,
        "status_source": "provider_health (unified, HEL-543)",
        "interfaces": [
            {"interface": "indices", "capability": "指数实时报价(东财失败时备用)", "datasets": ["index_quotes"]},
            {
                "interface": "market_quotes_fallback",
                "capability": "全市场快照(备用；按本地股票主档逐只请求拼接)",
                "datasets": ["quotes_latest"],
            },
            {"interface": "named_quotes", "capability": "指定个股实时报价(东财失败时备用)", "datasets": ["quotes_latest"]},
        ],
    },
    {
        "provider": "ifind",
        "label": "同花顺 iFinD",
        "role": "licensed_optional",
        "credential_key": "ifind_refresh_token",
        "status_source": "provider_health (unified, HEL-543) + adapter.status()",
        "interfaces": [
            {"interface": "wencai", "capability": "问财自然语言选股", "datasets": ["ifind_wencai"]},
            {"interface": "snapshots", "capability": "快照", "datasets": ["ifind_snapshots"]},
            {"interface": "history", "capability": "历史行情", "datasets": ["ifind_history"]},
            {"interface": "realtime", "capability": "实时行情", "datasets": ["ifind_realtime"]},
            {"interface": "intraday", "capability": "分时(高频)", "datasets": ["ifind_intraday"]},
        ],
    },
    {
        "provider": "ths",
        "label": "同花顺(预留)",
        "role": "reserved",
        "credential_key": None,
        "status_source": "adapter.probe()（占位，本阶段未接入真实数据）",
        "interfaces": [],
    },
    {
        "provider": "xgb",
        "label": "选股宝(预留)",
        "role": "reserved",
        "credential_key": None,
        "status_source": "adapter.probe()（占位，本阶段未接入真实数据）",
        "interfaces": [],
    },
    {
        "provider": "akshare",
        "label": "AKShare(预留)",
        "role": "reserved",
        "credential_key": None,
        "status_source": "adapter.probe()（占位，本阶段未接入真实数据）",
        "interfaces": [],
    },
]


def snapshot(db: Any, auth: Any = None) -> list[dict[str, Any]]:
    """Merge the static catalog with live credential/health facts.

    Purely read-only: never touches routing, credentials, or adapters. Any
    failure while enriching one entry only degrades that entry's live data;
    it never drops the entry or raises, so a directory read can never break
    on a partially-unhealthy database.
    """
    result: list[dict[str, Any]] = []
    for entry in CATALOG:
        item: dict[str, Any] = {
            "provider": entry["provider"],
            "label": entry.get("label", entry["provider"]),
            "role": entry["role"],
            "status_source": entry["status_source"],
            "interfaces": [dict(i) for i in entry.get("interfaces", [])],
        }
        cred_key = entry.get("credential_key")
        if cred_key:
            cred = None
            try:
                if auth is not None:
                    cred = auth.credential_status(cred_key)
            except Exception:
                cred = None
            item["credential"] = cred or {"configured": False, "last4": "", "updated_at": ""}
        else:
            item["credential"] = {"configured": True, "last4": "", "updated_at": "", "note": "无需凭证"}
        health_rows: list[dict[str, Any]] = []
        try:
            if db is not None:
                health_rows = db.fetchall(
                    "SELECT interface, state, last_ok_at, last_error, last_fallback_reason, "
                    "consec_failures, last_latency_ms, last_data_age_seconds, updated_at "
                    "FROM provider_health WHERE provider = ? ORDER BY interface",
                    (entry["provider"],),
                )
        except Exception:
            health_rows = []
        item["live_interfaces"] = health_rows
        result.append(item)
    return result