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`）。
