黄金眼数据查询设计说明

📅 2026-07-17 📂 股票分析 ⏱ 约 25 分钟
📑 目录
  1. 1. 文档目的
  2. 2. 一期范围
  3. 3. 接口位置
  4. 4. 查询定位
  5. 5. 请求参数设计
  6. 6. 数据来源路由规则
  7. 7. 对外字段策略
  8. 8. 响应结构设计
  9. 9. 与平台能力的衔接
  10. 10. Token 预留设计
  11. 11. 后续待确认项

黄金眼数据查询设计说明

1. 文档目的

本文档用于固化数据中心 WebAPI 一期中黄金眼数据查询的接口契约、字段白名单、查询规则、分页排序规则以及与平台级能力的衔接方式。

当前阶段只输出设计说明，不涉及最终实现代码。

2. 一期范围

2.1 功能范围

一期仅实现黄金眼数据查询能力，作为统一市场数据查询接口中的第一个 queryType。

2.2 数据来源

黄金眼数据当前阶段直接来自 ClickHouse 的两张表：

  • snapshotgoldeye1d
  • snapshotgoldeye3s

其中：

  • snapshotgoldeye1d：历史日表，一天一笔
  • snapshotgoldeye3s：实时 3 秒表，3 秒一笔

按数据中心整体规划，这两类数据理论上都应归入 ADS 层对外交付对象。当前阶段由于尚未完全拆分到独立 ADS 层，因此一期允许直接从 ODS 层 ClickHouse 获取，但接口字段和返回语义应尽量按交付层口径收敛。

2.3 不在一期范围内

  • 股票 L1 查询实现
  • 多证券批量查询
  • 多市场批量查询
  • 行情写入
  • 自定义排序
  • 任意表达式查询

3. 接口位置

黄金眼查询挂在统一市场数据接口下：

  • POST /api/marketdata/query

一期固定使用：

  • query_type = goldeneye

4. 查询定位

黄金眼一期查询固定为：

  1. 单市场查询
  2. 单证券标识查询
  3. 指定时间范围查询
  4. 指定字段白名单查询
  5. 固定时间倒序分页

5. 请求参数设计

虽然黄金眼当前挂在统一 POST /api/marketdata/query 入口下，但一期请求参数命名和分页语义应尽量遵循《第1期交付设计_v0.96.pdf》的交付契约风格。

黄金眼属于时序查询对象，因此正式时间窗口字段采用 starttime、endtime，分页字段采用 pagesize、pagetoken，证券标识字段采用 symbols。

需要注意的是，黄金眼一期中的 symbols 虽然沿用 PDF 契约名称，但参数值先不带 .XSHG、.XSHE 这类交易所扩展名，直接传证券代码即可。

请求示例如下：

{
  "query_type": "goldeneye",
  "symbols": [
    "009898"
  ],
  "start_time": "2026-06-23 00:00:00",
  "end_time": "2026-06-23 16:00:00",
  "time_granularity": "AUTO",
  "market_id": 153,
  "fields": [
    "market_id",
    "code_str",
    "trade_date",
    "market_time",
    "contracts_0_0",
    "amount_1_1"
  ],
  "page_size": 5,
  "page_token": null
}

上述示例已在当前生产环境实测通过，可返回“今日最新快照折算后的日级结果”。

5.1 参数说明

参数类型必填状态说明
query_typestring是第1期上线统一市场数据入口的路由参数，一期固定为 goldeneye。
symbolsstring[]是第1期上线一个或多个证券代码。为对齐 PDF 契约，一期正式请求参数使用 symbols；当前黄金眼查询仅支持传入 1 个元素，且参数值不带 .XSHG、.XSHE 等交易所扩展名。
start_timedatetime是第1期上线查询起始时间，采用本地交易所时间，格式必须为 yyyy-MM-dd HH:mm:ss。
end_timedatetime是第1期上线查询结束时间，采用本地交易所时间，格式必须为 yyyy-MM-dd HH:mm:ss。
time_granularitystring是第1期上线查询粒度控制参数，支持 AUTO、DAY、THREE_SECOND。
market_idint是第1期上线黄金眼特有扩展参数。当前底层查询仍按 marketid 路由，单次只允许传入一个值；常用值见下方 marketid 对照表。
fieldsstring[]是第1期上线指定返回字段。至少传 1 个字段，且仅允许白名单字段。
page_sizeint是第1期上线分页大小，最大 500。
page_tokenstring否第1期上线seek 翻页标记。首次请求不传，后续原样回传上一页的 nextpagetoken。当前游标为接口内部复合游标，不要求调用方解析。

5.1.1 market_id 对照表

market_id中文含义RealDataMarketId说明
150上海黄金眼网关0对应上海证券交易所黄金眼数据
151深圳黄金眼网关1对应深圳证券交易所黄金眼数据
152板块黄金眼网关10对应周边市场/板块黄金眼数据
153香港黄金眼网关2对应香港黄金眼数据

以上映射依据 获取行情数据 项目的 appsettings.json 中 Market 配置整理。当前文档中的已验证示例统一使用 153，因为该市场在现网环境存在稳定可返回样本数据。

5.2 一期固定约束

  1. symbols 为正式对外交付参数，一次只允许传入 1 个证券代码，且当前阶段不带交易所扩展名。
  2. 当前黄金眼底层仍按 marketid + codestr 命中数据，因此接入层需要能将 symbols 解析为黄金眼内部定位口径；在标准标识解析能力稳定前，market_id 仍作为一期显式参数保留。
  3. starttime、endtime 采用左闭右开区间 [starttime, endtime)。
  4. page_size 最大 500。
  5. 3 秒实时数据最多查近 7天。
  6. AUTO 即使结束日期落在今天，也只补当天最后一条 3 秒记录，不受“近 7 天 3 秒明细跨度”限制。
  7. 历史日线最多查近 3年。
  8. starttime < endtime。
  9. fields 直接使用数据库标准字段名。
  10. fields 至少传 1 个字段。
  11. 不允许请求未开放字段。
  12. 不允许自定义排序字段。
  13. 排序固定按时间倒序返回。

5.3 time_granularity 取值说明

time_granularity 用于控制查询应优先命中哪一类数据表，以及返回结果的时间粒度。

5.3.1 AUTO

AUTO 是一期默认取值，适用于“由系统自动判断历史日表和当日 3 秒表如何拼接”的场景。

具体规则如下：

  1. 当 endtime 不在今天时，只查询 snapshotgoldeye_1d。
  2. 当 end_time 落在今天时：
  • 今天之前的数据查 snapshotgoldeye1d
  • 今天当天不返回整段 3 秒明细，只取 snapshotgoldeye3s 中该证券当天 market_time 最大的一条记录
  • 这条记录按“今天的日线数据”参与拼接返回

适用场景：

  1. 调用方不想自己区分历史和实时数据来源。
  2. 希望在一个请求中自动拿到“历史日线 + 今日最新快照”的混合结果。
  3. 黄金眼默认查询场景。

5.3.2 DAY

DAY 表示强制按日粒度查询，只返回日表数据。

具体规则如下：

  1. 只查询 snapshotgoldeye1d。
  2. 返回结果以 trade_date 为主时间字段。
  3. 即使 endtime 落在今天，也不返回 snapshotgoldeye_3s 的盘中数据。
  4. 当前口径下可视为“只查历史日表”；当天数据不由 DAY 主动补齐。

适用场景：

  1. 只需要历史日统计数据。
  2. 做日级分析、日级回测、离线汇总。
  3. 明确不需要盘中 3 秒明细。

5.3.3 THREE_SECOND

THREE_SECOND 表示强制按 3 秒粒度查询，只返回实时 3 秒表数据。

具体规则如下：

  1. 只查询 snapshotgoldeye3s。
  2. 返回结果以 market_time 为主时间字段。
  3. 不返回任何 snapshotgoldeye1d 的历史日表记录。
  4. 查询时间范围仍受“最多近 7 天”的限制。

适用场景：

  1. 只需要盘中 3 秒级明细。
  2. 做实时监控、盘中分析、短周期行为观察。
  3. 调用方明确要排除历史日聚合结果。

6. 数据来源路由规则

6.1 基本规则

黄金眼查询按时间范围路由到底层两张表：

  1. 当 timegranularity = DAY 时，只查询 snapshotgoldeye_1d
  2. 当 timegranularity = THREESECOND 时，只查询 snapshotgoldeye3s
  3. 当 timegranularity = AUTO 且 endTime 不在今天时，只查询 snapshotgoldeye_1d
  4. 当 time_granularity = AUTO 且 endTime 落在今天时：
  • 今天之前的数据查 snapshotgoldeye1d
  • 今天当天只取 snapshotgoldeye3s 中最后一条记录参与拼接

6.2 今日数据规则

今天的数据不直接返回整段 snapshotgoldeye3s 明细，而是只取当天最后一条记录，按今天日线口径参与返回。

这样可以避免：

  1. 同一天同时出现大量 3 秒明细和历史日线混在一起
  2. AUTO 与 THREE_SECOND 的职责边界不清
  3. 调用方对“今日数据到底是明细还是日级快照”产生混淆

6.3 分页与排序

实现时需保证：

  1. 历史与实时数据统一合并
  2. 合并后按时间倒序排序
  3. 排序后再分页
  4. 分页基于时间倒序 seek 游标，下一页通过 nextpagetoken -> page_token 延续
  5. 复合游标按当前粒度选择次级排序键：
  • DAY 使用 tradedate + sourcerecord_index
  • THREESECOND 使用 markettime + insert_time

7. 对外字段策略

7.1 设计原则

当前阶段不再对黄金眼字段做接口层重命名映射，直接使用数据库字段定义。

原则如下：

  1. fields 参数直接传数据库标准字段名
  2. 返回结果字段名直接使用数据库标准字段名
  3. 仅允许白名单字段
  4. 非白名单字段直接拒绝
  5. 未启用字段应返回明确错误，不得返回推断值或占位值

7.2 公共字段

一期建议保留以下直接可见的核心字段：

  • market_id
  • code_str
  • trade_date
  • market_time
  • sourcerecordindex
  • imported_at
  • insert_time

7.3 黄金眼业务字段白名单

一期建议直接按数据库字段名开放黄金眼字段，并在文档中同步保留中文说明，便于调用方理解字段业务含义。

字段使用补充说明：

  1. tradedate、sourcerecordindex、importedat 只在日线表 snapshotgoldeye1d 中可用。
  2. markettime、inserttime 只在 3 秒表 snapshotgoldeye3s 中可用。
  3. 其它 24 个黄金眼业务字段在日线表和 3 秒表中都可用。
  4. 大小单编码说明：
  • 0 表示买方，1 表示卖方
  • 0 表示庄单，1 表示大单，2 表示中单，3 表示小单

7.3.1 定位与时间字段

字段名适用粒度中文说明
market_idDAY / THREE_SECOND / AUTO市场 ID，具体取值见上方 market_id 对照表
code_strDAY / THREE_SECOND / AUTO证券代码
trade_dateDAY / AUTO日线记录的交易日期
market_timeTHREE_SECOND / AUTO3 秒行情记录时间
sourcerecordindexDAY日线表内部排序辅助序号
imported_atDAY日线记录导入时间
insert_timeTHREE_SECOND3 秒记录入库时间

7.3.2 黄金眼业务字段

字段名中文说明
contracts00买方庄单成交笔数
volume00买方庄单成交量
amount00买方庄单成交额
contracts01买方大单成交笔数
volume01买方大单成交量
amount01买方大单成交额
contracts02买方中单成交笔数
volume02买方中单成交量
amount02买方中单成交额
contracts03买方小单成交笔数
volume03买方小单成交量
amount03买方小单成交额
contracts10卖方庄单成交笔数
volume10卖方庄单成交量
amount10卖方庄单成交额
contracts11卖方大单成交笔数
volume11卖方大单成交量
amount11卖方大单成交额
contracts12卖方中单成交笔数
volume12卖方中单成交量
amount12卖方中单成交额
contracts13卖方小单成交笔数
volume13卖方小单成交量
amount13卖方小单成交额

7.4 字段治理建议

虽然当前阶段不做字段重命名映射，但仍建议保留字段白名单治理能力。

推荐规则：

  1. 只开放对外交付需要的数据库字段
  2. 不暴露导入辅助字段、内部技术字段或临时字段
  3. 对后续字段按“第1批上线 / 上线前补齐 / 后续提供”分类管理
  4. 请求未开放字段时，应返回明确错误

8. 响应结构设计

建议统一响应如下：

{
  "code": "SUCCESS",
  "message": "请求成功",
  "traceId": "TRACE-20260623-000001",
  "data": {
    "query_type": "goldeneye",
    "items": [
      {
        "market_id": 153,
        "code_str": "009898",
        "market_time": "2026-06-23T15:59:54",
        "trade_date": "2026-06-23",
        "contracts_0_0": 0,
        "amount_1_1": 0.00
      }
    ],
    "page": {
      "page_size": 5,
      "next_page_token": null,
      "total": 1
    }
  },
  "page": {
    "page_size": 5,
    "next_page_token": null,
    "total": 1
  }
}

8.1 顶层字段

字段名说明
code响应码
message响应说明
traceId请求追踪标识
data业务数据
page分页信息

其中分页字段补充约定：

  1. page_size 表示本次请求的页大小。
  2. nextpagetoken 为下一页 seek 游标，没有下一页时返回 null。
  3. total 表示当前查询条件下的真实总量，而不是当前页返回条数。
  4. nextpagetoken 属于不透明复合游标，调用方只需原样回传，不应依赖其内部编码格式。

8.3 Swagger 联调分页示例

为了避免调用方在 Swagger 页面上把 page_token 写错，建议按下面的方式调试：

  1. 第一页请求时，可以完全不传 page_token。
  2. 如果需要显式传空值，必须写成合法 JSON："page_token": null。
  3. 不要写成 page_token:null，因为这不是合法 JSON，请求会在进入业务前就被拦截。
  4. 当响应返回 page.nextpagetoken 后，下一页请求只需要把该值原样回填到 page_token。
  5. 下一页请求除了 page_token 外，其余查询条件应保持不变。

8.2 items 公共字段

字段名说明
market_id市场 ID，具体取值见 market_id 对照表
code_str证券代码
trade_date日线记录的交易日
market_time3 秒记录的行情时间

9. 与平台能力的衔接

黄金眼查询虽然是一期唯一业务查询能力，但实现时应保持与平台级能力的衔接扩展点，而不是单独做一套封死结构。

一期建议实际落地的能力：

  1. 字段白名单校验
  2. 统一请求结构
  3. 统一响应结构
  4. 统一异常处理

后续扩展预留能力：

  1. Token 鉴权入口
  2. 用户与企业权限判断
  3. 数据集权限校验
  4. 限流与配额控制
  5. 统一审计日志

10. Token 预留设计

当前阶段黄金眼查询接口需要接入一期简化登录能力。

Token 传递方式约定如下：

  • Authorization: Bearer

一期建议：

  1. 通过 POST /api/auth/login 在首次使用时传递用户名和密码，获取 token
  2. 首次登录响应中返回后续续期所需的会话凭证字段，例如 refresh_token
  3. 后续通过 POST /api/auth/refresh 完成续期、换发或会话变更，不再重复传递用户名和密码
  4. 黄金眼查询接口请求头必须携带 Token
  5. 服务端校验 Token 有效性
  6. 后续如鉴权方案明确，再补用户、企业、权限、配额逻辑

11. 后续待确认项

在代码落地前，建议继续确认：

  1. 黄金眼数据库字段白名单最终清单
  2. 黄金眼 1D 与 3S 结果字段的统一对外可见范围
  3. 黄金眼查询错误码与参数校验规则
  4. ClickHouse 查询超时、连接池与熔断策略
  5. /api/marketdata/query 后续扩展到股票 L1 的路由规则
  6. 后续统一鉴权方案明确后的接入方式
股票分析

📎 相关文章

ST交昂（600530）重组分析报告

ST交昂（600530）重组分析报告 重组分析 ST交昂（600530.SH）重组分析报告 上海交大昂立股份有限公司 — "保健品第一股"的重组困境与出路 分析...

*ST瑞茂（600180）摘帽退市分析

*ST瑞茂（600180）摘帽退市分析 分析日期：2026年8月5日 数据来源：通达信/上交所公告 一、基本情况 项目 内容 公司名称 瑞茂通供应链管理股份有限...