From 05db452cc09c3217281e504a055d07360b71526c Mon Sep 17 00:00:00 2001 From: GitHub Date: Fri, 28 Aug 2026 20:14:41 +0800 Subject: [PATCH] =?UTF-8?q?release:=20v1.20.11=20=E2=80=94=20=E8=B5=84?= =?UTF-8?q?=E9=87=91=E6=B5=81=E5=8F=A3=E5=BE=84=E6=A0=87=E6=B3=A8=EF=BC=88?= =?UTF-8?q?#55=EF=BC=89=EF=BC=9A=E8=81=9A=E5=90=88=E9=80=90=E7=AC=94?= =?UTF-8?q?=E6=88=90=E4=BA=A4=E9=A2=9D=E5=88=86=E6=A1=A3=EF=BC=8C=E5=AE=9E?= =?UTF-8?q?=E8=B4=A8=E4=B8=BA=E4=B8=BB=E5=8A=A8=E4=B9=B0=E5=8D=96=E6=80=BB?= =?UTF-8?q?=E5=A4=B1=E8=A1=A1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- CHANGELOG.md | 14 ++++++++++++++ pyproject.toml | 2 +- 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 672f214..acf5f78 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,20 @@ 本文件记录 easy-tdx 的版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/)。 +## [1.20.11] — 2026-08-28 + +**资金流口径限制文档标注**（Issue #55，纯文档、无行为变更）——用户实测反馈：同日同股，本库资金流与东财"主力净额"（数据中心 `RPT_DMSK_TS_STOCKNEW` 的 `PRIME_INFLOW`，该字段已验证恒等于超大单+大单净额）差异极大且方向不一（工业富联 601138 偏大 36 倍、洛阳钼业 603993 偏小 2.4 倍，不可系数校正）。用户独立用 `get_history_transaction_data` 复算八个分档与库返回**逐分吻合（diff 0.00 元）**，证实库实现无误；根因在数据源口径——0x0fb5 的"逐笔"是交易所真实逐笔**聚合**后的记录（000001.SZ 单日实测 76,411 笔 → 仅 4,485 条，约 17:1），按聚合后单笔成交额分档把几乎全部成交推入主力档（实测 601138/603993 主力档占成交额 99.4%+、小单档仅 0.02%），故 `main_net_inflow` 实质是"当日主动买卖总失衡"（另有约 2–4% 方向未定的成交被排除）；而东财基于 L2 逐笔委托按**挂单额**分档、四档净额严格归零。实证两口径在选股层面几乎不相干（856 个共同信号日仅 13.9% 选中同一只股票；同规则策略 2020–2026 单笔均值 −0.12% vs 东财口径 +1.56%），不能互相替代。 + +### 文档 + +- **`get_fund_flow` / `get_history_fund_flow` docstring（sync/async 共 4 处，`client.py`）**——标注三点口径限制：① 分档基于 0x0fb5 聚合后的"单笔成交额"，不是挂单额；② 聚合导致高价股小单档可不足成交额 1%、主力档常占 95%+，值更接近"主动买卖总失衡"；③ 与东财/同花顺"主力净流入"不可比，勿混用于同一张表或同一个因子。 +- **`FundFlow` / `HistoricalFundFlow` 类 docstring**（`models/stats.py`）——同步口径说明（原"基于 Tick 数据加权计算"的描述不准确，实为逐笔重算）。 +- **README**——"标准协议"章节 `get_fund_flow` 示例后新增"资金流口径注意"引注块；TdxClient API 表两行加"口径注意见上文"指引。 +- **`docs/api_reference.md`**——"资金流向"章节新增完整"口径注意"段（含 17:1 聚合实测、2–4% 方向未定排除、东财四档归零等细节），`get_fund_flow` 小节加指引。 +- **`examples/08_fund_flow/`** 两个示例的模块 docstring 补口径注意；**Web 端点 `/fund-flow`、`/fund-flow/history`** 的 Swagger 描述各补一行口径提示。 + +全套 1035 个单测通过（`test_web_api.py` 2 个失败为基线已存在的环境问题，与本变更无关）。 + ## [1.20.10] — 2026-08-26 **`get_board_list` 板块涨速列恒为 0**（Issue #53）——用户反馈板块列表的涨速列存在但全是 0。逆向核实（0x1231 抓包 + 与 `SymbolQuotesCmd` 字段逐一对值锚定）发现根因：响应中 price 与 pre_close 之间的那个 float **不是固定的"涨速"，而是"当前排序列的值"**（板块与领涨股各一份）——请求里的 sort_column 此前硬编码为 0（涨跌幅），而涨跌幅列仅作排序键、值槽恒 0（客户端可由 price/pre_close 计算），所以永远拿到 0。实测锚定排序列映射：**0=涨跌幅（值槽恒 0）、1=涨速%、2=3日涨幅、3=20日涨幅、4=60日涨幅、5=年初至今、6=5日涨幅、7=10日涨幅**。 diff --git a/pyproject.toml b/pyproject.toml index a8c316d..52ba44a 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "easy-tdx" -version = "1.20.10" +version = "1.20.11" description = "通达信 TCP 协议行情数据客户端，支持在线行情、离线数据读取与写入同步" readme = "README.md" requires-python = ">=3.10"