From dea39db44114b38be27475451905f2475152a3be Mon Sep 17 00:00:00 2001 From: openbot-coder Date: Fri, 30 Oct 2026 13:38:51 +0800 Subject: [PATCH] =?UTF-8?q?fix(quotes):=20=E4=BF=AE=E6=AD=A3=20server=5Fti?= =?UTF-8?q?me=20=E8=A7=A3=E7=A0=81=E5=8F=A3=E5=BE=84=EF=BC=88=E5=8D=81?= =?UTF-8?q?=E8=BF=9B=E5=88=B6=E4=BD=8D=E6=8B=BC=E6=8E=A5=20HHMMSS=20+=20?= =?UTF-8?q?=E4=BB=B7=E6=A0=BC=E5=B0=8F=E6=95=B0=E4=BD=8D=EF=BC=89=20(#15)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: openbot-coder --- CHANGELOG.md | 32 +++++++ docs/API_REFERENCE.md | 12 +++ src/pytdxdata/models/__init__.py | 4 + src/pytdxdata/protocol/commands/quotes.py | 60 +++++++++--- tests/test_quote_time.py | 106 ++++++++++++++++++++++ 5 files changed, 203 insertions(+), 11 deletions(-) create mode 100644 tests/test_quote_time.py diff --git a/CHANGELOG.md b/CHANGELOG.md index bc6062e..6bfa387 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,38 @@ 本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。 +## [未发布] + +### 修复 + +- **修复 `get_quotes` 的 `server_time`(行情快照时间)解码错误**。 + + 原实现按「小时 + 百万分之一小时」(`divmod(raw, 1_000_000)`)解码,但协议实际是 + **十进制位拼接**: + + ``` + 整数 = HH*10**(4+d) + MM*10**(2+d) + SS*10**d + 小数 + d = 该品种价格小数位(股票 2 / ETF·LOF·B股 3 / 国债·回购 4) + ``` + + 后果:股票 13:29:59 显示成 `11:17:57`(基准错、速率也只有实际的 53%),ETF/债券 + 直接给出小时 > 23 的非法值。 + + | 标的 | raw | 0.7.1 显示 | 现在 | + |---|---|---|---| + | `sh600000`(dp=2) | `13224002` | `13:13:26.407` | **`13:22:40.02`** | + | `sh510300`(dp=3) | `132245903` | `132:14:45.250` | **`13:22:45.903`** | + | `sh204001`(dp=4) | `1310228050` | `1310:13:40.980` | **`13:10:22.8050`** | + + - 小数位数跟着品种价格精度走,输出 `HH:MM:SS.ff`(2~4 位,兼容旧文档的 `HH:MM:SS.mmm`)。 + - 服务端怪癖:**SS 落在 50~59 秒时写成 90~99**(编码值 +40 秒)。未修正时该区间的滞后 + 会从稳定的 10.6 秒突变成 -29.4 秒;现在 `SS >= 60` 一律减 40 秒还原。 + - **指数(`sh000001` / `sz399001` / `sh000300` …)该字段返回空串**:协议里它对指数不是 + 时钟(同一时刻 `000001` 解出 `12:89`、`399001` 解出 `12:15`,互相矛盾)。此前会给出一个 + 看着合理、其实是垃圾的时间。要指数时间请用 `get_minutes` / K 线。 + - 实测验收(2026-10-30 盘中,同服务器连续采样 3 分钟):`server_time` 与本地时钟的滞后 + 稳定在 10.5~10.9 秒;股票 / ETF / B股 / 国债 / 回购全覆盖,见 `tests/test_quote_time.py`。 + ## [0.7.1] - 2026-10-29 ### 性能 diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 781365d..7ee834a 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -228,6 +228,18 @@ from pytdxdata import ( > 注:`__init__` 仅导出 `Market/ExMarket/KlinePeriod/Adjust` 与 6 个核心模型;`BoardInfo/MemberQuote/AuctionItem` 等需 `from pytdxdata.models import ...`。 +**`SecurityQuote.server_time`(行情快照时间,0.7.2 修正)** + +- 格式 `HH:MM:SS.ff`,小数位数 = 该品种**价格小数位**:股票 2、ETF/LOF/B股 3、国债·回购 4。 + 例 `13:22:40.02` / `13:22:45.903` / `13:10:22.8050`。 +- 它比本地时钟**慢 5~15 秒**(服务器快照滞后),超低流动性品种(货币 ETF、国债)可能差几分钟。 + 判断「行情有没有更新」请看这个值有没有变,别看调用时刻 —— 盘口本身约 3 秒刷新一次。 +- **指数(`sh000001` / `sz399001` / `sh000300` …)恒为空串**:该字段对指数不是时钟 + (同一时刻 `000001` 解出 `12:89`、`399001` 解出 `12:15`,协议内没有可用信息)。 + 要指数时间请用 `get_minutes` / K 线。 +- ⚠️ 0.7.1 及之前按「小时 + 百万分之一小时」解码是**错的**:股票 `11:29:59` 会显示成 + `11:17:57`,ETF/债券会显示成 `113:00:21` 这种非法小时。 + **量纲对照(跨品种,2026-10-22 实测)** 同名字段在不同品种上单位不同。最典型的坑是用 `amount / vol` 算均价——它在可转债上会**错 10 倍**: diff --git a/src/pytdxdata/models/__init__.py b/src/pytdxdata/models/__init__.py index c9d9cb1..cf13329 100644 --- a/src/pytdxdata/models/__init__.py +++ b/src/pytdxdata/models/__init__.py @@ -216,6 +216,10 @@ class SecurityQuote: A股(标准通道):五档 ``bid``/``ask`` + 买卖量 + 涨跌停价齐全,``name`` 为空。 A股(``fields=[...]`` 走 MAC 0x122B):``name`` 与 ``fields`` 齐全,五档为空。 扩展市场(港股/美股/期货):``name`` + 基础价量在属性上,其余字段位在 ``fields``。 + + ``server_time`` 是**行情快照时间**:``HH:MM:SS.ff``,小数位数等于该品种价格小数位 + (股票 2 / ETF·LOF·B股 3 / 国债·回购 4),通常比本地时钟慢 5~15 秒。**指数恒为空串** + (协议里这个字段对指数不是时钟);判断行情是否更新看它有没有变,别看调用时刻。 """ market: int code: str diff --git a/src/pytdxdata/protocol/commands/quotes.py b/src/pytdxdata/protocol/commands/quotes.py index c9ff683..b093726 100644 --- a/src/pytdxdata/protocol/commands/quotes.py +++ b/src/pytdxdata/protocol/commands/quotes.py @@ -5,6 +5,7 @@ import struct from ..._binary import unpack_from from ...models import SecurityQuote +from ...symbols import is_cn_index from ..price import get_price from ..volume import get_volume from .base import BaseCommand @@ -161,13 +162,49 @@ def price_decimal_digits(market: int, code: str) -> int: return _decimal_digits_static(m, code) -def format_server_time(raw: int) -> str: - """服务器时间编码:小时 + 百万分之一小时。14999212 -> 14:59:57.163""" - hours, fractional_hour = divmod(raw, 1_000_000) - total_millis = fractional_hour * 3600 // 1000 - minutes, remainder = divmod(total_millis, 60_000) - seconds, millis = divmod(remainder, 1000) - return f"{hours:02d}:{minutes:02d}:{seconds:02d}.{millis:03d}" +_SERVER_TIME_SKEW = 40 +"""服务端在「50~59 秒」段会写成「90~99」秒,整数值固定多 40×10**d。""" + + +def format_server_time(raw: int, digits: int = 2) -> str: + """报价快照时间解码:十进制数字拼接 ``HH MM SS`` + ``digits`` 位小数。 + + 编码(2026-10-30 盘中实测确定):: + + 整数 = HH*10**(4+d) + MM*10**(2+d) + SS*10**d + 小数 + d = 该品种**价格小数位**(股票 2 / ETF·LOF·B股 3 / 国债·回购 4) + + 实测样例:``13224002``(d=2)→ ``13:22:40.02``;``132245903``(d=3)→ + ``13:22:45.903``;``1310228050``(d=4)→ ``13:10:22.8050``。 + + 历史错误(0.8.0 修正):此前按「小时 + 百万分之一小时」解码 —— 用 + ``divmod(raw, 1_000_000)`` 取小时、余数按每秒 3600/1e6 折算。股票会把 + 11:29:59 解成 **11:17:57**(基准错了、速率也只有真实时钟的 53%), + ETF / 债券更会解出 ``113:00:21.222`` 这种小时 > 23 的非法值。 + + ⚠️ 服务端怪癖:**SS 落在 50~59 秒时写成 90~99**(编码值 +40 秒)。实测 + 3 分钟连续采样,未修正时该区间的滞后会从稳定的 10.6 秒突然变成 -29.4 秒 + (正好差 40)。因此这里对 ``SS >= 60`` 一律减 40 秒还原。 + + ⚠️ 指数(``sh000001`` / ``sz399001`` …)该字段**不是**这只时钟:解出来 + MM 常 > 59、且不同指数互相矛盾(同一时刻 000001 是 12:89、399001 是 12:15), + 协议里没有给出可用信息。这类返回值一律为空串,不要编造时间;要指数时间 + 请用 :meth:`~pytdxdata.api.TdxData.get_minutes` 或 K 线。 + """ + if raw <= 0: + return "" + d = digits if 0 <= digits <= 6 else 2 + scale = 10 ** d + frac = raw % scale + rest = raw // scale + seconds = rest % 100 + minutes = (rest // 100) % 100 + hours = rest // 10000 + if seconds >= 60: + seconds -= _SERVER_TIME_SKEW + if hours > 23 or minutes > 59 or not 0 <= seconds <= 59: + return "" + return f"{hours:02d}:{minutes:02d}:{seconds:02d}.{frac:0{d}d}" class GetSecurityQuotesCmd(BaseCommand[list[SecurityQuote]]): @@ -235,13 +272,14 @@ class GetSecurityQuotesCmd(BaseCommand[list[SecurityQuote]]): pos += 4 code = code_b.decode("utf-8").rstrip("\x00") - divisor = 10 ** price_decimal_digits(market_b, code) + dp = price_decimal_digits(market_b, code) + divisor = 10 ** dp p = price_raw / divisor results.append(SecurityQuote( market=market_b, code=code, price=p, cur_vol=float(cur_vol), rise_speed=_rise_speed / 100.0, - decimal_point=price_decimal_digits(market_b, code), + decimal_point=dp, open_amount=float(_unknown_3), pre_close=(price_raw + last_close_diff) / divisor, open=(price_raw + open_diff) / divisor, @@ -250,8 +288,8 @@ class GetSecurityQuotesCmd(BaseCommand[list[SecurityQuote]]): vol=float(vol), amount=amount, s_vol=float(s_vol), b_vol=float(b_vol), bid=[((price_raw + d) / divisor, v) for d, v in bid], ask=[((price_raw + d) / divisor, v) for d, v in ask], - server_time=format_server_time(unknown_0), + server_time="" if is_cn_index(market_b, code) + else format_server_time(unknown_0, dp), trading_status=trading_status, )) return results - return results diff --git a/tests/test_quote_time.py b/tests/test_quote_time.py new file mode 100644 index 0000000..c26ec26 --- /dev/null +++ b/tests/test_quote_time.py @@ -0,0 +1,106 @@ +"""报价快照时间字段(0x053E 第 6 个变长字段)解码口径。 + +2026-10-30 修正前按「小时 + 百万分之一小时」解码,股票 11:29:59 会解成 +11:17:57、ETF 会解出 `113:00:21` 这种非法小时。这里把实测口径锁死: +十进制位拼接 `HH MM SS` + 价格小数位,SS 的 50~59 段服务端写成 90~99。 +""" +import struct + +from pytdxdata.protocol.commands.quotes import ( + GetSecurityQuotesCmd, + format_server_time, + price_decimal_digits, +) +from pytdxdata.protocol.price import put_price + +# ---------- 纯解码 ---------- + +def test_stock_two_digits(): + # 13:22:40.02(股票价格 2 位小数 → 时间带 2 位小数) + assert format_server_time(13224002, 2) == "13:22:40.02" + + +def test_etf_three_digits(): + # 13:22:45.903(ETF 3 位小数) + assert format_server_time(132245903, 3) == "13:22:45.903" + + +def test_bond_four_digits(): + # 13:10:22.8050(国债 / 回购 4 位小数) + assert format_server_time(1310228050, 4) == "13:10:22.8050" + + +def test_seconds_50_59_written_as_90_99(): + # 服务端把 52 秒写成 92 → 必须还原成 13:17:52.01 + assert format_server_time(13179201, 2) == "13:17:52.01" + assert format_server_time(13179501, 2) == "13:17:55.01" + assert format_server_time(13179801, 2) == "13:17:58.01" + # 90 以下原样(不要误伤 51、59 这类合法秒) + assert format_server_time(13175101, 2) == "13:17:51.01" + assert format_server_time(13175901, 2) == "13:17:59.01" + + +def test_index_and_garbage_return_empty(): + # 指数该字段不是时钟(同一时刻 000001 解出 12:89 → MM 越界) + assert format_server_time(12867393, 2) == "" + assert format_server_time(0, 2) == "" + # 小时越界 + assert format_server_time(113005895, 2) == "" + + +def test_digits_follow_decimal_point(): + assert price_decimal_digits(1, "600000") == 2 + assert price_decimal_digits(1, "510300") == 3 + assert price_decimal_digits(1, "019547") == 4 + + +# ---------- 整条报文 ---------- + +def _quote_record(market: int, code: str, price_raw: int, time_raw: int, + vol: int = 1000, rise: int = 0) -> bytes: + """按 0x053E 记录布局拼一条报价(金额字段填 0,不参与本节断言)。""" + out = bytearray(struct.pack(" bytes: + # 前 2 字节是服务端魔数(解析时跳过),随后是 2 字节条数 + return b"\x00\x00" + struct.pack("