data-backtest-live-common 0.2.0__tar.gz → 0.3.0__tar.gz

{data_backtest_live_common-0.2.0 → data_backtest_live_common-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-backtest-live-common
-Version: 0.2.0
+Version: 0.3.0
 Summary: 数据(Data)/回测(Backtest)/实盘(Live)三系统公共库：复权、A股交易规则全集（涨跌幅/时段/费用/交收/熔断/除权）、交易日历、原子写、无黑窗子进程
 Author: dbl_common maintainers
 License: MIT License
@@ -56,7 +56,7 @@ Dynamic: license-file
 
 - **发行名（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` 内容已全部迁入本库并停止维护（原目录删除被环境安全删除守卫拦截，只剩弃用标记，可随时人工删除）
+- **版本**：0.3.0 —— 2026-09-26 抽出独立成库 → 2026-09-27 并入 market_common 两库合一（0.2.0 上架 PyPI）→ 同日 **0.3.0 费用模块重大勘误**（逐条对照财政部/中登/交易所公告修正佣金封顶、过户费双轨制、印花税历史档）
 
 ## 收录标准（硬规则）
 
@@ -77,7 +77,7 @@ Dynamic: license-file
 | `trading_hours` | 交易时段（集合竞价/连续竞价/收盘集合竞价，`Phase` 枚举） | 实盘下单时段校验；回测撮合时点 |
 | `settlement` | 交收制度（T+1/T+0/T+3，`STOCK_T1_START`） | 实盘可卖判断；回测成交约束 |
 | `lots` / `ticks` | 申报单位（手数）/ 最小变动价位（含 snap/校验） | 实盘委托合法性；回测撮合精度 |
-| `fees` | 交易费用（印花税/过户费**时间线**，佣金必显式传） | 回测净收益；实盘成本预估 |
+| `fees` | 交易费用（印花税 1997 起全时间线 / 过户费 2015 前沪面值深金额双轨 / 佣金法定上限 3‰ / 经手+证管规费，**v0.3.0 逐条对照官方公告勘误**） | 回测净收益；实盘成本预估 |
 | `circuit_breaker` | 2016 熔断制度（历史触发记录） | 回测跨 2016-01 必须剔除熔断时段 |
 | `halts` | 盘中临时停牌（新股/转债临停规则与复牌时间） | 回测撮合跳过临停；实盘委托拦截 |
 | `corporate_actions` | 除权除息参考价官方公式 + 理论因子跳变 + 数据中心核验入口（容差 0.5%；B股/转债拒答） | 数据：dividend 对账；回测：复权核验 |
@@ -94,7 +94,7 @@ Dynamic: license-file
 
 # ② 正式（打 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
+python -m pip install dist/data_backtest_live_common-0.3.0-py3-none-any.whl
 
 # ③ 未来发布 PyPI 后（像 akshare 一样）
 pip install data-backtest-live-common
@@ -117,6 +117,7 @@ $env:PYTHONPATH = "F:\code\finance\quant_data_center\vendor"
 - `price_limit` 的 ST 判定只有当前名单、没有逐日历史 → 5% 档用「恰好贴板」精确判定（详见模块 docstring 的血泪教训：用 `≥` 会把普通涨超 5% 的交易日成片误判）；
 - `adjust` 的 hfq 锚定上市日（历史行永不变，适合增量落盘），qfq 锚定最新（历史随分红改写，只适合展示）；
 - 1996-12-16 之前 A 股无涨跌停制度，`vec.flags_from_bars` 一律不判；
+- `fees`（v0.3.0 勘误后口径）：佣金法定上限 **3‰ 从未变过**（不存在「0.03% 封顶」政策，2002-05-01 前固定佣金时代拒答）；过户费 **2015-08-01 前沪市按面值/深市按金额双轨**（沪 0.5‰→0.375‰→0.3‰ 按面值，深 0.0255‰ 按金额），之后统一按金额 0.02‰→0.01‰；印花税 A 股 1997-05-10 前拒答、B 股 2001-11-16 前拒答；B 股过户费/结算费体系未编码整体拒答；经手费/证管费通常**已含在佣金内**（helper 仅供净佣金分析，ETF/基金经手费未编码返回 None）；
 - `corporate_actions` 对 B 股（需当日汇率折算，属运行期数据非规则）与可转债（不除权）显式 raise 拒答，不猜；
 - 新股「首 N 日不设涨跌幅」没有交易日序号时按自然日近似，`reason` 里如实标注「近似」。
 

{data_backtest_live_common-0.2.0 → data_backtest_live_common-0.3.0}/README.md

@@ -5,7 +5,7 @@
 
 - **发行名（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` 内容已全部迁入本库并停止维护（原目录删除被环境安全删除守卫拦截，只剩弃用标记，可随时人工删除）
+- **版本**：0.3.0 —— 2026-09-26 抽出独立成库 → 2026-09-27 并入 market_common 两库合一（0.2.0 上架 PyPI）→ 同日 **0.3.0 费用模块重大勘误**（逐条对照财政部/中登/交易所公告修正佣金封顶、过户费双轨制、印花税历史档）
 
 ## 收录标准（硬规则）
 
@@ -26,7 +26,7 @@
 | `trading_hours` | 交易时段（集合竞价/连续竞价/收盘集合竞价，`Phase` 枚举） | 实盘下单时段校验；回测撮合时点 |
 | `settlement` | 交收制度（T+1/T+0/T+3，`STOCK_T1_START`） | 实盘可卖判断；回测成交约束 |
 | `lots` / `ticks` | 申报单位（手数）/ 最小变动价位（含 snap/校验） | 实盘委托合法性；回测撮合精度 |
-| `fees` | 交易费用（印花税/过户费**时间线**，佣金必显式传） | 回测净收益；实盘成本预估 |
+| `fees` | 交易费用（印花税 1997 起全时间线 / 过户费 2015 前沪面值深金额双轨 / 佣金法定上限 3‰ / 经手+证管规费，**v0.3.0 逐条对照官方公告勘误**） | 回测净收益；实盘成本预估 |
 | `circuit_breaker` | 2016 熔断制度（历史触发记录） | 回测跨 2016-01 必须剔除熔断时段 |
 | `halts` | 盘中临时停牌（新股/转债临停规则与复牌时间） | 回测撮合跳过临停；实盘委托拦截 |
 | `corporate_actions` | 除权除息参考价官方公式 + 理论因子跳变 + 数据中心核验入口（容差 0.5%；B股/转债拒答） | 数据：dividend 对账；回测：复权核验 |
@@ -43,7 +43,7 @@
 
 # ② 正式（打 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
+python -m pip install dist/data_backtest_live_common-0.3.0-py3-none-any.whl
 
 # ③ 未来发布 PyPI 后（像 akshare 一样）
 pip install data-backtest-live-common
@@ -66,6 +66,7 @@ $env:PYTHONPATH = "F:\code\finance\quant_data_center\vendor"
 - `price_limit` 的 ST 判定只有当前名单、没有逐日历史 → 5% 档用「恰好贴板」精确判定（详见模块 docstring 的血泪教训：用 `≥` 会把普通涨超 5% 的交易日成片误判）；
 - `adjust` 的 hfq 锚定上市日（历史行永不变，适合增量落盘），qfq 锚定最新（历史随分红改写，只适合展示）；
 - 1996-12-16 之前 A 股无涨跌停制度，`vec.flags_from_bars` 一律不判；
+- `fees`（v0.3.0 勘误后口径）：佣金法定上限 **3‰ 从未变过**（不存在「0.03% 封顶」政策，2002-05-01 前固定佣金时代拒答）；过户费 **2015-08-01 前沪市按面值/深市按金额双轨**（沪 0.5‰→0.375‰→0.3‰ 按面值，深 0.0255‰ 按金额），之后统一按金额 0.02‰→0.01‰；印花税 A 股 1997-05-10 前拒答、B 股 2001-11-16 前拒答；B 股过户费/结算费体系未编码整体拒答；经手费/证管费通常**已含在佣金内**（helper 仅供净佣金分析，ETF/基金经手费未编码返回 None）；
 - `corporate_actions` 对 B 股（需当日汇率折算，属运行期数据非规则）与可转债（不除权）显式 raise 拒答，不猜；
 - 新股「首 N 日不设涨跌幅」没有交易日序号时按自然日近似，`reason` 里如实标注「近似」。
 

{data_backtest_live_common-0.2.0 → data_backtest_live_common-0.3.0}/data_backtest_live_common.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: data-backtest-live-common
-Version: 0.2.0
+Version: 0.3.0
 Summary: 数据(Data)/回测(Backtest)/实盘(Live)三系统公共库：复权、A股交易规则全集（涨跌幅/时段/费用/交收/熔断/除权）、交易日历、原子写、无黑窗子进程
 Author: dbl_common maintainers
 License: MIT License
@@ -56,7 +56,7 @@ Dynamic: license-file
 
 - **发行名（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` 内容已全部迁入本库并停止维护（原目录删除被环境安全删除守卫拦截，只剩弃用标记，可随时人工删除）
+- **版本**：0.3.0 —— 2026-09-26 抽出独立成库 → 2026-09-27 并入 market_common 两库合一（0.2.0 上架 PyPI）→ 同日 **0.3.0 费用模块重大勘误**（逐条对照财政部/中登/交易所公告修正佣金封顶、过户费双轨制、印花税历史档）
 
 ## 收录标准（硬规则）
 
@@ -77,7 +77,7 @@ Dynamic: license-file
 | `trading_hours` | 交易时段（集合竞价/连续竞价/收盘集合竞价，`Phase` 枚举） | 实盘下单时段校验；回测撮合时点 |
 | `settlement` | 交收制度（T+1/T+0/T+3，`STOCK_T1_START`） | 实盘可卖判断；回测成交约束 |
 | `lots` / `ticks` | 申报单位（手数）/ 最小变动价位（含 snap/校验） | 实盘委托合法性；回测撮合精度 |
-| `fees` | 交易费用（印花税/过户费**时间线**，佣金必显式传） | 回测净收益；实盘成本预估 |
+| `fees` | 交易费用（印花税 1997 起全时间线 / 过户费 2015 前沪面值深金额双轨 / 佣金法定上限 3‰ / 经手+证管规费，**v0.3.0 逐条对照官方公告勘误**） | 回测净收益；实盘成本预估 |
 | `circuit_breaker` | 2016 熔断制度（历史触发记录） | 回测跨 2016-01 必须剔除熔断时段 |
 | `halts` | 盘中临时停牌（新股/转债临停规则与复牌时间） | 回测撮合跳过临停；实盘委托拦截 |
 | `corporate_actions` | 除权除息参考价官方公式 + 理论因子跳变 + 数据中心核验入口（容差 0.5%；B股/转债拒答） | 数据：dividend 对账；回测：复权核验 |
@@ -94,7 +94,7 @@ Dynamic: license-file
 
 # ② 正式（打 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
+python -m pip install dist/data_backtest_live_common-0.3.0-py3-none-any.whl
 
 # ③ 未来发布 PyPI 后（像 akshare 一样）
 pip install data-backtest-live-common
@@ -117,6 +117,7 @@ $env:PYTHONPATH = "F:\code\finance\quant_data_center\vendor"
 - `price_limit` 的 ST 判定只有当前名单、没有逐日历史 → 5% 档用「恰好贴板」精确判定（详见模块 docstring 的血泪教训：用 `≥` 会把普通涨超 5% 的交易日成片误判）；
 - `adjust` 的 hfq 锚定上市日（历史行永不变，适合增量落盘），qfq 锚定最新（历史随分红改写，只适合展示）；
 - 1996-12-16 之前 A 股无涨跌停制度，`vec.flags_from_bars` 一律不判；
+- `fees`（v0.3.0 勘误后口径）：佣金法定上限 **3‰ 从未变过**（不存在「0.03% 封顶」政策，2002-05-01 前固定佣金时代拒答）；过户费 **2015-08-01 前沪市按面值/深市按金额双轨**（沪 0.5‰→0.375‰→0.3‰ 按面值，深 0.0255‰ 按金额），之后统一按金额 0.02‰→0.01‰；印花税 A 股 1997-05-10 前拒答、B 股 2001-11-16 前拒答；B 股过户费/结算费体系未编码整体拒答；经手费/证管费通常**已含在佣金内**（helper 仅供净佣金分析，ETF/基金经手费未编码返回 None）；
 - `corporate_actions` 对 B 股（需当日汇率折算，属运行期数据非规则）与可转债（不除权）显式 raise 拒答，不猜；
 - 新股「首 N 日不设涨跌幅」没有交易日序号时按自然日近似，`reason` 里如实标注「近似」。
 

{data_backtest_live_common-0.2.0 → data_backtest_live_common-0.3.0}/dbl_common/__init__.py

@@ -47,8 +47,9 @@ from .trading_hours import Phase, PHASE_LABEL, phase_at, is_auction, \
 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 .fees import FeeResult, TransferFeeRule, calc_fees, stamp_tax, \
+    transfer_fee_rate, transfer_fee_rule, commission_cap, handling_fee_rate, \
+    regulatory_fee_rate, 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
@@ -58,7 +59,7 @@ from .trading_calendar import InjectedCalendar, from_baostock_csv, \
 from .corporate_actions import CorporateAction, from_per_ten, \
     ex_right_price, factor_jump, validate_against_factor, check_applicable
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 __all__ = [
     # boards
@@ -75,9 +76,10 @@ __all__ = [
     "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",
+    # fees（v0.3.0 勘误：佣金上限 3‰ 从未变；过户费 2015 前沪面值/深金额双轨）
+    "FeeResult", "TransferFeeRule", "calc_fees", "stamp_tax", "stamp_tax_timeline",
+    "transfer_fee_rate", "transfer_fee_rule", "commission_cap",
+    "handling_fee_rate", "regulatory_fee_rate",
     # circuit breaker
     "cb_is_active", "cb_state", "CB_START", "CB_END", "LEVEL1", "LEVEL2",
     "HISTORICAL_TRIGGERS",

data_backtest_live_common-0.3.0/dbl_common/fees.py

@@ -0,0 +1,362 @@
+# -*- coding: utf-8 -*-
+"""fees.py — A 股交易费用：制度时间线 + 费用计算器（公共模块 · 纯函数）。
+
+回测扣费与实盘对账必须同一套费率——各算各的会让「回测赚钱、实盘亏钱」
+的缺口无法解释。本模块把**随政策变化的费率**做成时间线（date → rate），
+把**随券商变化的佣金**做成显式参数（不藏在默认值里）。
+
+⚠️ 2026-09-27 v0.3.0 重大勘误（逐条对照官方公告核验后修正，旧版口径作废）：
+  ① 佣金封顶**从来都是 3‰**（2002-05-01 浮动佣金制改革起，证监会/税务总局
+     通知原文），旧版「2015-08-01 起降至 0.03%」是**错误政策**（把市场常见的
+     万 3 费率误当成法定封顶）——旧版会错杀万 3 以上的合法历史佣金；
+  ② 过户费 2015-08-01 之前是**沪市按成交面值 / 深市按成交金额的双轨制**
+     （中登 2015-07 通知原文：沪市按面值 0.3‰、深市按金额 0.0255‰，统一改
+     按金额 0.02‰），旧版对 2015 前一律按金额 0.002% 是**错的**；
+  ③ 印花税时间线补齐 1997-05-10 起（0.5%）与 1998-06-12 起（0.4%）两档。
+
+══════════════════════════════════════════════════════════════════════
+制度时间线（逐条对照：财政部/税务总局公告、中登通知、沪深交易所通知、
+发改委财政部监管费标准通知；每条都可在政府网站查到原文）
+══════════════════════════════════════════════════════════════════════
+
+一、印花税（财政部；对卖方征收——2008-09-19 起单边）：
+  · 1997-05-10 起 0.5%（双边）；1998-06-12 起 0.4%（双边）；
+  · 2001-11-16 起 0.2%（双边，A/B 股同步）；2005-01-24 起 0.1%（双边）；
+  · 2007-05-30 起 0.3%（双边，"5·30"）；2008-04-24 起 0.1%（双边）；
+  · 2008-09-19 起**改单边**（仅卖出）0.1%；2023-08-28 起 0.05%（卖出）。
+  · 1997-05-10 之前：沪深两市开征时间不同、双边/单边口径反复（1990-11 深市
+    双边 0.6%、1991-10 沪市开征 0.3% 等）→ **拒答**（返回 None，查公告再说）。
+  · B 股：2001-11-16 起与 A 股同步；之前与 A 股分叉（如 1999-06-01 B 股
+    单独由 0.4% 降至 0.3%）→ 之前拒答。
+  · 免征：基金（ETF/LOF）份额交易、债券（含可转债）、回购。
+
+二、过户费（中国结算；双向收取，仅股票类）：
+  · 2015-08-01 起：沪深统一按**成交金额** 0.02‰ 双向
+    （2022-04-29 起减半为 0.01‰ 双向；北京市场原 0.025‰ 同步降至 0.01‰）；
+  · 2015-08-01 之前（双轨制，中登 2015-07 调整通知原文确认旧口径）：
+      沪市：按**成交面值**——2012-09-01 起 0.3‰；2012-06-01 起 0.375‰；
+            更早 0.5‰（中置信，百度百科口径，精确日期以中登公告为准）；
+      深市：按**成交金额** 0.0255‰ 双向（起始日不详，如实标注）。
+  · 面值默认 1 元/股（A 股绝大多数量级；优先股等特殊面值请传参）。
+  · B 股：过户费/结算费体系与 A 股不同且未编码 → **拒答**（不编数）。
+  · 基金、债券、回购：不收。
+
+三、佣金（券商收，双向）：
+  · 2002-05-01 起：最高上限向下浮动制——上限 3‰，下限为代收的证券交易
+    监管费和证券交易所手续费等（规费）；A 股/基金每笔最低 5 元、
+    **B 股每笔最低 1 美元**（深 1 港元，税务总局通知原文）；
+  · 2002-05-01 之前：固定佣金时代（约 3.5‰）→ **拒答**；
+  · 本模块不设「默认佣金」——调用方必须显式传：模拟盘/实盘按实际开户
+    费率，回测建议做敏感性区间（万1 / 万2.5 / 万3）。
+
+四、规费（通常**已含在佣金内**，券商代收代缴——投资者总成本 = 佣金
+    （含规费）+ 印花税 + 过户费；下列 helper 供「券商净佣金/全佣金」分析）：
+  · 经手费（交易所收，双向）——沪深 A/B 股：
+      2012-06-01 起 0.0696‰（2012 年下调后口径；更早深市 0.122‰ 未细分）；
+      2015-08-01 起 0.0487‰（其中 0.00974‰ 转投资者保护基金）；
+      2023-08-28 起 0.0341‰（降 30%，沪深交易所通知）。
+      北交所：2021-11-15 起 0.5‰；2022-12-01 起 0.25‰；2023-08-28 起 0.125‰。
+  · 证管费（证监会收，交易所代收，双向）——A/B 股 0.02‰
+    （发改委/财政部通知口径，长期未变）。
+  · ETF/基金/债券的经手费费率与股票不同（含阶段性减免）→ 未编码返回 None，
+    请查交易所现行通知后用 extra_rate 显式传。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Optional, Sequence, Tuple
+
+from .boards import Board, SecurityType, board_of, normalize_code, security_type
+
+# ── 印花税时间线（(生效日, 边, 税率)；边 'both'/'sell'）──────────────────
+# A 股口径（B 股 2001-11-16 起同步，之前拒答）；1997-05-10 前拒答。
+_STAMP_TAX_TIMELINE: Tuple[Tuple[str, str, float], ...] = (
+    ("1997-05-10", "both", 0.005),
+    ("1998-06-12", "both", 0.004),
+    ("2001-11-16", "both", 0.002),
+    ("2005-01-24", "both", 0.001),
+    ("2007-05-30", "both", 0.003),
+    ("2008-04-24", "both", 0.001),
+    ("2008-09-19", "sell", 0.001),
+    ("2023-08-28", "sell", 0.0005),
+)
+_STAMP_TAX_START = "1997-05-10"        # A 股编码起点（此前拒答）
+_STAMP_TAX_B_SHARE_START = "2001-11-16"  # B 股与 A 股同步起点（此前分叉拒答）
+
+# ── 过户费时间线（2015-08-01 起统一「成交金额」口径，双向）────────────────
+_TRANSFER_FEE_AMOUNT_TIMELINE: Tuple[Tuple[str, float], ...] = (
+    ("2015-08-01", 0.00002),
+    ("2022-04-29", 0.00001),
+)
+# 2015-08-01 之前双轨制（沪市按面值 / 深市按金额；精确日期以中登公告为准）
+_SH_FACE_TIER_2012_09 = 0.0003      # 沪市 2012-09-01 起按面值 0.3‰
+_SH_FACE_TIER_2012_06 = 0.000375    # 沪市 2012-06-01 起按面值 0.375‰
+_SH_FACE_TIER_EARLY = 0.0005        # 沪市更早按面值 0.5‰（中置信）
+_SZ_AMOUNT_LEGACY = 0.0000255       # 深市按金额 0.0255‰（起始日不详）
+_TRANSFER_DUAL_TRACK_START = "2015-08-01"
+
+# ── 佣金封顶（2002-05-01 浮动佣金制；此前固定佣金时代拒答）─────────────────
+_COMMISSION_CAP = 0.003             # 3‰（上限，从未变过——不存在"0.03%封顶"政策）
+_COMMISSION_CAP_START = "2002-05-01"
+_COMMISSION_MIN_DEFAULT = 5.0       # A 股/基金每笔最低（法定口径 5 元；B 股 1 美元/1 港元）
+
+# ── 经手费（交易所，双向）────────────────────────────────────────────────
+_HANDLING_FEE_TIMELINE: Tuple[Tuple[str, float], ...] = (   # 沪深 A/B 股
+    ("2012-06-01", 0.0000696),
+    ("2015-08-01", 0.0000487),
+    ("2023-08-28", 0.0000341),
+)
+_HANDLING_FEE_BSE_TIMELINE: Tuple[Tuple[str, float], ...] = (  # 北交所
+    ("2021-11-15", 0.0005),
+    ("2022-12-01", 0.00025),
+    ("2023-08-28", 0.000125),
+)
+_REGULATORY_FEE_RATE = 0.02 / 1000   # 证管费 0.02‰ 双向（A/B 股，发改委口径）
+
+
+def _norm_date(date: Optional[str]) -> str:
+    return str(date)[:10] if date else "9999-12-31"
+
+
+def stamp_tax(date: Optional[str], *,
+              b_share: bool = False) -> Optional[Tuple[str, float]]:
+    """某日的印花税档位 → (征收边, 税率)。
+
+    A 股 1997-05-10 前返回 None（拒答，不猜）；
+    B 股 2001-11-16 前返回 None（此前与 A 股税率分叉）。
+    date=None 按现行（单边卖出 0.05%）。
+    """
+    d = _norm_date(date)
+    floor = _STAMP_TAX_B_SHARE_START if b_share else _STAMP_TAX_START
+    if d < floor:
+        return None
+    cur: Optional[Tuple[str, float]] = None
+    for start, side, rate in _STAMP_TAX_TIMELINE:
+        if d >= start:
+            cur = (side, rate)
+    return cur
+
+
+@dataclass(frozen=True)
+class TransferFeeRule:
+    """过户费规则（值对象）：mode 决定计费基数。
+
+    mode='face'   → 费用 = 数量 × 面值 × rate（沪市 2015-08-01 前）
+    mode='amount' → 费用 = 成交金额 × rate（2015-08-01 起统一）
+    note 带口径出处与置信度标注。
+    """
+
+    mode: str                 # 'face' / 'amount'
+    rate: float
+    note: str = ""
+
+
+def transfer_fee_rule(code: str, date: Optional[str]) -> TransferFeeRule:
+    """某代码某日的过户费规则（**仅 A 股**；B 股 raise 拒答，基金/转债不适用）。
+
+    2015-08-01 前沪深双轨（沪按面值、深按金额）；之后统一按金额。
+    """
+    d = _norm_date(date)
+    if d >= _TRANSFER_DUAL_TRACK_START:
+        rate = _TRANSFER_FEE_AMOUNT_TIMELINE[0][1]
+        for start, r in _TRANSFER_FEE_AMOUNT_TIMELINE:
+            if d >= start:
+                rate = r
+        return TransferFeeRule("amount", rate,
+                               "沪深统一按成交金额双向（中登口径）")
+    # ── 2015-08-01 之前：双轨制 ──
+    c = normalize_code(code)
+    if c[:2] in ("00", "30"):
+        # 深市主板/创业板：按成交金额 0.0255‰（起始日不详，如实标注）
+        return TransferFeeRule("amount", _SZ_AMOUNT_LEGACY,
+                               "深市 2015-08-01 前按成交金额 0.0255‰ 双向"
+                               "（中登 2015-07 通知确认的旧口径；起始日不详）")
+    if c[:2] in ("60", "68"):
+        if d >= "2012-09-01":
+            r, note = _SH_FACE_TIER_2012_09, "沪市 2012-09-01 起按成交面值 0.3‰"
+        elif d >= "2012-06-01":
+            r, note = _SH_FACE_TIER_2012_06, "沪市 2012-06-01 起按成交面值 0.375‰"
+        else:
+            r, note = _SH_FACE_TIER_EARLY, "沪市按成交面值 0.5‰（中置信口径，" \
+                                           "精确档位以中登公告为准）"
+        return TransferFeeRule("face", r, note + " 双向")
+    # 北交所（2021-11-15 开市前为新三板，制度不同）与其他：无可靠口径 → 拒答
+    raise ValueError(
+        f"{code} 在 {d}（2015-08-01 之前）的过户费口径未编码：北交所/新三板"
+        "早期制度不同，沪市口径亦随年代变化，请查中国结算公告后显式计算（不猜）")
+
+
+def transfer_fee_rate(date: Optional[str]) -> float:
+    """某日**统一口径**（2015-08-01 起沪深按成交金额）的过户费双边费率。
+
+    ⚠️ 2015-08-01 之前是沪面值/深金额双轨制，本函数无法表达 → raise，
+    请改用 `transfer_fee_rule(code, date)`（v0.3.0 勘误，旧版此处返回错误口径）。
+    """
+    d = _norm_date(date)
+    if d < _TRANSFER_DUAL_TRACK_START:
+        raise ValueError(
+            f"{d} 早于 2015-08-01：过户费为沪市按面值/深市按金额双轨制，"
+            "请用 transfer_fee_rule(code, date) 按代码判定（v0.3.0 勘误）")
+    rate = _TRANSFER_FEE_AMOUNT_TIMELINE[0][1]
+    for start, r in _TRANSFER_FEE_AMOUNT_TIMELINE:
+        if d >= start:
+            rate = r
+    return rate
+
+
+def commission_cap(date: Optional[str]) -> float:
+    """佣金法定上限（3‰，2002-05-01 浮动佣金制起从未变过）。
+
+    2002-05-01 前为固定佣金时代（约 3.5‰）→ raise 拒答。
+    ⚠️ 不存在「0.03% 封顶」政策（那是市场常见万 3 费率的误传，v0.3.0 勘误）。
+    """
+    d = _norm_date(date)
+    if d < _COMMISSION_CAP_START:
+        raise ValueError(
+            f"{d} 早于 2002-05-01：固定佣金时代（约 3.5‰），"
+            "请查券商协议/历史公告后显式传费率（不猜）")
+    return _COMMISSION_CAP
+
+
+def handling_fee_rate(code: str, date: Optional[str]) -> Optional[float]:
+    """经手费率（交易所收，双向；通常已含在佣金内——供净佣金分析）。
+
+    沪深 A/B 股：2012-06-01 起 0.0696‰ → 2015-08-01 起 0.0487‰ →
+    2023-08-28 起 0.0341‰；北交所：2021-11-15 起 0.5‰ → 2022-12-01 起
+    0.25‰ → 2023-08-28 起 0.125‰。
+    ETF/基金/债券费率不同且含阶段性减免 → 返回 None（未编码，不猜）。
+    """
+    d = _norm_date(date)
+    st = security_type(code)
+    if st not in (SecurityType.STOCK, SecurityType.B_SHARE):
+        return None
+    board = board_of(code)
+    timeline = _HANDLING_FEE_BSE_TIMELINE if board == Board.BSE \
+        else _HANDLING_FEE_TIMELINE
+    cur: Optional[float] = None
+    for start, r in timeline:
+        if d >= start:
+            cur = r
+    return cur
+
+
+def regulatory_fee_rate(code: str, date: Optional[str]) -> Optional[float]:
+    """证管费率（证监会收、交易所代收，双向；通常已含在佣金内）。
+
+    A/B 股 0.02‰（发改委/财政部通知口径，长期未变）；其他品种 None。
+    """
+    st = security_type(code)
+    if st not in (SecurityType.STOCK, SecurityType.B_SHARE):
+        return None
+    return _REGULATORY_FEE_RATE
+
+
+@dataclass(frozen=True)
+class FeeResult:
+    """一笔成交的费用明细（金额单位：元；逐项拆开以便对账）。"""
+
+    amount: float            # 成交金额（股数 × 价格）
+    commission: float        # 佣金（双边各收一次——调用方按 buy/sell 各算一笔）
+    stamp_tax: float         # 印花税（只对征收边非零）
+    transfer_fee: float      # 过户费（2015-08-01 前沪市按面值=数量×面值×率）
+    extra_fee: float         # 经手费/证管费等（调用方显式传比率才有）
+    total: float
+    breakdown: str           # 人读得懂的分项（进留痕，不许只给总数）
+
+    @property
+    def total_rate(self) -> float:
+        return self.total / self.amount if self.amount else 0.0
+
+
+def calc_fees(code: str, qty: float, price: float, side: str, *,
+              date: Optional[str] = None,
+              commission_rate: Optional[float] = None,
+              commission_min: float = _COMMISSION_MIN_DEFAULT,
+              extra_rate: float = 0.0,
+              stype: Optional[SecurityType] = None,
+              face_value: float = 1.0) -> FeeResult:
+    """计算一笔竞价成交的费用（投资者口径：佣金含规费 + 印花税 + 过户费）。
+
+    Args:
+        qty/price: 成交数量与单价（数量单位随品种：股/份/张）。
+        side: 'buy' / 'sell'。
+        date: 成交日（费率时间线判定；None = 现行）。
+        commission_rate: 佣金率（**必传**，如 0.00025=万2.5；None 抛错——
+            不设默认是故意的：回测/实盘费率不同，藏默认值就是埋雷。
+            上限 3‰，超上限抛错——回测里「夸张佣金」多半是单位写错）。
+        commission_min: 每笔最低佣金（A 股法定口径 5 元；B 股为 1 美元/1 港元，
+            以券商协议为准——调用方换算成人民币传参）。
+        extra_rate: 附加费率合计（不确定就传 0 并披露；经手/证管规费通常
+            已含在佣金里，不要在这里重复计——见 handling_fee_rate 的说明）。
+        stype: 品种显式覆盖（None = 前缀推断）。
+        face_value: 每股面值（默认 1 元——过户费 2015-08-01 前沪市按面值计）。
+
+    Returns:
+        FeeResult（逐项 + 总额 + 可读明细）。
+    """
+    if commission_rate is None:
+        raise ValueError("commission_rate 必须显式传（万2.5 → 0.00025）；"
+                         "不设默认是防止回测/实盘费率混用")
+    cap = commission_cap(date)  # 2002-05-01 前固定佣金时代在此 raise
+    if commission_rate > cap:
+        raise ValueError(f"佣金率 {commission_rate} 超过法定上限 {cap}（3‰，"
+                         "2002-05-01 起从未变过——若你以为上限是万3，那是把"
+                         "市场常见费率误当成了政策）")
+    st = security_type(code, stype)
+    amount = float(qty) * float(price)
+    if amount <= 0:
+        raise ValueError(f"成交金额必须为正（qty={qty}, price={price}）")
+
+    commission = max(amount * commission_rate, commission_min)
+
+    # ── 印花税：股票/B 股收；基金/债券/回购免 ──
+    stamp = 0.0
+    if st in (SecurityType.STOCK, SecurityType.B_SHARE):
+        tier = stamp_tax(date, b_share=(st == SecurityType.B_SHARE))
+        if tier is None:
+            floor = _STAMP_TAX_B_SHARE_START if st == SecurityType.B_SHARE \
+                else _STAMP_TAX_START
+            raise ValueError(
+                f"{date} 早于 {floor}：印花税历史档位未编码"
+                "（此前沪深不同步/AB 股分叉），请查财政部公告后显式计算（不猜）")
+        tside, rate = tier
+        if (tside == "both") or (tside == "sell" and side == "sell"):
+            stamp = amount * rate
+
+    # ── 过户费：仅 A 股股票（B 股体系未编码拒答；基金/转债不收）──
+    transfer = 0.0
+    transfer_note = ""
+    if st == SecurityType.STOCK:
+        rule = transfer_fee_rule(code, date)
+        if rule.mode == "face":
+            transfer = float(qty) * float(face_value) * rule.rate
+            transfer_note = f"（按面值{face_value:g}元×{rule.rate:.5f}）"
+        else:
+            transfer = amount * rule.rate
+    elif st == SecurityType.B_SHARE:
+        raise ValueError("B 股过户费/结算费体系与 A 股不同且未编码——"
+                         "请查中国结算公告后显式计算（不猜；印花税部分本模块"
+                         "2001-11-16 起可算，过户费整体拒答）")
+    extra = amount * extra_rate
+
+    total = commission + stamp + transfer + extra
+    parts = [f"佣金 {commission:.2f}(率{commission_rate:.5f},最低{commission_min:.0f})"]
+    if stamp:
+        parts.append(f"印花税 {stamp:.2f}({side}边)")
+    if transfer:
+        parts.append(f"过户费 {transfer:.2f}{transfer_note}")
+    if extra:
+        parts.append(f"附加 {extra:.2f}(率{extra_rate:.5f})")
+    return FeeResult(amount=amount, commission=commission, stamp_tax=stamp,
+                     transfer_fee=transfer, extra_fee=extra, total=total,
+                     breakdown="；".join(parts))
+
+
+def stamp_tax_timeline() -> Sequence[Tuple[str, str, float]]:
+    """公开印花税时间线（给报告/前端渲染，不许调用方各抄一份）。"""
+    return _STAMP_TAX_TIMELINE
+
+
+__all__ = ["FeeResult", "calc_fees", "stamp_tax", "stamp_tax_timeline",
+           "TransferFeeRule", "transfer_fee_rule", "transfer_fee_rate",
+           "commission_cap", "handling_fee_rate", "regulatory_fee_rate"]

{data_backtest_live_common-0.2.0 → data_backtest_live_common-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "data-backtest-live-common"
-version = "0.2.0"
+version = "0.3.0"
 description = "数据(Data)/回测(Backtest)/实盘(Live)三系统公共库：复权、A股交易规则全集（涨跌幅/时段/费用/交收/熔断/除权）、交易日历、原子写、无黑窗子进程"
 readme = "README.md"
 license = { file = "LICENSE" }

{data_backtest_live_common-0.2.0 → data_backtest_live_common-0.3.0}/tests/test_trading_rules.py

@@ -260,20 +260,74 @@ def test_tick_sizes():
 
 
 # ═══════════════════════════════════════════════════════════════════════
-# fees：政策时间线 + 计算器
+# fees：政策时间线 + 计算器（v0.3.0 勘误后锚点，逐条对照官方公告）
 # ═══════════════════════════════════════════════════════════════════════
 def test_stamp_tax_timeline():
     assert stamp_tax("2023-08-28") == ("sell", 0.0005)   # 减半日（关键锚点）
     assert stamp_tax("2023-08-27") == ("sell", 0.001)
     assert stamp_tax("2008-09-19") == ("sell", 0.001)   # 改单边日
     assert stamp_tax("2008-09-18") == ("both", 0.001)
-    assert stamp_tax("2007-06-01") == ("both", 0.003)   # 上调至 3‰
-    assert stamp_tax("2001-11-15") is None               # 拒答区间
-
-
-def test_transfer_fee_timeline():
+    assert stamp_tax("2007-06-01") == ("both", 0.003)   # "5·30" 上调至 3‰
+    assert stamp_tax("2001-11-16") == ("both", 0.002)   # 4‰→2‰
+    assert stamp_tax("2001-11-15") == ("both", 0.004)   # v0.3.0 补的档
+    assert stamp_tax("1998-06-12") == ("both", 0.004)   # 5‰→4‰
+    assert stamp_tax("1998-06-11") == ("both", 0.005)   # v0.3.0 补的档
+    assert stamp_tax("1997-05-10") == ("both", 0.005)   # 3‰→5‰
+    assert stamp_tax("1997-05-09") is None               # 拒答区间（沪深不同步）
+    assert stamp_tax("1990-06-30", b_share=True) is None  # B 股 2001-11-16 前分叉拒答
+
+
+def test_transfer_fee_rule_dual_track():
+    """2015-08-01 前双轨：沪按面值、深按金额（中登 2015-07 通知原文口径）。"""
+    from dbl_common import TransferFeeRule, transfer_fee_rule
+    # 沪市 2014：按面值 0.3‰（2012-09-01 档）
+    r = transfer_fee_rule("600519", "2014-06-03")
+    assert (r.mode, r.rate) == ("face", 0.0003)
+    # 沪市 2012-07：0.375‰ 档
+    assert transfer_fee_rule("600519", "2012-07-02").rate == 0.000375
+    # 沪市 2011：0.5‰ 档（中置信）
+    assert transfer_fee_rule("600519", "2011-06-01").rate == 0.0005
+    # 深市 2014：按金额 0.0255‰
+    r = transfer_fee_rule("000001", "2014-06-03")
+    assert (r.mode, r.rate) == ("amount", 0.0000255)
+    # 2015-08-01 起沪深统一按金额 0.02‰ → 2022-04-29 减半 0.01‰
+    r = transfer_fee_rule("600519", "2015-08-01")
+    assert (r.mode, r.rate) == ("amount", 0.00002)
+    assert transfer_fee_rule("000001", "2022-04-29").rate == 0.00001
+
+
+def test_transfer_fee_rate_unified():
     assert transfer_fee_rate("2022-04-28") == 0.00002
     assert transfer_fee_rate("2022-04-29") == 0.00001   # 下调 50%
+    with pytest.raises(ValueError):   # 2015 前双轨制 → 拒答（v0.3.0 勘误）
+        transfer_fee_rate("2014-06-03")
+
+
+def test_commission_cap_never_below_3pct():
+    """佣金法定上限 3‰ 自 2002-05-01 起从未变过（不存在 0.03% 封顶政策）。"""
+    from dbl_common import commission_cap
+    assert commission_cap("2024-06-03") == 0.003
+    assert commission_cap("2002-05-01") == 0.003
+    with pytest.raises(ValueError):   # 固定佣金时代拒答
+        commission_cap("2001-12-31")
+
+
+def test_handling_and_regulatory_fee():
+    """规费（通常含在佣金内，供净佣金分析）：经手费三档 + 证管费 0.02‰。"""
+    from dbl_common import handling_fee_rate, regulatory_fee_rate
+    # 沪深 A 股经手费：0.0696‰ → 0.0487‰（2015-08-01）→ 0.0341‰（2023-08-28）
+    assert handling_fee_rate("600519", "2014-06-03") == 0.0000696
+    assert handling_fee_rate("600519", "2015-08-01") == 0.0000487
+    assert handling_fee_rate("600519", "2023-08-28") == 0.0000341
+    # 北交所：0.5‰ → 0.25‰（2022-12）→ 0.125‰（2023-08-28）
+    assert handling_fee_rate("920002", "2022-01-04") == 0.0005
+    assert handling_fee_rate("920002", "2022-12-01") == 0.00025
+    assert handling_fee_rate("920002", "2023-08-28") == 0.000125
+    # ETF 经手费未编码 → None（不猜）
+    assert handling_fee_rate("510300", "2024-06-03") is None
+    # 证管费 A/B 股 0.02‰ 双向；ETF None
+    assert regulatory_fee_rate("600519", "2024-06-03") == 0.00002
+    assert regulatory_fee_rate("510300", "2024-06-03") is None
 
 
 def test_calc_fees_sell_stock_2024():
@@ -287,6 +341,22 @@ def test_calc_fees_sell_stock_2024():
     assert r.total == pytest.approx(76.0)
 
 
+def test_calc_fees_sh_2014_face_value_transfer():
+    """v0.3.0 勘误核心用例：2014 沪市过户费按面值 0.3‰ = 数量 × 1 × 0.0003。
+
+    卖 10000 股 × 10 元（2014-06-03）：印花税双边 0.1% = 100 元；
+    过户费 = 10000 × 1 × 0.0003 = 3 元（旧版错误地按金额 0.002% 算 2 元）。
+    """
+    r = calc_fees("600519", 10000, 10.0, "sell",
+                  date="2014-06-03", commission_rate=0.00025)
+    assert r.stamp_tax == pytest.approx(100.0)   # 2014 双边 0.1%（买卖都收）
+    assert r.transfer_fee == pytest.approx(3.0)  # 按面值，不按金额
+    # 同日深市：按金额 0.0255‰ = 100000 × 0.0000255 = 2.55 元
+    r2 = calc_fees("000001", 10000, 10.0, "sell",
+                   date="2014-06-03", commission_rate=0.00025)
+    assert r2.transfer_fee == pytest.approx(2.55)
+
+
 def test_calc_fees_buy_no_stamp():
     r = calc_fees("600519", 10000, 10.0, "buy",
                   date="2024-06-03", commission_rate=0.00025)
@@ -312,11 +382,23 @@ def test_calc_fees_etf_exempt():
 def test_calc_fees_guards():
     with pytest.raises(ValueError):   # 佣金必须显式传
         calc_fees("600519", 100, 10.0, "buy", commission_rate=None)
-    with pytest.raises(ValueError):   # 超封顶
-        calc_fees("600519", 100, 10.0, "buy", commission_rate=0.003)
-    with pytest.raises(ValueError):   # 2001 前印花税未编码 → 拒答
+    with pytest.raises(ValueError):   # 超法定上限 3‰（万5 合法，5‰ 不合法）
+        calc_fees("600519", 100, 10.0, "buy", commission_rate=0.005)
+    with pytest.raises(ValueError):   # 1997 前印花税未编码 → 拒答
         calc_fees("600519", 100, 10.0, "sell",
-                  date="2000-01-04", commission_rate=0.00025)
+                  date="1996-12-31", commission_rate=0.00025)
+    with pytest.raises(ValueError):   # 2002 前固定佣金时代 → 拒答
+        calc_fees("600519", 100, 10.0, "buy",
+                  date="2001-12-31", commission_rate=0.0035)
+    with pytest.raises(ValueError):   # B 股过户费体系未编码 → 拒答
+        calc_fees("900901", 100, 1.0, "buy", commission_rate=0.00025)
+
+
+def test_calc_fees_high_commission_legal():
+    """万 5 / 千 1 历史佣金合法（v0.3.0 勘误：旧版会错杀为「超封顶」）。"""
+    r = calc_fees("600519", 10000, 10.0, "buy",
+                  date="2010-06-03", commission_rate=0.001)  # 千1
+    assert r.commission == pytest.approx(100.0)
 
 
 # ═══════════════════════════════════════════════════════════════════════

data_backtest_live_common-0.2.0/dbl_common/fees.py

@@ -1,171 +0,0 @@
-# -*- coding: utf-8 -*-
-"""fees.py — A 股交易费用：制度时间线 + 费用计算器（公共模块 · 纯函数）。
-
-回测扣费与实盘对账必须同一套费率——各算各的会让「回测赚钱、实盘亏钱」
-的缺口无法解释。本模块把**随政策变化的费率**做成时间线（date → rate），
-把**随券商变化的佣金**做成显式参数（不藏在默认值里）。
-
-制度时间线（财政部/中登/交易所公告，锚点事件为高置信度）
---------------------------------------------------------
-印花税（对卖方征收的证券交易印花税）：
-· 2001-11-16 起 0.2%（双边改单边? — 此前多次调整，**2001 年前历史请查公告**，
-  本模块 2001-11-16 之前的查询返回 None 拒答）；
-· 2005-01-24 起 0.1%；2007-05-30 起 0.3%；2008-04-24 起 0.1%；
-· 2008-09-19 起 改**单边**（仅卖出）0.1%；
-· 2023-08-28 起 减半为**单边** 0.05%。
-免征：ETF/LOF 基金份额交易、债券（含可转债）、回购。
-
-过户费（中国结算，双边）：
-· 0.002% → **2022-04-29 起下调 50% 至 0.001%**（中登公告口径）；
-· 历史上仅沪市股票收取、深市 2015 年前后纳入（精确日以中登公告为准——
-  回测 2015 年前后成本差异 < 万分之二，影响可忽略但如实标注）；
-· 仅股票/B 股收；基金、转债不收。
-
-佣金（券商）：双边、成交金额的 0.03% 封顶（2015 年 8 月起沪深统一从
-0.3% 降至 0.03%——**注意封顶值本身也是政策变量**）、每笔最低 5 元
-（各券商可下浮）。本模块不设「默认佣金」——调用方必须显式传，
-模拟盘/实盘按实际开户费率，回测建议做敏感性区间（万1/万2.5/万3）。
-
-经手费/证管费/风险金：合计约万分之几、随交易所公告微调，本模块不硬编码
-（计算器留 `extra_rate` 参数），避免拿不确定的数冒充确定。
-"""
-from __future__ import annotations
-
-from dataclasses import dataclass
-from typing import Optional, Sequence, Tuple
-
-from .boards import SecurityType, security_type
-
-# ── 印花税时间线（(生效日, 边, 税率)；边 'both'/'sell'；None=拒答区间）────
-_STAMP_TAX_TIMELINE: Tuple[Tuple[str, str, float], ...] = (
-    ("2001-11-16", "both", 0.002),
-    ("2005-01-24", "both", 0.001),
-    ("2007-05-30", "both", 0.003),
-    ("2008-04-24", "both", 0.001),
-    ("2008-09-19", "sell", 0.001),
-    ("2023-08-28", "sell", 0.0005),
-)
-
-# ── 过户费时间线（双边费率）────────────────────────────────────────────
-_TRANSFER_FEE_TIMELINE: Tuple[Tuple[str, float], ...] = (
-    ("1990-01-01", 0.00002),
-    ("2022-04-29", 0.00001),
-)
-
-_COMMISSION_CAP = 0.0003       # 2015-08-01 起佣金封顶 0.03%（此前 0.3%）
-_COMMISSION_CAP_EARLY = 0.003  # 2015-08-01 前
-_COMMISSION_CAP_START = "2015-08-01"
-_COMMISSION_MIN_DEFAULT = 5.0  # 每笔最低佣金（常见 5 元，以券商协议为准）
-
-
-def stamp_tax(date: Optional[str]) -> Optional[Tuple[str, float]]:
-    """某日的印花税档位 → (征收边, 税率)；2001-11-16 前返回 None（拒答，不猜）。
-
-    date=None 按现行（单边卖出 0.05%）。
-    """
-    d = str(date)[:10] if date else "9999-12-31"
-    cur: Optional[Tuple[str, float]] = None
-    for start, side, rate in _STAMP_TAX_TIMELINE:
-        if d >= start:
-            cur = (side, rate)
-    return cur
-
-
-def transfer_fee_rate(date: Optional[str]) -> float:
-    """某日过户费双边费率（股票/B股适用；基金转债不收——见 calc_fees）。"""
-    d = str(date)[:10] if date else "9999-12-31"
-    rate = _TRANSFER_FEE_TIMELINE[0][1]
-    for start, r in _TRANSFER_FEE_TIMELINE:
-        if d >= start:
-            rate = r
-    return rate
-
-
-def commission_cap(date: Optional[str]) -> float:
-    """佣金法定封顶（回测里给「夸张佣金」做合法性钳制用）。"""
-    d = str(date)[:10] if date else "9999-12-31"
-    return _COMMISSION_CAP if d >= _COMMISSION_CAP_START else _COMMISSION_CAP_EARLY
-
-
-@dataclass(frozen=True)
-class FeeResult:
-    """一笔成交的费用明细（金额单位：元；逐项拆开以便对账）。"""
-
-    amount: float            # 成交金额（股数 × 价格）
-    commission: float        # 佣金（双边各收一次——调用方按 buy/sell 各算一笔）
-    stamp_tax: float         # 印花税（只对征收边非零）
-    transfer_fee: float      # 过户费
-    extra_fee: float         # 经手费/证管费等（调用方显式传比率才有）
-    total: float
-    breakdown: str           # 人读得懂的分项（进留痕，不许只给总数）
-
-    @property
-    def total_rate(self) -> float:
-        return self.total / self.amount if self.amount else 0.0
-
-
-def calc_fees(code: str, qty: float, price: float, side: str, *,
-              date: Optional[str] = None,
-              commission_rate: Optional[float] = None,
-              commission_min: float = _COMMISSION_MIN_DEFAULT,
-              extra_rate: float = 0.0,
-              stype: Optional[SecurityType] = None) -> FeeResult:
-    """计算一笔竞价成交的费用。
-
-    Args:
-        qty/price: 成交数量与单价（数量单位随品种：股/份/张）。
-        side: 'buy' / 'sell'。
-        date: 成交日（费率时间线判定；None = 现行）。
-        commission_rate: 佣金率（**必传**，如 0.00025=万2.5；None 抛错——
-            不设默认是故意的：回测/实盘费率不同，藏默认值就是埋雷）。
-        extra_rate: 经手+证管+风险金等附加费率合计（不确定就传 0 并披露）。
-
-    Returns:
-        FeeResult（逐项 + 总额 + 可读明细）。
-    """
-    if commission_rate is None:
-        raise ValueError("commission_rate 必须显式传（万2.5 → 0.00025）；"
-                         "不设默认是防止回测/实盘费率混用")
-    if commission_rate > commission_cap(date):
-        raise ValueError(f"佣金率 {commission_rate} 超过封顶 {commission_cap(date)}")
-    st = security_type(code, stype)
-    amount = float(qty) * float(price)
-    if amount <= 0:
-        raise ValueError(f"成交金额必须为正（qty={qty}, price={price}）")
-
-    commission = max(amount * commission_rate, commission_min)
-    # 基金/债券/回购免印花税
-    stamp = 0.0
-    if st in (SecurityType.STOCK, SecurityType.B_SHARE):
-        tier = stamp_tax(date)
-        if tier is None:
-            raise ValueError(f"{date} 早于 2001-11-16：印花税历史档位未编码，"
-                             "请查财政部公告后显式计算（不猜）")
-        tside, rate = tier
-        if (tside == "both") or (tside == "sell" and side == "sell"):
-            stamp = amount * rate
-    # 过户费：股票/B股双边
-    transfer = amount * transfer_fee_rate(date) \
-        if st in (SecurityType.STOCK, SecurityType.B_SHARE) else 0.0
-    extra = amount * extra_rate
-
-    total = commission + stamp + transfer + extra
-    parts = [f"佣金 {commission:.2f}(率{commission_rate:.5f},最低{commission_min:.0f})"]
-    if stamp:
-        parts.append(f"印花税 {stamp:.2f}({side}边)")
-    if transfer:
-        parts.append(f"过户费 {transfer:.2f}")
-    if extra:
-        parts.append(f"附加 {extra:.2f}(率{extra_rate:.5f})")
-    return FeeResult(amount=amount, commission=commission, stamp_tax=stamp,
-                     transfer_fee=transfer, extra_fee=extra, total=total,
-                     breakdown="；".join(parts))
-
-
-def stamp_tax_timeline() -> Sequence[Tuple[str, str, float]]:
-    """公开时间线（给报告/前端渲染，不许调用方各抄一份）。"""
-    return _STAMP_TAX_TIMELINE
-
-
-__all__ = ["FeeResult", "calc_fees", "stamp_tax", "transfer_fee_rate",
-           "commission_cap", "stamp_tax_timeline"]