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` 中添加以下配置：

```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. 健康检查

```http
GET /api/v1/datasource/health
```

**响应示例：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "enabled": true,
    "status": "ok"
  }
}
```

### 2. 查询K线数据

```http
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) - 限制条数

**响应示例：**
```json
{
  "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. 查询标的列表

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

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

**响应示例：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "count": 100,
    "items": [
      {
        "symbol": "000001.SZ",
        "name": "平安银行",
        "type": "stock",
        "exchange": "SZSE",
        "industry": "银行"
      }
    ]
  }
}
```

### 4. 批量查询K线

```http
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
}
```

**响应示例：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "requestCount": 2,
    "resultCount": 2,
    "items": [
      {
        "symbol": "000001.SZ",
        "data": [...]
      },
      {
        "symbol": "000002.SZ",
        "data": [...]
      }
    ]
  }
}
```

### 5. 获取交易日历

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

**响应示例：**
```json
{
  "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. 获取最近交易日

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

**响应示例：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "requestDate": "2024-01-01",
    "nearestTradingDate": "2024-01-02"
  }
}
```

### 7. 检查是否为交易日

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

**响应示例：**
```json
{
  "code": 200,
  "message": "success",
  "data": {
    "date": "2024-01-01",
    "isTrading": false
  }
}
```

## 在代码中使用

### 服务层调用

```typescript
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线数据格式

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

### 标的信息格式

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

### 交易日历格式

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

## 缓存策略

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

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

## 错误处理

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

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

## 示例：Python FastAPI 数据源服务

```python
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
```