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

data_backtest_live_common-0.2.0.dist-info/METADATA

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: data-backtest-live-common
+Version: 0.2.0
+Summary: 数据(Data)/回测(Backtest)/实盘(Live)三系统公共库：复权、A股交易规则全集（涨跌幅/时段/费用/交收/熔断/除权）、交易日历、原子写、无黑窗子进程
+Author: dbl_common maintainers
+License: MIT License
+        
+        Copyright (c) 2026 data-backtest-live-common contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Keywords: quant,data,backtest,live-trading,a-share,tushare,akshare
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: numpy
+Requires-Dist: duckdb
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# data-backtest-live-common（导入名 `dbl_common`）
+
+数据（Data）/ 回测（Backtest）/ 实盘（Live Trading）三个系统**共用**的公共库。
+独立项目，像 akshare 一样 pip 安装后直接 import 使用。
+
+- **发行名（pip 名）**：`data-backtest-live-common` —— 数据/回测/实盘三个英文单词 + common（用户 2026-09-26 指定口径）
+- **导入名**：`dbl_common` —— 三词首字母 + common（对齐 `beautifulsoup4 → import bs4` 的短名惯例，免得每次 import 敲 24 个字符）
+- **版本**：0.2.0 —— 2026-09-26 从 `quant_data_center/common` 抽出独立成库；**2026-09-27 并入原 `market_common`（A 股交易规则库）两库合一**，`f:/code/finance/market_common` 内容已全部迁入本库并停止维护（原目录删除被环境安全删除守卫拦截，只剩弃用标记，可随时人工删除）
+
+## 收录标准（硬规则）
+
+只收「**数据、回测、实盘三个系统都会用到**」的代码。
+单系统专属的公共代码放回各系统自己的 common 包
+（例如 quant_data_center 的 throttle 限频 / pagination 翻页是采集专属，留在那边）。
+
+## 模块清单
+
+| 模块 | 干什么 | 三系统各自的用途 |
+|---|---|---|
+| `adjust` | 本地复权引擎（hfq = raw×adj_factor 锚定上市日；qfq 锚定最新） | 数据：清洗层标准化；回测：价格连续序列；实盘：指标口径 |
+| `boards` | 证券代码规范化 / 品种识别 / 板块判定（规则库最底层，纯函数零依赖） | 所有系统问「这代码是什么品种、哪个板块」 |
+| `price_limit` | 涨跌停**规则全集**（主板/科创/创业/北交/ST/ETF/转债/B股/新股首日非对称档，含历史制度变更，返回 `LimitSpec` 值对象） | 数据：审核规则；回测：判板；实盘：委托价边界 |
+| `vec` | 涨跌停**向量化引擎唯一实现**（`limit_prices`/`flags_from_bars`/`board_flags`/`hfq_ret_on`，spec 驱动，支持 ETF 三位报价） | 回测全市场判板（5000+ 只 × 数千日） |
+| `trade_calendar` | 交易日历读取（Tushare cal Parquet；`cal_glob` 必传，不绑定任何系统路径） | 三系统同一套日历口径 |
+| `trading_calendar` | 交易日历**注入契约**（`InjectedCalendar`：BaoStock CSV / QDC raw 层 Parquet，三态诚实） | 回测/实盘注入自己的日历数据源 |
+| `trading_hours` | 交易时段（集合竞价/连续竞价/收盘集合竞价，`Phase` 枚举） | 实盘下单时段校验；回测撮合时点 |
+| `settlement` | 交收制度（T+1/T+0/T+3，`STOCK_T1_START`） | 实盘可卖判断；回测成交约束 |
+| `lots` / `ticks` | 申报单位（手数）/ 最小变动价位（含 snap/校验） | 实盘委托合法性；回测撮合精度 |
+| `fees` | 交易费用（印花税/过户费**时间线**，佣金必显式传） | 回测净收益；实盘成本预估 |
+| `circuit_breaker` | 2016 熔断制度（历史触发记录） | 回测跨 2016-01 必须剔除熔断时段 |
+| `halts` | 盘中临时停牌（新股/转债临停规则与复牌时间） | 回测撮合跳过临停；实盘委托拦截 |
+| `corporate_actions` | 除权除息参考价官方公式 + 理论因子跳变 + 数据中心核验入口（容差 0.5%；B股/转债拒答） | 数据：dividend 对账；回测：复权核验 |
+| `proc` | 子进程无黑窗（`no_window`/`no_window_if_detached`/`pid_alive`，Windows） | 任何会起子进程的系统（调度/并行网格/网关进程） |
+| `io_utils` | 原子写文件（tmp + os.replace + WinError5 重试） | 任何写「会被并发读」的状态/数据文件的系统 |
+
+依赖：`pandas` / `numpy` / `duckdb`（pip install 自动拉齐；已有这些包的系统可加 `--no-deps`）。
+
+## 安装（三种姿势）
+
+```bash
+# ① 开发期（editable：改源码立即生效，无需重装）
+"D:\Program Files\Python314\python.exe" -m pip install -e f:/code/finance/data-backtest-live-common --no-deps
+
+# ② 正式（打 wheel 安装）
+python -m pip wheel . --no-deps -w dist
+python -m pip install dist/data_backtest_live_common-0.2.0-py3-none-any.whl
+
+# ③ 未来发布 PyPI 后（像 akshare 一样）
+pip install data-backtest-live-common
+```
+
+quant_data_center 当前用姿势 ①（editable，装在 `D:\Program Files\Python314` 解释器上，
+tests / uvicorn / scheduler 子进程全部可见）。
+
+## 开发与测试
+
+```bash
+# 需要解释器里有 pandas / numpy / duckdb / pytest（vendor PYTHONPATH 或已 pip 安装）
+$env:PYTHONPATH = "F:\code\finance\quant_data_center\vendor"
+"D:\Program Files\Python314\python.exe" -m pytest tests -q
+```
+
+## 诚实边界
+
+- `trade_calendar` 只读「已经落盘的日历 Parquet」，不联网、不猜测：文件缺失返回 `[]` 由调用方降级；**参数（cal_glob）缺失直接 ValueError**（程序员错误必须响亮）；
+- `price_limit` 的 ST 判定只有当前名单、没有逐日历史 → 5% 档用「恰好贴板」精确判定（详见模块 docstring 的血泪教训：用 `≥` 会把普通涨超 5% 的交易日成片误判）；
+- `adjust` 的 hfq 锚定上市日（历史行永不变，适合增量落盘），qfq 锚定最新（历史随分红改写，只适合展示）；
+- 1996-12-16 之前 A 股无涨跌停制度，`vec.flags_from_bars` 一律不判；
+- `corporate_actions` 对 B 股（需当日汇率折算，属运行期数据非规则）与可转债（不除权）显式 raise 拒答，不猜；
+- 新股「首 N 日不设涨跌幅」没有交易日序号时按自然日近似，`reason` 里如实标注「近似」。
+
+## 与兄弟项目的关系（互不 import）
+
+| 项目 | 定位 | 关系 |
+|---|---|---|
+| `quant_data_center` | 数据系统 | 本库母体；现为 pip 依赖 `dbl_common` |
+| 回测 / 实盘系统（未来） | — | 直接 `pip install` 本库即可（原需另装 market_common，2026-09-27 已并入） |
+
+> **两库合一记录（2026-09-27）**：用户对比本库与 `market_common` 后指令「如有重复删除
+> market」。实测仅 `price_limit` 领域同源重复（本库=引擎+简化规则，market=规则全集），
+> 其余 10 个交易规则模块是独有内容 → **整体并入**：`price_limit` 取超集版（含
+> `round_half_up` 浮点修正），向量化引擎统一进 `vec.py`（spec 驱动签名），83 项守卫
+> 测试随迁为 `tests/test_trading_rules.py`，原 market_common 目录弃用（AI 删除时被环境
+> 安全删除守卫拦截，内容已 100% 迁入本库并经测试验证，该目录可随时人工删除）。
+
+## 怎么加新模块（给 AI 的守则）
+
+1. 先判定「三个系统都用到吗」——不是就放回各系统自己的 common，别塞进来；
+2. 纯函数优先、零系统路径耦合（需要路径/配置就做成必传参数，参照 `trade_calendar.cal_glob`）；
+3. 配 `tests/` 用例，锚点用真实制度事实（如创业板 2020-08-24 改 20%、round_half_up(2.675)=2.68）；
+4. 版本号 +1（`pyproject.toml` 与 `dbl_common/__init__.py` 同步改），更新本 README 模块表；
+5. Windows 环境跑命令一律后台无窗（`Start-Process -WindowStyle Hidden`）。

data_backtest_live_common-0.2.0.dist-info/RECORD

@@ -0,0 +1,22 @@
+data_backtest_live_common-0.2.0.dist-info/licenses/LICENSE,sha256=B01Wsyf9hVVsEvHxNQOkawcuyLt2jZwkJPJnmOTwn7I,1116
+dbl_common/__init__.py,sha256=MkNAeU8OQuFHdvScjuh5F4wjwqZJSmN6Wiya6aWfV1I,5769
+dbl_common/adjust.py,sha256=V8aRJatuGo_p0CtPZtuVUIZA2gBpavRxvtKHg89QV10,3305
+dbl_common/boards.py,sha256=zAij-SQF7WdvzymNeyxgAge3DS6GdsKGEFHzR7-7x4o,7203
+dbl_common/circuit_breaker.py,sha256=mNfBzeRBhpucjccczH9w6qPqg2sl-4CoLr39p2yB7sM,4029
+dbl_common/corporate_actions.py,sha256=mrWuYcNwHJdf34C5g36BVQNgb4zMkF7N4MHx8u-LNQw,8061
+dbl_common/fees.py,sha256=OlV0eayw48GV8dpClGi9caWQ26c8DqF_xq950-aOxoo,8083
+dbl_common/halts.py,sha256=ngJnCBZ0wN_LQUM_VgUwcHRuvtDR9vsNDXP1Z03z35Y,9070
+dbl_common/io_utils.py,sha256=a6Dx-UKRE4XCkxrLoexy4O7UXQ5RBxbDSbJvfc9GNhE,3162
+dbl_common/lots.py,sha256=xy_rX3sHNYP-7DDdsCyA-6tQGSuULN5u54uZN0rPQns,5403
+dbl_common/price_limit.py,sha256=vAxDt0fuwv7OQrKKJ6etDbCzCyCSDEkZqfHKanu_EkY,16993
+dbl_common/proc.py,sha256=mrMeL7l0z-PrOZmtCcCM9KFk0JysgFBMpyxrIl076ZM,6024
+dbl_common/settlement.py,sha256=TTmYS20MoXylCywg4Xshv3ZMoRuA5c6sAWXO0Gf4qfo,5219
+dbl_common/ticks.py,sha256=MjGy8v6LqNkr69D5tgvVXArSSkKxwKhHt0dwg5WFXRk,2376
+dbl_common/trade_calendar.py,sha256=638u9bkIsVuhs8jhc7Jj2O1hOGUYqd8UDrIOLESI0bw,5046
+dbl_common/trading_calendar.py,sha256=LMROwgyD_PPgAca1ntnowFnkikbKSiBl_QnLlrgER8U,8470
+dbl_common/trading_hours.py,sha256=5EiCUmAZAZsWTJin28nHqukYTesXxF0kzM1tEGWQqA0,7151
+dbl_common/vec.py,sha256=K9vgYhOJLGXhDQMGtJXzQtR0sTKpittQCOMIYouZ1X0,6452
+data_backtest_live_common-0.2.0.dist-info/METADATA,sha256=gyj0x4LTgC9hFrpUryPtWxcYYTXSj9-Vsnq79EwYBqg,9854
+data_backtest_live_common-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+data_backtest_live_common-0.2.0.dist-info/top_level.txt,sha256=dDBhJoMO_TN-iJxJE2lF2FYZ_V2RViuA60QOhSPzq-A,11
+data_backtest_live_common-0.2.0.dist-info/RECORD,,

data_backtest_live_common-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

data_backtest_live_common-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 data-backtest-live-common contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data_backtest_live_common-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+dbl_common

dbl_common/__init__.py

@@ -0,0 +1,93 @@
+# -*- coding: utf-8 -*-
+"""dbl_common — 数据 / 回测 / 实盘 三系统公共库（Data Backtest Live Common）
+
+命名口径（用户 2026-09-26 指定）：
+  · 发行名（pip 名）= 数据/回测/实盘三个英文单词 + common → ``data-backtest-live-common``；
+  · 导入名 = 三词首字母 + common → ``dbl_common``（对齐 beautifulsoup4 → ``import bs4``
+    的短名惯例，避免每次 import 敲 24 个字符）。
+
+收录标准（硬规则）：**只收「数据、回测、实盘三个系统都会用到」的代码**；
+单系统专属的公共代码放回各系统自己的 common 包（如 quant_data_center 的
+throttle 限频 / pagination 翻页是采集专属，留在那边，不进本库）。
+
+模块清单（2026-09-27 起 = 原 market_common 交易规则库整体并入，两库合一）：
+- adjust           : 本地复权引擎（hfq = raw × adj_factor，锚定上市日，增量追加安全）
+- boards           : 证券代码规范化 / 品种识别 / 板块判定（规则库最底层，纯函数零依赖）
+- price_limit      : 涨跌停规则全集（主板/科创/创业/北交/ST/ETF/转债/B股/新股首日，含历史制度变更）
+- vec              : numpy 向量化涨跌停引擎（limit_prices / flags_from_bars / board_flags / hfq_ret_on）
+- trade_calendar   : 交易日历（Tushare cal Parquet 读取；cal_glob 必传，不绑定任何系统路径）
+- trading_calendar : 交易日历注入契约（InjectedCalendar：BaoStock CSV / QDC raw 层 Parquet）
+- trading_hours    : 交易时段（集合竞价 / 连续竞价 / 收盘集合竞价）
+- settlement       : 交收制度（T+1 / T+0 / T+3）
+- lots / ticks     : 申报单位（手数）/ 价位（最小变动价位）
+- fees             : 交易费用（印花税 / 过户费时间线；佣金必显式传）
+- circuit_breaker  : 2016 熔断制度
+- halts            : 盘中临时停牌（新股 / 转债临停）
+- corporate_actions: 除权除息参考价官方公式 + 理论因子跳变 + 数据中心核验入口
+- proc             : 子进程无黑窗唯一实现（no_window / no_window_if_detached / pid_alive）
+- io_utils         : 原子写文件（atomic_write_text / atomic_write_bytes，tmp+os.replace+重试）
+
+历史：
+  · 2026-09-26 从 quant_data_center/common 抽出独立成库（adjust/price_limit/
+    trade_calendar/proc/io_utils 五模块）；
+  · 2026-09-27 用户指令「两库如有重复则删除 market」→ 实测仅 price_limit 领域
+    同源重复（规则超集 + 引擎），其余 10 个交易规则模块为本库没有的独有内容 →
+    **整体并入**（price_limit 取超集版 + round_half_up 浮点修正；引擎统一进
+    vec.py；83 项守卫测试随迁为 tests/test_trading_rules.py），market_common
+    目录删除。再往前溯源是 global_market_dashboard 的成熟代码「复制适配」。
+"""
+from .boards import Board, BOARD_LABEL, SecurityType, board_of, exchange_of, \
+    normalize_code, security_type
+from .price_limit import LimitSpec, limit_spec, round_half_up, \
+    limit_up_price, limit_down_price, price_decimals, candidates_of, \
+    LIMIT_ERA_START, ST_5PCT_START, GEM_20PCT_START, MAIN_REG_START, \
+    MAIN_IPO_4436_START, CB_20PCT_START, CENT_TOL, EPS
+from .trading_hours import Phase, PHASE_LABEL, phase_at, is_auction, \
+    is_continuous, can_cancel
+from .settlement import settle_rule, can_sell_today, STOCK_T1_START
+from .lots import lot_rule, validate_qty
+from .ticks import tick_size, snap_to_tick, is_valid_price
+from .fees import FeeResult, calc_fees, stamp_tax, transfer_fee_rate, \
+    commission_cap, stamp_tax_timeline
+from .circuit_breaker import is_active as cb_is_active, market_state as cb_state, \
+    CB_START, CB_END, LEVEL1, LEVEL2, HISTORICAL_TRIGGERS
+from .halts import HaltRule, intraday_halt_rule, resume_time, halt_price
+from .trading_calendar import InjectedCalendar, from_baostock_csv, \
+    from_parquet_dataset, weekend_is_trading_day, weekend_next_trading_day, \
+    weekend_prev_trading_day
+from .corporate_actions import CorporateAction, from_per_ten, \
+    ex_right_price, factor_jump, validate_against_factor, check_applicable
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # boards
+    "Board", "BOARD_LABEL", "SecurityType", "board_of", "exchange_of",
+    "normalize_code", "security_type",
+    # price_limit
+    "LimitSpec", "limit_spec", "round_half_up", "limit_up_price",
+    "limit_down_price", "price_decimals", "candidates_of",
+    "LIMIT_ERA_START", "ST_5PCT_START", "GEM_20PCT_START", "MAIN_REG_START",
+    "MAIN_IPO_4436_START", "CB_20PCT_START", "CENT_TOL", "EPS",
+    # trading_hours
+    "Phase", "PHASE_LABEL", "phase_at", "is_auction", "is_continuous", "can_cancel",
+    # settlement
+    "settle_rule", "can_sell_today", "STOCK_T1_START",
+    # lots / ticks
+    "lot_rule", "validate_qty", "tick_size", "snap_to_tick", "is_valid_price",
+    # fees
+    "FeeResult", "calc_fees", "stamp_tax", "transfer_fee_rate",
+    "commission_cap", "stamp_tax_timeline",
+    # circuit breaker
+    "cb_is_active", "cb_state", "CB_START", "CB_END", "LEVEL1", "LEVEL2",
+    "HISTORICAL_TRIGGERS",
+    # halts（盘中临时停牌）
+    "HaltRule", "intraday_halt_rule", "resume_time", "halt_price",
+    # calendar（注入契约；Tushare cal Parquet 读取见 dbl_common.trade_calendar）
+    "InjectedCalendar", "from_baostock_csv", "from_parquet_dataset",
+    "weekend_is_trading_day", "weekend_next_trading_day",
+    "weekend_prev_trading_day",
+    # corporate actions（除权除息参考价）
+    "CorporateAction", "from_per_ten", "ex_right_price", "factor_jump",
+    "validate_against_factor", "check_applicable",
+]

dbl_common/adjust.py

@@ -0,0 +1,74 @@
+# -*- coding: utf-8 -*-
+"""dbl_common.adjust — 本地复权引擎（数据/回测/实盘共用）
+
+溯源：global_market_dashboard tushare_fetcher.compute_hfq →
+quant_data_center/common/adjust.py → 2026-09-26 抽入本独立库（内容不变）。
+
+核心设计（为什么锚定上市日、而不是「÷ 最新因子」锚定最新）：
+  adj_factor 的历史值**永不回改**（新分红只抬高未来行的因子），
+  所以 hfq 的历史行也永不变 —— 增量追加天然安全。
+  若锚定最新，每次分红都会改写全部历史，合并接缝处必出人工断崖。
+
+连续性保证：除权日 raw 跳空、因子同幅度反向跳变，乘积天然连续 ——
+这就是 92 只 known-list 断崖（sina/腾讯因子基准漂移）的治本项。
+"""
+from __future__ import annotations
+
+import pandas as pd
+
+
+def compute_hfq(daily_df: pd.DataFrame, factor_df: pd.DataFrame) -> pd.DataFrame:
+    """本地后复权引擎：**hfq = raw × adj_factor**（锚定上市日）。
+
+    Args:
+        daily_df: 日线表，需含 date + OHLC 列
+        factor_df: 复权因子表，需含 date + adj_factor 列
+
+    Returns:
+        合并后的 DataFrame，OHLC 已乘上 adj_factor（后复权）；
+        因子缺失/非法（≤0）的行 OHLC 置 NaN 如实缺失（不冒充数据），
+        该行仍保留（volume/amount 是真实成交，不因价格缺失而丢）。
+    """
+    if daily_df is None or daily_df.empty:
+        return daily_df
+    m = daily_df.copy()
+    if factor_df is None or factor_df.empty:
+        for c in ("open", "high", "low", "close"):
+            if c in m.columns:
+                m[c] = float("nan")
+        m["adj_factor"] = float("nan")
+        return m
+    f = factor_df[["date", "adj_factor"]].copy()
+    f["adj_factor"] = pd.to_numeric(f["adj_factor"], errors="coerce")
+    m = m.merge(f, on="date", how="left").sort_values(
+        "date", kind="stable").reset_index(drop=True)
+    # 因子与日线同为逐交易日行，merge 应 1:1；个别日期缺因子时用前一交易日
+    # 因子兜底（因子在除权日之间保持不变，ffill 语义正确）。
+    m["adj_factor"] = m["adj_factor"].ffill()
+    bad = m["adj_factor"].isna() | (m["adj_factor"] <= 0)
+    for c in ("open", "high", "low", "close"):
+        if c in m.columns:
+            v = pd.to_numeric(m[c], errors="coerce") * m["adj_factor"]
+            m[c] = v.mask(bad)
+    return m
+
+
+def compute_qfq(daily_df: pd.DataFrame, factor_df: pd.DataFrame) -> pd.DataFrame:
+    """本地前复权引擎：**qfq = raw × adj_factor ÷ 最新 adj_factor**（锚定最新价）。
+
+    与 hfq 的区别：锚定最新价，历史行会随新分红而改写。
+    适合「按最新价看历史」的展示场景，不适合增量落盘（接缝会断）。
+    """
+    m = compute_hfq(daily_df, factor_df)
+    if m is None or m.empty or "adj_factor" not in m.columns:
+        return m
+    valid = m["adj_factor"].dropna()
+    if valid.empty:
+        return m
+    latest = valid.iloc[-1]
+    if latest <= 0:
+        return m
+    for c in ("open", "high", "low", "close"):
+        if c in m.columns:
+            m[c] = pd.to_numeric(m[c], errors="coerce") / latest
+    return m

dbl_common/boards.py

@@ -0,0 +1,162 @@
+# -*- coding: utf-8 -*-
+"""boards.py — 证券代码规范化 / 品种识别 / 板块判定（公共模块 · 纯函数零依赖）。
+
+为什么必须在公共模块最底层
+--------------------------
+回测、实盘、模拟盘、数据中心都会问同一个问题：「这只代码是什么品种、哪个板块、
+适用哪套规则」。各系统各写一份就会口径漂移（GMD 项目实测：同一交易日历被写成
+5 份、同一涨跌停规则被写成 2 份说法）。本模块是**唯一真相源**。
+
+设计约定
+--------
+· **纯函数 + 零第三方依赖**：只用标准库，任何系统 vendor / sys.path 直接可用。
+· **诚实边界**：代码前缀只能给出「最可能」的判定，无法识别的返回 None 并说明，
+  绝不猜。特别地：6 位代码 000001 既可能是上证指数也可能是平安银行——
+  **不带交易所信息时一律按股票处理**，跟踪指数的调用方必须显式传
+  `security_type=INDEX`。
+· 与时间相关的板块规则（如创业板 2020-08-24 注册制改革）不在本模块判定，
+  见 `price_limit.py`（板块归属是静态的，制度是随时间变的——分开管）。
+
+代码前缀事实表（沪深交易所公开规则，2026 年口径）
+------------------------------------------------
+· 60xxxx      沪市主板 A 股        00xxxx  深市主板 A 股（000/001/002/003）
+· 300/301     深市创业板           688/689 沪市科创板
+· 43/83/87/88/92  北交所（2021-11-15 开市，由新三板精选层平移）
+· 900xxx 沪 B / 200xxx 深 B
+· ETF：沪 51x/56x/58x（588=科创板ETF）；深 15x（159=股票ETF 等）
+· LOF：沪 501/502；深 16x
+· 可转债：沪 11x（110/111/113/118）；深 12x（123/127/128）
+· 国债逆回购：沪 204xxx；深 1318xx
+· 封闭式基金/其他：沪 50xxxx 等
+"""
+from __future__ import annotations
+
+import enum
+from typing import Optional
+
+
+class SecurityType(enum.Enum):
+    """品种大类（决定涨跌幅/交收/手数/价位整套规则）。"""
+
+    STOCK = "stock"          # A 股股票（含各板块）
+    B_SHARE = "b_share"      # B 股
+    INDEX = "index"          # 指数（无涨跌幅限制）
+    ETF = "etf"              # 交易型开放式指数基金
+    LOF = "lof"              # 上市开放式基金
+    CONVERTIBLE_BOND = "cb"  # 可转换公司债券
+    REPO = "repo"            # 国债逆回购（质押式回购）
+    FUND_OTHER = "fund_other"  # 封基/其他场内基金
+    UNKNOWN = "unknown"
+
+
+class Board(enum.Enum):
+    """交易板块（股票类适用；决定涨跌幅档位与申报单位）。"""
+
+    MAIN_SH = "main_sh"      # 沪市主板（60）
+    MAIN_SZ = "main_sz"      # 深市主板（000/001/002/003）
+    GEM = "gem"              # 创业板（300/301，2009-10-30 开市）
+    STAR = "star"            # 科创板（688/689，2019-07-22 开市）
+    BSE = "bse"              # 北交所（2021-11-15 开市）
+    B_SHARE = "b_share"      # B 股（900 沪 / 200 深）
+    NONE = "none"            # 非股票类
+
+
+def normalize_code(code) -> str:
+    """任意常见代码形态 → 6 位数字字符串。
+
+    `sh600660` / `600660.SS` / `600660.SH` / `600660` / `sh.600660` → `600660`。
+    B 股 / 北交所同样归一到 6 位。非数字字符全部剔除后取末 6 位（前导补零）。
+    """
+    s = str(code).strip().upper()
+    for pre in ("SH", "SZ", "BJ"):
+        if s.startswith(pre):
+            s = s[len(pre):]
+    s = s.lstrip(".").split(".")[0]     # "SH.600519"→"600519"；"600519.SS"→"600519"
+    digits = "".join(ch for ch in s if ch.isdigit())
+    if not digits:
+        return ""
+    return digits.zfill(6)[-6:]
+
+
+def exchange_of(code) -> Optional[str]:
+    """尽量识别交易所：`SH` / `SZ` / `BJ` / None（判不了就 None，不猜）。
+
+    只对**前缀能唯一定位**的代码可靠（60/68/90/51/56/58/11/20x→SH；
+    00/30/15/12/1318→SZ；43/83/87/88/92→BJ）。000001 这类深市前缀若调用方
+    实际跟踪的是沪指数，请显式传参，本函数管不了语义。
+    """
+    c = normalize_code(code)
+    if not c:
+        return None
+    if c[:2] in ("60", "68") or c[:3] in ("900", "510", "511", "512", "513",
+                                          "515", "516", "517", "518", "560",
+                                          "561", "562", "563", "588", "589",
+                                          "110", "111", "113", "118", "204",
+                                          "501", "502", "506", "588"):
+        return "SH"
+    if c[:2] in ("00", "30", "15", "16", "20") or c[:3] in ("123", "127", "128") \
+            or c[:4] == "1318":
+        return "SZ"
+    if c[:2] in ("43", "83", "87", "88", "92"):
+        return "BJ"
+    return None
+
+
+def security_type(code, explicit: Optional[SecurityType] = None) -> SecurityType:
+    """品种大类。`explicit` 优先（调用方明确知道时别让前缀猜）。"""
+    if explicit is not None:
+        return explicit
+    c = normalize_code(code)
+    if not c:
+        return SecurityType.UNKNOWN
+    if c[:3] in ("900",):
+        return SecurityType.B_SHARE
+    if c[:3] == "200":
+        return SecurityType.B_SHARE
+    if c[:3] in ("510", "511", "512", "513", "515", "516", "517", "518",
+                 "560", "561", "562", "563", "588", "589", "159"):
+        return SecurityType.ETF
+    if c[:3] in ("501", "502", "160", "161", "162", "163", "164", "165",
+                 "166", "167", "168"):
+        return SecurityType.LOF
+    if c[:3] in ("110", "111", "113", "118", "123", "127", "128"):
+        return SecurityType.CONVERTIBLE_BOND
+    if c[:3] == "204" or c[:4] == "1318":
+        return SecurityType.REPO
+    if c[:3] == "505" or c[:2] == "50":
+        return SecurityType.FUND_OTHER
+    if c[:2] in ("60", "00", "30", "68") or c[:3] in ("688", "689") \
+            or c[:2] in ("43", "83", "87", "88", "92"):
+        return SecurityType.STOCK
+    return SecurityType.UNKNOWN
+
+
+def board_of(code, explicit_type: Optional[SecurityType] = None) -> Board:
+    """股票类板块。非股票类返回 `Board.NONE`。"""
+    st = security_type(code, explicit_type)
+    if st != SecurityType.STOCK:
+        return Board.NONE if st != SecurityType.B_SHARE else Board.B_SHARE
+    c = normalize_code(code)
+    if not c:
+        return Board.NONE
+    if c.startswith("688") or c.startswith("689"):
+        return Board.STAR
+    if c.startswith("300") or c.startswith("301"):
+        return Board.GEM
+    if c[:2] in ("43", "83", "87", "88", "92"):
+        return Board.BSE
+    if c[:2] == "60":
+        return Board.MAIN_SH
+    if c[:2] == "00":
+        return Board.MAIN_SZ
+    return Board.NONE
+
+
+BOARD_LABEL = {
+    Board.MAIN_SH: "沪市主板", Board.MAIN_SZ: "深市主板", Board.GEM: "创业板",
+    Board.STAR: "科创板", Board.BSE: "北交所", Board.B_SHARE: "B股",
+    Board.NONE: "非股票类",
+}
+
+__all__ = ["SecurityType", "Board", "BOARD_LABEL", "normalize_code",
+           "exchange_of", "security_type", "board_of"]

dbl_common/circuit_breaker.py

@@ -0,0 +1,82 @@
+# -*- coding: utf-8 -*-
+"""circuit_breaker.py — 指数熔断制度（2016 年实施 4 个交易日后暂停）。
+
+为什么公共模块要收录一段只活了 4 天的制度：**回测要跨 2016 年 1 月**。
+2016-01-04 与 2016-01-07 两天沪深 300 触发 7% 阈值**提前收市**——
+这两天「下午的价格根本不存在」，按全天数据回测撮合就是作弊。
+
+制度原文（指数熔断机制，2016-01-01 起）：
+· 触发基准：沪深 300 指数较前一交易日收盘价；
+· ±5%（一级）：熔断 15 分钟；14:45 及之后触发 → 直接收市；
+· ±7%（二级）：当日直接收市；
+· 两级熔断每交易日最多各触发一次（15:00 前未触发过一级仍可触发）。
+· 2016-01-08 起暂停实施（1月4日、1月7日两度触发二级熔断后连夜暂停）。
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+CB_START = "2016-01-01"
+CB_END = "2016-01-07"           # 实施的最后一个交易日（1月8日起暂停）
+LEVEL1 = 0.05
+LEVEL2 = 0.07
+LEVEL1_HALT_MINUTES = 15
+LEVEL1_CUTOFF = "14:45"         # 此后触发一级 → 直接收市
+
+# 实际触发历史（公开行情事实，回测对账锚点）
+HISTORICAL_TRIGGERS = {
+    "2016-01-04": {"level": 2, "note": "沪深300跌7.02%，13:33 收市"},
+    "2016-01-07": {"level": 2, "note": "沪深300跌7.21%，09:59 收市"},
+    "2016-01-05": {"level": 1, "note": "午后触及-5.03%，熔断15分钟后恢复交易"},
+}
+
+
+def is_active(date: Optional[str]) -> bool:
+    """该交易日熔断制度是否有效（仅 2016-01-01 ~ 2016-01-07）。"""
+    if not date:
+        return False
+    d = str(date)[:10]
+    return CB_START <= d <= CB_END
+
+
+def market_state(date: str, hs300_change_pct: Optional[float],
+                 trigger_time: Optional[str] = None) -> dict:
+    """判定熔断状态（回测撮合闸门用）。
+
+    Args:
+        date: 交易日。
+        hs300_change_pct: 沪深300 当日涨跌幅（较前收，百分数如 -7.02 传 -7.02）；
+            None = 无数据 → 「未判」，调用方必须显式披露，不许当没触发。
+        trigger_time: 触发时点 "HH:MM"（判一级熔断后 14:45 直接收市的分支）。
+
+    Returns:
+        {"active": bool, "halted": bool, "closed_early": bool,
+         "resume_time": "HH:MM"|None, "reason": str}
+    """
+    if not is_active(date):
+        return {"active": False, "halted": False, "closed_early": False,
+                "resume_time": None, "reason": "熔断制度未实施（仅 2016-01-01~01-07）"}
+    if hs300_change_pct is None:
+        return {"active": True, "halted": False, "closed_early": False,
+                "resume_time": None,
+                "reason": "熔断制度有效但沪深300涨跌幅未知——未判，须披露"}
+    chg = float(hs300_change_pct)
+    if chg <= -LEVEL2 * 100 or chg >= LEVEL2 * 100:
+        return {"active": True, "halted": True, "closed_early": True,
+                "resume_time": None,
+                "reason": f"沪深300 {chg:+.2f}% 触及±7%：当日直接收市"}
+    if chg <= -LEVEL1 * 100 or chg >= LEVEL1 * 100:
+        if trigger_time is not None and str(trigger_time)[:5] >= LEVEL1_CUTOFF:
+            return {"active": True, "halted": True, "closed_early": True,
+                    "resume_time": None,
+                    "reason": f"14:45 后触及±5%：直接收市（触发 {trigger_time}）"}
+        return {"active": True, "halted": True, "closed_early": False,
+                "resume_time": None,
+                "reason": f"触及±5%：熔断 15 分钟（trigger={trigger_time}，"
+                          f"恢复时点请调用方按 trigger_time+15m 计算）"}
+    return {"active": True, "halted": False, "closed_early": False,
+            "resume_time": None, "reason": "未触及阈值"}
+
+
+__all__ = ["CB_START", "CB_END", "LEVEL1", "LEVEL2", "is_active",
+           "market_state", "HISTORICAL_TRIGGERS"]