yuxuanhui
36 lines
3.6 KiB
Markdown
36 lines
3.6 KiB
Markdown
# Tushare 板块雷达最小契约
|
||
|
||
本文件从 `docs/research/onechartlab-tushare-data-requirements.md` 提炼首个 Radar MVP 实际需要的接口，避免实现上下文被宏观择时和后续增强接口稀释。上线前仍以目标账号的只读 capability probe 为准。
|
||
|
||
## 最小接口
|
||
|
||
| 接口 | 作用 | 调用与必要字段 | 业务键与边界 |
|
||
| --- | --- | --- | --- |
|
||
| `trade_cal` | 确认开市日和窗口 | `exchange,start_date,end_date`；`exchange,cal_date,is_open,pretrade_date` | `(exchange,cal_date)`；初始化后按年刷新 |
|
||
| `dc_index` | 当日概念/行业 universe | `trade_date,idx_type`；`ts_code,trade_date,name,idx_type,level,pct_change,leading_code` | `(trade_date,ts_code)`；概念与行业分别拉取，单次上限公开页为 5,000 |
|
||
| `dc_member` | 当日 point-in-time 成员 | 优先 `trade_date`，必要时按 `ts_code` 分片；`trade_date,ts_code,con_code,name` | `(trade_date,ts_code,con_code)`；单次上限 5,000，命中上限或覆盖不足必须分片，不得用当前成员补历史 |
|
||
| `stock_basic` | 生命周期与市场过滤 | 分别拉 `list_status=L,D,P,G,UN`；`ts_code,symbol,name,market,exchange,list_status,list_date,delist_date` | `ts_code + observed_at`；默认只返回 L，不能漏掉其他状态 |
|
||
| `suspend_d` | 区分停牌与缺数 | `trade_date`；`ts_code,trade_date,suspend_timing,suspend_type` | `(ts_code,trade_date,suspend_type,suspend_timing)`；官方称不定期修订，需重叠回拉 |
|
||
| `daily` | 成交额、涨跌幅和行情可用性 | `trade_date`；`ts_code,trade_date,close,pre_close,pct_chg,vol,amount` | `(ts_code,trade_date)`；单次上限 6,000，停牌期间不返回；`amount` 单位千元 |
|
||
| `moneyflow_dc` | 个股东财口径主力净额 | `trade_date`；`trade_date,ts_code,name,net_amount,net_amount_rate,pct_change,close` | `(ts_code,trade_date)`；单次上限 6,000，历史始于 2023-09-11；`net_amount` 单位万元 |
|
||
|
||
## 单位与规范化
|
||
|
||
- `moneyflow_dc.net_amount` 万元转元时乘 `10_000`，转亿元时除 `10_000`。
|
||
- `daily.amount` 千元转元时乘 `1_000`，转亿元时除 `100_000`。
|
||
- `daily.pct_chg=1.5` 表示 1.5%；不与 OneChartLab 小数比例字段直接混算。
|
||
- 空字符串、`None` 和 `NaN` 规范为 NULL；`inf`、`-inf`、重复业务键和错误交易日属于硬错误。
|
||
- 缺失资金流不是 0。只有生命周期有效、非停牌且源接口应有记录的股票进入缺失率分母。
|
||
|
||
## Universe 与质量
|
||
|
||
- 只纳入沪深 A 股，排除北交所与沪深 B 股；OneChartLab Radar 契约未声明排除 ST，因此不能复用现有选股股票池的 ST 过滤。
|
||
- `dc_member` 某日缺失时标记 `membership_unknown`，不能向前或向后填充。
|
||
- 全局分别计算成员、`daily` 和 `moneyflow_dc` 覆盖率；publication 只有在全部必需接口通过、成员完整且事实覆盖率达到配置门槛时才为 success。
|
||
- 板块结果输出成员数、有效样本数、成交额、成员覆盖率与资金覆盖率；有效样本少于 5 时标记 `available_limited_sample`。
|
||
- 初始回填必须按交易日顺序完成至少 10 日，才能生成完整 3—10 日独立波段指标；`moneyflow_dc` 的最早日期是硬边界。
|
||
|
||
## 客户端与安全
|
||
|
||
项目使用 `ts.pro_api(token)` 返回的 `DataApi`，动态调用最终进入 `query(api_name, fields, **params)`。客户端不执行权限、积分、频率或行数保护，采集 adapter 必须处理服务端错误、退避、返回行数和覆盖率。token 只从 `Settings` 注入，不调用 `set_token()` 写用户目录，不写入日志、原始请求清单或错误摘要。
|