data-backtest-live-common 0.2.0__py3-none-any.whl

dbl_common/ticks.py

@@ -0,0 +1,57 @@
+# -*- coding: utf-8 -*-
+"""ticks.py — 最小申报价格单位（tick size）（公共模块 · 纯函数）。
+
+撮合价的合法性校验、回测成交价的取整、实盘限价单步进都要用同一个 tick。
+
+制度事实表（2026 口径）
+----------------------
+· A 股股票（沪深主板/科创板/创业板/北交所）：0.01 元。
+· B 股：沪 0.001 美元 / 深 0.01 港元（本模块返回数值口径 0.001/0.01，
+  币种换算归调用方）。
+· 场内基金（ETF/LOF）：0.001 元。
+· 可转债：0.001 元。
+· 沪市国债逆回购：0.005 元；深市 0.01 元（以交易所现行细则为准）。
+
+⚠️ 价格的历史变迁（如早年沪市 A 股曾按价位分档 0.01/0.001）不做回溯——
+对回测撮合影响可忽略；有实证需求再扩展。
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .boards import SecurityType, exchange_of, normalize_code, security_type
+
+
+def tick_size(code: str, *, stype: Optional[SecurityType] = None) -> float:
+    """最小申报价格单位（元）。未知品种保守返回 0.01 并在调用方核对。"""
+    st = security_type(code, stype)
+    if st in (SecurityType.ETF, SecurityType.LOF, SecurityType.FUND_OTHER,
+              SecurityType.CONVERTIBLE_BOND):
+        return 0.001
+    if st == SecurityType.REPO:
+        return 0.005 if exchange_of(code) == "SH" else 0.01
+    if st == SecurityType.B_SHARE:
+        return 0.001 if exchange_of(code) == "SH" else 0.01
+    return 0.01
+
+
+def snap_to_tick(price: float, code: str, *,
+                 stype: Optional[SecurityType] = None) -> float:
+    """把任意价格吸附到合法申报价（向下取整到 tick——**不四舍五入**：
+    买单向下吸保证不超预算；卖方向上吸请调用方显式选择方向）。"""
+    import math
+
+    t = tick_size(code, stype=stype)
+    return math.floor(round(float(price) / t, 9)) * t
+
+
+def is_valid_price(price: float, code: str, *,
+                   stype: Optional[SecurityType] = None,
+                   tol: float = 1e-9) -> bool:
+    """价格是否恰好落在合法申报档位上。"""
+    t = tick_size(code, stype=stype)
+    v = float(price) / t
+    return abs(v - round(v)) <= tol / t
+
+
+__all__ = ["tick_size", "snap_to_tick", "is_valid_price", "normalize_code"]

dbl_common/trade_calendar.py

@@ -0,0 +1,128 @@
+# -*- coding: utf-8 -*-
+"""dbl_common.trade_calendar — 交易日历公共模块（数据 / 回测 / 实盘共用）
+
+溯源：quant_data_center/common/trade_calendar.py → 2026-09-26 抽入本独立库。
+
+所有交易系统都必须遵守同一套日历口径，集中在此维护：
+  · 日历日期归一化：Tushare cal_date 的 YYYYMMDD → 标准 YYYY-MM-DD；
+  · 开市判定：按 is_open 列过滤周末与节假日（兼容字符串/数值多种存储）；
+  · Parquet schema 探测：兼容 DuckDB 版本差异（1.5.x 为 name 列，旧版 column_name）；
+  · load_trade_dates：从日历 Parquet 取升序开市日，支持自有/外部连接。
+
+与旧版（quant_data_center/common/trade_calendar.py）的关键差异：
+本库**不绑定任何系统的日历路径** —— ``cal_glob`` 必传：
+  · 参数缺失 = 程序员错误 → ValueError（响亮报错，不静默）；
+  · 日历文件缺失/不可读 = 数据状态 → 返回 []（调用方可据此降级，不抛异常）。
+各系统自己维护路径常量（quant_data_center 在 common/paths.py 的 DEFAULT_CAL_GLOB）。
+
+仅依赖 duckdb + 标准库。
+"""
+from __future__ import annotations
+
+import logging
+import re
+from datetime import datetime
+from typing import Optional
+
+import duckdb
+
+logger = logging.getLogger("dbl_common.trade_calendar")
+
+_8DIGIT = re.compile(r"^\d{8}$")
+_ISO = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+# is_open 真值集合（pandas/duckdb 落盘后可能出现字符串、浮点等形态）
+_OPEN_TRUE = {"1", "1.0", "true", "t", "yes", "y"}
+
+
+def normalize_cal_date(value) -> str:
+    """日历日期 → YYYY-MM-DD。已是 ISO 格式原样返回；非法值抛 ValueError。"""
+    s = str(value).strip()
+    if _8DIGIT.match(s):
+        return f"{s[:4]}-{s[4:6]}-{s[6:8]}"
+    if _ISO.match(s):
+        return s
+    raise ValueError(f"无法识别的日历日期：{value!r}")
+
+
+def is_open_true(value) -> bool:
+    """is_open 字段是否为开市（宽容判定）。"""
+    return str(value).strip().lower() in _OPEN_TRUE
+
+
+def parquet_columns(glob: str,
+                    con: Optional[duckdb.DuckDBPyConnection] = None) -> list[str]:
+    """Parquet 文件列名（兼容 DuckDB 版本差异）；文件不存在/出错 → []。"""
+    own = con is None
+    con = con or duckdb.connect()
+    try:
+        for col in ("name", "column_name"):
+            try:
+                return [r[0] for r in con.execute(
+                    f"SELECT {col} FROM parquet_schema(?)", [glob]).fetchall()]
+            except duckdb.BinderException:
+                continue
+        return []
+    except Exception:
+        return []
+    finally:
+        if own:
+            con.close()
+
+
+def has_column(glob: str, column: str,
+               con: Optional[duckdb.DuckDBPyConnection] = None) -> bool:
+    return column in parquet_columns(glob, con)
+
+
+def trade_days_between(dates, start: Optional[str] = None,
+                       end: Optional[str] = None) -> int:
+    """[start, end] 闭区间内的交易日数（dates 为 ISO 升序序列）。"""
+    return sum(1 for d in dates
+               if (start is None or d >= start) and (end is None or d <= end))
+
+
+def load_trade_dates(con: Optional[duckdb.DuckDBPyConnection] = None,
+                     cal_glob: Optional[str] = None,
+                     end_date: Optional[str] = None) -> list[str]:
+    """开市交易日（ISO 升序，≤ end_date，默认今天）。
+
+    ``cal_glob`` **必传**（本库不绑定任何系统的日历路径）；
+    con=None 时自建内存连接并关闭（回测/实盘一行调用即可）；
+    日历文件缺失或读取失败 → []（调用方可据此降级，不抛异常）。
+    """
+    if not cal_glob:
+        raise ValueError(
+            "cal_glob 必传：dbl_common 不绑定任何系统的日历路径"
+            "（quant_data_center 用 common/paths.py 的 DEFAULT_CAL_GLOB）")
+    end_date = end_date or datetime.now().strftime("%Y-%m-%d")
+    own = con is None
+    con = con or duckdb.connect()
+    try:
+        cols = parquet_columns(cal_glob, con)
+        if not cols:
+            logger.warning("交易日历不可读：%s（相关日历规则将被跳过）", cal_glob)
+            return []
+        use_open = "is_open" in cols
+        df = con.execute(
+            f"SELECT DISTINCT cal_date{', is_open' if use_open else ''} "
+            "FROM read_parquet(?, hive_partitioning=true)",
+            [cal_glob]).df()
+    except Exception as e:
+        logger.warning("交易日历读取失败：%s", e)
+        return []
+    finally:
+        if own:
+            con.close()
+
+    if use_open:
+        df = df[df["is_open"].map(is_open_true)]
+    days: set[str] = set()
+    for v in df["cal_date"]:
+        try:
+            s = normalize_cal_date(v)
+        except ValueError:
+            continue
+        if s <= end_date:
+            days.add(s)
+    return sorted(days)

dbl_common/trading_calendar.py

@@ -0,0 +1,202 @@
+# -*- coding: utf-8 -*-
+"""trading_calendar.py — 交易日历契约（公共模块）：规则归本模块，**数据归数据中心**。
+
+（模块名不用 `calendar.py`：会遮蔽标准库 `calendar`——任何把本目录挂进
+`sys.path` 的系统都会连带炸掉 `datetime` 内部实现，实测踩过。）
+
+为什么只定契约不定数据：节假日是**数据**不是**规则**（每年国务院发布），
+硬编码必然过期。正确分工（与用户架构一致）：
+    数据中心（quant_data_center）→ 产出权威交易日历落盘（如 BaoStock
+    `trade_cal`：date,is_trading 全历史）；
+    本模块 → 定义注入接口 + 三态诚实判定 + 只跳周末的显式降级。
+
+三态诚实（移植自 GMD `trading_calendar.py` 的设计，实测修过 5 份日历
+口径漂移的教训）：
+    `is_trading_day()` → True / False / **None**。
+    None = 日历不可用或日期在覆盖区间**之外**——绝不拿「猜」冒充「知道」，
+    不许 forward-fill（2027 年的问题不许静默沿用 2026 年的判断）。
+降级是调用方的事，但降级口径也只提供这一份（`weekend_*`，调用方必须
+显式选择并对外标注「用了近似」）。
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import csv
+from pathlib import Path
+from typing import Callable, Iterable, Optional, Protocol, Set
+
+
+class CalendarSource(Protocol):
+    """交易日历数据源契约（数据中心实现并注入）。"""
+
+    def is_trading_day(self, date) -> Optional[bool]: ...
+
+    def coverage(self) -> tuple: ...
+
+
+class InjectedCalendar:
+    """由「交易日集合」构成的日历（数据中心把 trade_cal 的开市日注入）。"""
+
+    def __init__(self, trading_days: Iterable[str],
+                 coverage_start: Optional[str] = None,
+                 coverage_end: Optional[str] = None):
+        self._days: Set[str] = {str(d)[:10] for d in trading_days}
+        ds = sorted(self._days)
+        self._cov = (coverage_start or (ds[0] if ds else None),
+                     coverage_end or (ds[-1] if ds else None))
+
+    def is_trading_day(self, date) -> Optional[bool]:
+        d = _iso(date)
+        if d is None:
+            return None
+        lo, hi = self._cov
+        if lo is None or hi is None or d < lo or d > hi:
+            return None                 # 覆盖区间外：不知道，不猜
+        return d in self._days
+
+    def coverage(self) -> tuple:
+        return self._cov
+
+    def next_trading_day(self, date, max_walk: int = 30) -> Optional[str]:
+        """下一交易日（区间尽头/走 30 天没找到 → None）。"""
+        cur = _iso(date)
+        if cur is None:
+            return None
+        for _ in range(max_walk):
+            cur = (_dt.date.fromisoformat(cur) + _dt.timedelta(days=1)).isoformat()
+            if self.is_trading_day(cur) is True:
+                return cur
+        return None
+
+    def prev_trading_day(self, date, max_walk: int = 30) -> Optional[str]:
+        cur = _iso(date)
+        if cur is None:
+            return None
+        for _ in range(max_walk):
+            cur = (_dt.date.fromisoformat(cur) - _dt.timedelta(days=1)).isoformat()
+            if self.is_trading_day(cur) is True:
+                return cur
+        return None
+
+    def trading_days_between(self, start, end) -> Optional[int]:
+        """[start, end] 内的交易日数（含端点；区间越界 → None）。"""
+        a, b = _iso(start), _iso(end)
+        if a is None or b is None or a > b:
+            return None
+        if self.is_trading_day(a) is None or self.is_trading_day(b) is None:
+            return None
+        n, cur = 0, a
+        while cur <= b:
+            if self.is_trading_day(cur) is True:
+                n += 1
+            cur = (_dt.date.fromisoformat(cur) + _dt.timedelta(days=1)).isoformat()
+        return n
+
+
+def from_baostock_csv(path, *, is_trading_col: str = "is_trading") -> InjectedCalendar:
+    """从 BaoStock trade_cal CSV（date,is_trading）构建日历。
+
+    这是与数据中心的**对接点**：quant_data_center 已把 BaoStock 权威交易日历
+    落盘（storage/raw/baostock/trade_cal），任何系统把该文件路径传进来即可，
+    不需要再各自联网拉日历（GMD 实测教训：5 份日历 5 个口径）。
+    """
+    p = Path(path)
+    days = []
+    with p.open("r", encoding="utf-8-sig", newline="") as f:
+        for row in csv.DictReader(f):
+            d = str(row.get("date") or "")[:10]
+            v = str(row.get(is_trading_col) or "").strip()
+            if d and v == "1":
+                days.append(d)
+    return InjectedCalendar(days)
+
+
+def from_parquet_dataset(dataset_dir, *, date_col: str = "date",
+                         is_trading_col: Optional[str] = None) -> InjectedCalendar:
+    """从数据中心 raw 层 parquet 数据集目录构建交易日历（标准对接点）。
+
+    数据中心落盘布局为 `storage/raw/<source>/<dataset>/year=YYYY/*.parquet`
+    （按年分区），本函数递归读取整目录。两种用法：
+      · 日历数据集（baostock/trade_cal）：传 `is_trading_col="is_trading"`
+        （只取值为 1/`'1'` 的开市日）；
+      · 无 `is_trading_col`：把该数据集出现过的**全部日期**视为交易日
+        （如 tencent/index_daily 的指数日线日期集——对账/兜底场景够用）。
+
+    需要 pandas（数据中心环境标配；本包核心仍零依赖，此函数按需 import）。
+    """
+    try:
+        import pandas as pd
+    except ImportError as e:  # pragma: no cover
+        raise ImportError(
+            "from_parquet_dataset 需要 pandas——数据中心/回测环境标配；"
+            "若在纯净环境用请改用 from_baostock_csv 或直接注入日期集合") from e
+    p = Path(dataset_dir)
+    if not p.is_dir():
+        raise FileNotFoundError(f"数据集目录不存在: {p}")
+    files = sorted(p.rglob("*.parquet"))
+    if not files:
+        raise FileNotFoundError(f"目录里没有 parquet: {p}")
+    frames = [pd.read_parquet(f, columns=None) for f in files]
+    df = pd.concat(frames, ignore_index=True) if len(frames) > 1 else frames[0]
+    if date_col not in df.columns:
+        raise ValueError(f"缺日期列 {date_col!r}，实际列: {list(df.columns)[:10]}")
+    dates = df[date_col].astype(str).str[:10]
+    if is_trading_col:
+        if is_trading_col not in df.columns:
+            raise ValueError(f"缺开市标记列 {is_trading_col!r}，"
+                             f"实际列: {list(df.columns)[:10]}")
+        mask = df[is_trading_col].astype(str).str.strip().isin(("1", "1.0", "True", "true"))
+        dates = dates[mask]
+    return InjectedCalendar(sorted(set(dates)))
+
+
+# ── 显式降级口径（唯一的近似实现，调用方须标注「近似」）─────────────────
+def weekend_is_trading_day(date) -> Optional[bool]:
+    """只跳周末的近似：周六日 False，工作日 **None**（不知道——节假日不认识）。"""
+    d = _to_date(date)
+    if d is None:
+        return None
+    return False if d.weekday() >= 5 else None
+
+
+def weekend_next_trading_day(date, max_walk: int = 10) -> Optional[str]:
+    cur = _to_date(date)
+    if cur is None:
+        return None
+    for _ in range(max_walk):
+        cur = cur + _dt.timedelta(days=1)
+        if cur.weekday() < 5:
+            return cur.isoformat()
+    return None
+
+
+def weekend_prev_trading_day(date, max_walk: int = 10) -> Optional[str]:
+    cur = _to_date(date)
+    if cur is None:
+        return None
+    for _ in range(max_walk):
+        cur = cur - _dt.timedelta(days=1)
+        if cur.weekday() < 5:
+            return cur.isoformat()
+    return None
+
+
+def _iso(x) -> Optional[str]:
+    d = _to_date(x)
+    return d.isoformat() if d else None
+
+
+def _to_date(x) -> Optional[_dt.date]:
+    if isinstance(x, _dt.datetime):
+        return x.date()
+    if isinstance(x, _dt.date):
+        return x
+    try:
+        return _dt.date.fromisoformat(str(x)[:10])
+    except ValueError:
+        return None
+
+
+__all__ = ["InjectedCalendar", "CalendarSource", "from_baostock_csv",
+           "weekend_is_trading_day", "weekend_next_trading_day",
+           "weekend_prev_trading_day"]

dbl_common/trading_hours.py

@@ -0,0 +1,159 @@
+# -*- coding: utf-8 -*-
+"""trading_hours.py — A 股交易时段与竞价阶段（公共模块 · 纯函数）。
+
+回测的「撮合时点」、模拟盘的「委托受理窗口」、实盘的「撤单合法性」都问
+同一个问题：「现在处于哪个竞价阶段」。本模块给出**现行制度**的精确判定
+与必要的**历史变更**标注。
+
+现行时段（沪深，2026 口径）
+---------------------------
+· 09:15-09:25 开盘集合竞价（09:20-09:25 沪深**不接受撤单**；09:15-09:20 可撤）。
+· 09:25-09:30 申报静默期（接收申报、不撮合——严格说 9:30 前不成交）。
+· 09:30-11:30 / 13:00-14:57 连续竞价。
+· 14:57-15:00 收盘集合竞价：**深市/北交所有**；沪市主板无（连续竞价至 15:00）。
+  ⚠️ 深市收盘集合竞价自 2018-08-20 前后引入（确切日期以深交所公告为准——
+  回测 2018 前后深市收盘价的撮合语义差异极小，但如实标注）。
+· 科创板/创业板盘后固定价格交易：15:05-15:30（申报 9:30-11:30/13:00-15:30）。
+· 北交所：9:15-9:25 集合竞价（9:20-9:25 不可撤），连续竞价同上，14:57-15:00
+  收盘集合竞价。
+
+诚实边界
+--------
+本模块不判「今天是否交易日」（日历数据归数据中心供给，见 `calendar.py`）；
+只判「若为交易日，此刻处于什么阶段」。午休/盘后返回明确枚举，调用方自行裁决。
+"""
+from __future__ import annotations
+
+import datetime as _dt
+import enum
+from typing import Optional
+
+from .boards import Board, board_of, normalize_code
+
+
+class Phase(enum.Enum):
+    """竞价阶段（判定撮合/撤单语义的最小粒度）。"""
+
+    PRE_OPEN = "pre_open"                # 开盘集合竞价·可撤单（9:15-9:20）
+    OPEN_AUCTION_LOCKED = "open_locked"  # 开盘集合竞价·不可撤单（9:20-9:25）
+    OPEN_AUCTION_IDLE = "open_idle"      # 静默期（9:25-9:30：接收不撮合）
+    MORNING = "morning"                  # 上午连续竞价（9:30-11:30）
+    LUNCH = "lunch"                      # 午间休市（11:30-13:00）
+    AFTERNOON = "afternoon"              # 下午连续竞价（13:00-14:57）
+    CLOSING_AUCTION = "closing_auction"  # 收盘集合竞价（深/北 14:57-15:00）
+    SH_CLOSE_RUN = "sh_close_run"        # 沪市尾段连续竞价（14:57-15:00）
+    POST_FIXED = "post_fixed"            # 科创/创业盘后固定价格（15:05-15:30）
+    LUNCH_AUCTION_IDLE = "lunch_idle"    # 中午申报静默（11:30-13:00 接收不撮合）
+    CLOSED = "closed"                    # 收市 / 非交易时段
+
+
+# 深市收盘集合竞价引入（2018-08-20，确切日以深交所公告为准——回测影响可忽略）
+SZ_CLOSING_AUCTION_START = "2018-08-20"
+
+
+def phase_at(code: str, when, *, date: Optional[str] = None) -> Phase:
+    """判定 `code`（按其市场/板块）在 `when`（time 或 datetime）所处阶段。
+
+    Args:
+        code: 证券代码（用于区分沪/深/北交所；无交易所信息的按前缀 best-effort）。
+        when: `datetime.time` / `datetime.datetime` / "HH:MM"[:SS] 字符串。
+        date: "YYYY-MM-DD"（深市收盘集合竞价历史判定用；None = 按现行制度）。
+
+    Notes:
+        盘后固定价格交易仅科创/创业板（15:05-15:30）。
+    """
+    t = _to_time(when)
+    hm = (t.hour, t.minute, t.second)
+
+    def _between(lo, hi):  # [lo, hi) 半开区间，hm 为 (h, m, s)
+        a = _sec(lo)
+        b = _sec(hi)
+        cur = hm[0] * 3600 + hm[1] * 60 + hm[2]
+        return a <= cur < b
+
+    if _between("09:15", "09:20"):
+        return Phase.PRE_OPEN
+    if _between("09:20", "09:25"):
+        return Phase.OPEN_AUCTION_LOCKED
+    if _between("09:25", "09:30"):
+        return Phase.OPEN_AUCTION_IDLE
+    if _between("09:30", "11:30"):
+        return Phase.MORNING
+    if _between("11:30", "13:00"):
+        return Phase.LUNCH
+    if _between("13:00", "14:57"):
+        return Phase.AFTERNOON
+    if _between("14:57", "15:00"):
+        return _closing_phase(code, date)
+    if _between("15:00", "15:05"):
+        return Phase.CLOSED
+    if _between("15:05", "15:30"):
+        if _is_star_or_gem(code):
+            return Phase.POST_FIXED
+        return Phase.CLOSED
+    return Phase.CLOSED
+
+
+def _closing_phase(code: str, date: Optional[str]) -> Phase:
+    """14:57-15:00：深/北收盘集合竞价；沪主板连续竞价。"""
+    board = board_of(code)
+    if board in (Board.MAIN_SZ, Board.GEM, Board.BSE):
+        if date is not None and board == Board.GEM and date < "2018-08-20":
+            return Phase.AFTERNOON  # 深市引入收盘集合竞价前：仍是连续竞价（近似标注）
+        return Phase.CLOSING_AUCTION
+    return Phase.SH_CLOSE_RUN
+
+
+def _is_star_or_gem(code: str) -> bool:
+    return board_of(normalize_code(code)) in (Board.STAR, Board.GEM)
+
+
+def _sec(hm: str) -> int:
+    h, m = hm.split(":")
+    return int(h) * 3600 + int(m) * 60
+
+
+def _to_time(when) -> _dt.time:
+    if isinstance(when, _dt.datetime):
+        return when.time()
+    if isinstance(when, _dt.time):
+        return when
+    s = str(when).strip()
+    if len(s) >= 5 and ":" in s:
+        parts = s.split(":")
+        return _dt.time(int(parts[0]), int(parts[1]),
+                        int(parts[2][:2]) if len(parts) > 2 and parts[2][:2].isdigit() else 0)
+    raise ValueError(f"无法解析时间: {when!r}")
+
+
+def is_auction(when, code: str = "600000") -> bool:
+    """此刻是否处于集合竞价（开盘锁定段或收盘集合竞价）。"""
+    return phase_at(code, when) in (Phase.OPEN_AUCTION_LOCKED, Phase.CLOSING_AUCTION)
+
+
+def is_continuous(when, code: str = "600000") -> bool:
+    """此刻是否处于连续竞价（含沪市尾段）。"""
+    return phase_at(code, when) in (Phase.MORNING, Phase.AFTERNOON, Phase.SH_CLOSE_RUN)
+
+
+def can_cancel(when, code: str = "600000") -> bool:
+    """此刻未成交委托能否撤单（9:20-9:25 集合竞价锁定段不可撤；收盘集合竞价可撤?）。
+
+    现行规则：开盘集合竞价 9:20-9:25 不可撤；收盘集合竞价（深/北）14:57-15:00
+    **不可撤**；盘后固定价格交易申报可撤（15:30 前）。静默期 9:25-9:30 可撤。
+    """
+    p = phase_at(code, when)
+    return p not in (Phase.OPEN_AUCTION_LOCKED, Phase.CLOSING_AUCTION)
+
+
+PHASE_LABEL = {
+    Phase.PRE_OPEN: "开盘集合竞价(可撤)", Phase.OPEN_AUCTION_LOCKED: "开盘集合竞价(不可撤)",
+    Phase.OPEN_AUCTION_IDLE: "申报静默期", Phase.MORNING: "上午连续竞价",
+    Phase.LUNCH: "午间休市", Phase.AFTERNOON: "下午连续竞价",
+    Phase.CLOSING_AUCTION: "收盘集合竞价(不可撤)", Phase.SH_CLOSE_RUN: "沪市尾段连续竞价",
+    Phase.POST_FIXED: "盘后固定价格交易", Phase.LUNCH_AUCTION_IDLE: "午间静默",
+    Phase.CLOSED: "非交易时段",
+}
+
+__all__ = ["Phase", "PHASE_LABEL", "phase_at", "is_auction", "is_continuous",
+           "can_cancel", "SZ_CLOSING_AUCTION_START"]

dbl_common/vec.py

@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+"""vec.py — numpy 向量化判定层（涨跌停引擎唯一实现）。
+
+**2026-09-27 起（market_common 并入 dbl_common）本模块是涨跌停向量化判定的
+唯一引擎**：原 dbl_common.price_limit 内嵌的同名引擎（candidate_pcts/
+exact_pcts 元组签名）已并入此处统一为 spec 驱动签名，避免两套引擎口径漂移。
+
+全市场回测（5000+ 只 × 数千日）必须向量化，逐股循环太慢。本层把
+`price_limit` 的纯标量规则翻译成 numpy 面板操作（接口语义与 GMD
+`app/datasources/price_limit.py` 的 `flags_from_bars`/`limit_prices`
+同构——经 200+ 轮实盘/回测验证的算法，独立改写）。
+
+核心算法（为什么能跨除权日算对）：
+    调后前收盘 = round_half_up( raw_close[t] / (1 + hfq_ret[t]) , 2)
+    涨停价     = round_half_up( 调后前收盘 × (1 + pct) , 2)
+`hfq_ret` 为后复权真实收益率（除权跳空已被复权消除）——不复权价的
+「前收盘」在除权日会跳空，直接 close/prev_close 会把除权跳空误判成跌停。
+"""
+from __future__ import annotations
+
+from typing import Dict, Optional, Sequence
+
+import numpy as np
+
+from .price_limit import (CENT_TOL, EPS, LIMIT_ERA_START, LimitSpec,
+                           limit_spec, price_decimals)
+
+FLAG_COLS = ("up_touch", "dn_touch", "up_close", "dn_close",
+             "up_open", "dn_open")
+
+
+def round_half_up_arr(x: np.ndarray, decimals: int = 2) -> np.ndarray:
+    """向量化 half-up 舍入（交易所算板价口径；不是 np.round 的银行家舍入）。"""
+    f = 10.0 ** int(decimals)
+    return np.floor(np.asarray(x, dtype=np.float64) * f + 0.5) / f
+
+
+def limit_prices(raw_close: np.ndarray, hfq_ret: np.ndarray,
+                 limit_pct: float) -> tuple:
+    """(涨停价, 跌停价) 数组——由不复权收盘 + 后复权收益率反推调后前收盘。"""
+    rc = np.asarray(raw_close, dtype=np.float64)
+    ret = np.asarray(hfq_ret, dtype=np.float64)
+    with np.errstate(invalid="ignore", divide="ignore"):
+        adj_prev = round_half_up_arr(
+            np.where(np.isfinite(ret) & (ret > -0.999), rc / (1.0 + ret), np.nan))
+        up = round_half_up_arr(adj_prev * (1.0 + float(limit_pct)))
+        dn = round_half_up_arr(adj_prev * (1.0 - float(limit_pct)))
+    return up, dn
+
+
+def flags_from_bars(dates: Sequence[str], raw_open, raw_high, raw_low,
+                    raw_close, hfq_ret, spec: LimitSpec,
+                    decimals: Optional[int] = None) -> Dict[str, np.ndarray]:
+    """六态涨跌停标记（纯数组运算，无 IO）。
+
+    Args:
+        dates: "YYYY-MM-DD" 序列。
+        raw_*: 不复权 OHLC（判板唯一正确口径）。
+        hfq_ret: 后复权真实收益率（首日/缺值 NaN → 该日不判）。
+        spec: `limit_spec()` 的判定结果（候选幅度 + 精确档）。
+        decimals: 报价位数（None = 自动按 2 处理；ETF/转债请传 3）。
+
+    Returns:
+        {col: bool数组}——up/dn × touch(盘中触及)/close(收盘封板)/open(开盘即板)。
+    """
+    n = len(dates)
+    op = np.asarray(raw_open, dtype=np.float64)
+    hi = np.asarray(raw_high, dtype=np.float64)
+    lo = np.asarray(raw_low, dtype=np.float64)
+    cl = np.asarray(raw_close, dtype=np.float64)
+    out = {k: np.zeros(n, dtype=bool) for k in FLAG_COLS}
+    if spec.unlimited or not spec.candidates:
+        return out
+
+    dec = int(decimals) if decimals is not None else 2
+    # 精确档容差按报价位数缩放（CENT_TOL 是「分」口径）
+    tol = CENT_TOL * (10.0 ** (2 - dec)) if dec <= 2 else CENT_TOL / (10.0 ** (dec - 2))
+
+    for up_pct, dn_pct, exact in spec.candidates:
+        up, _ = limit_prices(cl, hfq_ret, up_pct)
+        _, dn = limit_prices(cl, hfq_ret, dn_pct)
+        ok = (np.isfinite(up) & np.isfinite(dn) & np.isfinite(op)
+              & np.isfinite(hi) & np.isfinite(lo) & np.isfinite(cl))
+        if exact:
+            out["up_open"] |= ok & (np.abs(op - up) <= tol)
+            out["up_touch"] |= ok & (np.abs(hi - up) <= tol)
+            out["up_close"] |= ok & (np.abs(cl - up) <= tol)
+            out["dn_open"] |= ok & (np.abs(op - dn) <= tol)
+            out["dn_touch"] |= ok & (np.abs(lo - dn) <= tol)
+            out["dn_close"] |= ok & (np.abs(cl - dn) <= tol)
+        else:
+            out["up_open"] |= ok & (op >= up - EPS)
+            out["up_touch"] |= ok & (hi >= up - EPS)
+            out["up_close"] |= ok & (cl >= up - EPS)
+            out["dn_open"] |= ok & (op <= dn + EPS)
+            out["dn_touch"] |= ok & (lo <= dn + EPS)
+            out["dn_close"] |= ok & (cl <= dn + EPS)
+
+    for i, d in enumerate(dates):                       # 制度起点之前不判
+        if str(d) < LIMIT_ERA_START:
+            for k in FLAG_COLS:
+                out[k][i] = False
+    return out
+
+
+def hfq_ret_on(hfq_close: np.ndarray) -> np.ndarray:
+    """由（按日期对齐好的）后复权收盘算真实收益率；缺值处为 NaN（→ 该日不判）。
+
+    2026-09-27 随 market_common 并入时从原 dbl_common.price_limit 引擎迁入
+    （向量化判定统一在本模块，price_limit 只留标量规则）。
+    """
+    hc = np.asarray(hfq_close, dtype=np.float64)
+    with np.errstate(invalid="ignore", divide="ignore"):
+        out = np.full(hc.size, np.nan)
+        out[1:] = hc[1:] / hc[:-1] - 1.0
+    return out
+
+
+def board_flags(code: str, dates: Sequence[str], raw_open, raw_high,
+                raw_low, raw_close, hfq_ret, **kw) -> Dict[str, np.ndarray]:
+    """单只标的一站式：`limit_spec` + `flags_from_bars`（常用便捷入口）。
+
+    ⚠️ 一个 spec 对应**一个制度档位**——若 `dates` 跨越制度变更日（如创业板
+    2020-08-24 的 10%→20%、ST 状态变化），必须**分段调用再拼接**，否则整段
+    按单一档位判（GMD 的做法：逐段算完取并集/覆盖，别偷懒一次算完）。
+    """
+    spec = kw.pop("spec", None) or limit_spec(
+        code, str(dates[0]) if dates else None, **kw)
+    return flags_from_bars(dates, raw_open, raw_high, raw_low, raw_close,
+                           hfq_ret, spec, decimals=price_decimals(code))
+
+
+__all__ = ["FLAG_COLS", "round_half_up_arr", "limit_prices",
+           "flags_from_bars", "board_flags", "hfq_ret_on"]