@@ -0,0 +1 @@
|
||||
"""TickFlow 适配层 — 能力探测 / 调度 / Repository。"""
|
||||
@@ -0,0 +1,76 @@
|
||||
"""Capability 定义(§5.1)。
|
||||
|
||||
业务代码只依赖 CapabilitySet,不读 tiers.yaml,不感知"档位"。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
from dataclasses import dataclass
|
||||
from enum import StrEnum
|
||||
|
||||
|
||||
class Cap(StrEnum):
|
||||
"""所有 capability 的命名常量。新增能力时只在这里加一行。"""
|
||||
|
||||
QUOTE_BY_SYMBOL = "quote.by_symbol"
|
||||
QUOTE_BATCH = "quote.batch"
|
||||
QUOTE_POOL = "quote.pool"
|
||||
KLINE_DAILY_BY_SYMBOL = "kline.daily.by_symbol"
|
||||
KLINE_DAILY_BATCH = "kline.daily.batch"
|
||||
KLINE_MINUTE_BY_SYMBOL = "kline.minute.by_symbol"
|
||||
KLINE_MINUTE_BATCH = "kline.minute.batch"
|
||||
INTRADAY = "intraday"
|
||||
INTRADAY_BATCH = "intraday.batch"
|
||||
DEPTH5 = "depth5"
|
||||
DEPTH5_BATCH = "depth5.batch"
|
||||
WEBSOCKET = "websocket"
|
||||
FINANCIAL = "financial"
|
||||
ADJ_FACTOR = "adj_factor"
|
||||
|
||||
|
||||
@dataclass(slots=True, frozen=True)
|
||||
class CapabilityLimits:
|
||||
"""单个 capability 的运行时限制。"""
|
||||
rpm: int | None = None # 次/分钟,None 表示未知或不限
|
||||
batch: int | None = None # 标的/次
|
||||
subscribe: int | None = None # WS 订阅上限
|
||||
|
||||
|
||||
class CapabilitySet:
|
||||
"""探测得到的"用户当前可用能力"。业务代码的唯一真理源。"""
|
||||
|
||||
def __init__(self, caps: dict[Cap, CapabilityLimits] | None = None) -> None:
|
||||
self._caps: dict[Cap, CapabilityLimits] = dict(caps or {})
|
||||
|
||||
def has(self, cap: Cap) -> bool:
|
||||
return cap in self._caps
|
||||
|
||||
def limits(self, cap: Cap) -> CapabilityLimits | None:
|
||||
return self._caps.get(cap)
|
||||
|
||||
def require(self, cap: Cap) -> CapabilityLimits:
|
||||
"""断言可用,否则抛 CapabilityDenied。"""
|
||||
if cap not in self._caps:
|
||||
raise CapabilityDenied(cap)
|
||||
return self._caps[cap]
|
||||
|
||||
def all(self) -> dict[Cap, CapabilityLimits]:
|
||||
return dict(self._caps)
|
||||
|
||||
def to_dict(self) -> dict[str, dict]:
|
||||
return {
|
||||
str(cap): {
|
||||
"rpm": lim.rpm,
|
||||
"batch": lim.batch,
|
||||
"subscribe": lim.subscribe,
|
||||
}
|
||||
for cap, lim in self._caps.items()
|
||||
}
|
||||
|
||||
|
||||
class CapabilityDenied(Exception):
|
||||
"""请求的 capability 当前不可用。"""
|
||||
|
||||
def __init__(self, cap: Cap, suggestion: str | None = None) -> None:
|
||||
self.cap = cap
|
||||
self.suggestion = suggestion or f"加购『{cap}』能力可解锁"
|
||||
super().__init__(f"capability not available: {cap}; {self.suggestion}")
|
||||
@@ -0,0 +1,126 @@
|
||||
"""TickFlow SDK 封装(§5)。
|
||||
|
||||
进程内单例;Key 来源(优先级):secrets.json > .env。
|
||||
用户改 Key 后需要 `reset_clients()`,然后 `get_client()` 会拿新的。
|
||||
|
||||
5 档体系下服务器归属:
|
||||
- none 档(无 key / 无效 key) → TickFlow.free()(free-api 服务器)
|
||||
- free 档(免费有效 key) → TickFlow.free()(key 被 SDK 忽略,运行时走 free-api)
|
||||
- starter/pro/expert(付费 key) → TickFlow(api_key=key, base_url)
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
|
||||
from tickflow import AsyncTickFlow, TickFlow
|
||||
|
||||
from app import secrets_store
|
||||
|
||||
_sync_client: TickFlow | None = None
|
||||
_async_client: AsyncTickFlow | None = None
|
||||
_paid_realtime_client: TickFlow | None = None
|
||||
|
||||
|
||||
# ===== 服务器归属判定 =====
|
||||
|
||||
# free-api 服务器默认节点(SDK 默认值),none/free 档运行时走这里。
|
||||
FREE_ENDPOINT = "https://free-api.tickflow.org"
|
||||
# 付费端点默认节点(starter+ 运行时走这里,也是端点切换的默认值)。
|
||||
PAID_ENDPOINT = "https://api.tickflow.org"
|
||||
|
||||
|
||||
def _should_use_free_server() -> bool:
|
||||
"""是否应走 free-api 服务器。
|
||||
|
||||
判定依据:无 key,或当前档位为 none/free。
|
||||
付费档(starter+)走付费端点。
|
||||
"""
|
||||
if not secrets_store.get_tickflow_key():
|
||||
return True
|
||||
# 有 key 时按探测出的档位判定(避免读 capabilities.json 在首次启动前未生成的边界)
|
||||
from app.tickflow.policy import base_tier_name
|
||||
return base_tier_name() in ("none", "free")
|
||||
|
||||
|
||||
def _base_url() -> str | None:
|
||||
"""从 secrets.json 读取用户自定义端点,没有则返回 None(用 SDK 默认)。"""
|
||||
return secrets_store.load().get("tickflow_base_url") or None
|
||||
|
||||
|
||||
def get_client() -> TickFlow:
|
||||
"""同步客户端。能力探测、盘后管道用。"""
|
||||
global _sync_client
|
||||
if _sync_client is None:
|
||||
key = secrets_store.get_tickflow_key()
|
||||
if _should_use_free_server():
|
||||
# none/free 档:走 free-api 服务器(无 key 或免费 key 被 SDK 忽略)
|
||||
_sync_client = TickFlow.free()
|
||||
else:
|
||||
_sync_client = TickFlow(api_key=key, base_url=_base_url())
|
||||
return _sync_client
|
||||
|
||||
|
||||
def get_async_client() -> AsyncTickFlow:
|
||||
"""异步客户端。FastAPI 请求路径上用。"""
|
||||
global _async_client
|
||||
if _async_client is None:
|
||||
key = secrets_store.get_tickflow_key()
|
||||
if _should_use_free_server():
|
||||
_async_client = AsyncTickFlow.free()
|
||||
else:
|
||||
_async_client = AsyncTickFlow(api_key=key, base_url=_base_url())
|
||||
return _async_client
|
||||
|
||||
|
||||
def get_paid_realtime_client() -> TickFlow | None:
|
||||
"""实时行情专用付费服务器客户端。
|
||||
|
||||
none/free 的历史日K仍走 get_client() 的 free-api；实时行情全部走付费服务器。
|
||||
Free 档如果有有效 key，也使用这里的 paid endpoint 调按标的实时接口。
|
||||
"""
|
||||
global _paid_realtime_client
|
||||
key = secrets_store.get_tickflow_key()
|
||||
if not key:
|
||||
return None
|
||||
if _paid_realtime_client is None:
|
||||
_paid_realtime_client = TickFlow(api_key=key, base_url=_base_url())
|
||||
return _paid_realtime_client
|
||||
|
||||
|
||||
def reset_clients() -> None:
|
||||
"""Key 变化后调用 — 让下一次 get_client() 拿新实例。"""
|
||||
global _sync_client, _async_client, _paid_realtime_client
|
||||
_sync_client = None
|
||||
_async_client = None
|
||||
_paid_realtime_client = None
|
||||
|
||||
|
||||
def current_mode() -> str:
|
||||
"""供 UI 显示当前模式。三态:
|
||||
|
||||
- "none" : 无 key / 无效 key(走 free-api,仅历史日K)
|
||||
- "free" : 免费有效 key(走 free-api,仅历史日K)
|
||||
- "api_key" : 付费 key(starter+,走付费端点,有实时行情)
|
||||
"""
|
||||
if not secrets_store.get_tickflow_key():
|
||||
return "none"
|
||||
from app.tickflow.policy import base_tier_name
|
||||
tier = base_tier_name()
|
||||
if tier in ("none", "free"):
|
||||
return "free" if tier == "free" else "none"
|
||||
return "api_key"
|
||||
|
||||
|
||||
def current_endpoint() -> str:
|
||||
"""返回当前显示用的端点 URL(对应 endpoints.json 列表项)。
|
||||
|
||||
- none/free 档:显示 free-api 服务器节点
|
||||
- 付费档:显示用户自定义端点(测速切换后)或默认付费节点 api.tickflow.org
|
||||
"""
|
||||
if _should_use_free_server():
|
||||
return FREE_ENDPOINT
|
||||
# 自定义端点(付费模式测速切换后):优先返回
|
||||
base = _base_url()
|
||||
if base:
|
||||
return base.rstrip("/")
|
||||
return PAID_ENDPOINT
|
||||
@@ -0,0 +1,549 @@
|
||||
"""能力探测 + CapabilitySet 持久化(§5.3)。
|
||||
|
||||
探测策略:逐 capability 用最小代价请求试探。
|
||||
- 成功 → 记录可用,优先取响应头 X-RateLimit-* 否则用 tiers.yaml 默认
|
||||
- 抛权限错 → 不可用
|
||||
- 抛其他错 → 不可用(谨慎,保留日志)
|
||||
|
||||
Tier Label 算法见 §5.3:基线档 + 补丁能力。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import json
|
||||
import logging
|
||||
import time
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
import yaml
|
||||
|
||||
from app.config import settings
|
||||
from app import secrets_store
|
||||
|
||||
from .capabilities import Cap, CapabilityLimits, CapabilitySet
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
_CAPSET_CACHE_FILE = "capabilities.json"
|
||||
|
||||
# 缓存 schema 版本。capabilities 模型有结构性变更时 bump(如新增/拆分 Cap),
|
||||
# 旧缓存(无此字段或版本更低)会被判定过期,触发重新探测。
|
||||
# v2: 拆分 depth5 → depth5(单只) + depth5.batch(批量)
|
||||
# v3: 探测补全 quote.batch(此前 tiers.yaml 声明了但 _probe_real 漏探测)
|
||||
# v5: Free 档补充付费服务器 quote.by_symbol(10rpm/5标的),用于自选股实时监控。
|
||||
_CACHE_SCHEMA_VERSION = 5
|
||||
|
||||
# 探测用最小代价请求:挑流通性最好的 1 只标的试
|
||||
_PROBE_SYMBOL = "600000.SH" # 浦发银行,长期不会退市
|
||||
|
||||
|
||||
def _load_tiers_yaml() -> dict[str, dict[str, dict[str, Any]]]:
|
||||
for path in [settings.tiers_yaml, Path("/app/tiers.yaml"), Path("../tiers.yaml")]:
|
||||
if path.exists():
|
||||
with path.open(encoding="utf-8") as f:
|
||||
return yaml.safe_load(f)
|
||||
raise FileNotFoundError("tiers.yaml not found")
|
||||
|
||||
|
||||
def _tier_to_capset(tier_def: dict[str, dict[str, Any]]) -> CapabilitySet:
|
||||
caps: dict[Cap, CapabilityLimits] = {}
|
||||
for cap_name, limits_dict in tier_def.items():
|
||||
try:
|
||||
cap = Cap(cap_name)
|
||||
except ValueError:
|
||||
logger.warning("unknown cap in tiers.yaml: %s", cap_name)
|
||||
continue
|
||||
caps[cap] = CapabilityLimits(
|
||||
rpm=limits_dict.get("rpm"),
|
||||
batch=limits_dict.get("batch"),
|
||||
subscribe=limits_dict.get("subscribe"),
|
||||
)
|
||||
return CapabilitySet(caps)
|
||||
|
||||
|
||||
def _is_transient(e: Exception) -> bool:
|
||||
"""是否为"可重试的瞬时错误"——网络抖动 / 限流 / 服务端 5xx。
|
||||
|
||||
与权限/参数错误(403/401/400/404)区分:后者重试也无用,不重试。
|
||||
用类名匹配而非 import SDK 异常,避免探测期对 SDK 内部耦合。
|
||||
"""
|
||||
cls = e.__class__.__name__
|
||||
if cls in {
|
||||
"RateLimitError", "InternalServerError", "APIError",
|
||||
"ConnectionError", "TimeoutError", "ConnectError",
|
||||
"ConnectTimeout", "ReadTimeout", "RemoteProtocolError",
|
||||
"httpx.ConnectError", "httpx.TimeoutException",
|
||||
}:
|
||||
return True
|
||||
# APIError 体系下,status_code 5xx/429 视为瞬时
|
||||
status = getattr(e, "status_code", None)
|
||||
if isinstance(status, int) and (status == 429 or status >= 500):
|
||||
return True
|
||||
return False
|
||||
|
||||
|
||||
def _call_with_retry(fn, attempts: int = 3, backoff: float = 0.6) -> None:
|
||||
"""调用 fn();对瞬时错误退避重试,权限/参数错误立即抛出。
|
||||
|
||||
attempts=总尝试次数(含首次)。返回 None,异常由调用方分类。
|
||||
"""
|
||||
last_exc: Exception | None = None
|
||||
for i in range(attempts):
|
||||
try:
|
||||
fn()
|
||||
return
|
||||
except Exception as e: # noqa: BLE001
|
||||
last_exc = e
|
||||
# 权限/参数类错误:重试无意义,立即抛出交给 try_call 归类
|
||||
if not _is_transient(e):
|
||||
raise
|
||||
# 瞬时错误:最后一轮不再 sleep
|
||||
if i < attempts - 1:
|
||||
time.sleep(backoff * (i + 1))
|
||||
# 重试耗尽,抛出最后一次异常
|
||||
assert last_exc is not None
|
||||
raise last_exc
|
||||
|
||||
|
||||
def _probe_real(tiers: dict) -> tuple[CapabilitySet, list[str]]:
|
||||
"""逐 capability 试探。需要 API key。
|
||||
|
||||
**关键**:探测始终在付费端点(api.tickflow.org)上进行,用 key 鉴权验证有效性。
|
||||
绝不能读旧 capabilities 缓存的档位来选服务器 —— 否则首次保存 key 时,
|
||||
旧缓存是 none 档 → get_client() 返回 free 服务器 → free 服务器忽略 key →
|
||||
乱填 key 也能拿到日K → 误判成 free 档(鸡生蛋蛋生鸡的循环依赖 bug)。
|
||||
|
||||
返回 (capset, probe_log)。
|
||||
"""
|
||||
from tickflow import TickFlow
|
||||
from .client import _base_url, PAID_ENDPOINT
|
||||
|
||||
key = secrets_store.get_tickflow_key()
|
||||
# 探测专用客户端:强制走付费端点验证 key。
|
||||
# base_url 用用户自定义端点(若已配置测速切换),否则默认 api.tickflow.org。
|
||||
probe_base = _base_url() or PAID_ENDPOINT
|
||||
tf = TickFlow(api_key=key, base_url=probe_base)
|
||||
available: dict[Cap, CapabilityLimits] = {}
|
||||
log: list[str] = []
|
||||
|
||||
def try_call(cap: Cap, fn, default_limits: dict[str, Any]) -> None:
|
||||
try:
|
||||
_call_with_retry(fn)
|
||||
available[cap] = CapabilityLimits(
|
||||
rpm=default_limits.get("rpm"),
|
||||
batch=default_limits.get("batch"),
|
||||
subscribe=default_limits.get("subscribe"),
|
||||
)
|
||||
log.append(f"✓ {cap}")
|
||||
except Exception as e: # noqa: BLE001
|
||||
msg = str(e).lower()
|
||||
cls = e.__class__.__name__
|
||||
# PermissionError 类名 / HTTP 403 / 中英文权限关键词都算"明确无权限"
|
||||
is_perm_denied = (
|
||||
cls in {"PermissionError", "AuthorizationError"}
|
||||
or "permission" in msg or "unauthorized" in msg
|
||||
or "403" in msg or "forbidden" in msg
|
||||
or "套餐" in msg or "权限" in msg or "需要" in msg
|
||||
)
|
||||
if is_perm_denied:
|
||||
log.append(f"✗ {cap}(无权限)")
|
||||
else:
|
||||
# 重试耗尽仍失败的瞬时错误 — 标记为疑似,而非直接判定"无此能力"
|
||||
log.append(f"? {cap} ({cls}: {e})")
|
||||
|
||||
# 用各档默认上限作为占位(无 X-RateLimit-* 头时)
|
||||
# 取所有档的并集,逐 cap 试探
|
||||
all_caps_defaults: dict[str, dict[str, Any]] = {}
|
||||
for tier in ("free", "starter", "pro", "expert"):
|
||||
for cap_name, lim in tiers.get(tier, {}).items():
|
||||
all_caps_defaults.setdefault(cap_name, lim)
|
||||
|
||||
def defaults(cap: Cap) -> dict[str, Any]:
|
||||
return all_caps_defaults.get(str(cap), {})
|
||||
|
||||
# 全部用 keyword-only 形式调用,符合 SDK 真实签名
|
||||
# quote.by_symbol
|
||||
try_call(Cap.QUOTE_BY_SYMBOL,
|
||||
lambda: tf.quotes.get(symbols=[_PROBE_SYMBOL], as_dataframe=False),
|
||||
defaults(Cap.QUOTE_BY_SYMBOL))
|
||||
|
||||
# quote.batch — 批量行情(POST /v1/quotes)。用 get_by_symbols 试探。
|
||||
try_call(Cap.QUOTE_BATCH,
|
||||
lambda: tf.quotes.get_by_symbols([_PROBE_SYMBOL], as_dataframe=False),
|
||||
defaults(Cap.QUOTE_BATCH))
|
||||
|
||||
# quote.pool — 用一个真实存在的 universe id 试探。
|
||||
# universes.list() 在 Free 也开放,先拿任意一个 universe id 再用 get_by_universes 试。
|
||||
def _probe_pool():
|
||||
unis = tf.universes.list()
|
||||
if not unis:
|
||||
raise RuntimeError("no universes available")
|
||||
first_id = unis[0]["id"] if isinstance(unis[0], dict) else getattr(unis[0], "id")
|
||||
return tf.quotes.get_by_universes([first_id], as_dataframe=False)
|
||||
|
||||
try_call(Cap.QUOTE_POOL, _probe_pool, defaults(Cap.QUOTE_POOL))
|
||||
|
||||
# kline.daily.by_symbol — Free 也有
|
||||
try_call(Cap.KLINE_DAILY_BY_SYMBOL,
|
||||
lambda: tf.klines.get(_PROBE_SYMBOL, period="1d", count=1, as_dataframe=False),
|
||||
defaults(Cap.KLINE_DAILY_BY_SYMBOL))
|
||||
|
||||
# kline.daily.batch
|
||||
try_call(Cap.KLINE_DAILY_BATCH,
|
||||
lambda: tf.klines.batch([_PROBE_SYMBOL], period="1d", count=1, as_dataframe=False),
|
||||
defaults(Cap.KLINE_DAILY_BATCH))
|
||||
|
||||
# kline.minute.by_symbol
|
||||
try_call(Cap.KLINE_MINUTE_BY_SYMBOL,
|
||||
lambda: tf.klines.get(_PROBE_SYMBOL, period="1m", count=1, as_dataframe=False),
|
||||
defaults(Cap.KLINE_MINUTE_BY_SYMBOL))
|
||||
|
||||
# kline.minute.batch
|
||||
try_call(Cap.KLINE_MINUTE_BATCH,
|
||||
lambda: tf.klines.batch([_PROBE_SYMBOL], period="1m", count=1, as_dataframe=False),
|
||||
defaults(Cap.KLINE_MINUTE_BATCH))
|
||||
|
||||
# intraday
|
||||
try_call(Cap.INTRADAY,
|
||||
lambda: tf.klines.intraday(_PROBE_SYMBOL, count=1, as_dataframe=False),
|
||||
defaults(Cap.INTRADAY))
|
||||
|
||||
# intraday.batch
|
||||
try_call(Cap.INTRADAY_BATCH,
|
||||
lambda: tf.klines.intraday_batch([_PROBE_SYMBOL], count=1, as_dataframe=False),
|
||||
defaults(Cap.INTRADAY_BATCH))
|
||||
|
||||
# depth5 — 按标的查(单只)
|
||||
try_call(Cap.DEPTH5,
|
||||
lambda: tf.depth.get(_PROBE_SYMBOL),
|
||||
defaults(Cap.DEPTH5))
|
||||
|
||||
# depth5.batch — 批量查(SDK 0.1.23+ 提供 depth.batch,对应官方 /v1/depth/batch 端点)
|
||||
try_call(Cap.DEPTH5_BATCH,
|
||||
lambda: tf.depth.batch([_PROBE_SYMBOL]),
|
||||
defaults(Cap.DEPTH5_BATCH))
|
||||
|
||||
# financial — SDK 提供 income / balance_sheet / cash_flow / metrics / shares
|
||||
# 用 metrics 探测(单据最小)
|
||||
try_call(Cap.FINANCIAL,
|
||||
lambda: tf.financials.metrics([_PROBE_SYMBOL], latest=True, as_dataframe=False),
|
||||
defaults(Cap.FINANCIAL))
|
||||
|
||||
# adj_factor — 实际在 klines.ex_factors
|
||||
try_call(Cap.ADJ_FACTOR,
|
||||
lambda: tf.klines.ex_factors([_PROBE_SYMBOL], as_dataframe=False),
|
||||
defaults(Cap.ADJ_FACTOR))
|
||||
|
||||
# websocket 不在探测期试连接(成本太高且阻塞),按档位默认推断
|
||||
# 若 expert 的其他 cap 都通,则推断 websocket 也可用
|
||||
if (Cap.FINANCIAL in available and Cap.INTRADAY_BATCH in available):
|
||||
available[Cap.WEBSOCKET] = CapabilityLimits(
|
||||
subscribe=defaults(Cap.WEBSOCKET).get("subscribe", 100),
|
||||
)
|
||||
log.append("✓ websocket (inferred from expert tier)")
|
||||
|
||||
return CapabilitySet(available), log
|
||||
|
||||
|
||||
def detect_capabilities(force: bool = False) -> CapabilitySet:
|
||||
"""探测当前 API Key 的能力集。"""
|
||||
cache_path = settings.data_dir / _CAPSET_CACHE_FILE
|
||||
if not force and cache_path.exists():
|
||||
with cache_path.open(encoding="utf-8") as f:
|
||||
cached = json.load(f)
|
||||
# schema 版本校验:旧缓存或缺版本号 → 过期,丢弃后重新探测
|
||||
if cached.get("schema_version") == _CACHE_SCHEMA_VERSION:
|
||||
return _capset_from_json(cached)
|
||||
logger.info("capabilities 缓存 schema 版本过期(缓存=%s, 当前=%d), 重新探测",
|
||||
cached.get("schema_version"), _CACHE_SCHEMA_VERSION)
|
||||
|
||||
tiers = _load_tiers_yaml()
|
||||
if settings.use_free_mode:
|
||||
# 无 key —— 归 none 档(走 free-api 服务器,仅历史日K)
|
||||
capset = _tier_to_capset(tiers["none"])
|
||||
_persist(capset, "None", log=["无 API Key(无档 · free-api 服务器)"], missing=[], extras=[])
|
||||
return capset
|
||||
|
||||
# 有 API key — 真实探测
|
||||
try:
|
||||
capset, probe_log = _probe_real(tiers)
|
||||
# 判定档位:无效 key → none,免费 key → free,付费 → starter/pro/expert
|
||||
classified = _classify_tier(capset, tiers)
|
||||
if classified.is_invalid:
|
||||
# 无效 key(连单只日K都拿不到):归 none 档,标记要求清除 key
|
||||
capset = _tier_to_capset(tiers["none"])
|
||||
probe_log.append("⚠ Key 无效(单只日K也无法获取),判定为无档")
|
||||
_persist(capset, "None", log=probe_log, missing=[], extras=[], invalid_key=True)
|
||||
return capset
|
||||
if classified.is_free:
|
||||
# 免费有效 key:按 free 档能力持久化(日K free-api + 按标的实时)。
|
||||
capset = _tier_to_capset(tiers["free"])
|
||||
_persist(capset, "Free", log=probe_log + ["✓ 免费有效 key(运行时走 free-api 服务器)"], missing=[], extras=[])
|
||||
return capset
|
||||
# 付费档(starter+) — 探测出的能力即为真实可用
|
||||
label, missing, extras = _compute_label_and_missing(capset, tiers)
|
||||
capset = _override_limits_with_detected_tier(capset, label, tiers)
|
||||
_persist(capset, label, log=probe_log, missing=missing, extras=extras)
|
||||
return capset
|
||||
except Exception as e:
|
||||
logger.exception("detect_capabilities failed; using none baseline: %s", e)
|
||||
capset = _tier_to_capset(tiers["none"])
|
||||
_persist(capset, "None(探测失败)", log=[f"探测失败:{e}"], missing=[], extras=[])
|
||||
return capset
|
||||
|
||||
|
||||
# ===== Tier 代表性 capability(signature caps)=====
|
||||
# 拥有**任意一个**即认作该档及以上。自上而下匹配。
|
||||
# 这套设计的好处:单个 capability 探测的 transient 失败不会把整体档位"误降"。
|
||||
TIER_SIGNATURES: dict[str, set[Cap]] = {
|
||||
"expert": {Cap.FINANCIAL, Cap.INTRADAY_BATCH, Cap.WEBSOCKET},
|
||||
"pro": {Cap.KLINE_MINUTE_BATCH, Cap.KLINE_MINUTE_BY_SYMBOL,
|
||||
Cap.INTRADAY, Cap.DEPTH5, Cap.DEPTH5_BATCH},
|
||||
"starter": {Cap.QUOTE_BATCH, Cap.KLINE_DAILY_BATCH,
|
||||
Cap.ADJ_FACTOR, Cap.QUOTE_POOL},
|
||||
# free / none 不需 signature — 由 _classify_tier 的分水岭逻辑判定
|
||||
}
|
||||
|
||||
|
||||
@dataclass(slots=True, frozen=True)
|
||||
class TierClassification:
|
||||
"""档位判定结果。
|
||||
|
||||
判定依据是"复权因子分水岭":
|
||||
- 连单只日K都没有 → 无效 key(is_invalid),归 none 档
|
||||
- 有单只日K、无复权因子 → 免费 key(is_free)
|
||||
- 有复权因子 → 付费档(starter+),具体档位由 signature 决定
|
||||
"""
|
||||
|
||||
tier: str # "none" / "free" / "starter" / "pro" / "expert"
|
||||
is_invalid: bool # 无效 key(连单只日K都拿不到)
|
||||
is_free: bool # 免费有效 key(有日K、无复权因子)
|
||||
|
||||
|
||||
def _classify_tier(capset: CapabilitySet, tiers: dict) -> TierClassification:
|
||||
"""根据探测出的能力集判定档位。
|
||||
|
||||
分水岭是 KLINE_DAILY_BY_SYMBOL(单只日K)与 ADJ_FACTOR(复权因子):
|
||||
- 无单只日K → none(无效 key)
|
||||
- 有日K无复权 → free(免费 key)
|
||||
- 有复权因子 → 走 signature 判定 starter/pro/expert
|
||||
"""
|
||||
held = set(capset.all().keys())
|
||||
|
||||
# 1) 连单只日K都没有 → 无效 key
|
||||
if Cap.KLINE_DAILY_BY_SYMBOL not in held:
|
||||
return TierClassification(tier="none", is_invalid=True, is_free=False)
|
||||
|
||||
# 2) 有日K但无复权因子 → 免费 key
|
||||
if Cap.ADJ_FACTOR not in held:
|
||||
return TierClassification(tier="free", is_invalid=False, is_free=True)
|
||||
|
||||
# 3) 有复权因子 → 付费档,按 signature 自上而下判定
|
||||
if held & TIER_SIGNATURES["expert"]:
|
||||
base = "expert"
|
||||
elif held & TIER_SIGNATURES["pro"]:
|
||||
base = "pro"
|
||||
elif held & TIER_SIGNATURES["starter"]:
|
||||
base = "starter"
|
||||
else:
|
||||
# 有复权因子但无任何代表能力 — 兜底为 starter(复权本身是 starter 特征)
|
||||
base = "starter"
|
||||
return TierClassification(tier=base, is_invalid=False, is_free=False)
|
||||
|
||||
# 补丁友好命名(label 后缀用)
|
||||
_CAP_ALIASES: dict[Cap, str] = {
|
||||
Cap.KLINE_MINUTE_BATCH: "分钟K",
|
||||
Cap.KLINE_MINUTE_BY_SYMBOL: "分钟K",
|
||||
Cap.INTRADAY: "分时",
|
||||
Cap.INTRADAY_BATCH: "批量分时",
|
||||
Cap.DEPTH5: "五档",
|
||||
Cap.DEPTH5_BATCH: "批量五档",
|
||||
Cap.WEBSOCKET: "WS",
|
||||
Cap.FINANCIAL: "财务",
|
||||
Cap.ADJ_FACTOR: "复权",
|
||||
Cap.QUOTE_BATCH: "批量行情",
|
||||
Cap.QUOTE_POOL: "标的池",
|
||||
Cap.KLINE_DAILY_BATCH: "日K批量",
|
||||
}
|
||||
|
||||
|
||||
def _override_limits_with_detected_tier(
|
||||
capset: CapabilitySet, label: str, tiers: dict,
|
||||
) -> CapabilitySet:
|
||||
"""探测完成后,用判档对应的 limits 覆盖每个 cap 的速率/批量。
|
||||
|
||||
判档前每个 cap 用的是"所有档默认值的并集"(为了不漏数据),
|
||||
判档后才知道用户真实档位,limits 用该档的实际值更准。
|
||||
label 可能是 "Pro" / "Pro + 分钟K" / "Pro+" 等组合形式 — 取第一个词当作基线档名。
|
||||
"""
|
||||
base_name = label.split()[0].split("+")[0].strip().lower() # "Pro + 分钟K" → "pro"
|
||||
tier_limits = tiers.get(base_name, {})
|
||||
new_caps: dict[Cap, CapabilityLimits] = {}
|
||||
for cap, _old_lim in capset.all().items():
|
||||
spec = tier_limits.get(cap.value)
|
||||
if spec:
|
||||
new_caps[cap] = CapabilityLimits(
|
||||
rpm=spec.get("rpm"),
|
||||
batch=spec.get("batch"),
|
||||
subscribe=spec.get("subscribe"),
|
||||
)
|
||||
else:
|
||||
# 不在该档定义里(extras),用 expert 档兜底(最宽松)
|
||||
expert_spec = tiers.get("expert", {}).get(cap.value, {})
|
||||
new_caps[cap] = CapabilityLimits(
|
||||
rpm=expert_spec.get("rpm"),
|
||||
batch=expert_spec.get("batch"),
|
||||
subscribe=expert_spec.get("subscribe"),
|
||||
)
|
||||
return CapabilitySet(new_caps)
|
||||
|
||||
|
||||
def _tier_caps_set(tiers: dict, tier_name: str) -> set[Cap]:
|
||||
"""读 tiers.yaml 的某档定义,转为 Cap 集合。"""
|
||||
return {Cap(c) for c in tiers.get(tier_name, {}).keys() if c in {x.value for x in Cap}}
|
||||
|
||||
|
||||
def _compute_label_and_missing(
|
||||
capset: CapabilitySet, tiers: dict,
|
||||
) -> tuple[str, list[str], list[str]]:
|
||||
"""返回 (label, missing_caps, extra_caps)。
|
||||
|
||||
label:档位标签。
|
||||
missing_caps:本档**应有但未探测到**的 capability(用于诊断:可能是探测 bug 或权限丢失)。
|
||||
extra_caps:超出本档的额外 capability(自定义组合)。
|
||||
"""
|
||||
held = set(capset.all().keys())
|
||||
|
||||
# 1) 完全匹配 — 干净命中某档
|
||||
for tier_name in ["free", "starter", "pro", "expert"]:
|
||||
if held == _tier_caps_set(tiers, tier_name):
|
||||
return tier_name.capitalize(), [], []
|
||||
|
||||
# 2) 按 signature 自上而下判档
|
||||
if held & TIER_SIGNATURES["expert"]:
|
||||
base = "expert"
|
||||
elif held & TIER_SIGNATURES["pro"]:
|
||||
base = "pro"
|
||||
elif held & TIER_SIGNATURES["starter"]:
|
||||
base = "starter"
|
||||
else:
|
||||
base = "free"
|
||||
|
||||
base_caps = _tier_caps_set(tiers, base)
|
||||
missing = sorted(c.value for c in (base_caps - held))
|
||||
extras = base_caps and (held - base_caps) or set() # extras 是超出该档的部分
|
||||
|
||||
# 实际超出 = held 中"既不属于本档、也不属于本档下方任何档"的 cap
|
||||
# 简化:extras = held - base_caps
|
||||
extras_set = held - base_caps
|
||||
|
||||
# 3) 拼 label
|
||||
if not extras_set:
|
||||
# 完全在本档内(可能缺一两项 — 由 missing 反映)
|
||||
return base.capitalize(), missing, []
|
||||
|
||||
# 补丁过多 → 用 "≈" 形式
|
||||
if len(extras_set) > 3:
|
||||
return f"{base.capitalize()}+", missing, sorted(c.value for c in extras_set)
|
||||
|
||||
suffix = sorted({_CAP_ALIASES.get(e, str(e)) for e in extras_set})
|
||||
return f"{base.capitalize()} + " + " + ".join(suffix), missing, sorted(c.value for c in extras_set)
|
||||
|
||||
|
||||
def _compute_label(capset: CapabilitySet, tiers: dict) -> str:
|
||||
"""对外简化签名 — 只要 label。"""
|
||||
label, _missing, _extras = _compute_label_and_missing(capset, tiers)
|
||||
return label
|
||||
|
||||
|
||||
def _persist(
|
||||
capset: CapabilitySet,
|
||||
label: str,
|
||||
log: list[str] | None = None,
|
||||
missing: list[str] | None = None,
|
||||
extras: list[str] | None = None,
|
||||
invalid_key: bool = False,
|
||||
) -> None:
|
||||
settings.data_dir.mkdir(parents=True, exist_ok=True)
|
||||
cache_path = settings.data_dir / _CAPSET_CACHE_FILE
|
||||
payload = {
|
||||
"schema_version": _CACHE_SCHEMA_VERSION,
|
||||
"label": label,
|
||||
"capabilities": capset.to_dict(),
|
||||
"probe_log": log or [],
|
||||
"missing_caps": missing or [], # 本档应有但未探测到
|
||||
"extras_caps": extras or [], # 超出本档的额外能力
|
||||
"invalid_key": invalid_key, # 探测出的 key 无效(连单只日K都拿不到)
|
||||
}
|
||||
with cache_path.open("w", encoding="utf-8") as f:
|
||||
json.dump(payload, f, ensure_ascii=False, indent=2)
|
||||
|
||||
|
||||
def _capset_from_json(data: dict[str, Any]) -> CapabilitySet:
|
||||
caps: dict[Cap, CapabilityLimits] = {}
|
||||
for cap_name, lim in data.get("capabilities", {}).items():
|
||||
try:
|
||||
cap = Cap(cap_name)
|
||||
except ValueError:
|
||||
continue
|
||||
caps[cap] = CapabilityLimits(
|
||||
rpm=lim.get("rpm"),
|
||||
batch=lim.get("batch"),
|
||||
subscribe=lim.get("subscribe"),
|
||||
)
|
||||
return CapabilitySet(caps)
|
||||
|
||||
|
||||
def tier_label() -> str:
|
||||
cache_path = settings.data_dir / _CAPSET_CACHE_FILE
|
||||
if cache_path.exists():
|
||||
with cache_path.open(encoding="utf-8") as f:
|
||||
return json.load(f).get("label", "Unknown")
|
||||
return "Unknown"
|
||||
|
||||
|
||||
def probe_log() -> list[str]:
|
||||
cache_path = settings.data_dir / _CAPSET_CACHE_FILE
|
||||
if cache_path.exists():
|
||||
with cache_path.open(encoding="utf-8") as f:
|
||||
return json.load(f).get("probe_log", [])
|
||||
return []
|
||||
|
||||
|
||||
def missing_caps() -> list[str]:
|
||||
"""本档应有但未探测到的 capability — 通常意味着探测有 bug 或权限边界。"""
|
||||
cache_path = settings.data_dir / _CAPSET_CACHE_FILE
|
||||
if cache_path.exists():
|
||||
with cache_path.open(encoding="utf-8") as f:
|
||||
return json.load(f).get("missing_caps", [])
|
||||
return []
|
||||
|
||||
|
||||
def extras_caps() -> list[str]:
|
||||
cache_path = settings.data_dir / _CAPSET_CACHE_FILE
|
||||
if cache_path.exists():
|
||||
with cache_path.open(encoding="utf-8") as f:
|
||||
return json.load(f).get("extras_caps", [])
|
||||
return []
|
||||
|
||||
|
||||
def is_invalid_key() -> bool:
|
||||
"""最近一次探测是否判定 key 无效(连单只日K都拿不到)。
|
||||
|
||||
settings 层据此清除已存的 key,避免乱填的 key 被持久化。
|
||||
"""
|
||||
cache_path = settings.data_dir / _CAPSET_CACHE_FILE
|
||||
if cache_path.exists():
|
||||
with cache_path.open(encoding="utf-8") as f:
|
||||
return bool(json.load(f).get("invalid_key", False))
|
||||
return False
|
||||
|
||||
|
||||
def base_tier_name() -> str:
|
||||
"""当前档位的基础名(小写): none / free / starter / pro / expert。
|
||||
|
||||
供 client 层判断"是否走 free-api 服务器"(none/free → free 服务器)。
|
||||
"""
|
||||
label = tier_label()
|
||||
return label.split()[0].split("+")[0].strip().lower()
|
||||
@@ -0,0 +1,158 @@
|
||||
"""标的池(Universe)定义(§6.3)。
|
||||
|
||||
Phase 1 实现:
|
||||
- 常用指数成份(沪深 300 / 中证 500 / 上证 50)用 TickFlow `quote.pool` 端点拉取并缓存
|
||||
- 全 A 通过 instruments.batch 获取
|
||||
- 自选池 = 用户的 watchlist
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import logging
|
||||
from datetime import date
|
||||
from pathlib import Path
|
||||
from typing import Literal
|
||||
|
||||
import polars as pl
|
||||
|
||||
from app.config import settings
|
||||
from app.tickflow.client import get_client
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
PoolId = Literal["CSI300", "CSI500", "SSE50", "CN_Equity_A", "CN_Index", "watchlist"]
|
||||
|
||||
# TickFlow universe id 是它内部命名(见 tf.universes.list())。
|
||||
# 没有官方对照表,启动时按名称模糊匹配从 universes.list() 里找。
|
||||
# 常见名:沪深300 / 中证500 / 上证50 / 全 A
|
||||
_POOL_NAME_HINTS = {
|
||||
"CSI300": ["沪深300", "HS300", "CSI300"],
|
||||
"CSI500": ["中证500", "ZZ500", "CSI500"],
|
||||
"SSE50": ["上证50", "SH50", "SSE50"],
|
||||
}
|
||||
|
||||
|
||||
def _find_universe_id(hints: list[str]) -> str | None:
|
||||
"""从 universes.list() 里按 name/id 子串匹配找一个 universe id。"""
|
||||
try:
|
||||
tf = get_client()
|
||||
unis = tf.universes.list()
|
||||
except Exception as e: # noqa: BLE001
|
||||
logger.warning("universes.list failed: %s", e)
|
||||
return None
|
||||
for u in unis or []:
|
||||
item = u if isinstance(u, dict) else {"id": getattr(u, "id", ""), "name": getattr(u, "name", "")}
|
||||
haystack = (item.get("id", "") + " " + item.get("name", "")).lower()
|
||||
for h in hints:
|
||||
if h.lower() in haystack:
|
||||
return item["id"]
|
||||
return None
|
||||
|
||||
|
||||
def _pool_cache_path(pool_id: str) -> Path:
|
||||
return settings.data_dir / "pools" / f"{pool_id}.parquet"
|
||||
|
||||
|
||||
def get_pool(pool_id: PoolId, refresh: bool = False) -> list[str]:
|
||||
"""返回标的池里的 symbol 列表。"""
|
||||
if pool_id == "watchlist":
|
||||
return _load_watchlist()
|
||||
|
||||
cache = _pool_cache_path(pool_id)
|
||||
if cache.exists() and not refresh:
|
||||
df = pl.read_parquet(cache)
|
||||
return df["symbol"].to_list()
|
||||
|
||||
symbols = _fetch_pool(pool_id)
|
||||
if symbols:
|
||||
cache.parent.mkdir(parents=True, exist_ok=True)
|
||||
pl.DataFrame({"symbol": symbols, "as_of": [date.today()] * len(symbols)}).write_parquet(cache)
|
||||
return symbols
|
||||
|
||||
|
||||
def _fetch_pool(pool_id: PoolId) -> list[str]:
|
||||
"""从 TickFlow 拉取池成份。
|
||||
|
||||
实现:先用 universes.list 找到 universe id,再 quotes.get_by_universes 拉成份。
|
||||
"""
|
||||
tf = get_client()
|
||||
|
||||
if pool_id in _POOL_NAME_HINTS:
|
||||
uid = _find_universe_id(_POOL_NAME_HINTS[pool_id])
|
||||
if not uid:
|
||||
logger.warning("无法在 TickFlow universes 列表里匹配到 %s", pool_id)
|
||||
return []
|
||||
try:
|
||||
df = tf.quotes.get_by_universes([uid], as_dataframe=True)
|
||||
if df is not None and len(df) > 0 and "symbol" in df.columns:
|
||||
return df["symbol"].astype(str).tolist()
|
||||
except Exception as e: # noqa: BLE001
|
||||
logger.warning("fetch pool %s via universe %s failed: %s", pool_id, uid, e)
|
||||
|
||||
if pool_id == "CN_Equity_A":
|
||||
# 全 A — 优先直接用 CN_Equity_A universe (包含沪深京三市)
|
||||
uid = _find_universe_id(["CN_Equity_A", "沪深京A股", "全A"])
|
||||
if uid:
|
||||
try:
|
||||
df = tf.quotes.get_by_universes([uid], as_dataframe=True)
|
||||
if df is not None and len(df) > 0 and "symbol" in df.columns:
|
||||
return sorted(set(df["symbol"].astype(str).tolist()))
|
||||
except Exception as e: # noqa: BLE001
|
||||
logger.warning("fetch CN_Equity_A via universe %s failed: %s", uid, e)
|
||||
|
||||
# fallback: 聚合申万一级行业 (覆盖度较低, 缺北交所/新股)
|
||||
try:
|
||||
unis = tf.universes.list()
|
||||
except Exception as e: # noqa: BLE001
|
||||
logger.warning("universes.list failed: %s", e)
|
||||
unis = []
|
||||
sw1_ids = []
|
||||
for u in unis or []:
|
||||
item = u if isinstance(u, dict) else {"id": getattr(u, "id", "")}
|
||||
uid = item.get("id", "")
|
||||
if "SW1_" in uid:
|
||||
sw1_ids.append(uid)
|
||||
if sw1_ids:
|
||||
try:
|
||||
df = tf.quotes.get_by_universes(sw1_ids, as_dataframe=True)
|
||||
if df is not None and "symbol" in df.columns:
|
||||
return sorted(set(df["symbol"].astype(str).tolist()))
|
||||
except Exception as e: # noqa: BLE001
|
||||
logger.warning("aggregate SW1 fetch failed: %s", e)
|
||||
|
||||
if pool_id == "CN_Index":
|
||||
uid = _find_universe_id(["CN_Index", "沪深指数", "指数"])
|
||||
ids = [uid] if uid else ["CN_Index"]
|
||||
try:
|
||||
df = tf.quotes.get_by_universes(ids, as_dataframe=True)
|
||||
if df is not None and len(df) > 0 and "symbol" in df.columns:
|
||||
return sorted(set(df["symbol"].astype(str).tolist()))
|
||||
except Exception as e: # noqa: BLE001
|
||||
logger.warning("fetch CN_Index via universe %s failed: %s", ids, e)
|
||||
|
||||
return []
|
||||
|
||||
|
||||
def _load_watchlist() -> list[str]:
|
||||
"""读取用户自选(由 watchlist service 维护)。"""
|
||||
path = settings.data_dir / "user_data" / "watchlist.parquet"
|
||||
if not path.exists():
|
||||
return []
|
||||
df = pl.read_parquet(path)
|
||||
if df.is_empty() or "symbol" not in df.columns:
|
||||
return []
|
||||
return df["symbol"].to_list()
|
||||
|
||||
|
||||
# 兜底:Free 用户/无 API 时给一个小型可用集合,让 UI 不至于空白
|
||||
DEMO_SYMBOLS = [
|
||||
"600000.SH", # 浦发银行
|
||||
"600036.SH", # 招商银行
|
||||
"600519.SH", # 贵州茅台
|
||||
"601318.SH", # 中国平安
|
||||
"601398.SH", # 工商银行
|
||||
"000001.SZ", # 平安银行
|
||||
"000333.SZ", # 美的集团
|
||||
"000651.SZ", # 格力电器
|
||||
"000858.SZ", # 五粮液
|
||||
"002594.SZ", # 比亚迪
|
||||
]
|
||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,66 @@
|
||||
"""请求调度器(§5.6)。
|
||||
|
||||
按 capability 分别维护令牌桶。Phase 0:基础实现;Phase 1 接入批量合并、优先级队列。
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import asyncio
|
||||
import time
|
||||
from dataclasses import dataclass
|
||||
|
||||
from .capabilities import Cap, CapabilitySet
|
||||
|
||||
|
||||
@dataclass
|
||||
class _Bucket:
|
||||
capacity: int # 每分钟令牌数
|
||||
tokens: float
|
||||
last_refill: float # 单位:秒
|
||||
|
||||
def consume(self, n: int = 1) -> float:
|
||||
"""尝试消费 n 个令牌,返回需要等待的秒数(0 表示无需等待)。"""
|
||||
now = time.monotonic()
|
||||
elapsed = now - self.last_refill
|
||||
# 60s 内补满 capacity,匀速补
|
||||
refill = elapsed * (self.capacity / 60.0)
|
||||
self.tokens = min(self.capacity, self.tokens + refill)
|
||||
self.last_refill = now
|
||||
|
||||
if self.tokens >= n:
|
||||
self.tokens -= n
|
||||
return 0.0
|
||||
deficit = n - self.tokens
|
||||
# 还需多少秒才能补齐
|
||||
wait = deficit / (self.capacity / 60.0)
|
||||
# 不预扣,留给下一次再竞争(避免饿死优先级高的请求)
|
||||
return wait
|
||||
|
||||
|
||||
class Scheduler:
|
||||
"""每个 capability 一个桶。"""
|
||||
|
||||
def __init__(self, capset: CapabilitySet) -> None:
|
||||
self._capset = capset
|
||||
self._buckets: dict[Cap, _Bucket] = {}
|
||||
self._locks: dict[Cap, asyncio.Lock] = {}
|
||||
for cap, lim in capset.all().items():
|
||||
if lim.rpm:
|
||||
self._buckets[cap] = _Bucket(
|
||||
capacity=lim.rpm,
|
||||
tokens=lim.rpm,
|
||||
last_refill=time.monotonic(),
|
||||
)
|
||||
self._locks[cap] = asyncio.Lock()
|
||||
|
||||
async def acquire(self, cap: Cap, n: int = 1) -> None:
|
||||
"""阻塞直到拿到 n 个令牌。无桶 = 不限流(由调用方保证)。"""
|
||||
bucket = self._buckets.get(cap)
|
||||
if bucket is None:
|
||||
return
|
||||
lock = self._locks[cap]
|
||||
async with lock:
|
||||
while True:
|
||||
wait = bucket.consume(n)
|
||||
if wait == 0:
|
||||
return
|
||||
await asyncio.sleep(wait)
|
||||
Reference in New Issue
Block a user