MomentumLab/docs/CUSTOM_DATA_SOURCE.md

自定义数据源配置指南

概述

系统支持接入自定义数据源服务，用于获取股票K线数据、标的列表和交易日历等信息。

支持的接口

自定义数据源需要实现以下接口：

接口	方法	说明	参数
/v1/stock/klines/:symbol	GET	查询K线数据	period, startDate, endDate, limit
/v1/stock/symbols	GET	查询标的列表	type, exchange, limit, offset
/v1/stock/klines/batch	POST	批量查询K线	{ symbols, period, startDate, endDate, limit }
/v1/stock/trading-dates	GET	获取交易日历	startDate, endDate

配置说明

环境变量

在 app/backend/.env 中添加以下配置：

# 自定义数据源配置
CUSTOM_DATA_SOURCE_ENABLED=true
CUSTOM_DATA_SOURCE_URL=http://localhost:8080
CUSTOM_DATA_SOURCE_API_KEY=your-api-key
CUSTOM_DATA_SOURCE_TIMEOUT=30000

配置项说明

配置项	说明	默认值
CUSTOM_DATA_SOURCE_ENABLED	是否启用自定义数据源	false
CUSTOM_DATA_SOURCE_URL	数据源服务地址	http://localhost:8080
CUSTOM_DATA_SOURCE_API_KEY	API密钥（可选）	空
CUSTOM_DATA_SOURCE_TIMEOUT	请求超时时间（毫秒）	30000

API 接口文档

1. 健康检查

GET /api/v1/datasource/health

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "enabled": true,
    "status": "ok"
  }
}

2. 查询K线数据

GET /api/v1/datasource/klines/:symbol?period=day&limit=60

参数：

• symbol (path) - 标的代码，如 000001.SZ
• period (query) - 周期：day/week/month，默认 day
• startDate (query) - 开始日期 YYYY-MM-DD
• endDate (query) - 结束日期 YYYY-MM-DD
• limit (query) - 限制条数

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "symbol": "000001.SZ",
    "period": "day",
    "count": 60,
    "items": [
      {
        "date": "2024-01-01",
        "open": 10.5,
        "high": 11.2,
        "low": 10.3,
        "close": 10.8,
        "volume": 1000000,
        "amount": 10800000
      }
    ]
  }
}

3. 查询标的列表

GET /api/v1/datasource/symbols?type=stock&limit=100

参数：

• type (query) - 类型：stock/index/etf/bond
• exchange (query) - 交易所代码
• limit (query) - 限制条数
• offset (query) - 偏移量

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "count": 100,
    "items": [
      {
        "symbol": "000001.SZ",
        "name": "平安银行",
        "type": "stock",
        "exchange": "SZSE",
        "industry": "银行"
      }
    ]
  }
}

4. 批量查询K线

POST /api/v1/datasource/klines/batch
Content-Type: application/json

{
  "symbols": ["000001.SZ", "000002.SZ"],
  "period": "day",
  "startDate": "2024-01-01",
  "endDate": "2024-12-31",
  "limit": 100
}

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "requestCount": 2,
    "resultCount": 2,
    "items": [
      {
        "symbol": "000001.SZ",
        "data": [...]
      },
      {
        "symbol": "000002.SZ",
        "data": [...]
      }
    ]
  }
}

5. 获取交易日历

GET /api/v1/datasource/trading-dates?startDate=2024-01-01&endDate=2024-01-31

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "totalDays": 31,
    "tradingDays": 22,
    "items": [
      {
        "date": "2024-01-01",
        "isTrading": false
      },
      {
        "date": "2024-01-02",
        "isTrading": true
      }
    ]
  }
}

6. 获取最近交易日

GET /api/v1/datasource/nearest-trading-date?date=2024-01-01

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "requestDate": "2024-01-01",
    "nearestTradingDate": "2024-01-02"
  }
}

7. 检查是否为交易日

GET /api/v1/datasource/is-trading-date?date=2024-01-01

响应示例：

{
  "code": 200,
  "message": "success",
  "data": {
    "date": "2024-01-01",
    "isTrading": false
  }
}

在代码中使用

服务层调用

import { customDataSourceService } from '../services/customDataSourceService';

// 获取K线数据
const klines = await customDataSourceService.getKLines('000001.SZ', 'day', {
  limit: 60,
});

// 获取标的列表
const symbols = await customDataSourceService.getSymbols({
  type: 'stock',
  limit: 100,
});

// 批量获取K线
const batchData = await customDataSourceService.getBatchKLines({
  symbols: ['000001.SZ', '000002.SZ'],
  period: 'day',
  limit: 30,
});

// 获取交易日历
const tradingDates = await customDataSourceService.getTradingDates(
  '2024-01-01',
  '2024-12-31'
);

// 检查是否启用
if (customDataSourceService.isEnabled()) {
  // 使用自定义数据源
}

数据源接口规范

如果你要实现自己的数据源服务，需要遵循以下规范：

K线数据格式

{
  "date": "2024-01-01",
  "open": 10.5,
  "high": 11.2,
  "low": 10.3,
  "close": 10.8,
  "volume": 1000000,
  "amount": 10800000
}

标的信息格式

{
  "symbol": "000001.SZ",
  "name": "平安银行",
  "type": "stock",
  "exchange": "SZSE",
  "industry": "银行"
}

交易日历格式

{
  "date": "2024-01-01",
  "isTrading": false
}

缓存策略

系统对自定义数据源接口实现了多级缓存：

接口	缓存时间	说明
K线数据	5分钟	频繁更新
标的列表	1小时	相对稳定
批量K线	5分钟	频繁更新
交易日历	24小时	很少变化

错误处理

当自定义数据源不可用时，系统会返回相应的错误码：

状态码	说明
503	自定义数据源未启用
500	数据源请求失败
400	请求参数错误
404	数据不存在

示例：Python FastAPI 数据源服务

from fastapi import FastAPI
from typing import List, Optional
from pydantic import BaseModel

app = FastAPI()

class KLineItem(BaseModel):
    date: str
    open: float
    high: float
    low: float
    close: float
    volume: int
    amount: Optional[float] = None

class SymbolInfo(BaseModel):
    symbol: str
    name: str
    type: str
    exchange: Optional[str] = None
    industry: Optional[str] = None

class TradingDate(BaseModel):
    date: str
    isTrading: bool

class BatchKLineQuery(BaseModel):
    symbols: List[str]
    period: str = "day"
    startDate: Optional[str] = None
    endDate: Optional[str] = None
    limit: Optional[int] = None

@app.get("/v1/stock/klines/{symbol}", response_model=List[KLineItem])
async def get_klines(
    symbol: str,
    period: str = "day",
    startDate: Optional[str] = None,
    endDate: Optional[str] = None,
    limit: Optional[int] = None
):
    # 实现K线查询逻辑
    pass

@app.get("/v1/stock/symbols", response_model=List[SymbolInfo])
async def get_symbols(
    type: Optional[str] = None,
    exchange: Optional[str] = None,
    limit: Optional[int] = None,
    offset: Optional[int] = None
):
    # 实现标的列表查询逻辑
    pass

@app.post("/v1/stock/klines/batch")
async def get_batch_klines(query: BatchKLineQuery):
    # 实现批量K线查询逻辑
    pass

@app.get("/v1/stock/trading-dates", response_model=List[TradingDate])
async def get_trading_dates(startDate: str, endDate: str):
    # 实现交易日历查询逻辑
    pass