fix: 修复沪市指数价格少10倍 + 逐笔竞价委托污染(Σvol 虚高/跨主机不稳定) (#3)

核对 sh000016 上证50 与 50 只成分股的 tick 汇总时,发现三个口径
(快照/分时/逐笔)互不一致,追查到 5 个缺陷。

1. 沪市指数价格整体少 10 倍
   price_decimal_digits 把沪市 000xxx(上证/上证50/沪深300/科创50)与
   8xxxxx(板块指数)判为 3 位小数,实际协议是 2 位。
   上证指数 3713 -> 371、上证50 2747 -> 274。
   实证 6 只指数 + 2 只板块指数全部 ×10,而 ETF/股票/科创板/深市全类 ×1 正确。
   改法:沪市仅 ETF(5开头) 保留 3 位,其余 2 位。

2. get_ticks 把 bs_flag=8 竞价委托当成成交
   该记录是 09:15~09:25 / 14:57~15:00 竞价段的撮合委托快照,
   vol 是累计值(可被后续覆盖),不是成交增量。
   - Σvol 虚高:sh600000 含 b8 = 668,693 vs 快照 462,562(1.4456);
     剔 b8 = 462,634(1.000156,精确一致)
   - 跨主机不稳定:干净主机 0 条、脏主机 135 条 -> 同一 start 落到不同真实成交
   改法:分页后统一剔除 b8。

3. A股逐笔改单连接串行游标(_ticks_cn_serial)
   并发分页各页来自不同主机,而 0x122F 的 start 是「从最新往回数」的相对锚点,
   主机间 b8 收录差异导致页边界既重叠(冗余 116 条)又漏条(13:03 附近丢 59 条)。
   逐笔单日仅 5~6 页,串行开销可忽略。

4. trade_count 有符号解析(前序)、返回列表时间序(前序)保留。

- sh000016 三口径闭合:快照 vol/amount 比值 1.00000061/0.99999997;
  指数逐笔 Σvol = 分时 Σvol = 1,045,584,467(完全相等)
- 6 只标的 Σvol/快照 vol 全部回到 1.0001~1.0007
- 跨主机公共时间窗逐条一致(5/5 标的,条数差 0)
- 测试 194 -> 217 passed(+20 小数位、+3 逐笔回归)

- TransactionRecord 类注释 + get_ticks docstring 明示指数语义:
  vol 单位「百元」(成交额/100)、trade_count 为「均价×1000」而非笔数
- API_REFERENCE / llms.txt 同步

Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
This commit is contained in:
openbotandopenbot-coder authored and GitHub committed 2026-10-22 09:06:40 +08:00
1 parent dfd6fab3af
commit 8344ed6e6b
10 files changed
+493 -39

No files matched your search

+92 -22
View File
@@ -146,6 +146,8 @@ _EX_PAGE = 1000 # EX 商品列表单页
_TICK_PAGE = 1000 # MAC 逐笔单页
_EX_TICK_PAGE = 1800 # 港股逐笔单页
_ALL_PAGES_CAP = 50 # count=None(全量)时的翻页上限
# 集合竞价**委托**记录标记(0x122F 第 5 字段)。不是成交,见 _ticks_one 注释。
_BS_AUCTION_ORDER = 8
# 港股系市场:逐笔走 EX 专用 16B 协议(0x23FC/0x2406),其余扩展市场走 MAC 0x122F
_HK_MARKETS = frozenset({27, 31, 48, 49, 71, 98})
@@ -795,12 +797,26 @@ class TdxData:
参数:
date: ``None``=当日,``YYYYMMDD``=历史某日。
start: 起始偏移。
start: 起始偏移,**从最新一笔往回数**(``0``=当天最后一条)。
``start=1000`` 表示跳过最近 1000 条、从更早的位置开始。
count: ``None``=尽量取全量(自动翻页,上限 50 页);给了就取这么多条。
返回:
``list[TransactionRecord]``,按入参标的顺序拼接(A股含 ``trade_count``,
港股为 HH:MM 时间 + ``fields["zengcang"]`` 增仓)。
``list[TransactionRecord]``,按入参标的顺序拼接,**每条标的内部按时间升序**。
注意服务端是按约 3 秒聚合的切片,``vol``/``trade_count`` 是切片增量
而非当日累计。
A股含 ``trade_count``,港股为 HH:MM 时间 + ``fields["zengcang"]`` 增仓。
**集合竞价委托(``bs_flag=8``)不会出现在结果里**:它们不是成交,``vol``
是累计撮合量(会被后续记录覆盖),计入会让 Σvol 比真值虚高 20%~160%,
且不同主机收录的条数不同 → 同一查询两次调用结果不一致。
**指数(``sh000016`` 等)的两个字段语义与个股不同**:
- ``vol`` 单位是**百元**(成交额/100),不是手。
- ``trade_count`` 是**当时均价 × 1000**,不是笔数。
详见 :class:`~pytdxdata.models.TransactionRecord` 的类注释。
"""
syms = parse_symbols(symbols)
sem = asyncio.Semaphore(max(1, concurrency))
@@ -821,18 +837,19 @@ class TdxData:
if sym.is_ex:
rows = await self._ticks_ex(sym, date=date, start=start, count=count)
else:
def make_cmd(s: int, c: int):
return MacTransactionCmd(sym.market, sym.code, date or 0, s, c)
spec = PageSpec(
page_size=_TICK_PAGE,
total=None if count is None else start + count,
min_page=100,
stop_when_short=True,
max_pages=_ALL_PAGES_CAP if count is None else None,
start_offset=start,
)
rows = await self._fetch_paginated_list("mac", make_cmd, spec)
rows = await self._ticks_cn_serial(sym, date=date, start=start,
count=count)
# ★ 过滤集合竞价**委托**记录(bs_flag=8)。必须在逐页拉取**全部结束之后**做:
# 分页靠 `len(rows) < page_size` 判终止,若在 parse_response 里过滤,
# 满页会被剥短成"短页" → 提前终止 → 丢数据。
# 实测(2026-10-21 sh600000):b8 是 09:15~09:25 / 14:57~15:00 竞价段的
# 撮合快照,vol 是**累计值**(可被后续记录覆盖),不是成交增量;
# 计入后 Σvol 比真值虚高 20%~160%,且**不同主机的 b8 集合不同**
# (干净主机 0 条、脏主机 135 条)→ 同一查询两次调用结果不一致。
# 剔除后:Σvol 与快照 vol 精确相等(比值 1.0000),且跨主机逐条一致。
rows = [r for r in rows if r.bs_flag != _BS_AUCTION_ORDER]
# 排序放在 pack 之前,让缓存直接存入正确顺序,避免每次命中都重排。
rows.sort(key=lambda r: r.time)
return pack_payload(rows)
records = unpack_payload(await self._cache.get_or_fetch(key, fetch))
@@ -840,6 +857,54 @@ class TdxData:
r.symbol = sym.text
return records
async def _ticks_cn_serial(self, sym: Symbol, *, date: int | None, start: int,
count: int | None) -> list[TransactionRecord]:
"""A股逐笔(0x122F)**单连接串行游标**翻页。
为什么不用并发分页器:``0x122F`` 的 ``start`` 是「从**最新一笔**往回数的偏移」,
是个**相对锚点**,不是稳定的绝对序号。而池里各主机对集合竞价委托(``bs_flag=8``)
的收录**不一致**(实测干净主机 0 条、脏主机 135 条),同一 ``start`` 在不同主机上
落到**不同的真实成交**上。并发分页 = 各页来自不同主机 → 页边界既**重叠**
(sh600000 冗余 116 条)又**漏条**(13:03 附近丢 59 条),Σvol 偏移 −1.2%。
逐笔单日仅 5~6 页(1000 条/页),串行开销可忽略、换来精确一致,
故这里固定**单连接**、按 ``start`` 递增(= 向更早方向)推进。
返回:按页序累加后再**整体翻转**,得到时间升序的完整列表。
"""
chunks: list[list[TransactionRecord]] = []
pos = start
remaining = count
pc = await self._mac_pool.acquire()
try:
for _ in range(_ALL_PAGES_CAP):
n = _TICK_PAGE if remaining is None else min(_TICK_PAGE, remaining)
if n <= 0:
break
rows = await pc.execute(
MacTransactionCmd(sym.market, sym.code, date or 0, pos, n))
if not rows:
break
chunks.append(list(rows))
pos += len(rows)
if remaining is not None:
remaining -= len(rows)
if remaining <= 0:
break
# 短页 = 已到最早一笔
if len(rows) < n:
break
except Exception:
await self._mac_pool.release(pc, broken=True)
raise
await self._mac_pool.release(pc)
out: list[TransactionRecord] = []
for chunk in reversed(chunks):
out.extend(chunk)
for r in out:
r.symbol = sym.text
return out
async def _ticks_ex(self, sym: Symbol, *, date: int | None, start: int,
count: int | None) -> list[TransactionRecord]:
from .protocol.commands.ex_ext import (
@@ -848,7 +913,7 @@ class TdxData:
)
hk = sym.market in _HK_MARKETS
page = _EX_TICK_PAGE if hk else _TICK_PAGE
out: list[TransactionRecord] = []
chunks: list[list[TransactionRecord]] = []
pos = start
remaining = count
for _ in range(_ALL_PAGES_CAP):
@@ -860,22 +925,27 @@ class TdxData:
if date else
GetExTransactionDataCmd(sym.market, sym.code, pos, n))
rows = await self._execute_ex(cmd)
out.extend(self._ex_tick(sym, r) for r in rows)
chunk = [self._ex_tick(sym, r) for r in rows]
else:
cmd = MacTransactionCmd(sym.market, sym.code, date or 0, pos, n)
rows = await self._execute_ex(cmd)
for r in rows:
r.symbol = sym.text
out.extend(rows)
if not rows:
chunk = list(rows)
if not chunk:
break
pos += len(rows)
# EX 通道的 pos 同样是"从最新往回数",逐页倒序累加 → 最后整体翻转。
chunks.append(chunk)
pos += len(chunk)
if remaining is not None:
remaining -= len(rows)
remaining -= len(chunk)
if remaining <= 0:
break
if len(rows) < n:
if len(chunk) < n:
break
out: list[TransactionRecord] = []
for chunk in reversed(chunks):
out.extend(chunk)
return out
@staticmethod
+24 -4
View File
@@ -228,14 +228,34 @@ class SecurityInfo:
@dataclass(slots=True)
class TransactionRecord:
"""逐笔成交(跨市场统一模型;A股 MAC 通道含 trade_count=成交笔数)"""
"""逐笔成交(跨市场统一模型;A股 MAC 通道含 trade_count=成交笔数)。
注意(实测 2026-10-21):
- 服务端是按**约 3 秒聚合**返回的切片,不是交易所原始逐笔成交。
- ``vol`` / ``trade_count`` 都是**该切片自身的增量**,不是当日累计值。
- ``trade_count`` 为**有符号**值:集合竞价段(``bs_flag=8``)会是负数
(实测 sh600000 09:15 段为 -874),不要对全表直接求 max/mean。
- 返回列表已按时间升序,但同秒多条时顺序不保证。
- ``bs_flag=8`` 的**竞价委托记录已被 ``get_ticks()`` 过滤掉**,不会出现在结果里。
**指数语义完全不同**(``is_cn_index`` 为真时,如 ``sh000016``):
- ``vol`` 单位是**百元**(= 成交额 / 100),不是「手」。实测
``快照amount / Σtick.vol = 100.0002``,且 ``Σtick.vol`` 与分时 Σvol **逐位相等**。
想和成分股成交量对比必须先换算,直接比会得到 ~26 倍的假比例。
- ``trade_count`` **不是笔数**,而是**当时均价 × 1000**(实测 tc/1000 与分时
``avg_price`` 的差 < 1.1)。指数没有「成交笔数」概念。
- ``bs_flag`` 语义不成立(实测返回 2,而模型只定义 0=卖 / 1=买)。
"""
market: int
code: str
time: str # HH:MM:SS(扩展市场为 HH:MM)
price: float
vol: float # 手(MAC逐笔)
trade_count: int # 成交笔数(MAC=逐笔记录字段;标准当日逐笔协议也有但需单独解析)
bs_flag: int # 1=主动买 0=主动卖
vol: float # 股票=手;指数=百元(成交额/100),见类注释
trade_count: int # 股票=笔数增量;指数=均价×1000,见类注释
bs_flag: int # 1=主动买 0=主动卖 2=中性 5=盘后固定价(指数语义不成立)
symbol: str = ""
fields: dict[str, float] = field(default_factory=dict) # 扩展市场额外字段(增仓等)
+13 -6
View File
@@ -13,16 +13,23 @@ MAX_QUOTES = 80
def price_decimal_digits(market: int, code: str) -> int:
"""推断报价有效小数位:股票2位(/100)、指数/ETF/基金/转债/国债3位(/1000)。"""
"""推断报价有效小数位:股票 2 位(/100)、ETF/基金 3 位(/1000)。
**沪市指数必须是 2 位**,此前把 ``000``/``8`` 一并判成 3 位,导致上证50、
上证指数、科创50 等**价格整体少 10 倍**。实证(2026-10-21):协议原始整数
与分时/逐笔价格比对,6 只沪市指数 + 2 只板块指数(880001/880305)全部是
``×10`` 错误,而 4 只沪市 ETF(510300/510500/588000/511010)、4 只沪市
股票、3 只科创板、3 只深市指数、深市股票/创业板/ETF 全部 ``×1`` 正确。
"""
code = (code or "").strip().rstrip("\x00")
if market == 1: # SH
if code.startswith(("5", "000", "8")):
return 3
return 2
if code.startswith("5"):
return 3 # ETF/基金
return 2 # 指数(000xxx/880xxx)、股票(60xxxx/688xxx)
if market == 0: # SZ
if code.startswith("1"):
return 3
return 2
return 3 # 基金/债券
return 2 # 指数(399xxx)、股票(00xxxx/30xxxx)
return 2
@@ -111,8 +111,11 @@ class MacTransactionCmd(BaseCommand[list[TransactionRecord]]):
for i in range(count):
offset = 39 + i * 18
try:
# trade_count 必须按**有符号** int32 解析:集合竞价段(bs_flag=8)
# 该字段实为负值,按 uint32 会读出 42 亿量级的脏数据。
# 实测(2026-10-21 sh600000):09:15:03 原始 96fcffff = -874。
time_sec, price, volume, trade_count, bs_flag = unpack_from(
"<IfIIH", body, offset, "mac transaction item"
"<IfIiH", body, offset, "mac transaction item"
)
except ValueError:
break
+7 -3
View File
@@ -27,6 +27,7 @@ class PageSpec:
ordered: bool = True # 按 start 升序拼接
min_page: int = 100 # 规避标准K线 count<100 空响应坑
start_offset: int = 0 # 起始偏移(从该偏移开始分页,避免拉取历史全量)
newest_first: bool = False # 服务端 start 从最新往回数(0x122F 逐笔即如此)
@dataclass(slots=True)
@@ -94,7 +95,7 @@ class Paginator:
if s.pc is not None:
pc, s.pc = s.pc, None
await self.pool.release(pc)
return self._assemble(out, spec.ordered)
return self._assemble(out, spec.ordered, spec.newest_first)
def _plan_starts(self, spec: PageSpec) -> list[tuple[int, int]]:
"""切页:返回 [(start, count), ...]。"""
@@ -158,9 +159,12 @@ class Paginator:
return None, False
return None, False
def _assemble(self, results: list[PageResult], ordered: bool) -> list[Any]:
def _assemble(self, results: list[PageResult], ordered: bool,
newest_first: bool = False) -> list[Any]:
# newest_first=True:start=0 是最新一页,start 越大越旧 → 反向拼才对得上时间序。
# 单页内部服务端已按时间升序,所以只翻页序,不翻页内元素。
if ordered:
results.sort(key=lambda r: r.start)
results.sort(key=lambda r: r.start, reverse=newest_first)
out: list[Any] = []
for r in results:
out.extend(r.items)