feat: 指数成分成交汇总 + 债券/回购价格标度修复 + 美股分时 hour 修复 (0.6.5) (#6)
* feat: 指数成分成交汇总 + 债券/回购价格标度修复 + 美股分时 hour 修复 新增 - get_index_members / get_index_trade_stats / get_index_trade_stats_multi: 由成分股逐笔累加出指数的每分钟成交量与成交笔数(协议里指数本身没有笔数, trade_count 实为均价*1000) - CLI: tdx index-stats 修复 - price_decimal_digits 补齐债券/回购 4 位小数档:沪市少 100 倍、深市少 10 倍, 沪市 B 股 900xxx 改为 3 位。已用全量 51982 只标的的 SecurityInfo.decimal_point 逐条比对,零例外 - MinuteBar.hour 对美股(EX)出现 24~27:改为 hour%=24 + day_offset, 新增 datetime / trading_date 只读属性;A股/港股零行为变化 测试 217 -> 289 * chore: bump version 0.6.5 --------- Co-authored-by: openbot-coder <openbot-coder@users.noreply.github.com>
This commit is contained in:
1 parent
ca24521d2c
commit
b84a6c8a1b
15 files changed
+1129
-21
No files matched your search
+123
@@ -2,6 +2,129 @@
|
||||
|
||||
本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
|
||||
|
||||
## [0.6.5] - 2026-10-22
|
||||
|
||||
### 新增
|
||||
|
||||
- **指数成分成交汇总:一条接口拿到「某指数下全部股票的成交量与成交笔数」**
|
||||
(`get_index_members` / `get_index_trade_stats` / `get_index_trade_stats_multi`)。
|
||||
|
||||
起因是一个绕不开的协议事实:**指数本身没有成交笔数**。指数逐笔(`sh000001`)的
|
||||
`trade_count` 字段实际是「当时均价 × 1000」(2026-10-21 已验证),`get_minutes` /
|
||||
`get_market_stat` / `SecurityBar` / `get_quotes` 的 160 个字段位里也都**没有**笔数
|
||||
(扫描 0x122C 全字段位确认,`0x8`/`0x9` 是外盘/内盘手数)。所以「指数笔数」唯一可行
|
||||
的口径是**把成分股的逐笔笔数累加**。
|
||||
|
||||
```python
|
||||
async with TdxData() as td:
|
||||
st = await td.get_index_trade_stats("000300") # 沪深300,约 10 s
|
||||
for hhmm, cum in st.cum_trade_count(): # 截止该分钟的累计笔数
|
||||
print(hhmm, cum)
|
||||
st.minutes[0] # MinuteTradeStat(time='09:25', volume=…, trade_count=…)
|
||||
st.total_volume # 手
|
||||
st.total_trade_count # 笔
|
||||
```
|
||||
|
||||
| 方法 | 作用 |
|
||||
|---|---|
|
||||
| `get_index_members(index, *, fields=None, count=100000)` | 指数成分股(含实时报价)。裸 6 位按**指数语义**解析:`000001`=上证指数,不是平安银行 |
|
||||
| `get_index_trade_stats(index, date=None, *, concurrency=24, batch_size=50, members=None, skip_errors=True, on_progress=None)` | 成分逐笔 → 每分钟成交量/笔数;`date` 支持历史 |
|
||||
| `get_index_trade_stats_multi(index, dates, *, ...)` | 多日批量(成分只请求一次),用于「近 N 日同时点均值」基准 |
|
||||
|
||||
**口径校验(2026-10-22 实测)**:``total_amount`` 是**成分股**合计。对「成分 = 指数
|
||||
覆盖面」的指数,它与指数快照 ``amount`` 完全相等 —— 说明成分清单与量能口径一致。
|
||||
|
||||
| 指数 | 成分 | 成分合计 | 指数快照 | 比值 | 耗时 |
|
||||
|---|---|---|---|---|---|
|
||||
| `sh000016` 上证50 | 50 | 661.38 亿 | 661.34 亿 | 1.0001 | 5.8 s |
|
||||
| `sh000300` 沪深300 | 300 | 2373.98 亿 | 2373.98 亿 | 1.0000 | 9.7 s |
|
||||
| `sh000001` 上证指数 | 2230 | 3907.00 亿 | 4111.56 亿 | 0.9503 | 35.6 s |
|
||||
|
||||
历史日期同样成立(2026-10-21 收盘数据):`sh000016` 1046.29 / 1045.59 亿(1.0007)、
|
||||
`sh000300` 3881.65 / 3879.30 亿(1.0006)。
|
||||
|
||||
单只股票级别的口径更硬:`Σ(逐笔价 × 手 × 100)` 与日线 `amount` 比值
|
||||
**1.0000~1.0004**(`sh600000` / `sz000001` / `sh601398` / `bj920002` / `bj920015`
|
||||
全部吻合),`Σvol` 与快照 `vol` 比值 1.0000。
|
||||
|
||||
CLI 同步新增:`tdx index-stats 000300 --top 10`。
|
||||
|
||||
**三个必须知道的限制**:
|
||||
|
||||
1. **深市 `399xxx` 的指数成交额是「全板块」口径**,不是样本股 —— 实测
|
||||
`sz399001` 快照 5081.40 亿 = 深市 2908 只股票合计 5081.01 亿,`sz399006`
|
||||
2568.60 亿 = 创业板全部股票合计。所以拿它跟 `total_amount` 比会得到 0.43 这种
|
||||
无意义比值,不是数据错。**`get_index_trade_stats` 返回的始终是成分口径。**
|
||||
2. **北交所(`899xxx`)没有笔数字段** —— 逐笔 `trade_count` 恒为 0,此时
|
||||
`trade_count_available` 为 `False`,只有成交量可用。
|
||||
3. **成分表比全市场滞后** —— 上证指数返回 2230 只,而 `get_universe("sh")` 里
|
||||
股票段共 2360 只,差 130 只(新上市尚未纳入服务端板块),这正是上表
|
||||
0.9503 的来源;`sh000016`/`sh000300` 这类固定样本指数不受影响。
|
||||
需要精确覆盖时可自行传 `members=[...]`。
|
||||
|
||||
### 修复
|
||||
|
||||
- **债券与回购价格全线偏差:沪市少 100 倍、深市少 10 倍**(`get_quotes`)。
|
||||
|
||||
`price_decimal_digits` 只覆盖了「股票 2 位 / 基金 3 位」两档,债券与回购没有对应
|
||||
分支,落到默认档位。它们实际是 **4 位小数**,于是被读大了两个数量级:
|
||||
|
||||
| 标的 | 真实价 | 修复前 | 偏差 |
|
||||
|---|---|---|---|
|
||||
| `sh019742` 国债 24特国01 | 110.2280 | 11022.8000 | ×100 |
|
||||
| `sh110077` 可转债 洪城转债 | 199.2790 | 19927.9000 | ×100 |
|
||||
| `sh204001` 回购 GC001 | 1.3850 | 138.5000 | ×100 |
|
||||
| `sh900901` B股 云赛B股 | 0.5670 | 5.6700 | ×10 |
|
||||
| `sz123107` 可转债 温氏转债 | 112.1890 | 1121.8900 | ×10 |
|
||||
| `sz131810` 回购 R-001 | 1.3800 | 13.8000 | ×10 |
|
||||
|
||||
沪市 `010/018/019/020/1xx/2xx` 与深市 `10x-14x/19x/50x/52x/56x` 全部改为 4 位;
|
||||
沪市 B 股 `900xxx` 另改为 3 位(与深市 `200xxx` 的 2 位不同,两市不一致)。
|
||||
股票 / ETF / 指数 / 板块的行为**不变**。
|
||||
|
||||
**验证方式(可作为该函数的验收标准)**:拿 `pre_close`(五档快照口径,走
|
||||
`price_decimal_digits`)除以上一交易日**日线收盘**(K线口径,走独立的 `/1000`
|
||||
路径),比值 1.0 即两口径一致。修复后 15 类标的全数为 1.0000,零偏差。
|
||||
|
||||
**权威来源已确认**:证券列表里协议**自带** `SecurityInfo.decimal_point` 字段。
|
||||
2026-10-22 拉取全量 **51,982 只**(沪 27,520 + 深 24,462)逐条比对,本函数与
|
||||
协议字段**完全一致、零例外**——因为全量清单里没有任何一个「三位前缀」出现混合
|
||||
小数位。`get_quotes` 解析时拿不到证券清单,故仍用前缀推断;需要权威值时读
|
||||
`SecurityInfo.decimal_point`。
|
||||
|
||||
- **美股(EX 通道)分时的 `hour` 是非法时钟值**(`get_minutes("usAAPL")`)。
|
||||
|
||||
EX 分时的 `minutes` 字段是**自开盘起的连续分钟数**,不是「当天的分钟数」。
|
||||
旧代码直接 `minutes // 60`,于是 390 条里 **240 条** 的 `hour` ≥ 24:
|
||||
|
||||
```
|
||||
修复前: 21:30, 21:31, ..., 23:59, 24:00, 24:01, ..., 27:59 ← hour=27 不存在
|
||||
修复后: 21:30, 21:31, ..., 23:59, 00:00, 00:01, ..., 03:59 ← 真实北京时间
|
||||
```
|
||||
|
||||
任何 `datetime(...)` 拼接都会因 `hour=27` 抛 `ValueError`,按小时聚合也会把
|
||||
凌晨段错误地归到同一个自然日。
|
||||
|
||||
**修法**:`MinuteBar.__post_init__` 把越界的 `hour` 拆成
|
||||
「`hour %= 24` + `day_offset += hour // 24`」,并新增两个只读属性:
|
||||
|
||||
| 属性 | 用途 |
|
||||
|---|---|
|
||||
| `MinuteBar.datetime` | 该分时点的时刻(北京时间,已含跨日偏移) |
|
||||
| `MinuteBar.trading_date` | 归属的交易日 `YYYY-MM-DD`。美股一个交易日横跨两个北京自然日(21:30~次日 04:00),**按交易日聚合必须用它**,与 `SecurityBar.trading_date` 口径一致 |
|
||||
|
||||
A股(合成时间 09:30~15:00)/ 港股(09:30~16:00)/ 期货的 `hour` 本就合法
|
||||
→ **零行为变化**,`day_offset` 恒为 0。
|
||||
|
||||
实测(2026-10-22):`usAAPL` / `usTSLA` / `usNVDA` 各 390 条,修复后
|
||||
`hour` 全在 0~23、时间轴严格单调、`trading_date` 收敛为单一交易日;
|
||||
`hk00700` 90 条无任何变化。
|
||||
|
||||
### 说明
|
||||
|
||||
- 新增回归测试:债券/回购/B股小数位 ×29、美股分时跨日 ×6、指数成分成交汇总 ×34、
|
||||
全接口 ×1,测试总数 **217 → 289**。
|
||||
|
||||
## [0.6.4] - 2026-10-22
|
||||
|
||||
### 修复
|
||||
|
||||
Reference in new issue
Block a user