美股盘前盘后数据接入前的 4 项核验：交易窗口、返回样本、timestamp 与失败分支
摘要：面向开发者的美股盘前盘后数据接入核验清单：先查交易窗口，再验证真实样本与timestamp，最后保留限流和空返回等失败分支，避免把一次成功查询误写成行情覆盖或策略有效性证明。
接入美股盘前盘后数据时，最容易写错的不是请求语法，而是验证顺序：先假定“有盘前盘后”，再默认“这些时段持续有可用行情”，最后直接拿样本讨论研究或策略。
更稳妥的工程顺序是：先确认查询到的交易窗口，再检查真实样本是否返回，然后统一timestamp口径并保留失败分支。本文以 TickDB MCP 的一次结构核验为例，不展示动态价格，也不将单次返回外推为完整行情覆盖。
1. 先查交易窗口，不先假定数据覆盖
在支持 TickDB MCP 的环境中，可先执行get_trading_sessions("US")。在2026-05-27的当次核验中，该查询返回了US市场及三段会话结构，原始时间段为400-930、930-1600、1600-2000，前后两段带有 session 标记。
这一步只能回答“接口返回了哪些交易窗口结构”，不能回答以下问题：
| 可确认 | 不能据此确认 |
|---|---|
| 查询得到三段会话结构 | 每个美股标的在各段都有连续报价 |
| 返回包含盘前、常规、盘后区分信息 | 所有交易场所、券商或数据源口径完全一致 |
| 后续样本检查应按窗口划分 | 这些数据已适合回测或交易决策 |
工程上还应把返回窗口与目标交易场所的官方时段说明交叉核对，并在转换展示时间前确认时区口径。
2. 再验证真实样本返回，而不是只验证 symbol 可识别
窗口存在后，下一步是用真实标的检查是否真的拿到样本。本文核验顺序为：
| 核验动作 | 验收项 | 失败时怎么记录 |
|---|---|---|
get_stock_info("AAPL.US", type="stock") | AAPL.US可被识别为美股标的 | 记录 symbol 或资产类型不匹配 |
get_recent_trades("AAPL.US", type="stock", limit=1) | 返回symbol与非空trades | 记录为空、权限失败或调用错误 |
| 检查单条成交字段 | 存在id、price、quantity、side、timestamp | 不臆造缺失字段，不补写演示输出 |
当次核验确实获得了一条包含上述字段的成交样本。但这仍然只证明“该次请求返回了样本”，没有证明该样本属于盘前或盘后，更没有证明任意时点都可稳定返回 Extended Hours 数据。
因此，真正的覆盖核验还应追加记录：采样日期、目标时间窗口、symbol 列表、请求次数、空返回比例和失败原因。没有这些日志，就不应把一次成功请求写成覆盖承诺。
3. 处理 timestamp：先统一单位，再判断样本属于哪个窗口
接入过程中，timestamp是最容易被误读的字段之一。当次AAPL.US最近成交样本中的timestamp为秒级结构；审计事实也要求区分不同通道的时间单位。
验证清单应至少包含四项：
| 检查项 | 写法边界 |
|---|---|
检查timestamp位数与单位 | 不假定所有接口都统一为毫秒 |
| 统一转换为 UTC 后再对齐交易窗口 | 不在单位未确认前判断盘前或盘后 |
| 同时记录查询时间与返回样本时间 | 不把字段精度等同于数据新鲜度 |
| 跨接口拼接时检查时间差 | 不由 13 位时间戳推出高频或实盘可用性 |
尤其需要注意：时间字段更细，并不自动意味着行情更快、更连续，也不代表它可以直接支持某类策略判断。
4. 把失败分支当作核验结果的一部分
只展示成功路径，会让接入文章看起来顺畅，却无法指导真实排错。在本次结构核验中，另一次行情查询命中了3001限流错误，这正说明验证流程必须留下失败记录。
建议将失败分支分成四类处理：
| 失败类型 | 处理原则 |
|---|---|
| 鉴权或缺少 Key | 阻断继续请求，先修复凭证或请求头 |
| symbol 不存在 | 回到可用品种查询，确认代码和资产类别 |
| 限流 | 记录错误；REST 场景按当前规则读取重试信息并做有限退避 |
| 空数据或无样本 | 记为验证结果，不将空返回改写为“支持但暂未展示” |
本文不提供完整 REST 调用代码，是因为本次证据足以支撑 MCP 核验步骤和返回结构边界，却不足以为盘前盘后场景声明一套经过全文验证的 HTTP 输出示例。
结论：完成接入核验，不等于证明策略有效
美股盘前盘后数据接入前，至少应完成四件事：确认交易窗口、获取真实样本、统一时间口径、保留失败分支。
即使这些步骤全部通过，也只能说明数据链路在指定样本和指定时点下可被验证。它不能直接证明全品种持续覆盖、不能证明样本足以用于回测，更不能证明任何交易策略有效。涉及研究或交易使用时，还需要另行验证样本缺失、成交可执行性、时间对齐误差和风险边界。
标签：美股盘前盘后Extended Hours数据接入timestampTickDB工程排错