统一行情品种模型与 MarketDataProvider 接口设计

[363045841]

背景

当前各数据源通过独立 Fetcher 接入，market、params、周期能力和上游路由信息存在混用。前端需要先建立与后端协议无关的统一品种模型，再由 GOTDX、BaoStock、TradingView 等 Provider 适配。

关联：#105

目标

• 由前端定义统一的品种、能力、查询和结果模型。
• UI 只读取标准字段和能力，不解析 GOTDX 的 market/category/kind。
• 搜索、K 线、分时、深度按能力组合，不要求每个数据源实现全部接口。
• 为 GOTDX 优先迁移提供稳定目标，后续数据源复用同一模型。

V1 品种支持范围

品种	sessionId	K 线	分时	复权	深度	V1 状态
A 股股票	CN	是	是	qfq/hfq/none	否	支持
A 股指数	CN	是	是	none	否	支持
ETF/基金	CN	是	是	数据源声明	否	支持
港股股票/指数	HK	是	是	数据源声明	否	支持
美股股票/指数	US	是	是	splits/none	否	支持
Mock	CN	是	否	none	否	支持
Crypto	待定义 24x7	暂未接入	暂未接入	none	是	仅保留现有 Binance Depth
期货/期权/外汇	尚无完整会话	暂不开放	暂不开放	none	否	预留模型，不进入可选列表

只有 CN/HK/US 已具备完整的前端交易时段定义。数据源可以搜索到某类品种，不等同于前端已经支持该品种。

基础枚举

模型	值
AssetClass	stock/index/fund/etf/future/option/forex/crypto/unknown
KLinePeriod	1min/5min/15min/30min/60min/daily/weekly/monthly/quarterly/yearly
KLineAdjustment	qfq/hfq/splits/none
VolumeUnit	share/lot/contract/baseAsset
MarketDataSourceStatus	online/offline/degraded

InstrumentDescriptor

字段	类型	必填	说明
id	string	是	数据源范围内稳定唯一，例如 gotdx:stock:0:000001
sourceId	string	是	Provider 注册标识
symbol	string	是	展示和请求使用的代码
name	string	是	品种名称
assetClass	AssetClass	是	前端统一品种类别
exchange	string	是	交易所代码
sessionId	string	否	对应前端 MarketSessionRegistry；纯深度品种可缺失
currency	string	否	计价币种
tickSize	number	否	最小价格变动
lotSize	number	否	每手数量
providerRef	Record<string, primitive>	否	Provider 私有不透明路由信息，业务和 UI 禁止解析
capabilities	InstrumentCapabilities	是	当前品种实际支持的行情能力

能力配置

字段	类型	说明
capabilities.bars.periods	KLinePeriod[]	品种支持的 K 线周期
capabilities.bars.adjustments	KLineAdjustment[]	品种支持的复权方式
capabilities.timeShare	boolean	是否支持分时
capabilities.depth	boolean	是否支持实时深度

周期和复权下拉框必须由品种能力驱动，不再始终展示全部选项。缺少有效 sessionId 的品种不得进入分时模式。

查询与结果模型

模型	关键字段	返回值/说明
InstrumentSearchQuery	keyword, limit, assetClasses?, signal?	搜索 Provider 内的标准品种描述
BarQuery	instrument, period, adjustment, from, to, signal?	from/to 为 UTC 毫秒
BarSeries	instrumentId, period, adjustment, timezone, volumeUnit?, data	data 为统一 KLineData[]
TimeShareQuery	instrument, tradingDate, signal?	tradingDate 为品种时区内 YYYY-MM-DD
TimeShareSeries	instrumentId, tradingDate, timezone, preClose, volumeUnit?, data	data 为统一 TimeShareData[]
SourceProbeResult	status, checkedAt, latencyMs?, message?	替代用搜索请求探测数据源

volumeUnit 必须明确；“手”不适用于美股、Crypto 和全部期货场景。

Provider 接口

模块	方法	职责	是否可选
MarketDataProvider	probe(signal?)	探测数据源状态	否
InstrumentCatalog	search(query)	搜索和归一化品种目录	是
BarDataSource	fetch(query)	拉取历史 K 线	是
TimeShareDataSource	fetch(query)	拉取单个交易日分时	是
DepthDataSource	connect(instrument)	创建实时深度连接	是

interface MarketDataProvider {
  readonly source: DataSourceDescriptor
  probe(signal?: AbortSignal): Promise<SourceProbeResult>
  readonly catalog?: InstrumentCatalog
  readonly bars?: BarDataSource
  readonly timeShare?: TimeShareDataSource
  readonly depth?: DepthDataSource
}

数据源配置模型

字段	类型	说明
source.id	string	稳定注册名，如 gotdx
source.displayName	string	UI 展示名
source.description	string?	数据源说明
source.marketSessions	Record<string, MarketSessionConfig>?	数据源声明的额外时段，注册前由前端校验
baseUrl	string?	Transport/Provider 配置，不进入品种领域模型

迁移顺序

1. 在 core 中引入领域类型和 MarketDataProvider，不改变现有请求行为。
2. 实现 GotdxMarketDataProvider，先包装当前 GOTDX HTTP API。
3. 搜索结果迁移到 InstrumentDescriptor，身份判断改用稳定 id。
4. 周期、复权和分时入口改为读取 InstrumentCapabilities。
5. 用 Legacy Adapter 将 Provider 暂时桥接到现有 DataFetcher/TimeShareFetcherFn。
6. 前端模型稳定后据此制定统一 HTTP/OpenAPI 协议。
7. GOTDX 后端实现统一协议，再迁移 BaoStock、TradingView。

验收标准

• UI 和 Chart/DataBuffer 不读取 providerRef 内容。
• 同代码、不同市场或不同来源由稳定 InstrumentDescriptor.id 区分。
• 不支持的周期、复权、分时能力不会出现在 UI 中。
• CN/HK/US 品种能依据 sessionId 使用正确时区和交易时段。
• Provider 返回统一 K 线和分时模型，前端不再解析 GOTDX 原始大写字段。
• 新模型不破坏现有 DataFetcher 公共 API，迁移期间通过适配器兼容。

非 V1 范围

实时报价、逐笔成交、财务数据、期权链、期货夜盘日历和统一深度传输协议暂不纳入本 Issue。

[363045841]

当前协议实现状态

统一行情 V1 已完成前端模型、GOTDX 后端路由和前端 GOTDX Provider 切换。

V1 REST 协议

能力	Endpoint	GOTDX 状态	前端状态
数据源探测	GET /api/v1/market-data/sources/{sourceId}/probe	已实现（当前支持 gotdx）	MarketDataProvider.probe() 已使用
品种搜索	POST /api/v1/market-data/instruments/search	已实现	catalog.search() 已使用
历史 K 线	POST /api/v1/market-data/bars	已实现	bars.fetch() 已使用
单交易日分时	POST /api/v1/market-data/timeshare	已实现	timeShare.fetch() 已使用
实时深度	独立 SSE/WS Transport	未纳入 REST V1	现有 Binance DepthSource 保持不变

协议 SSOT：docs/market-data-v1.openapi.yaml。已通过 Redocly 校验。

请求与响应约束

• 请求使用 sourceId 和 InstrumentReference：id/symbol/exchange/providerRef。
• providerRef 是不透明数据源路由参数，UI、Chart 和业务代码不解析；GOTDX 后端仅在适配边界读取 market/category/kind。
• 成功响应统一为 { data, requestId }。
• 错误响应统一为 { error: { code, message, details? }, requestId }。
• K 线与分时均使用 UTC 毫秒时间戳；分时交易日为品种时区内 YYYY-MM-DD。
• 搜索响应直接返回 InstrumentDescriptor，含稳定 id、assetClass、sessionId、能力声明和 providerRef。

前端落地范围

• 搜索 UI、主品种选择和比较选择直接消费 InstrumentDescriptor。
• 品种稳定 id 用于搜索去重、目录去重和比较品种身份。
• 周期、复权、分时入口根据 InstrumentCapabilities 过滤。
• sessionId 映射现有 MarketSessionRegistry；无分时能力或无 session 的品种不能进入分时模式。
• 旧 DataFetcher/SearchFetcher/TimeShareFetcher 仍通过 Legacy Adapter 与旧 controller 调用链兼容。

兼容与迁移状态

项目	状态
旧 GOTDX /api/stock/*、/api/ex/*、/api/symbol/search	保留，未移除
旧 @DataFetcher GOTDX 实现	保留，继续走旧 endpoint
新 gotdxMarketDataProvider	已切换至 V1 endpoint
BaoStock / TradingView	尚未实现 V1 Provider 或后端协议
Binance depth	保持独立 Transport，暂不并入 REST V1

验证

• 前端 core 相关测试：49 项通过。
• Vue 构建通过。
• GOTDX go test ./... 通过。
• GOTDX 新旧 K 线、分时结果对照测试通过。